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

> 对应迁移计划 [langgraph-backend-migration-plan.md](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. 调用链路

```text
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 失败）：

```bash
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 路径>`）。