Merge remote-tracking branch 'origin/qyqy_develop' into nl-merge-colleague

docs/32-平台侧交接与联调准备.md

@@ -1,26 +1,30 @@
 # 平台侧交接与联调准备
 
 > **读者**：接手平台侧的人，以及联调前要确认状态的人
-> **时点**：2026-09-11
-> **一句话**：三条组员线（袁聪的场外/推广、NL 的客服画像与知识管理、投顾）已并入
+> **时点**：2026-09-11 建立，2026-09-12 更新
+> **一句话**：四条线（袁聪的场外/推广、NL 的客服画像与知识、投顾、ZSY 的客服接入）已并入
 > `qyqy_develop`，库已跟上（89 张业务表），登录与 RBAC 只读接口已补齐；
-> 等组员继续推送后按本文 §5 的清单联调。
+> **但截至 2026-09-12 14:20 仍有线在推**，功能性测试/联调按 §5 的触发条件启动。
 
 ---
 
-## 1. 当前状态（2026-09-11 实测）
+## 1. 当前状态（2026-09-12 实测，**非终态**）
+
+> ⚠️ **这不是最终快照**：`lzl_qyqy_integration` 那条线仍在持续推送 —— 本轮我推第一次时
+> 就被它抢先（远端在两次 `fetch` 之间前进了 4 个提交）。**做功能性测试前请先按 §5.0
+> 确认各线都已停止推送**，然后重跑 §5.3 的命令并把数字更新到新的交接文档里。
 
 | 项 | 值 |
 |---|---|
-| 分支 | `qyqy_develop`（本地 ahead 若干，待推送） |
-| 工作区 | 干净 |
+| 分支 | `qyqy_develop` = `c8cdc06`（与 `origin` 同步，待推送 0，工作区干净） |
 | 数据库 | **89 张业务表**，`alembic current` = head = `20260911_merge_adv_risk_heads` |
 | `ruff check app tests tools` | 干净 |
-| `mypy app` | **228 个文件 0 错** |
-| `pytest tests/unit tests/contract` | **1207 passed, 2 skipped, 0 failed** |
-| `pytest tests/integration` | **99 passed** |
-| `tools/check_authoritative_docs.py` | **40 份文档，无编号冲突** |
-| 后台进程 | 无（登录测试台已关闭，端口已释放） |
+| `mypy app` | **245 个文件 0 错** |
+| `pytest tests/unit tests/contract` | **1317 passed, 2 skipped, 0 failed** |
+| `pytest tests/integration` | **104 passed** |
+| 文档守卫 / 端点编号守卫 | 53 份文档无编号冲突；§19 **62 个端点 / 6 个号段**无重复 |
+| RBAC 号段自检 | 一致（种子 40 条权限，各 `grant_*.py` 与种子逐条一致） |
+| 后台进程 | 无 |
 
 > `mypy` 与测试数在本项目**必须带环境**读：架构师环境用
 > `D:\conda\envs\jr_py313\python.exe`，NL 那边用本机 `.venv`。此前出现过
@@ -122,6 +126,45 @@ D:\conda\envs\jr_py313\python.exe -m pytest -q
 
 ## 5. 等组员推完之后的联调清单
 
+### 5.0 触发条件：先确认"没人还在推"
+
+**判据**：下面这段输出**为空**，才算各线都合完了。都搞完之前不要开始功能性测试 ——
+否则测的是一个还会变的树，结论没有意义。
+
+```powershell
+git fetch --all --prune
+foreach ($b in (git branch -r --format='%(refname:short)' | Where-Object { $_ -notmatch 'HEAD' })) {
+  $n = git rev-list --count "origin/qyqy_develop..$b" 2>$null
+  if ($n -gt 0) { "$b 独有 $n 个提交未合" }
+}
+```
+
+> 2026-09-12 的实测：`NL_develop` 曾独有 16 个（已合）、`lzl_qyqy_integration` 正在持续推送。
+> 注意**别把"落后很多的老分支"当成待合分支**（如 `lzl_develop` 落后 206 个提交，
+> 它的产出走的是新建的 `lzl_qyqy_integration`），但也**别反过来把活跃分支当废弃分支**——
+> 先看它的最新提交时间。
+
+### 5.1 外部依赖前置（不满足会产生**假失败**，别当代码缺陷）
+
+| 依赖 | 检查方式 | 不满足的后果 |
+|---|---|---|
+| **MySQL + RBAC 种子** | `python tools/seed_test_rbac.py` → `python tools/set_user_password.py` | **不跑这两步，`tests/integration` 会有 13 个登录/RBAC 用例因 401 而红**。口令脚本**非幂等**（重复执行等于重设密码） |
+| Docker Desktop（Milvus） | `docker ps` 能连上 | 检索、知识链路不可用；`tools/setup_milvus_profile_collection.py` 建不了集合 |
+| Redis | 健康检查 | 登录限流、客服短期会话记忆链路不可用 |
+| Neo4j | `127.0.0.1:7687` 可连 | 关系/图投影链路不可用 |
+| SMTP / IMAP | `.env` 里的开关 | 场外通知与邮件识别只能走离线数据集 |
+
+### 5.2 已知的"看起来像缺陷但不是"
+
+- `tests/unit/service/test_offsite_document_recognition_adapter.py` 有 2 个用例被记为**环境相关失败**
+  （断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，字节序列自然不匹配）。
+  **主干的架构师环境复现不了**（2026-09-12 全量为 0 failed）。不要为了"让它绿"去动实现；
+  若要修，正确做法是断言 `json.loads(body)` 后的字段值 —— 字节级断言不该用来测 JSON。
+- `mypy app` 的数字**先对版本再对代码**：SQLAlchemy 补丁版不同会差出上百个错，
+  复现矩阵见 `AGENTS.md` 的"环境与命令口径"一节。
+
+### 5.3 合并与验证命令
+
 ```powershell
 git fetch origin --prune