张胜宇
c5adf01603
补两道守卫，覆盖 2026-09-12 那次合并评审暴露出来的两个盲区。 一、`docs/05` §19 端点编号唯一性（新增 `tools/check_docs_endpoint_ids.py`） - 背景：`tools/check_authoritative_docs.py` 只校验 `docs/` 的**文件名编号**，不校验 §19 的**端点编号**。两条线各自新增端点时都占了 `A034`/`A035`，合并后 §19 同时 存在两个 `A034` 与两个 `A035`，而文档守卫照样通过 —— 编号复用会静默遗留。 - 口径要点：**不枚举前缀白名单**，前缀从数据里归纳后连同数量一起输出。同一件事上 还踩过一次"扫描正则写成 `[AMKCS]`，漏掉 `O`/`R` 两段，把 62 个端点报成 55 个"—— 漏掉的号段一旦被复用，脚本仍会报"重复 0"。所以覆盖报告会打印 `62 个端点编号 / 6 个号段（A×40、C×7、K×4、M×4、O×3、R×4）`，让漏扫本身可见。 - 只读、不依赖任何环境变量（纯解析文档），可在裸检出环境直接跑。 二、端点权限判定的 HTTP 层用例（新增 `tests/unit/api/test_permission_enforcement.py`） - 背景：既有用例都通过 `build_request_context` 覆写注入**已经带好权限**的上下文， 只覆盖"有权限能通"，覆盖不到"缺权限必须被拒"。而"权限码在库里根本不存在"这类 环境数据问题（本次三个新权限码）恰恰只会在这一层暴露：权限判定发生在身份解析之后， 服务层测试自己构造 `RequestContext`，权限字段由测试塞入，所以全绿也照样漏。 - 覆盖客服二期三个权限码对应的 5 个端点： `handover:read`（工单列表/详情）、`memory:candidate:review`（候选列表/审核）、 `memory:candidate:confirm`（用户确认）。 - 正反双向断言：缺权限 → 必须 403 且错误码为 `AGENT_PERMISSION_DENIED`； 带权限 → **不能**再是 403（这一条把端点要求的权限码钉住，改动即红）。 - 只替换两处边界：`build_request_context`（跳过 JWT 与身份库）与 `AuthorizationService` 的审计落库（内存替身）；真实路由、真实权限判定与真实 403 信封。 - 已做反向验证：给一个不存在的权限码时，5 个端点全部被拒（403），确认正向断言非空过。 验证（隔离 worktree，基线 `origin/qyqy_develop` = 4d8edb4）： pytest tests/unit tests/contract -> 1294 passed, 2 skipped, 0 failed； ruff check app tests tools alembic 全通过；mypy app 244 源文件 0 错； check_authoritative_docs（50 份文档无撞号）与本脚本均通过。