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

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

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

## 1. 接口信息

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

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

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

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

## 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，排队时可能返回：

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

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

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

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

### 3.2 正在执行某一步骤

HTTP 200，例如正在执行 Step3：

```json
{
  "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 尚未更新快照：

```json
{
  "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 和以下最后快照：

```json
{
  "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]
}
```

此时查询任务状态接口：

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

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

```json
{
  "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：

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

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

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

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

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

## 5. 处理完成拿到的结果

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

```json
{
  "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]
}
```

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

```json
{
  "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` 是服务器路径，浏览器不能直接打开；通过下载接口获取文件：

```bash
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 响应：

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

下载 409 响应：

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

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

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

## 7. 推荐对接流程

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

判定逻辑示意：

```text
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` 仅在步骤开始或结束时更新，长时间不变化本身不能证明失败。

对接验收至少覆盖：排队无步骤字段、步骤 running、中间步骤 completed、失败但进度仍 running、Step6 completed 但任务仍 processing、任务 completed 后下载，以及 404/409。