From 4c00db5636313df33d2a71b48ef78fbafa2b967c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Sat, 12 Sep 2026 14:57:56 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20docs/32=20=E5=B7=A5=E5=85=B7=E7=B4=A2?=
 =?UTF-8?q?=E5=BC=95=E8=A1=A5=E4=B8=8A=E5=8A=9F=E8=83=BD=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E5=8F=B0=E4=B8=8E=E4=B8=A4=E4=B8=AA=E6=96=B0=E5=AE=88=E5=8D=AB?=
 =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E6=AD=A3=E5=B7=B2=E8=BF=87=E6=9C=9F=E7=9A=84?=
 =?UTF-8?q?=E6=9D=83=E9=99=90=E5=8F=B7=E6=AE=B5=E5=8F=A3=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/32-平台侧交接与联调准备.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/docs/32-平台侧交接与联调准备.md b/docs/32-平台侧交接与联调准备.md
index 77727c4..176694e 100644
--- a/docs/32-平台侧交接与联调准备.md
+++ b/docs/32-平台侧交接与联调准备.md
@@ -109,18 +109,26 @@ D:\conda\envs\jr_py313\python.exe -m pytest -q
 |---|---|
 | `tools/set_user_password.py` | 设置/查看登录密码（`--list` 只读） |
 | `tools/create_test_user.py` | 建可登录的测试账号（用户+角色+密码），并**验证权限能解析出来** |
-| `tools/grant_advisor_role.py` | 建 `advisor` 角色与 16 个权限（只增不删，带 `--dry-run`） |
+| `tools/grant_advisor_role.py` | 建 `advisor` 角色 + 补种子里缺的 3 个治理类权限并绑定（只增不删，带 `--dry-run`） |
+| `tools/grant_customer_service_phase2_permissions.py` | 补客服二期的 3 个权限并授权（幂等；这 3 个已并进种子，脚本只作局部补齐） |
 | `tools/publish_profile_tool_whitelist.py` | 补发客服白名单（画像工具），继承全部受管表 |
 | `tools/login_console.py` | 浏览器登录测试台（`http://127.0.0.1:8099`） |
+| **`tools/api_console.py`** | **平台功能测试台**（`http://127.0.0.1:8100`）：自动覆盖 `docs/05` §19 全部 62 个端点、用平台 OpenAPI 补齐参数与请求体模板、四个演示账号一键切换身份，并提供**一键只读冒烟**（30 个 GET，**只有 5xx 算缺陷**）。还会列出「OpenAPI 有、§19 未登记」的接口 —— 首次运行查出 **67 个未登记** |
 | `tools/seed_advisor_demo.py` | 投顾演示数据（产品目录+测评+归属），并报告方案那步卡在哪 |
 | `tools/probe_release_state.py` | 只读：生效配置版本与 `agent_tools` 明细 |
 | `tools/probe_auth_state.py` | 只读：`sys_user` 的密码状态（只出前缀与长度，不出完整哈希） |
 | `tools/probe_knowledge_collections.py` | 只读：Milvus 集合 schema 与行数 |
+| `tools/check_rbac_seed_consistency.py` | 只读：权限号段一致性（种子 vs 各 `grant_*.py`），**已纳入门禁** |
+| `tools/check_docs_endpoint_ids.py` | 只读：`docs/05` §19 端点编号唯一性 + 号段覆盖自检，**已纳入门禁** |
 
-> `tools/seed_test_rbac.py` 是 **DELETE 重建**语义，它的
-> `DELETE FROM sys_permission WHERE id BETWEEN 9001 AND 9099` 会**清掉
-> `grant_advisor_role.py` 建的投顾权限**。要在种子里固化投顾权限，请并进它的
-> `PERMISSIONS` 常量，而不是两个脚本各建一套。
+> ⚠️ **RBAC 权限码的定义源是 `tools/seed_test_rbac.py` 的 `PERMISSIONS`**（9001-9046 号段）。
+> 那个脚本对权限/角色/绑定是 **DELETE 重建**（`DELETE FROM sys_permission WHERE id BETWEEN
+> 9001 AND 9099`，且只清 `role_id 9001-9003` 的角色绑定），**没并进它的权限码重建一次就没了**，
+> 表现是"接口突然 403"而没有任何报错线索。投顾的 13 个业务权限、治理类 3 个、客服二期 3 个
+> **都已并进种子**；`grant_*.py` 只补种子里缺的，且 id 必须与种子逐条一致 —— 一致性由
+> `python tools/check_rbac_seed_consistency.py` 及其单测守着（2026-09-12 出过一次
+> "两套 id→code 映射并存、`advisor` 静默拿到语义错误权限"的事故）。
+> 另：种子对 `sys_user` 已是「存在则更新、不存在才插入」且**不覆盖密码**，所以重跑种子不会再弄丢演示口令。
 
 ---