4. 创建导出任务接口（POST）

创建导出任务是报表导出服务的核心入口，客户端通过 POST 请求提交导出需求，服务端同步返回任务标识与初始状态。本节聚焦接口契约的请求体与响应体结构，确保前后端在数据格式、必填字段与状态语义上达成一致。

4.1 请求体设计

请求体采用 JSON 格式，包含四个核心字段：reportType、format、filters 与 callbackUrl。其中前三个字段用于定义导出内容与样式，callbackUrl 用于异步通知导出完成。

请求体示例

{
  "reportType": "daily_sales",
  "format": "xlsx",
  "filters": {
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "region": "华东"
  },
  "callbackUrl": "https://myapp.com/callback/export"
}

4.2 响应体设计

服务端在接收到创建请求后，立即返回任务标识与初始状态，不等待实际导出完成。响应体包含三个字段：taskId、status、estimatedTime。

响应体示例

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "estimatedTime": 120
}

4.3 请求与响应流程

下图展示了客户端发起创建导出任务请求后，服务端同步返回任务标识与初始状态的完整交互流程：

4.4 字段校验规则

服务端在接收请求后，需对关键字段进行校验，避免无效任务进入队列。以下为校验清单：

• reportType：必须在已注册的报表类型列表中，否则返回 400 错误码 INVALID_REPORT_TYPE。
• format：仅允许 csv、xlsx、pdf 三个枚举值，大小写敏感。
• filters：若传入，服务端根据 reportType 对应的元数据校验键名与值类型，非法字段直接忽略并记录警告日志。
• callbackUrl：若传入，必须为合法的 HTTPS URL，否则返回 400 错误码 INVALID_CALLBACK_URL。

4.5 状态同步设计要点

创建接口返回的 status 固定为 pending，后续状态变更通过以下两种方式同步给客户端：

1. 轮询模式：客户端携带 taskId 调用查询任务状态接口（GET /api/v1/export/tasks/{taskId}），获取最新状态。
2. 回调模式：服务端在任务完成后，向 callbackUrl 发送 POST 请求，携带任务结果数据。

两种模式可同时启用，客户端可根据业务场景选择或组合使用。轮询间隔建议不低于 5 秒，避免对服务端造成压力。

4.6 接口契约总结

创建导出任务接口的设计遵循“同步创建、异步执行”原则，请求体与响应体结构清晰、字段语义明确。以下为关键设计决策：

• 请求体：reportType 与 format 为必填，filters 与 callbackUrl 为可选，兼顾灵活性与安全性。
• 响应体：立即返回 taskId 与 pending 状态，estimatedTime 为客户端提供进度参考。
• 状态同步：轮询与回调双模式并行，满足不同客户端架构的需求。