优化

docs/头程项目目录结构与服务说明.md

@@ -223,7 +223,7 @@ deploy/
 推荐顺序：
 
 1. 外部基础设施：MySQL、Redis、Nacos；启用公共导出时再准备 RocketMQ。
-2. 核心认证：IAM、Auth。
+2. 核心认证：Auth、IAM。
 3. 主数据与适配：Warehouse、Integration。
 4. 业务依赖：Order、File。
 5. 核心编排与支撑：Firstleg、Print、Audit、Event Bridge。
@@ -231,6 +231,32 @@ deploy/
 
 Nacos 服务发现允许部分服务交换顺序，但联调时按上述顺序更容易判断故障来源。
 
+### Auth/IAM RBAC 会话撤销发布验证
+
+角色启停或角色权限全量变更会由 IAM 调用 Auth 的
+`POST /internal/auth/accounts/sessions/revoke`，批量撤销受影响成员的 Access/Refresh 会话。
+该契约发布时必须先部署 Auth，再部署 IAM，不得只更新 IAM。
+
+发布后至少完成以下验证：
+
+1. 确认 Auth、IAM 使用同一提交对应的镜像版本，且 IAM 能通过服务发现和内部服务令牌访问上述 Auth 内部接口；404、连接失败、内部令牌不一致或非成功业务码均不得放行 IAM 角色变更。
+2. 为测试成员分配带订单查看权限的自定义角色，成员登录并确认订单列表可访问。
+3. 停用该角色必须返回业务成功；继续使用停用前的 Access Token 访问订单列表必须被拒绝，旧 Refresh Token 也必须失效。
+4. 成员重新登录后权限集合应为空；重新启用角色并再次登录后，原角色权限应恢复。
+5. 修改角色权限集合后重复验证旧 Access/Refresh Token 失效，避免 `grantPermissions` 路径遗留旧权限。
+
+2026-08-08 测试环境曾出现版本不一致：停用已分配角色返回 HTTP 200、业务码 `S0503`，
+提示“认证会话撤销失败，角色变更未生效”。证据报告为
+`reports/client-test-env-20260808021636-b5090589.json`，`requestId=client-e2e-d9e860c8-b061-43fd-b67b-196f76d95b3d`，
+`traceId=f2812578869349b1b4393421498d05df`。该结果说明 IAM 已包含会话撤销调用，但 Auth
+内部接口尚未部署或不可达；必须在 Auth 先行部署并通过连通性检查后重新执行上述验收。
+
+本轮 Client 扩展测试的发布前最终基准为
+`reports/client-test-env-20260808022313-1798dc6c.json`：共 150 项，143 通过、5 失败、2 跳过。
+5 个阻断项分别为角色停用和角色权限收缩时 Auth/IAM 版本不一致导致 `S0503`、清空成员角色未撤销旧 JWT、
+缺少 `Idempotency-Key` 返回 `S0500`、跨客户资质文件读取返回 `B0001`。订单条件必填 `A0422`、
+已提交订单编辑 `A0409`、密码恢复和报告脱敏均已通过。后续发布验证应以该报告为对照，确认上述 5 项全部关闭。
+
 ## 9. 开发和拆分约束
 
 - 每个业务服务只访问自己的数据库；禁止跨库 Join 和直接读取其他服务表。