Start LangGraph backend migration foundation

docs/baselines/fastgpt-baseline-20260726.md

@@ -0,0 +1,101 @@
+# FastGPT 迁移前基线
+
+> 采集日期：2026-07-26
+> Git 基线：`5c719ed`
+> 环境：本地 macOS，项目 `.venv`，FakeBackend/FakeClient；未调用真实 FastGPT
+> 用途：冻结可复现工程基线，不冒充生产业务指标
+
+## 自动化基线
+
+执行：
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Phase 0 开始前结果：
+
+```text
+32 passed in 0.32s
+```
+
+覆盖范围：
+
+- Pydantic 公共请求/响应 schema；
+- `/chat` 对 backend-neutral contract 的适配；
+- FastGPT backend 的 SDK/Event 转换；
+- state prefix 跨 chunk 的基础兼容；
+- 文本分句。
+
+未覆盖范围：
+
+- 真实 FastGPT 网络延迟和错误；
+- 真实 workflow 状态序列稳定性；
+- `/set_info`、`/get_info` 完整兼容行为；
+- 生产转人工比例和 prefix 失败率；
+- 数据库、并发恢复和 LangGraph。
+
+Phase 0 完成后的测试数量和耗时见本报告底部。
+
+## 本地 API 适配层耗时
+
+使用内存 FakeBackend，关闭日志后直接调用 endpoint 并完整消费流式响应。该数据只衡量 Python 适配、prefix/SSE 处理开销，不包含 HTTP、网络、FastGPT 或模型延迟。
+
+```text
+nonstream n=2000 p50=0.004ms p95=0.014ms p99=0.030ms
+stream-consume n=1000 p50=0.011ms p95=0.034ms p99=0.051ms
+```
+
+这组数据用于后续发现 API 适配层的明显性能回退，不能与生产端到端延迟混用。
+
+## 生产指标采集口径
+
+以下数据无法从仓库推导，必须由部署环境日志或监控采集。负责人应使用同一时间窗口、同一调用方集合，并排除压测流量。
+
+| 指标 | 计算方式 | 当前值 |
+|---|---|---|
+| `/chat` 请求数 | 成功与失败总请求 | 待生产采集 |
+| 非流式 P50/P95/P99 | endpoint 总耗时 | 待生产采集 |
+| 流式 TTFB P50/P95/P99 | 收到请求至首个 `text_delta` | 待生产采集 |
+| 响应体错误率 | `code != "200"` / 请求数 | 待生产采集 |
+| FastGPT 超时率 | timeout / FastGPT 调用数 | 待生产采集 |
+| Prefix 失败率 | 缺失、格式错误、未知码 / 模型回复数 | 当前未结构化记录 |
+| 转人工率 | `0001/0002/0003/0004/0005` / session 数 | 待生产采集 |
+| `formUpdate` 产生率 | 非空 patch / `needFormUpdate=true` 轮次 | 待生产采集 |
+| 平均轮次 | chat 轮次 / 完结 session 数 | 待生产采集 |
+| `/set_info`、`/get_info` 错误率 | `code != "200"` / 请求数 | 待生产采集 |
+
+## 当前可观测性限制
+
+当前日志虽然记录延迟，但也记录完整 `sessionId`、输入、输出和 `formUpdate`，不能直接作为长期生产基线方案。Phase 1/8 应先加入 request ID、session hash、结构化事件和脱敏，然后再持续采集。
+
+建议临时聚合时只输出：
+
+- 时间桶；
+- endpoint；
+- 成功/稳定错误类别；
+- 耗时；
+- stage code；
+- 是否产生 form patch；
+- 不可逆 session hash。
+
+不得导出原始对话、身份证、手机号、车牌、Token 或完整表单。
+
+## Phase 0 最终验证
+
+完成日期：2026-07-26
+
+```text
+48 passed in 0.49s
+```
+
+相对 Phase 0 开始前新增 16 个测试，覆盖：
+
+- `/set_info`、`/get_info` 的 FastGPT 辅助调用和兼容序列化；
+- SSE 成功事件顺序、唯一终止事件和文本拼接；
+- 当前缺失流式 prefix 的历史行为；
+- 状态/迁移/字段注册表闭合性；
+- 黄金场景唯一性和敏感号码扫描；
+- 源码、文档、测试和配置样例中的 FastGPT Token 扫描。
+
+生产业务指标仍标记为“待生产采集”。这是外部可观测数据依赖，不用估算值替代；最迟必须在 Phase 9 shadow 前完成采集。