ZNJJ-api-server/docs/assignment-baseline.md

阶段交付说明：后端适配层基线（LangGraph 迁移准备）

对应迁移计划 langgraph-backend-migration-plan.md 的“开工前准备”。本阶段不改变任何对外 API 行为，只把供应商细节收敛到适配层， 为作业 1—2 引入 LangGraph 后端提供可测试的接缝。

1. 交付内容

文件	职责
src/backends/chat.py	后端中立契约：ChatBackend Protocol、ChatInput、ChatResult、流式事件 TextDelta / FormUpdate、统一异常 ChatBackend*Error
src/backends/fastgpt.py	FastGPT 适配器：调用 SDK，把响应正文、表单更新节点（更新表单）和 SDK 异常翻译为中立契约
src/core/fastgpt_client.py	AsyncChatClient 的初始化/关闭（lifespan）与依赖注入，新增 get_chat_backend()
src/api/endpoints.py	HTTP 协议层：/chat 只面向中立契约；保留 state 前缀解析、状态映射（3001/3002→1002 等）、SSE 事件序列
test/api/test_public_schema_contract.py	公共 schema 契约冻结测试（默认值、必填、长度上限、JSON 编码字符串）
test/api/test_chat_backend_boundary.py	用 fake 后端验证 API 层不依赖 FastGPT：非流式结果映射、流式 state 前缀跨 chunk 缓冲
test/backends/test_fastgpt_backend.py	FastGPT 适配器翻译测试：响应 → ChatResult、SSE 事件 → 中立事件、异常映射、SDK 调用参数

2. 调用链路

POST /chat
  └─ endpoints.chat()                      # 协议层：解析请求、解析 <state> 前缀、SSE
      └─ ChatBackend.complete() / .stream()  # 中立契约
          └─ FastGPTBackend                 # 本阶段唯一实现
              └─ AsyncChatClient (fastgpt-client SDK)

迁移时只需新增 src/backends/langgraph.py 实现同一 Protocol，并在依赖工厂中按配置 选择，协议层与公共契约保持不变（作业 2）。

3. 契约要点（冻结项）

• 请求：sessionId/timeStamp/text 必填；clientMode 缺省、空串、空白、null 均归一为 direct，允许 browser_addon；needFormUpdate/useTextChunk 默认 false。
• 非流式响应：正文需带 <state>XXXX</state> 前缀，API 解析后映射内部状态码 （3001/3002/1002→1002，2006→2004，2017→2016，2020→0002）， browser_addon 模式外部码加 browser_addon. 命名空间。
• SSE 事件名：stage_code、formUpdate、text_delta、done、error； 保证 stage_code 先于正文、成功只有一个 done、失败以 error 终止。
• get_info 的 value 始终是 JSON 编码字符串；分组读取时布尔值映射为 "1"/"0"。

4. 验证证据

Conda py3.11 环境执行（2026-02 验证，42 通过、0 失败）：

conda run -n py3.11 python -m pytest -q
# 42 passed

不需要 FastGPT 密钥即可运行全部单元测试（适配器测试使用 fake SDK）。

5. 已知限制与后续作业的对应关系

限制	处理计划
仅 FastGPT 一个后端实现	骨架已就位（作业 1—2），LangGraph 节点与适配器实现为 TODO
set_info/get_info/delete_session 仍直接读写 FastGPT 状态与历史	作业 6：应用服务 + repository，四接口共享业务状态
流式“先攒完整答案再切片”不是真实增量输出	作业 8：基于 LangGraph 流式 API 的真实增量 SSE
缺少健康检查与运行指标	作业 9
服务启动强依赖 FastGPT 配置，无法无密钥启动文本模式	作业 2：按后端开关分别校验配置

6. 提交说明

按作业规则，每次提交应附运行命令、预期结果、实际结果。本阶段：

• 运行命令：见第 4 节。
• 预期结果：全部测试通过。
• 实际结果：42 passed。
• 环境说明：fastgpt-client 以本地 editable 方式安装（pip install -e <sdk 路径>）。