2026Technology-Competition/docs/api-design.md

API 与编排接口设计

版本: v1.0 | 日期: 2026-07-30 | 状态: 初版

本文档定义 Web 后端（FastAPI Orchestrator）的 REST API 端点、WebSocket 事件通道、编排调用链与部署拓扑。是 docs/design.md §8（Web UI）与 docs/agent-runtime-design.md §3（编排能力）的接口级展开。

---

目录

1. 定位与架构
2. REST API 端点清单
3. WebSocket 事件通道
4. 编排调用链
5. 任务队列抽象
6. 部署拓扑
7. 错误码约定
8. 与各文档的关系

---

1. 定位与架构

浏览器 (React UI)
      │  REST API (JSON) + WebSocket (实时事件)
      ▼
FastAPI Orchestrator（单进程，默认）
      │
      ├── SessionManager（会话状态机，见 agent-runtime §3）
      ├── Agent 调度（Parser / Impact / Writer / QA）
      ├── TaskQueue 抽象（默认 InMemory；Redis/Valkey 为 v2 预留，见 §5）
      └── RagService 调用（规则检索）

架构决策（与用户确认）：

• 编排形态：抽象 TaskQueue 接口 + 单一 InMemoryQueue 实现（开发/测试/演示零依赖）。（T5 架构审查整改：Scope 缩减裁定移除 Redis/Valkey 双实现；接口保留供 v2 扩展。）
• 所有 API 返回 JSON；长任务（解析/影响调查/生成）采用「异步启动 + 轮询/推送」模式。

---

2. REST API 端点清单

2.1 会话管理

Method	Path	说明	请求体	响应	触发状态转移
POST	/api/sessions	创建会话	{user_id}	{session_id, status, locked_rule_version}	→ uploading
GET	/api/sessions/{id}	获取会话详情	—	会话对象（状态/步骤/进度摘要）	只读
DELETE	/api/sessions/{id}	删除会话	—	{deleted: true}	终态清理
GET	/api/sessions	会话列表（按用户）	?user_id=	[{session_id, status, updated_at}]	只读

2.2 文件上传

Method	Path	说明	请求体	响应	触发状态转移
POST	/api/sessions/{id}/files	上传文件（multipart）	file + file_type（requirements/template/write_instruction/rules/existing_system）	{file_id, file_name, size}	uploading 保持

file_type 取值说明（v1.1 修订，随 web-ui-design §3.1 补齐大赛输入资料）：

• requirements — 要件定义 Excel（核心数据源）
• template — 概要设计模板 docx（输出结构/样式）
• write_instruction — 概要设计做成说明书 docx（各章作成指引；RAG 归类 Type A 写入规则，Parser 解析）
• rules — 记入规则 / 图表规则等规则文档（可多个）
• existing_system — 现系统源码或既有设计书（追加/改修场景） | POST | /api/sessions/{id}/start-parse | 开始解析（全部文件上传完成后） | {} | {task_id}（解析异步执行） | uploading → parsing | | GET | /api/sessions/{id}/parse-result | 获取解析结果 | — | {structured_summary, sheets, template_sections} | 只读 |

2.3 解析确认

Method	Path	说明	请求体	响应	触发状态转移
POST	/api/sessions/{id}/confirm-parse	确认解析结果	{sheet_fixes?, template_fixes?}	{ok: true}	awaiting_parse_confirm → impact_running
POST	/api/sessions/{id}/reparse	修正后重新解析	{sheet_overrides}	{task_id}	awaiting_parse_confirm → parsing

2.4 影响调查

Method	Path	说明	请求体	响应	触发状态转移
POST	/api/sessions/{id}/start-impact	启动影响调查	{}	{task_id}	impact_running 保持
GET	/api/sessions/{id}/impact-result	获取影响调查结果	—	ImpactReport JSON	只读
POST	/api/sessions/{id}/impact-edits	逐条修正关联	{edits: [{type, id, action, data}]}	{ok: true, correction_history_id}	awaiting_impact_confirm 保持
POST	/api/sessions/{id}/confirm-impact	确认影响调查	{}	{ok: true}	awaiting_impact_confirm → writing
POST	/api/sessions/{id}/reject-impact	打回（重推或回到解析）	{target: "impact" | "parse"}	{ok: true}	awaiting_impact_confirm → impact_running | awaiting_parse_confirm

2.5 生成（Writer + QA）

Method	Path	说明	请求体	响应	触发状态转移
POST	/api/sessions/{id}/generate	启动章节生成	{}	{task_ids: [逐章]}	writing 保持
GET	/api/sessions/{id}/generation-status	各章生成进度	—	[{chapter_id, status, duration_ms}]	只读
GET	/api/sessions/{id}/chapters/{chapter_id}	获取单章内容块	—	ContentBlock JSON	只读
POST	/api/sessions/{id}/regenerate-chapter	单章重生成	{chapter_id, reason}	{task_id}	writing 保持
POST	/api/sessions/{id}/run-qa	启动 QA 校验	{}	{task_id}	writing → qa
GET	/api/sessions/{id}/qa-result	QA 校验结果	—	QAReport JSON	只读
POST	/api/sessions/{id}/writer-fix	QA 发现问题后反馈 Writer 重生成	{issues: [...]}	{task_ids}	qa → writing
POST	/api/sessions/{id}/rollback-to-impact	回退到影响调查（writing 阶段用户要求调整关联/不确定处）	{}	{ok: true}	writing → awaiting_impact_confirm

2.6 结果与下载

Method	Path	说明	请求体	响应	触发状态转移
GET	/api/sessions/{id}/result/preview	HTML 预览	—	{html}	只读
GET	/api/sessions/{id}/result/download	下载 docx	—	application/vnd.openxmlformats...（文件流）	只读
GET	/api/sessions/{id}/result/qa-report	下载 QA 报告	—	application/json	只读
GET	/api/sessions/{id}/result/impact-report	下载影响调查书	—	application/json	只读

2.7 规则管理

Method	Path	说明	请求体	响应	触发状态转移
GET	/api/rules/versions	规则手册版本列表	—	[{version_id, active, created_at, doc_count}]	只读
POST	/api/rules/update	触发规则手册重建	{files, categories}	{version_id | "no_change"}	不涉及会话
POST	/api/rules/rollback	回退到指定版本	{version_id}	{ok: true}	不涉及会话
GET	/api/rules/conflicts	待决策的规则冲突	?session_id=	[{conflict_id, topic, chunks}]	只读
POST	/api/rules/conflicts/{id}/resolve	冲突决策	{session_id, decision}	{ok: true}	继续该章生成

2.8 设置与状态

Method	Path	说明	请求体	响应
GET	/api/settings	获取配置（脱敏）	—	{models, vector_store, limits}
GET	/api/health	健康检查	—	{status: "ok", version}
POST	/api/sessions/{id}/cancel	取消当前任务	{task_id?}	{ok: true}
GET	/api/sessions/{id}/logs	获取会话事件日志	?event_type=	[{event_type, ...}]

---

3. WebSocket 事件通道

3.1 端点

WS /api/ws/sessions/{id}

3.2 事件类型（服务端 → 客户端）

事件	载荷	时机
status_change	{from, to, at}	状态机转移时
progress	{task_id, chapter_id?, percent?, detail}	任务进度更新
tool_call	{tool, args_summary, status, duration_ms}	工具调用（runtime §5.7）
llm_call	{model, prompt_version, status, duration_ms, input_tokens, output_tokens}	LLM 调用（runtime §6.1）
conflict_pending	{conflict_id, topic, chapter_id}	规则冲突待用户决策
qa_completed	{summary: {pass, fail, warnings}}	QA 完成
error	{code, message, options: ["retry","skip","abort"]}	任务失败（异常 UX）
done	{download_url}	全部完成

3.3 客户端 → 服务端

事件	载荷	说明
ping	—	心跳（保持连接）
request_status	—	请求当前完整状态（断线重连时同步）

---

4. 编排调用链

4.1 正常流程时序

客户端               Orchestrator                 Agent / 基础设施
  │  POST /sessions       │                              │
  │──────────────────────►│ 创建会话 → uploading          │
  │  POST /files          │                              │
  │──────────────────────►│                              │
  │  POST /start-parse    │                              │
  │──────────────────────►│ 投递解析任务 ────────────────►│ Parser
  │◄───WS progress────────│                              │
  │◄───WS status_change───│ parsing → awaiting_parse_confirm
  │  POST /confirm-parse  │                              │
  │──────────────────────►│ → impact_running             │
  │  POST /start-impact   │ 投递影响调查 ────────────────►│ Impact
  │◄───WS status_change───│ → awaiting_impact_confirm    │
  │  POST /confirm-impact │                              │
  │──────────────────────►│ → writing                    │
  │  POST /generate       │ 投递逐章任务 ────────────────►│ Writer
  │◄───WS progress(章)────│                              │
  │  POST /run-qa         │ 投递 QA 任务 ────────────────►│ QA
  │◄───WS qa_completed────│ → done（或 qa → writing 反馈）│
  │  GET /result/download │                              │
  │──────────────────────►│ 返回 docx 文件流              │

4.2 Orchestrator 职责边界

• 不做业务逻辑（解析/推理/生成/校验在各 Agent）
• 做：状态机推进、任务调度、事件收集与推送、异常路由（重试/跳过/中断）、规则版本锁定、会话持久化

4.3 进程内调用 vs 队列

默认（InMemoryQueue):
  Orchestrator 进程内 asyncio 任务池消费队列
  状态与任务结果共享内存（FastAPI 进程内）

串行生成约束（T10 文档化，对应 design.md §6.8.1 / I14）：同一会话的逐章生成 任务严格按模板章节顺序串行消费。POST /generate 投递后不并发执行多章—— 后章依赖前章 WriterState 摘要（design §6.9），并行会造成竞态。单章失败可独立 regenerate-chapter 重试，不影响其余章。

（v2 预留）RedisQueue/ValkeyQueue: Orchestrator 投递 → Redis/Valkey Stream worker 进程消费 → 执行 → 状态写回 SQLite / 事件回传 需额外部署 worker 容器（见 §6）—— v1 不实现（Scope 缩减裁定）

---

## 5. 任务队列抽象

### 5.1 接口定义

```python
class TaskQueue(ABC):
    """统一任务队列抽象（v1 仅 InMemory 实现；Redis/Valkey 为 v2 预留，Scope 缩减裁定）"""

    @abstractmethod
    def enqueue(self, task: TaskSpec) -> TaskHandle: ...
        # TaskSpec = {task_id, session_id, step, chapter_id?, payload, idempotency_key}

    @abstractmethod
    def poll(self, session_id: str) -> list[TaskHandle]: ...

    @abstractmethod
    def update_status(self, handle: TaskHandle, status: str, result: Any = None) -> None: ...
        # status: pending | running | completed | failed

    @abstractmethod
    def get(self, task_id: str) -> TaskHandle | None: ...

    @abstractmethod
    def cancel(self, task_id: str) -> bool: ...

    @abstractmethod
    def close(self) -> None: ...

5.2 实现类

实现	依赖	使用场景	说明
PersistentTaskQueue	标准库 sqlite3	开发 / 测试 / 演示（默认）	T16 任务级持久化（OV7）：状态/payload/result 落盘 SQLite；recover() 重启后 running→failed、pending 保留；实现于 src/genesis/orchestrator/task_queue.py
RedisQueue / ValkeyQueue	redis-py	v2 预留（不实现）	Scope 缩减裁定移除双实现；接口保留供 v2 扩展

5.3 幂等去重

• 任务幂等键：(session_id, step, chapter_id)（runtime §7.3）
• 重复 enqueue 同一幂等键 → 已完成直接返回缓存结果；进行中则返回原 handle
• v1 由 PersistentTaskQueue 实现（单测覆盖）

---

6. 部署拓扑

6.1 默认（单容器，InMemoryQueue）

docker-compose.yml（最小）:
  services:
    api:
      build: .
      ports: ["8000:8000"]
      env_file: .env
      volumes:
        - ./data:/data            # 用户数据 + 规则手册
        - ./config:/config        # inference.yaml / rag.yaml
      command: uvicorn app.main:app --host 0.0.0.0 --port 8000

6.2 生产（v1 单容器；Redis/Valkey worker 为 v2 预留）

docker-compose.yml（扩展）:
  services:
    api:                          # FastAPI 编排 + REST/WS
      ...
      command: uvicorn app.main:app --host 0.0.0.0 --port 8000
    # worker / queue: v2 预留（Scope 缩减裁定移除 Redis/Valkey 双实现，v1 不启用）

6.3 目录结构

/data/
├── users/{user_id}/            # 用户隔离（web-ui-design §4.3）
│   ├── uploads/
│   └── outputs/
├── shared/
│   ├── rules-handbook/          # 规则手册（RAG 层）
│   │   ├── chroma/              # Chroma 持久化
│   │   ├── manifest.json
│   │   └── v1/ v2/ ...          # 版本目录
│   └── templates/               # 公共模板
└── db/                          # SQLite（sessions/events/snapshots）

---

7. 错误码约定

错误码	HTTP	含义	用户选项	来源
FILE_TYPE_INVALID	400	文件类型不支持	更换文件	—
FILE_TOO_LARGE	400	超过 100MB 限制	压缩/分割	—
STATE_TRANSITION_INVALID	409	非法状态转移（如 uploading 直接 generate）	提示正确流程	—
LLM_TIMEOUT	502	LLM 调用超时	retry / skip / abort	exceptions.LLMTimeoutError
LLM_NETWORK_ERROR	502	网络失败/5xx 重试耗尽	retry / skip / abort	exceptions.LLMNetworkError
LLM_NOT_CONFIGURED	503	LLM Key 未配置	配置 Key	exceptions.LLMNotConfiguredError
LLM_PARSE_ERROR	502	结构化输出解析失败	retry	exceptions.LLMResponseError
EMBEDDING_FAILED	503	Embedding 服务故障（降级为 BM25）	继续（降级提示）	—
RULES_HANDBOOK_MISSING	404	规则手册不存在	上传规则文档	—
CHAPTER_NOT_FOUND	404	章节不存在	—	—
CONFLICT_PENDING	409	规则冲突待用户决策	决策后继续	—
INTERNAL_ERROR	500	未知错误	重试/联系支持	—

---

8. 与各文档的关系

文档	关系
docs/design.md §8	Web UI 页面设计；本文档为后端 API 的接口级展开
docs/agent-runtime-design.md §3	状态机与任务队列抽象；本文档定义 REST/WS 入口
docs/web-ui-design.md	前端各页面调用本文档的端点
docs/config-design.md	部署配置（env / yaml / docker-compose）