项目导出（参数和项目列表一致）

导出接口 API 文档

POST /api/project/export

1. 请求说明

请求头（Headers）

字段	必填	说明
`Authorization`	是	认证 Token，格式：`Bearer <token>` 或直接 `<token>`

请求体（Body）

{
  "page": 1,
  "pageSize": 100,
  "filters": { /* 项目筛选条件 */ }
}

注：具体字段根据业务需求调整。

2. 响应说明

成功响应（HTTP 200）

{
  "message": "项目数：50，填入模板成功",
  "output": "/var/www/exports/projects_20240520.xlsx",
  "filename": "projects_20240520.xlsx",
  "downloadUrl": "https://api.example.com/exports/projects_20240520.xlsx?download=1&filename=projects_20240520.xlsx"
}

字段	类型	说明
`message`	string	导出结果描述
`output`	string	文件在服务器上的绝对路径（仅调试用，前端无需处理）
`filename`	string	生成的文件名（用于前端显示）
`downloadUrl`	string	前端直接使用此 URL 触发文件下载（已配置 Nginx 强制下载）

冲突响应（HTTP 423）

{
  "error": "系统繁忙，请稍后再试",
  "retryAfter": 15000
}

字段	类型	说明
`retryAfter`	number	剩余等待时间（毫秒），建议前端显示倒计时

错误响应（HTTP 401/500）

// 401 未授权
{ "error": "缺少 Authorization 头" }

// 500 服务器错误
{ "error": "导出过程中发生错误：<具体错误信息>" }

3. 前端调用示例

JavaScript（Fetch API）

Nginx 配置参考

4. 状态管理逻辑

场景	系统行为
导出开始	设置全局锁 `isExporting=true`，记录开始时间
导出完成/失败	通过 `on-finished` 自动解锁，触发 GC（内存回收）
并发请求	返回 HTTP 423 和剩余等待时间，前端轮询 `/export/status` 或显示倒计时

5. 注意事项

文件下载

直接使用返回的 downloadUrl，不要拼接路径（避免跨域或路径错误）。

如果浏览器拦截下载，需引导用户手动点击 <a href="downloadUrl">下载</a>。

授权安全

所有请求必须携带有效的 Authorization 头。

大文件处理

如果导出文件较大（>50MB），建议分片导出或使用 WebSocket 推送进度。

调试信息

output 字段仅用于后端日志，前端无需解析。

请求参数

Authorization

在 header 添加参数

Authorization

示例：

Authorization: ********************

Body 参数application/json

示例

{
    "page": 1,
    "pageSize": 50,
    "keyword": "",
    "filters": [
        {
            "field": "district",
            "value": [
                "岳麓区"
            ],
            "type": "string"
        }
    ]
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Body

示例

{
    "message": "项目数：234，填入模板成功",
    "output": "exports/export_250702_0828_00234items.xlsx",
    "filename": "export_250702_0828_00234items.xlsx",
    "downloadUrl": "https://dev.tieta.dongqianshan.com/exports/export_250702_0828_00234items.xlsx?download=1&filename=export_250702_0828_00234items.xlsx"
}

项目导出（参数和项目列表一致）

导出接口 API 文档#

1. 请求说明#

请求头（Headers）#

请求体（Body）#

2. 响应说明#

成功响应（HTTP 200）#

冲突响应（HTTP 423）#

错误响应（HTTP 401/500）#

3. 前端调用示例#

JavaScript（Fetch API）#

Nginx 配置参考#

4. 状态管理逻辑#

5. 注意事项#