Proposa AI 任务进度查询接口对接文档

版本日期：2026-09-09。适用范围：当前仓库 API 实现。

本文中的响应为按实现整理的示例，时间、错误场景和业务 ID 均为示意，不是对任务 b429d8ddce344f2fadac91195aa56d97 的线上查询结果。服务地址请替换为实际部署地址。

1. 接口信息

项目	说明
用途	查询投标文件生成任务的 Step1–6 步骤进度
方法	`GET`
路径	`/api/v1/jobs/{request_id}/progress`
本次任务路径	`/api/v1/jobs/b429d8ddce344f2fadac91195aa56d97/progress`
路径参数	路径中的 ID 可以是提交后返回的 `request_id`，也可以是请求中的 `txbId` 值；字符串，必填
Query / Body	无
响应格式	`application/json`，直接返回对象，没有 `code` / `data` 外层包装
鉴权	当前应用代码未要求 token；若部署网关设置鉴权，按网关要求提供

请求示例（将 https://api.example.com 替换为实际地址）：

curl "https://api.example.com/api/v1/jobs/b429d8ddce344f2fadac91195aa56d97/progress" -H "Accept: application/json"

对接核心规则：/progress 是步骤快照，最终成功或失败必须查询 GET /api/v1/jobs/{request_id} 的 status。HTTP 200 仅表示查询成功，不表示生成成功。

1.1 使用 txbId 查询最新任务

状态、进度、下载三个接口共用同一套 ID 解析规则。假设提交时传入 "txbId": "TEST-TXB-001"，可直接请求：

GET /api/v1/jobs/TEST-TXB-001
GET /api/v1/jobs/TEST-TXB-001/progress
GET /api/v1/jobs/TEST-TXB-001/file

无需增加 ?txbId= 查询参数，也不需要请求体。提交参数名仍是大小写准确的 txbId。

优先精确匹配 request_id，找不到时再按 txbId 找最新任务。如果某个 txbId 恰好与已有 request_id 相同，优先返回该 request_id 对应任务。
同一个 txbId 每次提交仍产生新的唯一 request_id 和独立文件目录；映射指向最近提交的任务，不按完成时间排序。并发请求按服务端校验后注册任务的顺序确定先后。
新任务排队、处理中或处理失败时，不会回退到之前的成功任务；新任务未完成时用 txbId 下载仍返回 409。
请求校验失败或后台提交失败（未成功接收的请求），不替换之前有效的映射。
历史任务通过原有 request_id 查询。查询状态响应中的 request_id、提交响应和回调中的 ID、下载 URL 仍使用真正的任务 ID，不替换为 txbId。
ID 值区分大小写。提交时 txbId 首尾空白会被去除；查询应使用处理后的值。本文 URL 示例使用可直接放入路径的 ID。

如果要保证状态、进度、下载对应同一次生成：先通过 txbId 查询任务状态，拿到响应中的 request_id，后续固定使用该 ID。 否则在两次请求之间有同一 txbId 的新任务提交时，最新任务可能发生切换。

2. 进度响应字段

有步骤快照时返回以下字段；无快照时仅返回 status、message，其余字段缺省。

字段	类型	含义
`updated_at`	string	快照最后更新时间，ISO 8601，UTC，如 `2026-09-09T02:30:00+00:00`；北京时间需加 8 小时
`current_step`	integer	当前或最近完成的步骤编号，1–6
`total_steps`	integer	总步骤数，当前固定为 6
`current_step_name`	string	步骤名称
`status`	string	有快照时为 `running` 或 `completed`；无快照时回退为任务状态，见后文
`message`	string	展示提示语，不应作为程序判断条件
`completed_steps`	integer[]	已执行完成的步骤编号；正在执行的步骤不包含在其中

此接口不返回 request_id、txbId、error、resultPath、下载地址或 progress_url。调用方需保存提交时获得的任务 ID。

步骤	`current_step_name`
1	Step 1 文档解析及表/函/表格提取
2	Step 2 招标需求、评分项、废标项分析
3	Step 3 投书大纲生成
4	Step 4 章节内容生成与模板填充
5	Step 5 覆盖性、风险与完整性审核修复
6	Step 6 最终 DOCX 聚合装配

3. 处理中拿到的结果

3.1 尚未产生步骤快照

HTTP 200，排队时可能返回：

{
  "status": "queued",
  "message": "任务已排队或尚未开始"
}

后台已启动但尚未写入有效快照时：

{
  "status": "processing",
  "message": "任务已排队或尚未开始"
}

调用方显示“排队中”或“处理中”并继续轮询；不要强制读取此时不存在的 current_step、completed_steps。

3.2 正在执行某一步骤

HTTP 200，例如正在执行 Step3：

{
  "updated_at": "2026-09-09T02:30:00+00:00",
  "current_step": 3,
  "total_steps": 6,
  "current_step_name": "Step 3 投书大纲生成",
  "status": "running",
  "message": "Step 3 投书大纲生成 正在处理",
  "completed_steps": [1, 2]
}

含义：Step1、Step2 已完成，Step3 正在执行。仍需查询任务状态确认任务没有失败，原因见第 4 节。

3.3 某一步骤刚完成，但任务仍在处理

HTTP 200，例如 Step3 刚完成、Step4 尚未更新快照：

{
  "updated_at": "2026-09-09T02:35:00+00:00",
  "current_step": 3,
  "total_steps": 6,
  "current_step_name": "Step 3 投书大纲生成",
  "status": "completed",
  "message": "Step 3 投书大纲生成 处理完成",
  "completed_steps": [1, 2, 3]
}

这里的 completed 仅表示 Step3 完成，不能停止轮询或提示整个任务完成。

4. 处理失败拿到的结果

4.1 已产生快照后失败：进度可能仍为 running

当前实现失败时不会把步骤快照改写为 failed。例如 Step4 执行失败，/progress 仍可能返回 HTTP 200 和以下最后快照：

{
  "updated_at": "2026-09-09T02:40:00+00:00",
  "current_step": 4,
  "total_steps": 6,
  "current_step_name": "Step 4 章节内容生成与模板填充",
  "status": "running",
  "message": "Step 4 章节内容生成与模板填充 正在处理",
  "completed_steps": [1, 2, 3]
}

此时查询任务状态接口：

curl "https://api.example.com/api/v1/jobs/b429d8ddce344f2fadac91195aa56d97"

该接口 HTTP 200 响应中的关键字段如下（仅摘录字段，不是完整响应）：

{
  "request_id": "b429d8ddce344f2fadac91195aa56d97",
  "txbId": "TEST-TXB-001",
  "status": "failed",
  "error": "Step1-6 处理进程异常退出（退出码 1）",
  "callback_delivered": true
}

调用方以任务 status=failed 判定失败，停止轮询，展示 error，隐藏下载入口。失败原因可能是“处理超时”、进程异常退出或其他错误文本，不能仅匹配某个固定错误字符串。

callback_delivered=true 只说明结果回调已按 HTTP 状态成功投递，不表示生成成功。回调失败也不改变生成结果；可查看任务的 callback_error。

4.2 未产生有效快照就失败

/progress 可返回 HTTP 200：

{
  "status": "failed",
  "message": "任务已排队或尚未开始"
}

此处 message 是统一兜底文案，并非真实失败原因。仍需从任务状态接口读取 error。

4.3 全部步骤完成后，最终文件校验或发布失败

此时 /progress 甚至可能仍是 Step6 的 completed 快照，而任务状态接口返回 failed。最终结果仍以任务状态为准。

注意：失败回调里的 resultPath="error: ..." 属于回调协议；/progress 不返回该字段，任务状态查询也不自动构造该字段。任务查询中如有 output_path，它只是预定输出路径，不能据此判成功。

5. 处理完成拿到的结果

步骤全部执行完成后，/progress 返回 HTTP 200：

{
  "updated_at": "2026-09-09T03:20:00+00:00",
  "current_step": 6,
  "total_steps": 6,
  "current_step_name": "Step 6 最终 DOCX 聚合装配",
  "status": "completed",
  "message": "Step 6 最终 DOCX 聚合装配 处理完成",
  "completed_steps": [1, 2, 3, 4, 5, 6]
}

再查询任务状态接口，成功时关键字段如下（仅摘录字段，不是完整响应；文件名及路径为虚构示例）：

{
  "request_id": "b429d8ddce344f2fadac91195aa56d97",
  "txbId": "TEST-TXB-001",
  "status": "completed",
  "output_path": "/srv/proposa/output/api_jobs/b429d8ddce344f2fadac91195aa56d97/示例招标文件.docx",
  "final_review_path": "/srv/proposa/output/api_jobs/b429d8ddce344f2fadac91195aa56d97/示例招标文件.docx",
  "final_review_url": "https://api.example.com/api/v1/jobs/b429d8ddce344f2fadac91195aa56d97/file",
  "callback_delivered": true,
  "callback_error": ""
}

只有任务 status=completed 才展示“生成完成”和下载按钮。final_review_path / output_path 是服务器路径，浏览器不能直接打开；通过下载接口获取文件：

curl "https://api.example.com/api/v1/jobs/b429d8ddce344f2fadac91195aa56d97/file" --output "投标文件.docx"

下载成功：HTTP 200，响应为 DOCX 二进制，Content-Type 为 application/vnd.openxmlformats-officedocument.wordprocessingml.document，不是 JSON。

Step6 完成后还有文件检查、发布和回调投递过程；当前实现等回调尝试结束才更新任务终态。因此短暂出现“进度 Step6 completed、任务 processing”时，应继续等待。回调最终失败仍可得到任务 completed，但 callback_delivered=false。

6. 异常响应和任务保留

请求	HTTP 状态	含义与处理
`/progress`、任务查询、下载	404	任务不存在；核对任务 ID 和服务实例，不应当作生成失败原因
下载 `/file`	409	任务未完成，或最终文件不存在；不可按 DOCX 保存响应
查询	网络异常 / 5xx	本次查询失败，不等于任务生成失败；提示重试，避免直接把业务任务改为 failed

404 响应：

{
  "detail": "任务不存在"
}

下载 409 响应：

{
  "detail": "任务尚未生成可下载文件"
}

任务记录及 txbId → 最新 request_id 映射当前保存在 API 进程内存中，服务重启后旧 ID 或 txbId 可能返回 404，即使磁盘文件还在。多实例部署需确保查询访问持有该任务记录及映射的实例。

默认清理中间文件时，会先将末次步骤快照保存在任务内存记录中，再清理中间目录。因此同一进程内，处理中间文件清理后仍可查询末次快照；该快照不会因清理自动变成成功或失败状态。

7. 推荐对接流程

提交任务后保存 request_id，与自己的业务 txbId 关联；也可直接用 txbId 查询最新任务，再从任务状态响应取实际 request_id。
建议每 3–5 秒查询一次任务状态；当状态为 queued 或 processing 时，同时查询 /progress 更新步骤展示。这是调用建议，服务端没有强制该轮询间隔。
任务状态为 failed：停止轮询，展示 error，不提供下载。
任务状态为 completed：停止轮询，提供 /file 下载；下载仍需检查 HTTP 状态。
两个查询不是同一时刻的原子快照，发生矛盾时以任务终态优先；未知字段可以忽略，未知状态保留重试和异常提示。

判定逻辑示意：

job = GET /api/v1/jobs/{request_id}
如果查询失败：处理 HTTP/网络异常
否则如果 job.status == failed：展示 job.error，结束轮询
否则如果 job.status == completed：展示完成及下载按钮，结束轮询
否则：
    progress = GET /api/v1/jobs/{request_id}/progress
    若有步骤字段：显示当前步骤和已完成步骤
    否则：显示排队中或处理中
    等待后继续查询 job

接口没有提供百分比或预计剩余时间。可显示“已完成 2/6 步”；各步骤耗时不同，不宜将步骤比例当作实际耗时百分比。updated_at 仅在步骤开始或结束时更新，长时间不变化本身不能证明失败。

对接验收至少覆盖：两种 ID 的三个查询接口、同一 txbId 重复提交后最新任务切换及历史任务可查、提交失败不污染映射、排队无步骤字段、步骤 running、中间步骤 completed、失败但进度仍 running、Step6 completed 但任务仍 processing、任务 completed 后下载，以及 404/409。

API进度查询接口对接文档.md 12 KB Vēsture Neapstrādāts