diff --git a/docs/32-平台侧交接与联调准备.md b/docs/32-平台侧交接与联调准备.md index c15489b..77727c4 100644 --- a/docs/32-平台侧交接与联调准备.md +++ b/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