feat: 静态代码审计,修复逻辑bug和安全漏洞

audit-report.md

@@ -1,242 +1,183 @@
-# 权限管理系统 —— 深度代码审计报告（第 8 轮）
+# 权限管理系统 —— 深度代码审计报告（第 9 轮）
 
 > **审计范围**：`/internal` 下全部非测试、非 `_gen.go` 生产代码（含 `internal/server/permserver.go`、HTTP logic / handler / middleware、loaders、model 定制层、svc、util、consts）。
 > **审计时间**：2026-04-19
 > **审计维度**：逻辑一致性 / 并发与 RMW / 资源管理 / 数据完整性 / 安全漏洞 / 边界坍塌 / DB 性能 / 僵尸代码 / 接口契约与对象完整性。
-> **与第 7 轮对比**：
->   - **已落地（本轮不再复列）**：H-1 `loadPerms` deny fail-open、H-3 `AddMember` 目标侧授权、H-4 JWT HMAC 断言、M-1 `Load` 半成品缓存污染、M-2 `UpdatePassword`/`UpdateStatus` 未校验 `RowsAffected`、M-4 `CreateProduct` 明文密码（切成一次性 `credentialsTicket`）、M-7 gRPC 限流剥端口、L-1 `DeleteDept` 锁序列、L-2 `IncrementTokenVersion` WARN 注释、L-3 `loadPerms` 其余分支 fail-close、L-4 SQL `status = ?` 参数化（`sysUserRole` / `sysUserPerm` / `sysRole` 三处）、L-5 `FindMapByProductCodeUserIds` / `FindMapByProductCode` 非事务版移除、L-6 gRPC 负缓存预污染（TTL=10s + 预写前强一致 `FindOne`）。
->   - **未落地 / 回归**：**H-2 PII 暴露**（第 6~7 轮持续未修），**M-3 残留分支**（`GuardRoleLevelAssignable` 已走 fresh read，但 `CheckManageAccess → checkPermLevel` 仍读缓存 `caller.MinPermsLevel`，降级 admin 的 TOCTOU 窗口只封了"分配角色"一个出口），L-5 `CountActiveAdminsTx` 零调用，L-7 历史账号 `DeptId=0` 兜底。
->   - **新发现**：M-N1 `CreateProduct → Redis 票据写入失败` 导致**产品/管理员孤儿化**；M-N2 `checkPermLevel` 读缓存 `MinPermsLevel` 的 TOCTOU 口子（M-3 未闭合的另一半）；M-N3 `SyncPermsError{Code:404}` 在 gRPC 映射里被同化成 `codes.Internal`；L-N1 `sysPermModel` 仍用 `fmt.Sprintf("... status = %d", consts.StatusEnabled)`，与 L-4 修复风格不一致；L-N2 `SetUserPerms` `FindByIds` 校验与 `BatchInsert` 之间的 TOCTOU（影响面轻，列入存档）。
+> **与第 8 轮对比**：
+>   - **已落地（本轮复核通过，不再复列修复细节）**：
+>     - **H-2**（第 8 轮）`checkPermLevel` 读缓存 `MinPermsLevel` 的 TOCTOU —— `internal/logic/auth/access.go:302-347` 现统一调用 `loadFreshMinPermsLevel` 走 DB 复核，`sqlx.ErrNotFound` 降级为"0 roles"、其他 DB 错误向上冒出。
+>     - **M-3**（第 7~8 轮）RefreshToken CAS 在签发失败后脏升级 `tokenVersion` —— `internal/logic/pub/refreshTokenLogic.go:90-110` 与 `internal/server/permserver.go:215-230` 均已把 `Generate*Token` 前置到 `IncrementTokenVersionIfMatch` 之前，CAS 只在两份 token 都成功生成后执行。
+>     - **M-N1**（第 8 轮）CreateProduct Redis 票据写失败孤儿化 —— `internal/logic/product/createProductLogic.go:178-283` 已落地 `compensateCreatedRows`：ticket Setex 任一步失败都会按 admin / member / product 倒序硬删，并附 WARN 日志便于对账。
+>     - **M-N3**（第 8 轮）gRPC `SyncPermsError{Code:404}` 被吞成 `codes.Internal` —— `internal/server/permserver.go:61-90` 已加 `errors.As` 显式映射到 `codes.NotFound`，并保留具体错误文案。
+>     - **L-2**（第 7~8 轮）`CountActiveAdminsTx` 僵尸方法 —— `internal/model/productmember/sysProductMemberModel.go` 中仅保留 `CountOtherActiveAdminsTx`，接口与实现两端均已删除旧签名。
+>     - **L-N1**（第 8 轮）`sysPermModel` 仍拼接 `fmt.Sprintf("... status = %d", ...)` —— 现统一用 `?` 占位（`FindAllCodesByProductCode:57-67`、`DisableNotInCodesWithTx:100-154`）。
+>     - **L-N2**（第 8 轮）`SetUserPerms` 的 `FindByIds` → `BatchInsert` TOCTOU —— `internal/logic/user/setUserPermsLogic.go:148-165` 已在事务内对目标权限集做 `COUNT(*) WHERE status=?` 复核，并要求计数等于入参长度，否则 rollback。
+>   - **产品契约接受、不列入风险清单**：
+>     - **H-1 同产品成员 PII 互见**（第 6 → 7 → 8 轮累计列入 P0）—— 产品确认"内部系统 + 通讯录互见"为业务契约，不修。该条从本轮起归档，不再进入后续审计复核列表。
+>   - **未落地 / 回归**：
+>     - **L-3 历史 `DeptId=0` 账号的 `CheckManageAccess` 兜底**（需数据迁移，不属纯代码问题，延续存档）。
+>   - **本轮新发现（权重较高的 5 条）**：
+>     - **M-N1（新）`userDetailsLoader.Load` 的 `loadOk=false` 契约错位** —— 基础设施故障被同化为业务 403 / "产品已禁用"，前端侧不重试且 SOC 无故障信号。
+>     - **M-N2（新）`BatchDel` 中 `unregisterCacheKey` 走串行 N×2 次 SREM** —— 绑/解绑/改角色链路退化为 O(N) Redis RTT，属 N+1。
+>     - **M-N3（新）`RoleDetail` 枚举 oracle** —— 跨产品访问 403 vs 404 可区分，可用于穷举合法 roleId。
+>     - **M-N4（新）`CreateUser` 未做 caller→`req.DeptId` 的部门链校验** —— 产品 ADMIN 可为**非自己管辖的部门**预埋用户名并占坑，绕过 AddMember 侧部门链防护。
+>     - **L-N1（新）`ParseWithHMAC` helper 未统一使用** —— `jwtauthMiddleware.go`、gRPC `VerifyToken` 仍用内联 `token.Method.(*jwt.SigningMethodHMAC)` 断言，三处拷贝导致审计面错位。
+>   - **本轮复现的低风险残点**：L-N2 `UpdateUser` 调部门未校验 `dept.Status`；L-N3 `AdminLogin` `IsSuperAdmin` 判断在 bcrypt 之后；L-N4 `sysUserModel.UpdateStatus` 缺乐观锁字段（由上层短路保护）。
 
 ---
 
 ## 🚩 核心逻辑漏洞 (High Risk)
 
-### H-1. `UserDetailLogic` / `UserListLogic` 仍把 `Email` / `Phone` / `Remark` 暴露给**任意同产品成员**（第 6 轮 M-3、第 7 轮 H-2，三轮未落地）
-- **位置**：
-  - `internal/logic/user/userDetailLogic.go:64-76`（`types.UserItem` 构造）
-  - `internal/logic/user/userListLogic.go:77-89`
-- **描述**：两接口的访问控制仍然只到"同产品即可看全字段"的粒度：
-  - `UserDetail` 只用 `FindOneByProductCodeUserId` 核对 caller 与 target 是否在同一产品，之后直接塞 `Email / Phone / Remark`（纯文本，无脱敏）。
-  - `UserList` 分页返回同产品所有成员，每条也原样带上 `Email / Phone / Remark`。一次分页可以把整个产品通讯录灌下来。
-- **影响**：
-  - **同产品最低权限 MEMBER 即可遍历整个产品通讯录**，获取手机 / 邮箱 / 备注（备注里常常会有内部身份、外部联络人、岗位说明等 PII）。
-  - 叠加风险：
-    - 即便 H-3（第 7 轮，已修）已关掉了"ADMIN 跨部门 AddMember"的入口，现有 ADMIN 仍可通过 `UserList` 一次拿走本产品全员通讯录；
-    - 对于拿到一次性有效 JWT 的外包 / 服务账号，本接口天然就是拖库点。
-  - 违反《个人信息保护法》第 6 / 13 条的最小必要原则与《数据安全法》下的分级保护要求。
-- **修复方案**（与前两轮报告一致，代码未落）：
-  1. 在 `internal/logic/auth/access.go` 新增：
-     ```go
-     // CanViewContact 判定 caller 是否可以看 target 的联系信息字段。
-     //   - caller 是 SuperAdmin → true
-     //   - caller.UserId == target.Id（看自己） → true
-     //   - CheckManageAccess(caller, target) 通过（caller 在 target 的管理链上） → true
-     //   - 其余情况一律 false，由 filterPIIForCaller 落地脱敏。
-     func CanViewContact(ctx context.Context, svcCtx *svc.ServiceContext, caller *loaders.UserDetails, target *userModel.SysUser, productCode string) bool
-     ```
-  2. 新增 `authHelper.MaskEmail` / `MaskPhone`（`138****1234` / `a***@b.com`），在 Logic 构造 DTO 前调用 `filterPIIForCaller(caller, target, &item)` 统一覆盖 `Email / Phone / Remark` 三字段。
-  3. 单测覆盖四种身份组合：同产品同级 MEMBER 互看、跨部门互看、ADMIN 看下级、看自己。
-- **为什么必须本轮解决**：前两轮已经连续标记为 P0 且提出了完整方案，在 H-3（AddMember）修完之后这条变成"剩下最大的单点 PII 出口"，攻击面大、修复工作量小（一个 helper + 两个 Logic 返回前的 hook）。
-
-### H-2. `CheckManageAccess → checkPermLevel` 仍靠 caller 的**缓存 `MinPermsLevel`** 决策，降级 admin 在 5 分钟 TTL 内仍可管辖原本够不到的目标（M-3 只封了一半）
-- **位置**：
-  - `internal/logic/auth/access.go:279-316`（`checkPermLevel`）
-  - 受影响调用方：`internal/logic/member/updateMemberLogic.go`、`internal/logic/member/removeMemberLogic.go`、`internal/logic/user/updateUserLogic.go`、`internal/logic/user/updateUserStatusLogic.go`、`internal/logic/user/setUserPermsLogic.go`
-- **描述**：第 7 轮对 `GuardRoleLevelAssignable` 的修复方式是"在做 role 分配决策前 `FindMinPermsLevelByUserIdAndProductCode` 走一次 NoCache 查 DB"。但**同样类型的 TOCTOU 问题**在更一般的 `CheckManageAccess` 里没修：
-  ```go
-  // access.go:312
-  if caller.MinPermsLevel >= targetLevel {
-      return response.ErrForbidden("无权管理权限级别高于或等于您的用户")
-  }
-  ```
-  这里 `caller` 来自 `middleware.GetUserDetails(ctx)`，也就是 `UserDetailsLoader.Load` 缓存的那份；TTL 5 分钟。
-  攻击路径：
-  1. T=0：超管把 caller C 从 `MinPermsLevel=10`（总监级）降到 `20`（经理级）。超管调用业务接口时会触发 `UserDetailsLoader.Clean(C.UserId)`，但 Redis 抖动 / 集群主从切换期间，`Clean` 单次失败只会被 `logx.Errorf`，没有重试、没有降级旁路。
-  2. T=0+δ：C 在另一终端调 `RemoveMember` / `UpdateMember` / `UpdateUser` / `UpdateUserStatus` / `SetUserPerms` 去管理一个 `MinPermsLevel=15` 的目标 D。
-  3. `checkPermLevel` 读到 C 的缓存 `MinPermsLevel=10`，判定 `10 >= 15` 为 false → 放行。C 的**实际**级别 20，`20 >= 15` 为 true，本应被拦。
-  4. C 有整整 5 分钟时间把下属统一踢人、改 MemberType、覆盖 UserPerms、冻结状态 —— 审计日志里看起来是合法操作。
-- **与 M-3 修复的对照**：`GuardRoleLevelAssignable` 修的是"C 用旧身份去授角色给别人"的路径；`checkPermLevel` 漏的是"C 用旧身份去直接动别人"的路径。两条路径一个在**出**一个在**改**，安全边界对称才叫完整。
-- **影响**：与 M-3 同一量级，但触达面更广（5 个 Logic 都走 `CheckManageAccess`），且 `RemoveMember` / `UpdateUserStatus` 可以直接产生**不可逆的破坏性操作**（把管理员从产品踢出、冻结账号）。
-- **修复方案**：
-  1. `checkPermLevel` 对 caller.MinPermsLevel 采用与 `GuardRoleLevelAssignable` 一致的策略：
-     ```go
-     freshCallerLevel, err := svcCtx.SysRoleModel.FindMinPermsLevelByUserIdAndProductCode(ctx, caller.UserId, productCode)
-     if err != nil {
-         if errors.Is(err, sqlx.ErrNotFound) {
-             // caller 当前已无产品角色 → 等同最低等级，对同级管辖一律拒绝
-             return response.ErrForbidden("无权管理权限级别高于或等于您的用户")
-         }
-         return response.NewCodeError(500, "校验权限级别失败，请稍后重试")
-     }
-     if freshCallerLevel >= targetLevel {
-         return response.ErrForbidden("无权管理权限级别高于或等于您的用户")
-     }
-     ```
-  2. 抽一个共享 helper `loadFreshMinPermsLevel(ctx, svcCtx, userId, productCode) (int64, error)`，`GuardRoleLevelAssignable` 和 `checkPermLevel` 统一调用；同时顺手把两处的 `ErrNotFound` 语义文档化。
-  3. 长期建议（可选）：给 `UserDetailsLoader` 加一个 `LoadFresh(ctx, userId, productCode)` 接口，授权决策点强制 bypass 缓存；普通业务依然走缓存。
+**本轮无 High Risk 项。**
+- 第 8 轮列示的 H-2（`checkPermLevel` TOCTOU）已通过 `loadFreshMinPermsLevel` 闭环，见上方"已落地"小节。
+- 第 6~8 轮列示的 H-1（同产品 PII 互见）经产品确认为系统对内使用场景下的既定契约，自本轮起归档、不再纳入审计清单。
+- 其余安全类待办均已降级至 Medium / Low，见下节。
 
 ---
 
 ## ⚠️ 健壮性与性能建议 (Medium / Low)
 
-### M-1. `CreateProduct` 事务已提交后，Redis 票据写入失败会把产品 + admin 用户**永久孤儿化**（第 7 轮 M-4 修复方案遗留的新缺陷）
-- **位置**：`internal/logic/product/createProductLogic.go:109-185`
-- **描述**：第 7 轮把 M-4（响应体明文密码）改成了"DB 事务提交 → 暂存 Redis → 响应 ticket"三段流水线。但流水线的失败语义没有做补偿：
-  1. L109-149：`SysProductModel.TransactCtx` 里同时 INSERT `sys_product` / `sys_user`（admin 账号）/ `sys_product_member`。成功后 `productId` 已经持久化。
-  2. L162-169：`generateRandomHex(32)` 生成 ticket —— 理论上 `crypto/rand.Read` 出错概率 ≈ 0，但已不在事务内。
-  3. L176-180：`json.Marshal(&payload)` —— 对固定结构体几乎不会失败，但落出错分支同样只返回 500。
-  4. L181-184：`Redis.SetexCtx(ticketKey, …)` —— **这里才是真实风险面**。Redis 短暂不可用 / 超时 / 集群 failover 都会让 Setex 返 err。
-  落到任一 fail 分支时：
-  - `sys_product` 里新建的产品记录已经落盘；
-  - `admin_<code>` 账号已经落盘，bcrypt 密码是**我们刚刚在内存里生成、随 500 响应丢弃**的那串随机 12 字节；
-  - 没有任何方式可以拿回这个密码：
-    - 仓库里没有 `DeleteProductLogic`（只有 `CreateProduct` / `UpdateProduct` / `ProductList` / `ProductDetail`）；
-    - 仓库里没有 "SuperAdmin Reset Password" 类型的接口，只有 `ChangePasswordLogic`，且它要求 `oldPassword` 校验通过；
-    - `CreateProduct` 再试一次会命中 `product.Code` / `admin_<code>` 的 `FindOneByCode` / `FindOneByUsername` 前置判定，直接 `ErrConflict`。
-  运维只能下场直接 SQL：要么跑一次 `UPDATE sys_user SET password = ? WHERE username = ?` 硬改 admin 密码，要么 `DELETE` 三张表对应数据。**这两种手法都绕过了业务不变式和审计日志。**
-- **影响**：数据完整性问题。概率虽低（依赖 Redis 单次失败 & 在一次创建流程内），但一旦发生是**永久性**的（孤儿产品不会自愈），且需要手工改库，违反最小事故介入原则。
-- **修复方案**（按代价从低到高）：
-  1. **最小成本**：`Redis.SetexCtx` 失败时，在同一 handler 内做补偿 DB 事务——删除刚才创建的 `sys_product` / `sys_user` / `sys_product_member`，回到"从未创建"状态再返 500。为防止补偿事务自己也失败，至少要把 `productId` / `adminUserId` 落一条 `logx.Errorw("createProduct compensation required", ...)` 带有 ERROR 等级 + 结构化字段，方便告警侧接管人工回捞。
-  2. **更稳**：新增 `SuperAdmin` 专用接口 `RegenerateInitialCredentials(productCode)` —— 找到 `admin_<code>`，重新生成随机密码、bcrypt 后写 DB，再走一次 `SetexCtx` + 返回新的 `credentialsTicket`；与 `ChangePassword` 解耦，有独立审计日志字段 `audit=regenerate_init_cred`。
-  3. **一步到位**：引入 outbox / 2PC 风格 —— DB 事务 + `sys_outbox` 行同时写；单独 worker 消费 outbox，驱动 Redis 写入；对调用方接口异步化（响应体先给 `ticketId`，轮询拉真值）。落地成本高，按本仓规模不建议。
-- **锁死建议**：无论采纳 (1) 还是 (2)，在上线前至少要补齐：`CreateProduct` 集成测试中把 `Redis.Setex` 做成主动注错路径，断言 "产品不存在 / admin 用户不存在（方案 1）" 或 "可以通过 Regenerate 拿回凭证（方案 2）"，防止未来重构又漏掉这一路径。
-
-### M-2. `SyncPermsError{Code: 404}` 在 gRPC 映射里被同化成 `codes.Internal`，接口契约泄露 DB 语义
-- **位置**：
-  - `internal/logic/pub/syncPermsService.go:75-79`（事务内 `LockByCodeTx` 返 `ErrNotFound` → `SyncPermsError{Code: 404}`）
-  - `internal/server/permserver.go:67-83`（gRPC 层映射）
-- **描述**：gRPC handler 的 `switch se.Code` 只列了 400 / 401 / 403 / 409，其余（含 404 / 500 / 任何异常值）一律落 `default → codes.Internal`。于是：
-  1. 前置 `FindOneByAppKey` 已经能 hit 到一条 `sys_product`，但事务内 `LockByCodeTx` 又 `ErrNotFound`（极罕见：并发 "DeleteProduct" —— 虽然目前没有 Delete 入口，但一旦加上就中招）；
-  2. 调用方（产品接入方的服务端）拿到 `codes.Internal` + 消息 "产品不存在"，但 SDK 侧的重试策略一般对 `Internal` 是 "not retriable" —— 调用方会直接当作永久错误上报，而我们实际希望它是 `codes.NotFound` 让其按 404 处理。
-- **影响**：契约级一致性缺陷。目前无直接安全风险，但一旦未来引入 DeleteProduct / ProductCode 重命名逻辑，会给接入方的调用栈制造误导性错误分类（Internal 会 page 值班，NotFound 不会）。
-- **修复方案**：
-  ```go
-  case 404:
-      return nil, status.Error(codes.NotFound, se.Message)
-  ```
-  同时把 HTTP 侧的 `response.NewCodeError(se.Code, …)` / gRPC 侧的映射表都抽到一个 `mapSyncPermsErr` helper，避免两边漂移。
-
-### M-3. `RefreshToken` CAS 成功后，若 `GenerateAccessToken` / `GenerateRefreshTokenWithExpiry` 失败，tokenVersion 已递增但客户端拿不到新令牌，用户被强制退出
-- **位置**：`internal/server/permserver.go:198-229`
+### M-N1. `userDetailsLoader.loadFromDB` 的 `loadOk=false` 语义错位，导致基础设施故障被同化为业务拒绝（新发现）
+- **位置**：`internal/loaders/userDetailsLoader.go:138-204`、`:321-574`（`loadFromDB`、`loadDept`、`loadProduct`、`loadPerms` 等子加载）。
 - **描述**：
-  - L199：`IncrementTokenVersionIfMatch` 成功把 DB 的 `tokenVersion` 从 N 增到 N+1，返回 `newVersion`。
-  - L206：`UserDetailsLoader.Clean(ctx, claims.UserId)` 清缓存（此时 TokenVersion 在 DB 是 N+1，但在用户手上的 refreshToken 还是 N）。
-  - L208-214：生成新 accessToken 失败（理论上 HMAC signing 几乎不会失败，但 OOM / 奇怪的运行时错误不是 0 概率）。
-  - L216-223：生成新 refreshToken 失败亦然。
-  - 任一处失败就直接 `return nil, status.Error(codes.Internal / codes.Unauthenticated, ...)`。**客户端的老 refreshToken 因为 tokenVersion 对不上，下一次刷新会被 `claims.TokenVersion != ud.TokenVersion` 一刀切成 "登录状态已失效"**。用户必须完整重登，体验上等同于被踢下线。
-- **影响**：可用性 / 数据完整性：签名失败原本是 100% 服务端 bug，用户却要重登。量不大但会污染"非预期登出"告警，淹没真正的会话劫持信号。
-- **修复方案**：
-  1. 重排顺序：先生成两个新 token（不成功就直接 500，不动 DB），成功后再 CAS 递增 tokenVersion、Clean 缓存。即便递增后 log 层有问题，至少签名成功的 token 一定带回给了客户端。
-  2. 若坚持"先 CAS 再签名"（语义上更安全：CAS 成功才证明本次 refresh 是唯一 winner），则失败路径需要记一条明确的 `audit=refresh_post_cas_sign_fail userId=X oldVer=N newVer=N+1` 的 ERROR 日志，并把返回消息改成用户可感知的 "登录刷新失败，请重新登录"（保留现有行为但补上 observability）。
-
-### L-1. `sysPermModel.go` SQL 仍用 `fmt.Sprintf("... status = %d", consts.StatusEnabled)`，与 L-4 本轮修复风格不一致
-- **位置**：`internal/model/perm/sysPermModel.go:59,102,135`
-  ```go
-  query := fmt.Sprintf("SELECT `code` FROM %s WHERE `productCode` = ? AND `status` = %d", m.table, consts.StatusEnabled)
-  findQuery := fmt.Sprintf("SELECT %s FROM %s WHERE `productCode` = ? AND `status` = %d", sysPermRows, m.table, consts.StatusEnabled)
-  updateQuery := fmt.Sprintf("UPDATE %s SET `status` = %d, `updateTime` = ? WHERE `productCode` = ? AND `status` = %d", m.table, consts.StatusDisabled, consts.StatusEnabled)
-  ```
-- **描述**：第 7 轮 L-4 已经把 `sysUserRole` / `sysUserPerm` / `sysRole` 三处改成了占位符 `?` + 参数传 `consts.StatusEnabled`，但 `sysPermModel` 的三条查询还是走 `fmt.Sprintf` 把 `int` 直接嵌到 SQL 里。问题不是注入（`consts.StatusEnabled` 是编译期常量），而是：
-  1. **类型契约不稳**：如果未来把 `StatusEnabled` 从 `int` 改成 `int8` / `uint8` / `ActiveStatus` enum，`%d` 可能要改，占位符版本可以稳定。
-  2. **审计一致性**：L-4 的修复初衷是"SQL 里**不再出现**状态常量字面值，统一走 prepared statement 占位"。`sysPermModel` 的三处仍然把数字编进 SQL 字符串（虽然是间接通过 Sprintf），与 L-4 的意图偏离。
-- **影响**：非安全问题，属于审计口径一致性 / 未来可维护性。
+  - `loadFromDB` 约定：
+    - `(ud, true, nil)` — 全量成功，写 5 分钟缓存；
+    - `(ud, false, nil)` — 子段（dept / product / membership / roles / perms）中某段失败，**返回残缺 ud、仅跳过缓存写**；
+    - `(nil, _, err)` — 主体加载失败，`Load` 向上传 error。
+  - `Load(:180-183)` 在 `loadOk=false` 时 `return ud, nil`。调用方拿到的是 `Username≠""`、但 `DeptPath=""` / `Perms=nil` / `ProductStatus=0` 的"半成品"：
+    - `jwtauthMiddleware.go` 只校 `tokenVersion` 与 `IsSuperAdmin || MemberType!=""`，**放行**；
+    - `refreshTokenLogic.go` 的 `ProductStatus != StatusEnabled` 分支把这种 case 归类为"产品已被禁用"，返 403；
+    - 其余业务接口因 `Perms=nil` 命中 `hasPerm=false`，返 403。
+  - 结果：一次 Redis / MySQL 抖动对外就是 403 "无权 / 产品禁用"，而真正应该是 503 "上游暂不可用，请重试"。**前端不会重试**，SOC 也不会出现任何异常信号，故障被静默。
+- **影响**：
+  - 故障可观测性塌陷；SLO 把"基础设施降级"错报成"正常业务拒绝"。
+  - 用户体验上，一次瞬时 DB 抖动会对全体在线用户抛"产品已被禁用" / "无权限"——比直接 500 更容易引起误解和 P1 工单。
 - **修复方案**：
-  ```go
-  query := fmt.Sprintf("SELECT `code` FROM %s WHERE `productCode` = ? AND `status` = ?", m.table)
-  // 调用处:
-  QueryRowsNoCacheCtx(ctx, &dest, query, productCode, consts.StatusEnabled)
-  ```
-  三条一致处理；`BatchUpdateWithTx` 里的 `status = ?` 同理。
-
-### L-2. `CountActiveAdminsTx` 零调用仍在接口里公开（第 7 轮 L-5 部分遗留）
-- **位置**：`internal/model/productmember/sysProductMemberModel.go`（接口 + 实现）
-- **描述**：第 7 轮已经把 `FindMapByProductCodeUserIds` / `FindMapByProductCode`（非事务版）从模型接口里干掉。但与之同批引入的 `CountActiveAdminsTx`（不带 `Other`）在业务层的实际调用方是 `CountOtherActiveAdminsTx`；`CountActiveAdminsTx` 自身只在 mock / test 里被引用。
-- **验证方式**：
-  ```shell
-  rg -n 'CountActiveAdminsTx' internal/logic | wc -l     # 0
-  rg -n 'CountOtherActiveAdminsTx' internal/logic | wc -l # >0
-  ```
-- **影响**：僵尸接口方法，增加接口 surface area 与未来误用机会（"应该用 `CountActiveAdminsTx` 还是 `CountOtherActiveAdminsTx`？"的歧义）。
-- **修复方案**：从 interface / 实现 / mock / 单测里删除 `CountActiveAdminsTx`；保留一条 `CountOtherActiveAdminsTx`（业务语义是"除自己以外还有几个活跃 admin"，刚好吻合"不能移除/降级最后一个 admin"的不变式）。
-
-### L-3. `CheckManageAccess` 对 caller `DeptId=0` 且非 ADMIN / SuperAdmin 的历史账号直接 403（第 7 轮 L-7 未消化）
-- **位置**：`internal/logic/auth/access.go`（`checkDeptHierarchy` 内 `caller.DeptId == 0 || caller.DeptPath == ""` 分支）
-- **描述**：历史遗留账号仍有 `DeptId=0` 的 MEMBER / DEVELOPER，即使在自己的产品范围内想做简单的"看自己 / 改自己"操作，也会被 `checkDeptHierarchy` 拒 403（除非上层已短路）。
-- **修复方案**（任选其一，两者都不破坏现有安全边界）：
-  1. 运维侧一次性 SQL：
-     ```sql
-     UPDATE sys_user SET deptId = <DEFAULT_NORMAL_DEPT_ID>
-     WHERE deptId = 0 AND isSuperAdmin = 0 AND (
-       userId IN (SELECT userId FROM sys_product_member WHERE memberType != 'ADMIN')
-       OR userId NOT IN (SELECT userId FROM sys_product_member)
-     );
-     ```
-     同时 `UserDetailsLoader.CleanByUserIds` 一次性批量清缓存。
-  2. 代码侧：`CheckManageAccess` 早期追加
-     ```go
-     if caller.UserId == targetUserId {
-         return nil
-     }
-     ```
-     （这一条已经在 L60-69 实现了，但仅对"看自己"生效；真正被 403 的路径是"看同部门的人"——仍需要数据修复）。
-
-### L-4. `SetUserPerms` 在 `FindByIds` 校验与 `BatchInsertWithTx` 之间存在 perm 状态 TOCTOU
-- **位置**：`internal/logic/user/setUserPermsLogic.go:90-130`
+  1. 把 `loadOk=false` 的语义改为"基础设施故障"：`Load` 里遇到该分支直接 `return nil, ErrLoaderDegraded`（新定义 sentinel）。
+  2. HTTP 中间件 & gRPC AuthInterceptor 对 `ErrLoaderDegraded` 统一返 503（或 `codes.Unavailable`），并附 `retry-after`。
+  3. 保留 `(ud, false, nil)` 作为内部观测用途时，**改为 panic-safe 的诊断日志聚合**而非对外返回。
+  4. 配套：`refreshTokenLogic` 里的 "产品已被禁用" 分支前增加 `if ud.ProductCode != "" && ud.DeptStatus == 0 { return ErrLoaderDegraded }` 兜底。
+  5. 单测：`TC-9101 loadPerms 报错 → Load 返回 Unavailable`、`TC-9102 loadProduct 报错 → Load 不返回"产品已禁用"`。
+
+### M-N2. `UserDetailsLoader.BatchDel` 在大 roleId 场景退化为 O(N) Redis RTT（N+1 新发现）
+- **位置**：`internal/loaders/userDetailsLoader.go:257-272`，调用方 `internal/logic/role/updateRoleLogic.go`、`internal/logic/role/bindRolePermsLogic.go`、`internal/logic/user/bindRolesLogic.go`。
 - **描述**：
-  - L95-109：循环检查 `dbPerms` 里每条权限都 `ProductCode == productCode` 且 `Status == StatusEnabled`；
-  - L112-131：在新事务里 `DeleteByUserIdForProductTx` + `BatchInsertWithTx`。
-  - 两段之间若并发一次 `SyncPermissions` 把某个 permId 的 `status` 置成 DISABLED，本次 `SetUserPerms` 依然会把那条 `user_perm` 落库。
-- **影响**：`loadPerms` 在组装缓存时是 `JOIN sys_perm WHERE sys_perm.status = ?`（L-4 修过的部分），失效权限不会真正生效。本漏洞**不造成越权**，但会留下一行"脏"`sys_user_perm`，让审计查询 "X 拥有哪些权限" 与 "X 实际享有哪些权限" 出现微小偏差，是数据一致性噪声。
-- **修复方案**（按实际需要决定是否做）：
-  1. 把 `FindByIds` 挪到事务内，并对 `sys_perm` 这几行加 `FOR SHARE`（`SyncPerms` 已经通过 `LockByCodeTx` 在 sys_product 行上串行化；这里加 `FOR SHARE` 只是为了在事务边界内读到一致的 status，开销很低）；
-  2. 或者最廉价：在 `BatchInsertWithTx` 之后补一条 `COUNT(*)` 校验 —— "我刚才插入的 permId 全部仍是 Enabled"，不满足就主动回滚事务。任一方案都能把 TOCTOU 窗口缩到零。
+  - `BatchDel` 先用一次 `DelCtx(keys...)` 批量删主 key（OK），但紧跟着 **for-range 调用 `unregisterCacheKey`，每个用户串行 2 次 `SremCtx`**（userIndex + productIndex）。
+  - 对"角色改名 / 角色禁用 / 批量重绑角色"场景，该角色下绑定的用户数可能上千人（即使"几万部门"不现实，但"单个业务角色跨几千人"在大型中台里常见）。意味着一次普通的 `UpdateRole` 会对 Redis 发出 **2N 次** 串行往返。
+  - 相较之下，`registerCacheKey` 已经用 `PipelinedCtx` 合并 RTT，表明作者清楚 pipeline 的必要性，`unregisterCacheKey` 却没同步改造。
+- **影响**：
+  - 在角色批量维护/权限大盘扫描期对 Redis 连接池形成突刺，尾延迟 P99 明显抬升；极端场景可导致 `UpdateRole` 接口被 go-zero 的 ctx timeout 打断，落入"已 UPDATE DB 但 Clean 缓存失败"的分支（目前该分支仅写 Errorf，不回滚）。
+  - 当 Redis 集群跨机房时，2N 串行比一次 pipeline 多出 (N-1)×RTT，个位数 ms 的 RTT 在 N=1000 时就是秒级延迟。
+- **修复方案**：
+  1. 把 `unregisterCacheKey` 的 per-user 逻辑合入一次 `PipelinedCtx`：对每个 key 发 `pipe.SRem(userIdxKey, cacheKey)` / `pipe.SRem(productIdxKey, cacheKey)`，一次 Exec。
+  2. 更彻底：直接给 `BatchDel` 写一个专用 `batchUnregister(ctx, pairs)`，单 pipeline 内合并所有 userIndex / productIndex 的 SREM + 可选 EXPIRE。
+  3. 回归测试：`TC-9201 BatchDel(1000 users) 的 Redis 命令数 ≤ 3 次 pipeline Exec`（用 redis-mock 的 CallCount 断言）。
 
----
+### M-N3. `RoleDetail` 枚举 oracle：跨产品访问 404 vs 403 可区分（新发现）
+- **位置**：`internal/logic/role/roleDetailLogic.go:29-58`。
+- **描述**：
+  - 现状流程：
+    1. 先 `SysRoleModel.FindOne(req.Id)`：找不到返 **404 "角色不存在"**；
+    2. 再判 `!IsSuperAdmin && caller.ProductCode != role.ProductCode`：返 **403 "无权访问该产品的数据"**。
+  - 非超管攻击者遍历 `req.Id`，即可通过响应码精确区分"该 id 不存在" vs "存在于别的产品"，从而绘制跨产品的 role id 分布图，为后续定向攻击（社工、横向越权尝试）提供素材。
+  - 同一脚本在 `ProductDetailLogic.productDetail` 也存在（先 `FindOneByCode`，再做成员检查）；`RoleList`/`ProductList` 因天然按 `caller.ProductCode` 过滤不泄漏。
+- **影响**：
+  - 边界信息泄露，属于"先查后授权"反模式；在任何以 id 为目标的枚举场景都会被利用。
+  - 与第 7 轮把 `AdminLogin` 非法用户名的 bcrypt 时序补齐的精神不一致。
+- **修复方案**：
+  1. 合并成"授权失败即返 404"的统一契约：先用 `caller.ProductCode` 做过滤（或查询时把 `productCode = ?` 塞进 WHERE），未命中或跨产品一律返 `ErrNotFound("角色不存在")`。
+  2. `ProductDetailLogic` 同步处理：对非超管直接用 `FindByCodeWithMemberCheck` 或先查 `sys_product_member` 命中后再读 `sys_product`，省掉"存在性差异"泄漏。
+  3. 单测：`TC-9301 非超管请求别产品 roleId → 404`、`TC-9302 非超管请求不存在 roleId → 404`，两者响应体必须完全一致。
 
-## 📋 修复优先级汇总
+### M-N4. `CreateUser` 允许产品 ADMIN 为"非自己管辖部门"预埋用户名（新发现）
+- **位置**：`internal/logic/user/createUserLogic.go:37-100`。
+- **描述**：
+  - 现状只用 `RequireProductAdminFor(productCode)` 校验 caller 是该产品的 ADMIN，并用 `FindOne(req.DeptId)` 核对部门存在，**未校验 caller 的 `DeptPath` 是否覆盖 `newDept.Path`**。
+  - 产品 ADMIN 可以为任意存在的部门创建用户，随后：
+    1. 占坑关键用户名（`admin_*`、`ops_*`、`sre_*` 等易被运营/运维复用的账号）；
+    2. 预埋账号后等待配合方（比如跨部门协作的另一位 ADMIN）触发 `AddMember`，由于 `AddMember` 会走 `CheckAddMemberAccess` 的部门链校验，**对方 ADMIN** 的部门链可能覆盖，最终把这个"伪造种子账号"挂进产品。
+  - 与 `UpdateUserLogic` 的设计（调部门时严格校验 `caller.DeptPath` 前缀，见 `updateUserLogic.go:116-120`）**不一致**：同样的敏感位，创建时无校验、修改时严校验，出现"先创建后改部门"的绕路。
+- **影响**：
+  - 横向越权路径：产品 ADMIN 在"应当只管 X 部门"的治理约束下，可以在 DEV 部门、总部部门等任意位置生成账号，后续借由 AddMember 协同路径落地。
+  - 用户名命名空间被占用，正常部门 ADMIN 新建时收到"用户名已存在"，排查困难。
+- **修复方案**：
+  1. 与 `UpdateUserLogic` 保持对称：`if req.DeptId > 0 && !caller.IsSuperAdmin && caller.MemberType != Admin || caller.DeptPath != "" && !strings.HasPrefix(newDept.Path, caller.DeptPath) { return ErrForbidden }`。
+  2. 若业务上允许产品 ADMIN "跨部门拉新人"，则至少要求 `req.DeptId` 必须是 caller 所在产品已有成员的部门集合之一（查 `sys_product_member` join `sys_user` 得到部门白名单）。
+  3. 单测：`TC-9401 部门 ADMIN 创建跨部门用户 → 403`、`TC-9402 产品 ADMIN 创建本部门子部门用户 → 200`、`TC-9403 SuperAdmin 创建任意部门用户 → 200`。
 
-| 优先级 | finding                                                       | 一句话概要                                                                                  |
-| :----- | :------------------------------------------------------------ | :------------------------------------------------------------------------------------------ |
-| **P0** | **H-1** UserDetail/UserList PII 暴露（3 轮未落地）            | 任意同产品 MEMBER 可读全员手机邮箱备注，违反 PIPL 最小必要                                  |
-| **P0** | **H-2** `checkPermLevel` 仍读缓存 MinPermsLevel（M-3 另一半） | 降级 admin 在 5 分钟 TTL 内仍可 RemoveMember / UpdateMember / SetUserPerms                  |
-| P1     | **M-1** CreateProduct Redis 写失败 → 产品 + admin 孤儿化      | 一次 Redis 失败 → 永久不可恢复，只能手动 SQL                                                |
-| P1     | **M-2** SyncPermsError 404 → codes.Internal 契约错位          | 接入方 SDK 的错误分类/重试策略失真                                                          |
-| P1     | **M-3** RefreshToken CAS 后签名失败 → 用户被强制登出          | tokenVersion 已推进，客户端必须重登，可用性事件                                             |
-| P2     | **L-1** `sysPermModel` 仍用 `fmt.Sprintf`（L-4 风格漂移）     | 三条 SQL 统一改占位符，接近审计一致性                                                       |
-| P2     | **L-2** `CountActiveAdminsTx` 零调用（L-5 遗留）              | 接口层可见的僵尸方法                                                                        |
-| P2     | **L-3** `CheckManageAccess` 对 `DeptId=0` 老账号 403（L-7）   | 需数据迁移或 "看自己" 短路                                                                  |
-| P3     | **L-4** SetUserPerms FindByIds / BatchInsert TOCTOU           | 不越权，但会留脏 `sys_user_perm` 行                                                         |
+### L-N1. JWT 解析三处重复：`ParseWithHMAC` helper 未统一使用
+- **位置**：
+  - 定义：`internal/logic/auth/jwt.go:16-31`；
+  - 内联实现 1：`internal/middleware/jwtauthMiddleware.go:62-66`；
+  - 内联实现 2：`internal/server/permserver.go` 的 `VerifyToken`（`jwt.ParseWithClaims(... keyfunc {...})`）。
+- **描述**：`ParseWithHMAC` 的注释明确写着"所有 JWT 解析点（HTTP 中间件 / gRPC VerifyToken / RefreshToken）统一走这里"，但目前只有 `ParseRefreshToken` 一个调用方。另两处自己又写了一遍 `token.Method.(*jwt.SigningMethodHMAC)` 断言 —— 功能上一致，但：
+  - 未来若增加算法白名单（例如仅允许 HS384、禁 HS256）或添加 `typ` 断言，要改 3 处；
+  - 把"算法混淆防御"的审计覆盖矩阵从 1 个函数摊到 3 个函数，`test-design.md` 的 TC-0951~0960 只覆盖了 `ParseRefreshToken` 一条路径。
+- **影响**：安全属性正确，但代码一致性差、改动风险高。属于"长期隐患"。
+- **修复方案**：
+  1. `jwtauthMiddleware.go` 改用 `authHelper.ParseWithHMAC(tokenStr, secret, &UserClaims{})`，移除内联 keyfunc；
+  2. gRPC `VerifyToken` 同样替换；
+  3. 把 TC-0951~0960 复用到这两条路径（直接 table-driven 调三个入口）。
+
+### L-N2. `UpdateUserLogic` 调部门时未校验目标 `dept.Status`
+- **位置**：`internal/logic/user/updateUserLogic.go:110-131`。
+- **描述**：`FindOne(*req.DeptId)` 仅判存在，不判 `Status`。产品 ADMIN 可把用户调入已 `Disabled` 的部门，随后该用户在 `loadPerms` 里会命中"普通成员 + DeptStatus!=Enabled"分支，其 DEV 全权特权被撤销。若业务意图是"停用部门=冻结该部门所有活动"，该路径破坏了不变量。
+- **影响**：中低优。主要是产品语义一致性（"停用部门"的含义被稀释），不构成越权。
+- **修复方案**：`if newDept.Status != StatusEnabled { return ErrBadRequest("目标部门已停用") }`，与 `UpdateDept` 禁用时的数据流闭环。
+
+### L-N3. `AdminLogin` `IsSuperAdmin` 判断在 bcrypt 之后，对"合法用户名"的时序侧漏略大于"非法用户名"分支
+- **位置**：`internal/logic/pub/adminLoginLogic.go:55-85`。
+- **描述**：流程是"查用户 → bcrypt 校验 → 校 `IsSuperAdmin` → 校 status"。对于一个**存在但非超管**的账号，攻击者即便密码随机也会触发 bcrypt 计算（约 60~100ms），与"存在且密码错"分支耗时相近；而"不存在"分支走 `dummyBcryptHash` 也有类似耗时兜底 —— 单凭这点难以区分。但若攻击者能获取大量样本，`IsSuperAdmin` 这一步的耗时（sql 比较）理论上可让"存在但非超管"比"存在是超管且密码错"略快（无 token 签发路径），仍可能形成<10ms 级的统计差。
+- **影响**：属学术级别时序泄漏，实战价值低。但该入口按第 7 轮审计精神是"高敏感且对抗公网扫描"，建议把 `IsSuperAdmin` 判断**前置到 `FindByUsername` 之后、bcrypt 之前**：若非超管，仍走 `dummyBcryptHash` 消耗一次 bcrypt，再返回 403，恒定时序。
+- **修复方案**：重排为：`FindByUsername → 非超管则用 dummy 计算再统一返 ErrInvalidCredentials → 超管再真 bcrypt → Status 校验`。
+
+### L-N4. `sysUserModel.UpdateStatus` 缺乐观锁字段（由上层短路保护，但 model 自身语义不自洽）
+- **位置**：`internal/model/user/sysUserModel.go:154-175`。
+- **描述**：`UpdateStatus` 的 `WHERE id=?` 无 `updateTime` / `tokenVersion` 比较；与同文件里 `UpdateProfile` 使用乐观锁、`IncrementTokenVersionIfMatch` 使用 CAS 的风格不一致。上层 `UpdateUserStatusLogic` 做了"状态相同则短路"、`UserDetailsLoader` 5 分钟 TTL 也提供事实一致性，所以实际故障概率低。
+- **影响**：不会造成越权，但并发改状态会出现"我改了 Enabled 你覆成 Disabled"的 last-write-wins。
+- **修复方案**：把 `UpdateStatus` 改为 `WHERE id=? AND updateTime=?`，接口加入 `expectedUpdateTime` 参数，语义与 `UpdateProfile` 对齐。
 
 ---
 
-## 🛠 建议修复次序
+## ✅ 本轮复核通过、认定安全的机制（仅挑敏感点列示）
+
+| 机制 | 位置 | 关键保护点 |
+| --- | --- | --- |
+| `checkPermLevel` fresh read | `logic/auth/access.go:302-347`、`loadFreshMinPermsLevel:339-343` | caller.MinPermsLevel 每次走 DB，降级 admin 后续的跨级分配被立即拒绝（第 8 轮 H-2 已闭环） |
+| CreateProduct 补偿 | `logic/product/createProductLogic.go:178-283` | Redis 票据写入 `SetexCtx` 失败调用 `compensateCreatedRows` 级联删除 admin / member / product |
+| RefreshToken CAS 顺序 | `logic/pub/refreshTokenLogic.go:90-110`、`server/permserver.go:215-230` | 先生成 access+refresh 再 `IncrementTokenVersionIfMatch`，签名失败不会吞掉旧 refresh |
+| DeleteDept AB-BA 防护 | `logic/dept/deleteDeptLogic.go` | 自身 `FOR UPDATE`，子部门 / 成员 `FOR SHARE`，锁顺序与 CreateDept 对齐 |
+| 负缓存投毒防御 | `loaders/userDetailsLoader.go:161-178` | 写哨兵前再 `FindOne` 强一致复核，避免 Insert→Load 并发把新用户哨兵掉 |
+| AddMember 部门链二次校验 | `logic/auth/access.go:CheckAddMemberAccess`、`logic/member/addMemberLogic.go:76-78` | 产品 ADMIN 也要过部门链，切断第 6 轮 H-3 |
+| RemoveMember 末位守卫 | `logic/member/removeMemberLogic.go:49-53` | `CountOtherActiveAdminsTx` 事务内排除自己并 lock row，杜绝并发撤 admin 导致 0 admin |
+| GuardRoleLevelAssignable | `logic/user/bindRolesLogic.go:86-88` | caller 的 min-level fresh read，避免缓存 admin 权级绑定高于自己的角色 |
+| SetUserPerms 事务内复核 | `logic/user/setUserPermsLogic.go:148-165` | `BatchInsertWithTx` 前后 `COUNT(*) WHERE status=?` 复核，并发禁用权限的 TOCTOU 闭环 |
+| gRPC SyncPerms 错误分级 | `server/permserver.go:61-90` | `SyncPermsError{Code:404}` → `codes.NotFound`，不再同化为 Internal |
+| gRPC 限流剥端口 | `server/permserver.go` / `ratelimit` | PeriodLimit key 用客户端 IP 而非 `host:port`，防单连接多端口绕限 |
+| JWT HMAC 断言本身 | `logic/auth/jwt.go:16-31` | `alg=none` / RS256 / ES256 全拒；L-N1 指出的是"调用点未统一"，算法防御自身 OK |
 
-1. **本轮必修 P0**（对称封口）：
-   - H-1：`filterPIIForCaller` + `CanViewContact` 两个 helper，落到 `UserDetail` / `UserList` 返回前。
-   - H-2：`checkPermLevel` 把 `caller.MinPermsLevel` 换成 `loadFreshMinPermsLevel(...)`；与 `GuardRoleLevelAssignable` 共享同一个 helper。两条 P0 建议同批上线，一起做回归单测。
+---
 
-2. **P1**（稳定性与契约）：
-   - M-1：CreateProduct 失败路径补偿（删 `sys_product` + `sys_user` + `sys_product_member`）或新增 SuperAdmin-only `RegenerateInitialCredentials`；集成测试强制注入 Redis fault。
-   - M-2：`SyncPermsError{Code:404}` 补到 switch 里，映射到 `codes.NotFound`；抽 `mapSyncPermsErr` 统一 HTTP / gRPC。
-   - M-3：RefreshToken 重排为"先签新 token 成功才做 CAS"；或至少给 post-CAS 失败路径加 audit 字段。
+## 🎯 修复建议优先级与落地顺序
 
-3. **P2 / P3 收尾**：
-   - L-1：`sysPermModel` 三条 SQL 改占位符；
-   - L-2：`CountActiveAdminsTx` 删除（接口 + 实现 + mock），`CountOtherActiveAdminsTx` 保留；
-   - L-3：数据迁移脚本批量把历史 `deptId=0` 账号挪到默认部门，然后 `CleanByUserIds` 刷缓存；
-   - L-4：`SetUserPerms` 要么把 `FindByIds` 挪进事务 + `FOR SHARE`，要么事务末补一条 status 复核 `COUNT(*)`。
+| 优先级 | 议题 | 预估工作量 | 风险 |
+| --- | --- | --- | --- |
+| P0 | **M-N1 Loader 半成品降级** | 1 天：新增 sentinel 错误 + 中间件映射 + refreshToken 分支修正 + 2 条新单测 | 中：需验证 5xx 监控告警路径 |
+| P1 | **M-N3 RoleDetail 枚举 oracle** | 半天：`RoleDetail` + `ProductDetail` 合并成"404 或 200" | 低 |
+| P1 | **M-N4 CreateUser 部门链校验** | 半天：对称复用 `UpdateUserLogic` 的校验代码 | 低 |
+| P2 | **M-N2 BatchDel pipeline 化** | 半天：改 `unregisterCacheKey` 支持批量 + 回归压测 | 低 |
+| P2 | **L-N1 ParseWithHMAC 统一** | 半天：替换 2 处调用 + table-driven 用例复用 | 低 |
+| P3 | **L-N2 UpdateUser 目标部门 Status** | 1 小时 | 低 |
+| P3 | **L-N3 AdminLogin IsSuperAdmin 前置** | 1 小时 | 低 |
+| P3 | **L-N4 UpdateStatus 乐观锁** | 2 小时（需调上层一处调用） | 低 |
+| Backlog | **L-3 `DeptId=0` 历史账号迁移** | 需 DBA 配合 | — |
 
 ---
 
-## 🔎 备注：本轮已验证仍在正轨上的机制
+## 📎 审计方法论与覆盖率说明
 
-下列机制经过完整阅读后认为仍然安全、无需调整，特此备注以免未来误改：
+- 本轮审计共读取并分析 27 个 `.go` 文件（不含 `_test.go` / `_gen.go` / `testdata/`），覆盖 logic（全部）、loaders、server、middleware、model 定制层、consts、util；
+- 复核维度：针对第 8 轮每一条未决项都读取相关 code path 做实际行为确认，避免"报告里写修复实际没改"；
+- 新发现筛选原则：仅列出**能构造具体攻击序列或业务损害场景**的项，纯风格性建议已过滤；
+- "几万部门"等非现实场景已按 USER 要求过滤；保留"角色下绑千人"这一现实高频场景作为 M-N2 的论据。
 
-- `UserDetailsLoader`：H-1（deny fail-close）、M-1（半加载不写缓存 + 中间件按 `(ud, err)` 分流 401/503）、L-3（loadPerms 任一子步骤错误都 fail-close）、L-6（负缓存 TTL=10s + 写前 `FindOne`）全部落地。
-- `RefreshToken` / `Logout` 走 `IncrementTokenVersionIfMatch` / `IncrementTokenVersion` 两把刀，前者是 CAS（单会话轮转），后者是"无条件大杀器"（强制全量失效），`L-2` 的 WARN 注释已就位。
-- `DeleteDeptLogic` 的锁序列：`X(target dept)` → `FOR SHARE(children)` → `FOR SHARE(users in dept range)`，AB-BA 死锁风险大幅收敛。
-- `SyncPermissions` 通过 `LockByCodeTx` 把同 product 的 sync 串行化，sys_perm UNIQUE 再撞 1062 会落一条 `audit=mysql_error_1062` ERROR 日志，足以触发告警。
-- `LoginLogic` / `AdminLoginLogic` / `UserInfoLogic` 里的 `Email` / `Phone` 返回属于"看自己"合法场景，本轮不纳入 H-1 修复范围。
-- `ExtractClientIP` 对 `X-Forwarded-For` / `X-Real-IP` 做了严格解析 + `firstValidIP` 过滤，gRPC 侧 `net.SplitHostPort` 剥端口（M-7 已修）。
-- `CheckAddMemberAccess` 对 ADMIN 也强制走部门链校验 + 拒绝 `target.IsSuperAdmin`，H-3 入口已封住。

internal/loaders/userDetailsLoader.go

@@ -35,6 +35,13 @@ const (
 	negativeCacheMarker = "_NOT_FOUND_"
 )
 
+// ErrLoaderDegraded 表示 UserDetails 的子段加载（dept / product / membership / roles / perms）
+// 中至少有一段因基础设施抖动失败。调用方（HTTP 中间件 / gRPC 拦截器）应映射为 503 / codes.Unavailable
+// 让客户端走临时故障重试策略，**绝不能**与"用户不存在（ud.Username == ""）"同化成 401/403
+// （见审计 M-N1：半成品 ud 被当作"产品禁用 / 无权限"会把一次 DB 抖动放大成全站 403，监控侧完全
+// 观测不到基础设施故障）。
+var ErrLoaderDegraded = errors.New("user details loader degraded: partial load failure")
+
 // -------- UserDetails 及子结构 --------
 
 // UserDetails 用户完整信息，包含用户、部门、产品、成员、角色、权限等所有有效字段。
@@ -123,7 +130,7 @@ func (l *UserDetailsLoader) productIndexKey(productCode string) string {
 
 // Load 根据 userId 和 productCode 加载完整的 UserDetails。
 //
-// 返回 (ud, nil) 的三种成功语义：
+// 返回 (ud, nil) 的两种成功语义：
 //  1. DB 有该用户 → ud.Username != ""，为真实数据；
 //  2. DB 确认用户不存在 → ud.Username == ""（调用方据此返回"用户不存在/已删除"）；
 //     同时会在 Redis 写入短 TTL 负缓存哨兵，避免残余 token 持续打 DB（见审计 M-3）。
@@ -132,9 +139,10 @@ func (l *UserDetailsLoader) productIndexKey(productCode string) string {
 // 否则单次 DB 抖动会把全站在线用户同化为"用户已被删除"并要求重新登录，反过来把更多流量打到 DB
 // 形成雪崩（见审计 M-1）。调用方（HTTP / gRPC 中间件）应据此返回 503/临时不可用，而不是 401。
 //
-// 此外，当 loadFromDB 内任一子步骤（perm / role / dept / product / membership）失败时，本次
-// 不会写入 5 分钟缓存，交给下一次 Load 重试，避免把"半残 UD"固化到缓存里持续影响授权判定
-// （见审计 H-1 / L-3）。
+// 特别地，当 loadFromDB 内任一子步骤（perm / role / dept / product / membership）失败时，
+// 本函数返回 `ErrLoaderDegraded`（见审计 M-N1）；该错误同样应映射为 503 / Unavailable，
+// 绝不能被吞成"产品已禁用" / "无权限"。此时本次加载不会写入 5 分钟正缓存，交给下一次 Load 重试，
+// 避免把"半残 UD"固化到缓存里持续影响授权判定（见审计 H-1 / L-3）。
 func (l *UserDetailsLoader) Load(ctx context.Context, userId int64, productCode string) (*UserDetails, error) {
 	key := l.cacheKey(userId, productCode)
 
@@ -178,9 +186,13 @@ func (l *UserDetailsLoader) Load(ctx context.Context, userId int64, productCode
 			return ud, nil
 		}
 		if !loadOk {
-			// 部分子加载失败：返回当前 ud 以便调用方观测到具体失败原因，但**不写 5 分钟正缓存**，
-			// 等下次 Load 重试（见审计 M-1 / H-1 / L-3）。
-			return ud, nil
+			// 审计 M-N1：部分子加载失败属于基础设施故障，必须以 error 向上冒。历史实现把这里
+			// 同化为 "(ud, nil) 的半成品" 并由调用方各自判断 DeptPath=="" / Perms==nil，在
+			// jwtauth 中间件 / refreshToken / gRPC VerifyToken 里分别会被当成 "产品已禁用" /
+			// "无权限" 返 403，让一次 DB 抖动彻底静默、SOC 完全看不到基础设施信号。现统一返
+			// ErrLoaderDegraded，由调用方映射为 503 / codes.Unavailable。
+			// 不写 5 分钟正缓存的语义保留：等下次 Load 重试（见审计 M-1 / H-1 / L-3）。
+			return nil, ErrLoaderDegraded
 		}
 		if val, err := json.Marshal(ud); err == nil {
 			if err := l.rds.SetexCtx(ctx, key, string(val), l.ttl); err != nil {
@@ -255,6 +267,11 @@ func (l *UserDetailsLoader) CleanByProduct(ctx context.Context, productCode stri
 }
 
 // BatchDel 批量删除多个用户在指定产品下的缓存。
+// 审计 M-N2：历史实现对每个用户串行调用 unregisterCacheKey，触发 2N 次 SREM 串行 RTT，
+// "角色下绑千人"的业务场景里会把 UpdateRole / BindRoles 的尾延迟抬到秒级；更糟糕的是
+// go-zero 的请求 ctx 超时兜不住时会命中"DB 已更新但缓存未清"分支。改为：
+//   (1) 主 key 批 DEL（和原来一致，一次 RTT）；
+//   (2) 所有 userIndex / productIndex 的 SREM 合进一次 Pipelined RTT，把 2N 串行压到常数。
 func (l *UserDetailsLoader) BatchDel(ctx context.Context, userIds []int64, productCode string) {
 	if len(userIds) == 0 {
 		return
@@ -266,8 +283,31 @@ func (l *UserDetailsLoader) BatchDel(ctx context.Context, userIds []int64, produ
 	if _, err := l.rds.DelCtx(ctx, keys...); err != nil {
 		logx.WithContext(ctx).Errorf("batch del user details cache failed: %v", err)
 	}
-	for i, uid := range userIds {
-		l.unregisterCacheKey(ctx, keys[i], uid, productCode)
+	l.batchUnregister(ctx, userIds, keys, productCode)
+}
+
+// batchUnregister 把一批 (userId, cacheKey) 的 userIndex SREM 以及（可选的）productIndex
+// SREM 全部合进同一次 Pipelined 调用；相比 per-user 串行的 unregisterCacheKey，RTT 数从 2N 降到 1。
+// 调用方应保证 len(userIds) == len(cacheKeys) 且索引语义一一对应。
+func (l *UserDetailsLoader) batchUnregister(ctx context.Context, userIds []int64, cacheKeys []string, productCode string) {
+	if len(userIds) == 0 {
+		return
+	}
+	pIdxKey := ""
+	if productCode != "" {
+		pIdxKey = l.productIndexKey(productCode)
+	}
+	err := l.rds.PipelinedCtx(ctx, func(pipe redis.Pipeliner) error {
+		for i, uid := range userIds {
+			pipe.SRem(ctx, l.userIndexKey(uid), cacheKeys[i])
+			if pIdxKey != "" {
+				pipe.SRem(ctx, pIdxKey, cacheKeys[i])
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		logx.WithContext(ctx).Errorf("batchUnregister pipeline failed: %v", err)
 	}
 }
 

internal/loaders/userDetailsLoader_batchdel_mn2_audit_test.go

@@ -0,0 +1,120 @@
+package loaders
+
+import (
+	"context"
+	"testing"
+
+	"perms-system-server/internal/consts"
+	productModel "perms-system-server/internal/model/product"
+	userModel "perms-system-server/internal/model/user"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 M-N2 修复 —— BatchDel 必须把 userIndex / productIndex 的 SREM
+// 合进一次 Pipelined RTT，历史 per-user 串行路径下"角色绑千人"时尾延迟会抬到秒级。
+// 本测试以"主缓存 + user/product 索引集合"的最终一致性为切入点，在 N 条数据下验证：
+//   (1) 主 cacheKey 全量清空
+//   (2) 每个 userIndex 集合中对应的 cacheKey 已经被 SREM
+//   (3) productIndex 集合中所有 cacheKey 也已经被 SREM
+// 相比只断言 (1) 的 TC-0513，本 TC 把 index 一致性钉死，防止 pipelined 分支被回退到
+// "只 DEL 主 key、遗漏 SREM"的静默回归。
+// ---------------------------------------------------------------------------
+
+// TC-1013: M-N2 —— BatchDel 必须同步清理 userIndex / productIndex 中的 cacheKey 集合（Pipelined）。
+func TestUserDetailsLoader_MN2_BatchDelClearsUserAndProductIndexes(t *testing.T) {
+	ctx := context.Background()
+	conn := testConn()
+	m := testModels()
+	loader := newTestLoader()
+	rds := testRedis()
+
+	ts := now()
+	pcode := "mn2_" + uniqueId()
+
+	// 插入两个用户 + 一个真实产品，确保 Load 走到 5 分钟正缓存分支并注册索引
+	uid1 := uniqueId()
+	uid2 := uniqueId()
+	userId1 := insertUser(ctx, t, m, &userModel.SysUser{
+		Username: uid1, Password: hashPwd("pass123"), Nickname: "nick_" + uid1,
+		Email: uid1 + "@t.com", Phone: "13800000008", DeptId: 0,
+		IsSuperAdmin: consts.IsSuperAdminNo, MustChangePassword: consts.MustChangePasswordNo,
+		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
+	})
+	userId2 := insertUser(ctx, t, m, &userModel.SysUser{
+		Username: uid2, Password: hashPwd("pass123"), Nickname: "nick_" + uid2,
+		Email: uid2 + "@t.com", Phone: "13800000009", DeptId: 0,
+		IsSuperAdmin: consts.IsSuperAdminNo, MustChangePassword: consts.MustChangePasswordNo,
+		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
+	})
+	pid := insertProduct(ctx, t, m, &productModel.SysProduct{
+		Code: pcode, Name: "p_" + pcode, AppKey: "ak_" + pcode, AppSecret: "as_" + pcode,
+		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
+	})
+	t.Cleanup(func() {
+		loader.Del(ctx, userId1, pcode)
+		loader.Del(ctx, userId2, pcode)
+		cleanTable(ctx, conn, "`sys_product`", pid)
+		cleanTable(ctx, conn, "`sys_user`", userId1, userId2)
+	})
+
+	// 把缓存一次预热，让 userIndex/productIndex 被 registerCacheKey 真实写入
+	_, err := loader.Load(ctx, userId1, pcode)
+	require.NoError(t, err)
+	_, err = loader.Load(ctx, userId2, pcode)
+	require.NoError(t, err)
+
+	k1 := loader.cacheKey(userId1, pcode)
+	k2 := loader.cacheKey(userId2, pcode)
+	pIdx := loader.productIndexKey(pcode)
+	u1Idx := loader.userIndexKey(userId1)
+	u2Idx := loader.userIndexKey(userId2)
+
+	// 预检：主 key 写入、productIndex / userIndex 存在对应元素
+	for _, k := range []string{k1, k2} {
+		val, gerr := rds.GetCtx(ctx, k)
+		require.NoError(t, gerr)
+		require.NotEmpty(t, val, "M-N2 预检：主 cacheKey 必须被写入才有意义")
+	}
+	has, _ := rds.SismemberCtx(ctx, pIdx, k1)
+	require.True(t, has, "M-N2 预检：productIndex 必须含 k1")
+	has, _ = rds.SismemberCtx(ctx, pIdx, k2)
+	require.True(t, has, "M-N2 预检：productIndex 必须含 k2")
+	has, _ = rds.SismemberCtx(ctx, u1Idx, k1)
+	require.True(t, has, "M-N2 预检：userIndex(u1) 必须含 k1")
+	has, _ = rds.SismemberCtx(ctx, u2Idx, k2)
+	require.True(t, has, "M-N2 预检：userIndex(u2) 必须含 k2")
+
+	// 触发被测路径：BatchDel（pipelined SREM）
+	loader.BatchDel(ctx, []int64{userId1, userId2}, pcode)
+
+	// 主 key 被清空（原 TC-0513 已保障）
+	for _, k := range []string{k1, k2} {
+		val, _ := rds.GetCtx(ctx, k)
+		assert.Empty(t, val, "M-N2：BatchDel 必须删除主 cacheKey")
+	}
+
+	// userIndex / productIndex 中的对应 cacheKey 必须被 SREM 清除（本 TC 核心断言）
+	has, _ = rds.SismemberCtx(ctx, u1Idx, k1)
+	assert.False(t, has, "M-N2：BatchDel 必须把 k1 从 userIndex(u1) SREM 出去")
+	has, _ = rds.SismemberCtx(ctx, u2Idx, k2)
+	assert.False(t, has, "M-N2：BatchDel 必须把 k2 从 userIndex(u2) SREM 出去")
+	has, _ = rds.SismemberCtx(ctx, pIdx, k1)
+	assert.False(t, has, "M-N2：BatchDel 必须把 k1 从 productIndex SREM 出去")
+	has, _ = rds.SismemberCtx(ctx, pIdx, k2)
+	assert.False(t, has, "M-N2：BatchDel 必须把 k2 从 productIndex SREM 出去")
+}
+
+// TC-1014: M-N2 —— productCode 为空时 BatchDel 仅 SREM userIndex，不得 panic 或误访问 productIndex。
+// 目前业务侧 BatchDel 的所有调用都传了 productCode；但 pipeline 分支必须对空串 fail-safe，
+// 防止未来调用方误传时 pipeline 里塞空 key 把 Redis 侧写脏。
+func TestUserDetailsLoader_MN2_BatchDelEmptyProductCodeDoesNotPanic(t *testing.T) {
+	ctx := context.Background()
+	loader := newTestLoader()
+	// 即便 uid 不存在，pipelined SREM 对不存在的集合是 no-op，不应报错/panic
+	require.NotPanics(t, func() {
+		loader.BatchDel(ctx, []int64{9999999991, 9999999992}, "")
+	})
+}

internal/loaders/userDetailsLoader_contract_audit_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 	"time"
@@ -64,9 +65,17 @@ func TestUserDetailsLoader_Load_L6_CreateUserThenLoadDoesNotWriteSentinel(t *tes
 		Avatar: sql.NullString{}, IsSuperAdmin: consts.IsSuperAdminNo, MustChangePassword: consts.MustChangePasswordNo,
 		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
 	})
+	// M-N1 修复后，Load 要求 productCode 对应的产品真实存在才能进入正缓存分支；否则
+	// loadProduct 失败会被提升为 ErrLoaderDegraded。L-6 的主题是"新用户写入后首次 Load
+	// 不得被自身写的负缓存哨兵投毒"，与"产品不存在"正交，因此这里补一条真实产品。
+	pid := insertProduct(ctx, t, m, &productModel.SysProduct{
+		Code: productCode, Name: "l6_prod", AppKey: "ak", AppSecret: "as",
+		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
+	})
 	t.Cleanup(func() {
 		loader.Del(ctx, userId, productCode)
 		cleanTable(ctx, conn, "`sys_user`", userId)
+		cleanTable(ctx, conn, "`sys_product`", pid)
 	})
 
 	loader.Del(ctx, userId, productCode)
@@ -83,24 +92,27 @@ func TestUserDetailsLoader_Load_L6_CreateUserThenLoadDoesNotWriteSentinel(t *tes
 		"L-6：新创建的用户首次 Load 不得被写入负缓存哨兵，否则 10s 内所有请求都会被判为'已删除'")
 }
 
-// TC-0915: M-1 —— dept 子步骤失败时 Load 不写 5 分钟正缓存。
+// TC-0915 (重写 · M-N1): partial load 失败必须返回 ErrLoaderDegraded（而非 (ud,nil) 半成品），
+// 让调用方统一把它映射为 503 / codes.Unavailable；同时 5 分钟正缓存绝不能被写入。
 //
-// 通过构造"用户 DeptId 指向一个不存在的 deptId"来模拟子加载错误：SysDeptModel.FindOne 会返回
-// ErrNotFound，在新契约下 loadDept 返回 error，Load 标记 !loadOk 进而不写缓存。
-// （审计里 DeptId=0 是合法值不触发加载；这里取一个不存在的正数让 FindOne 确实失败。）
-func TestUserDetailsLoader_Load_M1_PartialLoadDoesNotWriteCache(t *testing.T) {
+// 历史契约：loadOk=false 时 Load 返回 (ud, nil)，ud 是 Username 非空但 DeptPath=""/Perms=nil 的
+// 半成品，然后 jwtauth / refreshToken / GetUserPerms 等调用方因 MemberType=="" 或
+// ProductStatus!=Enabled 错把它当成"产品已被禁用 / 无权限" 返 403，一次 DB 抖动全站静默 403。
+// 新契约（审计 M-N1）：loadOk=false → (nil, ErrLoaderDegraded)；调用方 err!=nil 分支自然映射
+// 503 / codes.Unavailable，SOC 侧能明确观测到基础设施故障。
+func TestUserDetailsLoader_Load_MN1_PartialLoadReturnsErrDegradedAndSkipsCache(t *testing.T) {
 	ctx := context.Background()
 	loader := newTestLoader()
 	conn := testConn()
 	m := testModels()
 	ts := now()
 	uid := uniqueId()
-	productCode := "pc_m1_" + uid
+	productCode := "pc_mn1_" + uid
 
-	// 用一个极大的 DeptId 指向不存在的部门。
+	// 用一个极大的 DeptId 指向不存在的部门，让 loadDept 报 ErrNotFound → loadFromDB loadOk=false。
 	phantomDeptId := int64(999_000_000_000)
 	userId := insertUser(ctx, t, m, &userModel.SysUser{
-		Username: uid, Password: hashPwd("pw"), Nickname: "m1",
+		Username: uid, Password: hashPwd("pw"), Nickname: "mn1",
 		Avatar: sql.NullString{}, DeptId: phantomDeptId,
 		IsSuperAdmin: consts.IsSuperAdminNo, MustChangePassword: consts.MustChangePasswordNo,
 		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
@@ -108,7 +120,7 @@ func TestUserDetailsLoader_Load_M1_PartialLoadDoesNotWriteCache(t *testing.T) {
 
 	// 给产品落一条真实数据，让 loadProduct 本身成功，单独锁定"dept 子步骤失败"这个变量。
 	pid := insertProduct(ctx, t, m, &productModel.SysProduct{
-		Code: productCode, Name: "m1_prod", AppKey: "ak", AppSecret: "as",
+		Code: productCode, Name: "mn1_prod", AppKey: "ak", AppSecret: "as",
 		Status: consts.StatusEnabled, CreateTime: ts, UpdateTime: ts,
 	})
 
@@ -121,22 +133,32 @@ func TestUserDetailsLoader_Load_M1_PartialLoadDoesNotWriteCache(t *testing.T) {
 	loader.Del(ctx, userId, productCode)
 
 	ud, err := loader.Load(ctx, userId, productCode)
-	require.NoError(t, err)
-	require.NotNil(t, ud)
-	assert.Equal(t, uid, ud.Username, "主体加载成功，Username 应被填充")
+	// 新契约：partial load 必须向上冒 ErrLoaderDegraded；ud 必须为 nil，避免调用方误用半成品。
+	require.ErrorIs(t, err, ErrLoaderDegraded,
+		"M-N1：partial load 必须返回 ErrLoaderDegraded，而不是把半成品 ud 静默当成业务拒绝")
+	assert.Nil(t, ud, "M-N1：err 非 nil 时 ud 必须为 nil，杜绝上层误用半成品字段")
 
-	// 断言：Redis 里没有 5 分钟正缓存 —— value 为空，或虽非空但至少不是 Username != "" 的 JSON。
-	// 规范实现下应该直接没写缓存。
+	// 断言 1：Redis 里没有 5 分钟正缓存，主 key 要么完全未写，要么仅留空串。
 	val, err := loader.rds.GetCtx(ctx, loader.cacheKey(userId, productCode))
 	require.NoError(t, err)
 	if val != "" {
-		// 如果因为某种原因仍然写了哨兵/空 ud，也不能写入"包含 Username 的正缓存"；
-		// 若走到正缓存分支，说明 partial-load 被误当成 loadOk 写缓存了（M-1 回归）。
 		assert.NotContains(t, val, "\"username\":\""+uid+"\"",
-			"M-1/H-1/L-3：partial-load 不得把半残 UD 写进 5 分钟正缓存")
+			"M-N1/M-1/H-1/L-3：partial-load 不得把半残 UD 写进 5 分钟正缓存")
 	}
 }
 
+// TC-0917 (新增 · M-N1): ErrLoaderDegraded 必须是可用 errors.Is 断言的独立 sentinel，
+// 供调用方在 HTTP 中间件 / gRPC 拦截器里做到"统一映射 503"而不需要字符串匹配。
+func TestUserDetailsLoader_ErrLoaderDegraded_IsStableSentinel(t *testing.T) {
+	require.NotNil(t, ErrLoaderDegraded, "必须导出 sentinel 便于调用方识别")
+	// 再次发生的派生错误仍应 errors.Is 成立（防御"被包一层后调用方失配"）。
+	wrapped := errors.New("extra: " + ErrLoaderDegraded.Error())
+	assert.False(t, errors.Is(wrapped, ErrLoaderDegraded),
+		"新 error 与 sentinel 不应共享身份；如需传染请显式 fmt.Errorf(\"%%w\", ErrLoaderDegraded)")
+	assert.True(t, errors.Is(ErrLoaderDegraded, ErrLoaderDegraded),
+		"自身 Is 必须为 true（sanity check）")
+}
+
 // TC-0916: M-1 —— deny 查询失败时 fail-close 保底（H-1）。通过写一个完全无 perm 的普通 MEMBER，
 // 再通过 productCode 设为 disabled 让 loadPerms 走 ProductStatus != Enabled 提前返回；再切回
 // Enabled 状态，确保 perm 分支被正常 reach 到，覆盖 "allowIds 查询路径正常结束" 的成功契约。

internal/logic/auth/jwt.go

@@ -2,7 +2,6 @@ package auth
 
 import (
 	"errors"
-	"fmt"
 	"time"
 
 	"perms-system-server/internal/consts"
@@ -13,21 +12,11 @@ import (
 
 var ErrTokenTypeMismatch = errors.New("token type mismatch")
 
-// ParseWithHMAC 统一的 keyfunc 断言入口。所有 JWT 解析点（HTTP 中间件 / gRPC VerifyToken / RefreshToken）
-// 都必须走这里，而不是直接 jwt.ParseWithClaims(... func() {return []byte(secret)}) ——
-// 必须显式断言 token.Method 是 *jwt.SigningMethodHMAC，避免未来迁移到 RSA/ECDSA 非对称密钥
-// 时，攻击者把公钥当成 HMAC 共享密钥伪造 token（jwt-go 历史上 CVE-2016-10555 同类问题，
-// OWASP JWT Cheat Sheet / RFC 8725 均强制要求 alg 白名单，见审计 H-4）。
-//
-// alg=none 在 jwt-go v4 早已默认拒绝，但显式 method 断言仍是深度防御的必要一步：
-// 即使未来有人误签出 alg=HS512 的 token，这里也会直接报错而不是当成 HS256 尝试解析。
+// ParseWithHMAC 转发到 middleware 包的统一 JWT 解析入口。保留本别名以兼容旧调用方（测试与
+// 历史 logic 代码）；真实实现已经上移到 middleware 层，避免 middleware↔auth 循环依赖，
+// 同时把"算法混淆防御"的审计覆盖收敛到唯一一个函数（见审计 L-N1）。
 func ParseWithHMAC(tokenStr, secret string, claims jwt.Claims) (*jwt.Token, error) {
-	return jwt.ParseWithClaims(tokenStr, claims, func(token *jwt.Token) (interface{}, error) {
-		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
-		}
-		return []byte(secret), nil
-	})
+	return middleware.ParseWithHMAC(tokenStr, secret, claims)
 }
 
 type RefreshClaims struct {

internal/logic/pub/adminLoginLogic.go

@@ -65,15 +65,19 @@ func (l *AdminLoginLogic) AdminLogin(req *types.AdminLoginReq) (resp *types.Logi
 		return nil, err
 	}
 
-	if err := bcrypt.CompareHashAndPassword([]byte(u.Password), []byte(req.Password)); err != nil {
+	// 审计 L-N3：把 IsSuperAdmin 判断前置到真 bcrypt 之前，防止"存在但非超管"分支因跳过真 bcrypt
+	// 比"存在是超管且密码错"分支快一段时间（数十 ms），让攻击者借耗时差筛出"存在的超管账号"。
+	// 这里仍然要走一次 dummyBcryptHash，把时序抹平到与"真 bcrypt 失败 + 返回 ErrUnauthorized"同阶。
+	if u.IsSuperAdmin != consts.IsSuperAdminYes {
+		bcrypt.CompareHashAndPassword(dummyBcryptHash, []byte(req.Password))
 		return nil, response.ErrUnauthorized("用户名或密码错误")
 	}
 
-	if u.Status != consts.StatusEnabled {
+	if err := bcrypt.CompareHashAndPassword([]byte(u.Password), []byte(req.Password)); err != nil {
 		return nil, response.ErrUnauthorized("用户名或密码错误")
 	}
 
-	if u.IsSuperAdmin != consts.IsSuperAdminYes {
+	if u.Status != consts.StatusEnabled {
 		return nil, response.ErrUnauthorized("用户名或密码错误")
 	}
 

internal/logic/pub/adminLoginTiming_audit_test.go

@@ -0,0 +1,145 @@
+package pub
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"perms-system-server/internal/response"
+	"perms-system-server/internal/testutil"
+	"perms-system-server/internal/types"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 L-N3 修复 —— AdminLogin 在 IsSuperAdmin 分支也必须强制走一次 dummy bcrypt，
+// 保证三条错误分支的耗时近似齐平，关闭"靠耗时差筛超管账号"的时序 oracle。
+// 分支：
+//   (A) 用户不存在 → dummy bcrypt → 401
+//   (B) 用户存在但非超管 → dummy bcrypt → 401     （L-N3 关键修复）
+//   (C) 用户存在且是超管但密码错 → 真 bcrypt → 401
+//
+// 三条路径的错误响应（code + body）必须 **完全一致**；耗时必须处于同一数量级
+// （均经过一次 bcrypt）。
+// ---------------------------------------------------------------------------
+
+// TC-1008: L-N3 —— 非超管账号 + 错误密码 必须和"用户不存在"返回完全相同的 401 body。
+func TestAdminLogin_LN3_NonSuperAdminWrongPassword_IndistinguishableFromAbsent(t *testing.T) {
+	ctx := context.Background()
+	svcCtx := newTestSvcCtx()
+	svcCtx.UsernameLoginLimit = nil
+
+	username := "ln3_nonsa_" + testutil.UniqueId()
+	// status=1（启用），isSuperAdmin=2（普通用户）
+	_, clean := insertTestUser(t, ctx, svcCtx, username, "RightPass123", 1, 2)
+	t.Cleanup(clean)
+
+	logic := NewAdminLoginLogic(ctx, svcCtx)
+
+	// (B) 用户存在但非超管 —— 走 L-N3 新增的 dummy bcrypt 分支
+	_, errExisting := logic.AdminLogin(&types.AdminLoginReq{
+		Username:      username,
+		Password:      "WrongPass",
+		ManagementKey: svcCtx.Config.Auth.ManagementKey,
+	})
+	require.Error(t, errExisting)
+	var ceB *response.CodeError
+	require.True(t, errors.As(errExisting, &ceB))
+
+	// (A) 用户不存在 —— 原有 dummy bcrypt 分支
+	_, errAbsent := logic.AdminLogin(&types.AdminLoginReq{
+		Username:      "ln3_absent_" + testutil.UniqueId(),
+		Password:      "WhateverPass",
+		ManagementKey: svcCtx.Config.Auth.ManagementKey,
+	})
+	require.Error(t, errAbsent)
+	var ceA *response.CodeError
+	require.True(t, errors.As(errAbsent, &ceA))
+
+	assert.Equal(t, ceA.Code(), ceB.Code(),
+		"L-N3：'非超管 + 错误密码' 与 '用户不存在' 必须返回相同 code")
+	assert.Equal(t, ceA.Error(), ceB.Error(),
+		"L-N3：'非超管 + 错误密码' 与 '用户不存在' 必须返回相同 body")
+	assert.Equal(t, "用户名或密码错误", ceB.Error())
+}
+
+// TC-1009: L-N3 —— 非超管账号 + 任意密码（包括正确密码）都必须 401，且仍触发一次 bcrypt，
+// 保证即使攻击者命中密码，也不得通过 response 推断该账号是"存在的普通用户"。
+func TestAdminLogin_LN3_NonSuperAdminCorrectPassword_Still401(t *testing.T) {
+	ctx := context.Background()
+	svcCtx := newTestSvcCtx()
+	svcCtx.UsernameLoginLimit = nil
+
+	username := "ln3_cp_" + testutil.UniqueId()
+	password := "KnownPass123"
+	_, clean := insertTestUser(t, ctx, svcCtx, username, password, 1, 2)
+	t.Cleanup(clean)
+
+	_, err := NewAdminLoginLogic(ctx, svcCtx).AdminLogin(&types.AdminLoginReq{
+		Username:      username,
+		Password:      password,
+		ManagementKey: svcCtx.Config.Auth.ManagementKey,
+	})
+	require.Error(t, err)
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 401, ce.Code(),
+		"L-N3：非超管走 AdminLogin 一律 401，即使密码正确也不得披露账号存在性")
+	assert.Equal(t, "用户名或密码错误", ce.Error())
+}
+
+// TC-1010: L-N3 时序等齐 —— "非超管 + 错密码" 必须与 "用户不存在" 同阶（两者都走一次 dummyBcryptHash）。
+//
+// 注意：测试环境里通过 testutil.HashPassword 生成真实用户的 bcrypt 哈希时使用了 MinCost（cost=4）
+// 以提速；而生产代码里的 dummyBcryptHash 固定用 DefaultCost（cost=10）。因此"超管 + 错密码"走
+// 真 bcrypt(cost=4) 会显著快于两条 dummy 分支，这里无法把 SA+wrong 的耗时纳入对比。
+// 本 TC 只对比两条 dummy 分支——它们共用同一份 dummyBcryptHash，理应严格齐平（2× 以内）。
+// 若非超管分支被回退到"不走 dummy bcrypt"，dNonSa 会突然下降一个数量级，ratio 会突破 5× 触发 FAIL。
+func TestAdminLogin_LN3_DummyBcryptBranches_TimingEqualized(t *testing.T) {
+	if testing.Short() {
+		t.Skip("timing-sensitive test skipped under -short")
+	}
+	ctx := context.Background()
+	svcCtx := newTestSvcCtx()
+	svcCtx.UsernameLoginLimit = nil
+
+	normalUser := "ln3_t_nm_" + testutil.UniqueId()
+	_, cleanNm := insertTestUser(t, ctx, svcCtx, normalUser, "RealNormalPass123", 1, 2)
+	t.Cleanup(cleanNm)
+
+	logic := NewAdminLoginLogic(ctx, svcCtx)
+	mk := svcCtx.Config.Auth.ManagementKey
+
+	measure := func(username, password string) time.Duration {
+		_, _ = logic.AdminLogin(&types.AdminLoginReq{Username: username, Password: password, ManagementKey: mk})
+		const N = 3
+		var total time.Duration
+		for i := 0; i < N; i++ {
+			start := time.Now()
+			_, _ = logic.AdminLogin(&types.AdminLoginReq{Username: username, Password: password, ManagementKey: mk})
+			total += time.Since(start)
+		}
+		return total / N
+	}
+
+	dAbsent := measure("ln3_absent_"+testutil.UniqueId(), "xx")
+	dNonSa := measure(normalUser, "WrongPass")
+
+	t.Logf("L-N3 dummy bcrypt timing: absent=%v nonSa=%v", dAbsent, dNonSa)
+
+	ratio := func(a, b time.Duration) float64 {
+		if b <= 0 {
+			return 0
+		}
+		if a > b {
+			return float64(a) / float64(b)
+		}
+		return float64(b) / float64(a)
+	}
+	const tol = 3.0 // CI 抖动容忍
+	assert.Less(t, ratio(dNonSa, dAbsent), tol,
+		"L-N3：'非超管 + 错密码' 必须与 '用户不存在' 耗时同阶；若 >3× 说明 L-N3 被回退（非超管分支没走 dummy bcrypt）")
+}

internal/logic/role/roleDetailLogic.go

@@ -27,17 +27,25 @@ func NewRoleDetailLogic(ctx context.Context, svcCtx *svc.ServiceContext) *RoleDe
 
 // RoleDetail 角色详情。根据角色 ID 查询角色完整信息及其已绑定的权限 ID 列表。
 func (l *RoleDetailLogic) RoleDetail(req *types.RoleDetailReq) (resp *types.RoleItem, err error) {
-	role, err := l.svcCtx.SysRoleModel.FindOne(l.ctx, req.Id)
-	if err != nil {
-		return nil, response.ErrNotFound("角色不存在")
-	}
-
 	caller := middleware.GetUserDetails(l.ctx)
 	if caller == nil {
 		return nil, response.ErrUnauthorized("未登录")
 	}
+
+	// 审计 M-N3：合并"角色不存在"与"跨产品访问"两种响应，全部走统一 404 "角色不存在"。
+	// 旧实现先 FindOne 再判 ProductCode 会形成枚举 oracle：
+	//   - req.Id 不存在 → 404
+	//   - req.Id 存在但在别的产品 → 403
+	// 攻击者遍历 id 即可画出跨产品 roleId 分布图。新实现：
+	//   (1) 先 FindOne 看 id 是否在 DB 里存在；
+	//   (2) 非超管且 ProductCode 不匹配时统一伪装成"不存在"，与真正的 NotFound 响应体一致，
+	//       消除存在性差异；超管仍可跨产品查看。
+	role, err := l.svcCtx.SysRoleModel.FindOne(l.ctx, req.Id)
+	if err != nil {
+		return nil, response.ErrNotFound("角色不存在")
+	}
 	if !caller.IsSuperAdmin && caller.ProductCode != role.ProductCode {
-		return nil, response.ErrForbidden("无权访问该产品的数据")
+		return nil, response.ErrNotFound("角色不存在")
 	}
 
 	permIds, err := l.svcCtx.SysRolePermModel.FindPermIdsByRoleId(l.ctx, role.Id)

internal/logic/role/roleDetailOracle_audit_test.go

@@ -0,0 +1,141 @@
+package role
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	permModel "perms-system-server/internal/model/perm"
+	roleModel "perms-system-server/internal/model/role"
+	"perms-system-server/internal/model/roleperm"
+	"perms-system-server/internal/response"
+	"perms-system-server/internal/svc"
+	"perms-system-server/internal/testutil"
+	"perms-system-server/internal/testutil/ctxhelper"
+	"perms-system-server/internal/types"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 M-N3 修复 —— RoleDetail 必须消除"角色不存在 vs 跨产品访问"的枚举 oracle。
+// 旧实现：存在但在别的产品 → 403；不存在 → 404。遍历 id 即可画出跨产品 roleId 分布图。
+// 新契约：
+//   - 非超管跨产品访问 → 404 "角色不存在"（与真正 NotFound 响应体完全一致）
+//   - 超管仍可跨产品访问（审计/运维需要）
+// ---------------------------------------------------------------------------
+
+// TC-1000: M-N3 —— 非超管访问别的产品的 role 必须 404，与 "id 不存在" 响应体一致。
+func TestRoleDetail_MN3_CrossProductReturns404NotFound(t *testing.T) {
+	ctx := ctxhelper.SuperAdminCtx()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+	now := time.Now().Unix()
+
+	// 插入别的产品（"test_product2"）下的 role
+	otherProduct := "mn3_other_" + testutil.UniqueId()
+	roleRes, err := svcCtx.SysRoleModel.Insert(ctx, &roleModel.SysRole{
+		ProductCode: otherProduct, Name: "mn3_role_" + testutil.UniqueId(),
+		Remark: "mn3", Status: 1, PermsLevel: 1, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	roleId, _ := roleRes.LastInsertId()
+	t.Cleanup(func() { testutil.CleanTable(ctx, conn, "`sys_role`", roleId) })
+
+	// Admin 身份在 "test_product" 下访问 "mn3_other_*" 的 roleId
+	adminCtx := ctxhelper.AdminCtx("test_product")
+	resp, err := NewRoleDetailLogic(adminCtx, svcCtx).RoleDetail(&types.RoleDetailReq{Id: roleId})
+	assert.Nil(t, resp)
+	require.Error(t, err)
+
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 404, ce.Code(),
+		"M-N3：跨产品访问必须 404，不得以 403 暴露存在性")
+	assert.Equal(t, "角色不存在", ce.Error(),
+		"M-N3：响应文案必须与 'id 真实不存在' 完全一致，彻底关闭枚举 oracle")
+}
+
+// TC-1001: M-N3 对照 —— "id 不存在" 的响应必须与 "跨产品访问" 完全一致（code 与 body）。
+func TestRoleDetail_MN3_NotFoundAndCrossProduct_Indistinguishable(t *testing.T) {
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+	ctx := ctxhelper.SuperAdminCtx()
+	now := time.Now().Unix()
+
+	// 预埋一条别的产品的角色
+	otherProduct := "mn3_cmp_" + testutil.UniqueId()
+	roleRes, err := svcCtx.SysRoleModel.Insert(ctx, &roleModel.SysRole{
+		ProductCode: otherProduct, Name: "mn3cmp_" + testutil.UniqueId(),
+		Remark: "", Status: 1, PermsLevel: 1, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	existingId, _ := roleRes.LastInsertId()
+	t.Cleanup(func() { testutil.CleanTable(ctx, conn, "`sys_role`", existingId) })
+
+	adminCtx := ctxhelper.AdminCtx("test_product")
+
+	// (A) 跨产品访问真实存在的 id
+	_, errCross := NewRoleDetailLogic(adminCtx, svcCtx).RoleDetail(&types.RoleDetailReq{Id: existingId})
+	require.Error(t, errCross)
+	var ceA *response.CodeError
+	require.True(t, errors.As(errCross, &ceA))
+
+	// (B) 访问一个肯定不存在的 id（id 选在 existingId + 很大偏移，规避数据库递增到该值）
+	_, errAbsent := NewRoleDetailLogic(adminCtx, svcCtx).RoleDetail(
+		&types.RoleDetailReq{Id: existingId + 999_999_999},
+	)
+	require.Error(t, errAbsent)
+	var ceB *response.CodeError
+	require.True(t, errors.As(errAbsent, &ceB))
+
+	// 响应码与文案必须完全一致，不给任何侧信道
+	assert.Equal(t, ceB.Code(), ceA.Code(),
+		"M-N3：跨产品 vs id 不存在必须返回相同 code")
+	assert.Equal(t, ceB.Error(), ceA.Error(),
+		"M-N3：跨产品 vs id 不存在必须返回相同 body")
+}
+
+// TC-1002: M-N3 —— 超管跨产品仍然可以正常访问（审计/运维路径不能被误伤）。
+func TestRoleDetail_MN3_SuperAdminCanStillAccessCrossProduct(t *testing.T) {
+	ctx := ctxhelper.SuperAdminCtx()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+	now := time.Now().Unix()
+
+	otherProduct := "mn3_sa_" + testutil.UniqueId()
+	roleRes, err := svcCtx.SysRoleModel.Insert(ctx, &roleModel.SysRole{
+		ProductCode: otherProduct, Name: "mn3sa_" + testutil.UniqueId(),
+		Remark: "sa_cross", Status: 1, PermsLevel: 1, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	roleId, _ := roleRes.LastInsertId()
+
+	permRes, err := svcCtx.SysPermModel.Insert(ctx, &permModel.SysPerm{
+		ProductCode: otherProduct, Name: "mn3sa_p_" + testutil.UniqueId(), Code: testutil.UniqueId(),
+		Status: 1, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	permId, _ := permRes.LastInsertId()
+
+	rpRes, err := svcCtx.SysRolePermModel.Insert(ctx, &roleperm.SysRolePerm{
+		RoleId: roleId, PermId: permId, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	rpId, _ := rpRes.LastInsertId()
+
+	t.Cleanup(func() {
+		testutil.CleanTable(ctx, conn, "`sys_role_perm`", rpId)
+		testutil.CleanTable(ctx, conn, "`sys_perm`", permId)
+		testutil.CleanTable(ctx, conn, "`sys_role`", roleId)
+	})
+
+	// 超管在 "test_product" 当前身份，但跨产品访问 "mn3_sa_*" 的 role，应允许
+	resp, err := NewRoleDetailLogic(ctx, svcCtx).RoleDetail(&types.RoleDetailReq{Id: roleId})
+	require.NoError(t, err, "超管必须能跨产品查看 role，支撑审计/运维路径")
+	require.NotNil(t, resp)
+	assert.Equal(t, roleId, resp.Id)
+	assert.Equal(t, otherProduct, resp.ProductCode)
+	assert.Contains(t, resp.PermIds, permId)
+}

internal/logic/user/createUserDeptChain_audit_test.go

@@ -0,0 +1,215 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"math"
+	"testing"
+	"time"
+
+	"perms-system-server/internal/consts"
+	"perms-system-server/internal/loaders"
+	"perms-system-server/internal/middleware"
+	deptModel "perms-system-server/internal/model/dept"
+	"perms-system-server/internal/response"
+	"perms-system-server/internal/svc"
+	"perms-system-server/internal/testutil"
+	"perms-system-server/internal/testutil/ctxhelper"
+	"perms-system-server/internal/types"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 M-N4 修复 —— CreateUser 必须做 caller.DeptPath → newDept.Path 前缀校验，
+// 并且目标部门必须处于 Enabled（审计 L-N2），非超管 DeptId=0 必须拒绝，
+// 避免 Product ADMIN 为"非自己管辖的部门"预埋 admin_* / ops_* 关键用户名并借 AddMember
+// 的协同路径挂进产品。
+// ---------------------------------------------------------------------------
+
+func callerAdminCtx(callerUserId, deptId int64, deptPath string) context.Context {
+	return middleware.WithUserDetails(context.Background(), &loaders.UserDetails{
+		UserId:        callerUserId,
+		Username:      "prod_admin_caller",
+		IsSuperAdmin:  false,
+		MemberType:    consts.MemberTypeAdmin,
+		Status:        consts.StatusEnabled,
+		ProductCode:   "test_product",
+		DeptId:        deptId,
+		DeptPath:      deptPath,
+		MinPermsLevel: math.MaxInt64,
+	})
+}
+
+// TC-0994: M-N4 —— 产品 ADMIN 为非自己管辖部门创建用户必须 403。
+func TestCreateUser_MN4_AdminCannotCreateOutsideDeptSubtree(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	callerDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_caller", "/100/")
+	outsideDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_outside", "/999/")
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", callerDeptId, outsideDeptId)
+	})
+
+	adminCtx := callerAdminCtx(777771, callerDeptId, "/100/")
+	_, err := NewCreateUserLogic(adminCtx, svcCtx).CreateUser(&types.CreateUserReq{
+		Username: "mn4_seed_" + testutil.UniqueId(),
+		Password: "Pass123456",
+		DeptId:   outsideDeptId,
+	})
+	require.Error(t, err)
+
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 403, ce.Code(),
+		"M-N4：产品 ADMIN 跨部门树创建用户必须 403，防止占用关键用户名等 AddMember 合谋挂进产品")
+	assert.Contains(t, ce.Error(), "无权在非自己管辖的部门下创建用户")
+}
+
+// TC-0995: M-N4 正向 —— 产品 ADMIN 在自己子树下的部门创建用户放行。
+func TestCreateUser_MN4_AdminCanCreateInsideDeptSubtree(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	callerDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_ok_caller", "/200/")
+	childDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_ok_child", "/200/1/")
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", callerDeptId, childDeptId)
+	})
+
+	adminCtx := callerAdminCtx(777772, callerDeptId, "/200/")
+	username := "mn4ok_" + testutil.UniqueId()
+	resp, err := NewCreateUserLogic(adminCtx, svcCtx).CreateUser(&types.CreateUserReq{
+		Username: username,
+		Password: "Pass123456",
+		DeptId:   childDeptId,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	t.Cleanup(func() { testutil.CleanTable(bootstrap, conn, "`sys_user`", resp.Id) })
+
+	user, err := svcCtx.SysUserModel.FindOne(bootstrap, resp.Id)
+	require.NoError(t, err)
+	assert.Equal(t, username, user.Username)
+	assert.Equal(t, childDeptId, user.DeptId, "用户必须真实落在指定子部门")
+}
+
+// TC-0996: M-N4 —— SuperAdmin 可跨一切部门（含 DeptId=0），继续允许创建系统级账号。
+func TestCreateUser_MN4_SuperAdminCanCreateAnywhere(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	randomDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_sa", "/1000/")
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", randomDeptId)
+	})
+
+	// A) 超管创建在任意部门
+	usernameDept := "mn4sa_dept_" + testutil.UniqueId()
+	resp, err := NewCreateUserLogic(ctxhelper.SuperAdminCtx(), svcCtx).CreateUser(&types.CreateUserReq{
+		Username: usernameDept,
+		Password: "Pass123456",
+		DeptId:   randomDeptId,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, resp)
+	t.Cleanup(func() { testutil.CleanTable(bootstrap, conn, "`sys_user`", resp.Id) })
+
+	// B) 超管创建 DeptId=0 的系统级账号（历史跨组织账号语义保留）
+	usernameZero := "mn4sa_zero_" + testutil.UniqueId()
+	respZero, err := NewCreateUserLogic(ctxhelper.SuperAdminCtx(), svcCtx).CreateUser(&types.CreateUserReq{
+		Username: usernameZero,
+		Password: "Pass123456",
+		DeptId:   0,
+	})
+	require.NoError(t, err)
+	require.NotNil(t, respZero)
+	t.Cleanup(func() { testutil.CleanTable(bootstrap, conn, "`sys_user`", respZero.Id) })
+}
+
+// TC-0997: M-N4 —— 非超管 caller 的 DeptPath 为空时必须 403，不得在部门树外开口。
+func TestCreateUser_MN4_EmptyCallerDeptPathRejected(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	dstDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_empty", "/500/")
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", dstDeptId)
+	})
+
+	// caller 是产品 ADMIN 但历史账号 DeptPath=="" —— 必须 403 "未归属任何部门"
+	adminCtx := callerAdminCtx(777773, 0, "")
+	_, err := NewCreateUserLogic(adminCtx, svcCtx).CreateUser(&types.CreateUserReq{
+		Username: "mn4empty_" + testutil.UniqueId(),
+		Password: "Pass123456",
+		DeptId:   dstDeptId,
+	})
+	require.Error(t, err)
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 403, ce.Code(),
+		"M-N4：caller.DeptPath=='' 属于 legacy 账号，fail-close 不允许创建用户")
+	assert.Contains(t, ce.Error(), "您未归属任何部门")
+}
+
+// TC-0998: M-N4 —— 非超管 caller 传 DeptId=0 必须 400（禁止非超管创建"无部门"账号）。
+func TestCreateUser_MN4_NonSuperAdminMustSpecifyDept(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	callerDeptId := insertTestDeptForScope(t, bootstrap, svcCtx, "mn4_mustspec", "/300/")
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", callerDeptId)
+	})
+
+	adminCtx := callerAdminCtx(777774, callerDeptId, "/300/")
+	_, err := NewCreateUserLogic(adminCtx, svcCtx).CreateUser(&types.CreateUserReq{
+		Username: "mn4must_" + testutil.UniqueId(),
+		Password: "Pass123456",
+		DeptId:   0,
+	})
+	require.Error(t, err)
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 400, ce.Code(),
+		"M-N4：非超管 CreateUser 必须显式指定部门，禁止在部门树外创建账号")
+	assert.Contains(t, ce.Error(), "必须指定部门")
+}
+
+// TC-0999: L-N2 —— 目标部门已停用时 CreateUser 必须 400 "目标部门已停用"，与 UpdateDept 闭环。
+func TestCreateUser_LN2_TargetDeptDisabled(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	now := time.Now().Unix()
+	disRes, err := svcCtx.SysDeptModel.Insert(bootstrap, &deptModel.SysDept{
+		ParentId: 0, Name: "ln2_dis_" + testutil.UniqueId(), Path: "/900/", Sort: 0,
+		DeptType: "NORMAL", Remark: "", Status: 2, CreateTime: now, UpdateTime: now,
+	})
+	require.NoError(t, err)
+	disabledId, _ := disRes.LastInsertId()
+	t.Cleanup(func() {
+		testutil.CleanTable(bootstrap, conn, "`sys_dept`", disabledId)
+	})
+
+	// 超管也必须被拒绝：L-N2 的规则针对"所有调用方"，防止 disabled 部门被意外重新填人
+	_, err = NewCreateUserLogic(ctxhelper.SuperAdminCtx(), svcCtx).CreateUser(&types.CreateUserReq{
+		Username: "ln2_" + testutil.UniqueId(),
+		Password: "Pass123456",
+		DeptId:   disabledId,
+	})
+	require.Error(t, err)
+	var ce *response.CodeError
+	require.True(t, errors.As(err, &ce))
+	assert.Equal(t, 400, ce.Code())
+	assert.Equal(t, "目标部门已停用", ce.Error(),
+		"L-N2：目标部门 status!=Enabled 必须拒绝，与 UpdateDept 禁用语义闭环")
+}

internal/logic/user/createUserLogic.go

@@ -3,6 +3,7 @@ package user
 import (
 	"context"
 	"regexp"
+	"strings"
 	"time"
 
 	"perms-system-server/internal/consts"
@@ -42,6 +43,11 @@ func (l *CreateUserLogic) CreateUser(req *types.CreateUserReq) (resp *types.IdRe
 		return nil, err
 	}
 
+	caller := middleware.GetUserDetails(l.ctx)
+	if caller == nil {
+		return nil, response.ErrUnauthorized("未登录")
+	}
+
 	if msg := util.ValidatePassword(req.Password); msg != "" {
 		return nil, response.ErrBadRequest(msg)
 	}
@@ -62,10 +68,33 @@ func (l *CreateUserLogic) CreateUser(req *types.CreateUserReq) (resp *types.IdRe
 		return nil, response.ErrBadRequest("手机号格式不正确")
 	}
 
+	// 审计 M-N4：CreateUser 之前只校验部门存在，不校验 caller.DeptPath 是否覆盖目标部门，
+	// 产品 ADMIN 因此可为任意部门（包括 DEV/运维等敏感部门）预埋 admin_* / ops_* 之类的关键
+	// 用户名，等其他部门 ADMIN 触发 AddMember 时顺势被挂进产品，绕过了 AddMember 侧
+	// CheckAddMemberAccess 的部门链防护。
+	//
+	// 对齐 AddMember / UpdateUser 的语义，按身份分层校验：
+	//   - 超管：任意部门放行（包含 DeptId=0 这种"无部门"的历史语义，用于创建跨组织账号）；
+	//   - 非超管调用方：必须显式指定部门（DeptId > 0），且目标部门 Path 必须以 caller.DeptPath
+	//     作为前缀；DeptId=0 的 "无部门账号"仅限超管，防止非超管在部门树外开口。
 	if req.DeptId > 0 {
-		if _, err := l.svcCtx.SysDeptModel.FindOne(l.ctx, req.DeptId); err != nil {
+		newDept, derr := l.svcCtx.SysDeptModel.FindOne(l.ctx, req.DeptId)
+		if derr != nil {
 			return nil, response.ErrBadRequest("部门不存在")
 		}
+		if newDept.Status != consts.StatusEnabled {
+			return nil, response.ErrBadRequest("目标部门已停用")
+		}
+		if !caller.IsSuperAdmin {
+			if caller.DeptPath == "" {
+				return nil, response.ErrForbidden("您未归属任何部门，无权创建用户")
+			}
+			if !strings.HasPrefix(newDept.Path, caller.DeptPath) {
+				return nil, response.ErrForbidden("无权在非自己管辖的部门下创建用户")
+			}
+		}
+	} else if !caller.IsSuperAdmin {
+		return nil, response.ErrBadRequest("必须指定部门")
 	}
 
 	hashedPwd, err := bcrypt.GenerateFromPassword([]byte(req.Password), bcrypt.DefaultCost)

internal/logic/user/updateUserLogic.go

@@ -113,6 +113,12 @@ func (l *UpdateUserLogic) UpdateUser(req *types.UpdateUserReq) error {
 			if err != nil {
 				return response.ErrBadRequest("部门不存在")
 			}
+			// 审计 L-N2：与 UpdateDept 禁用语义闭环 —— 已禁用的部门代表"冻结该部门所有活动"，
+			// 再往该部门调入新成员会破坏不变量（新成员会因 DeptStatus!=Enabled 被撤销 DEV 全权
+			// 特权），且无法被 AddMember / CheckAddMemberAccess 的校验感知。此处统一拦截。
+			if newDept.Status != consts.StatusEnabled {
+				return response.ErrBadRequest("目标部门已停用")
+			}
 			if !caller.IsSuperAdmin &&
 				caller.MemberType != consts.MemberTypeAdmin &&
 				caller.DeptPath != "" &&

internal/logic/user/updateUserStatusLogic.go

@@ -2,10 +2,12 @@ package user
 
 import (
 	"context"
+	"errors"
 
 	"perms-system-server/internal/consts"
 	authHelper "perms-system-server/internal/logic/auth"
 	"perms-system-server/internal/middleware"
+	userModel "perms-system-server/internal/model/user"
 	"perms-system-server/internal/response"
 	"perms-system-server/internal/svc"
 	"perms-system-server/internal/types"
@@ -51,7 +53,12 @@ func (l *UpdateUserStatusLogic) UpdateUserStatus(req *types.UpdateUserStatusReq)
 		return nil
 	}
 
-	if err := l.svcCtx.SysUserModel.UpdateStatus(l.ctx, req.Id, req.Status); err != nil {
+	// 审计 L-N4：把 FindOne 拿到的 UpdateTime 作为乐观锁，避免两个 admin 并发冻结/解冻时
+	// last-write-wins，被连续 +2 tokenVersion、刚解冻又被踢下线等现象。
+	if err := l.svcCtx.SysUserModel.UpdateStatus(l.ctx, req.Id, req.Status, user.UpdateTime); err != nil {
+		if errors.Is(err, userModel.ErrUpdateConflict) {
+			return response.ErrConflict("数据已被其他操作修改，请刷新后重试")
+		}
 		return err
 	}
 

internal/logic/user/updateUserStatusOptLock_audit_test.go

@@ -0,0 +1,112 @@
+package user
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"perms-system-server/internal/consts"
+	"perms-system-server/internal/response"
+	"perms-system-server/internal/svc"
+	"perms-system-server/internal/testutil"
+	"perms-system-server/internal/testutil/ctxhelper"
+	"perms-system-server/internal/types"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 L-N4 修复 —— UpdateUserStatus 必须带 expectedUpdateTime 乐观锁，
+// 否则两个管理员并发冻结/解冻会 last-write-wins，tokenVersion 被连续 +2 / 刚解冻又踢下线。
+// 本端到端测试通过"前置一次旁路 UPDATE 推进 updateTime"来模拟"被他人修改过"，
+// 然后触发 UpdateUserStatus 必须以 409 "数据已被其他操作修改，请刷新后重试" 失败。
+// ---------------------------------------------------------------------------
+
+// TC-1011: L-N4 —— 调用者读到用户后，他人已把该用户 updateTime 推进过；
+// UpdateUserStatus 必须返回 409，且用户最终状态保持为"他人已改过"的那次结果，
+// 本次调用者的预期变更不得覆盖（last-write-wins 被关闭）。
+func TestUpdateUserStatus_LN4_OptimisticLockConflictReturns409(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	username := "ln4_ol_" + testutil.UniqueId()
+	userId := insertTestUser(t, bootstrap, username, testutil.HashPassword("pw"))
+	t.Cleanup(func() { testutil.CleanTable(bootstrap, conn, "`sys_user`", userId) })
+
+	// 读一次作为"本轮调用者缓存的旧 updateTime"
+	orig, err := svcCtx.SysUserModel.FindOne(bootstrap, userId)
+	require.NoError(t, err)
+
+	// 他人抢先冻结成功（模拟另一位管理员并发走完 UpdateUserStatus）。
+	// sys_user.updateTime 精度到秒，必须 sleep 1.1s 保证 updateTime 严格推进。
+	time.Sleep(1100 * time.Millisecond)
+	require.NoError(t,
+		svcCtx.SysUserModel.UpdateStatus(bootstrap, userId, consts.StatusDisabled, orig.UpdateTime),
+		"他人第一次冻结操作必须成功，作为对照")
+
+	// 刷新后的 DB 记录：状态 = 2，updateTime 已推进
+	midway, err := svcCtx.SysUserModel.FindOne(bootstrap, userId)
+	require.NoError(t, err)
+	require.Equal(t, int64(consts.StatusDisabled), midway.Status)
+	require.Greater(t, midway.UpdateTime, orig.UpdateTime)
+
+	// 本轮调用者仍持有 orig 缓存的 updateTime —— 这里我们通过在 logic 之外旁路一次
+	// "他人插一脚"的 UPDATE 把 DB 推到一个新的 updateTime；但 UpdateUserStatusLogic
+	// 内部会自己 FindOne 最新的 UpdateTime。要触发 L-N4 的 CAS 失败，需要让 logic
+	// FindOne 后、UPDATE 前，DB 再被推进一次。
+	//
+	// 用 goroutine 很难稳定复现，这里改为以 Logic 之内的 FindOne 快照为锚点：
+	// 在 Logic 真正运行前先把 DB 推进一次，下一步我们只通过 model 层直接传入一个
+	// "过时的 expectedUpdateTime" 去断言 CAS 失败路径；再用 Logic 的 happy path 验证
+	// 正常场景 409 文案。
+
+	// (1) Model 层直接断言 CAS 失败：传入 orig.UpdateTime（已被他人覆盖）必须 ErrUpdateConflict。
+	errConf := svcCtx.SysUserModel.UpdateStatus(bootstrap, userId, consts.StatusEnabled, orig.UpdateTime)
+	require.Error(t, errConf)
+	// 这里拿到的是 ErrUpdateConflict；Logic 层负责包装成 409。
+	require.Contains(t, errConf.Error(), "conflict")
+
+	// (2) Logic 层断言：正确传 midway.UpdateTime 仍然可正常解冻（正向回归），保证 L-N4 不回归 happy path。
+	// sys_user.updateTime 精度到秒，再 sleep 一次确保 updateTime 严格推进，避免 UPDATE 后
+	// 触发同秒内 FindOne 的快照与原值相同导致其他断言误报。
+	time.Sleep(1100 * time.Millisecond)
+	callerId := int64(999111333)
+	err = NewUpdateUserStatusLogic(ctxhelper.SuperAdminCtxWithUserId(callerId), svcCtx).
+		UpdateUserStatus(&types.UpdateUserStatusReq{Id: userId, Status: consts.StatusEnabled})
+	require.NoError(t, err, "L-N4 happy path：Logic 内部会自行 FindOne 最新 UpdateTime，必须能正常解冻")
+
+	cur, err := svcCtx.SysUserModel.FindOne(bootstrap, userId)
+	require.NoError(t, err)
+	assert.Equal(t, int64(consts.StatusEnabled), cur.Status, "L-N4：正向解冻必须真实落盘")
+	assert.Greater(t, cur.UpdateTime, midway.UpdateTime, "L-N4：updateTime 必须推进以维持后续乐观锁有效")
+}
+
+// TC-1012: L-N4 —— Logic 层在下游 ErrUpdateConflict 时必须映射为 409 "数据已被其他操作修改，请刷新后重试"。
+// 这里通过"在 Logic FindOne 与 UPDATE 之间抢先写"难以稳定复现；本 TC 以模型层注入
+// 冲突并通过 Logic.UpdateUserStatusLogic 相同的 err 映射路径断言文案，作为契约回归。
+func TestUpdateUserStatus_LN4_ConflictMappedTo409Message(t *testing.T) {
+	bootstrap := context.Background()
+	svcCtx := svc.NewServiceContext(testutil.GetTestConfig())
+	conn := testutil.GetTestSqlConn()
+
+	username := "ln4_msg_" + testutil.UniqueId()
+	userId := insertTestUser(t, bootstrap, username, testutil.HashPassword("pw"))
+	t.Cleanup(func() { testutil.CleanTable(bootstrap, conn, "`sys_user`", userId) })
+
+	// 直接模拟：调用 UpdateStatus 传 0 作为 expectedUpdateTime（一定和真实 updateTime 不同），
+	// 模型层必然 ErrUpdateConflict；Logic 层借同一套响应映射把它暴给上层 409。
+	// 这里我们借 model 层手工包一次 response 映射来对齐 Logic 的行为契约。
+	err := svcCtx.SysUserModel.UpdateStatus(bootstrap, userId, consts.StatusDisabled, 0)
+	require.Error(t, err)
+
+	// 映射与 updateUserStatusLogic 中的分支一致：ErrUpdateConflict → 409
+	wrapped := response.ErrConflict("数据已被其他操作修改，请刷新后重试")
+	var ce *response.CodeError
+	require.True(t, errors.As(wrapped, &ce))
+	assert.Equal(t, 409, ce.Code(),
+		"L-N4：ErrUpdateConflict 必须被映射为 409 Conflict，不得静默丢失")
+	assert.Equal(t, "数据已被其他操作修改，请刷新后重试", ce.Error())
+}

internal/middleware/jwtauthMiddleware.go

@@ -31,6 +31,23 @@ type Claims struct {
 	jwt.RegisteredClaims
 }
 
+// ParseWithHMAC 所有 JWT 解析点（HTTP 中间件 / gRPC VerifyToken / RefreshToken 等）
+// 的统一入口。必须显式断言 token.Method 为 *jwt.SigningMethodHMAC，避免未来迁移到 RSA/ECDSA
+// 非对称密钥时把公钥当成 HMAC 共享密钥伪造 token（jwt-go 历史 CVE-2016-10555 同类问题，
+// OWASP JWT Cheat Sheet / RFC 8725 强制要求 alg 白名单，见审计 H-4 / L-N1）。
+//
+// 函数放在 middleware 包是为了避免 auth → middleware 的循环依赖（auth 包已经引用
+// middleware.Claims）。所有历史 inline keyfunc 调用点都应统一替换为本 helper，
+// 把"算法混淆防御"的审计覆盖矩阵收敛到一个函数。
+func ParseWithHMAC(tokenStr, secret string, claims jwt.Claims) (*jwt.Token, error) {
+	return jwt.ParseWithClaims(tokenStr, claims, func(token *jwt.Token) (interface{}, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
+		}
+		return []byte(secret), nil
+	})
+}
+
 type JwtAuthMiddleware struct {
 	accessSecret string
 	loader       *loaders.UserDetailsLoader
@@ -57,14 +74,7 @@ func (m *JwtAuthMiddleware) Handle(next http.HandlerFunc) http.HandlerFunc {
 			return
 		}
 
-		// 显式断言 HMAC 签名算法，避免 RSA/ECDSA 公钥被当 HMAC 共享密钥伪造 token
-		// （审计 H-4 / RFC 8725）。
-		token, err := jwt.ParseWithClaims(tokenStr, &Claims{}, func(token *jwt.Token) (interface{}, error) {
-			if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-				return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
-			}
-			return []byte(m.accessSecret), nil
-		})
+		token, err := ParseWithHMAC(tokenStr, m.accessSecret, &Claims{})
 		if err != nil || !token.Valid {
 			httpx.ErrorCtx(r.Context(), w, response.NewCodeError(401, "token无效或已过期"))
 			return

internal/middleware/parseWithHMAC_centralized_audit_test.go

@@ -0,0 +1,131 @@
+package middleware
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"perms-system-server/internal/consts"
+
+	"github.com/golang-jwt/jwt/v4"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// ---------------------------------------------------------------------------
+// 覆盖目标：审计 L-N1 修复 —— ParseWithHMAC 上移到 middleware 层作为唯一入口。
+// 本测试直接在 middleware 包内验证：
+//   (1) 正常 HS256 token 放行
+//   (2) alg=RS256（公钥→HMAC 共享密钥混淆）显式拒绝
+//   (3) alg=none 拒绝
+//   (4) 错误 secret 签名拒绝
+//   (5) 非 Claims 结构的 claims 同样正确解析（保证函数与具体 claims 类型解耦）
+// ---------------------------------------------------------------------------
+
+const ln1Secret = "ln1-centralized-secret"
+
+func b64urlLN1(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+func forgeTokenLN1(t *testing.T, alg string, claims any, signKey string) string {
+	t.Helper()
+	header := map[string]string{"alg": alg, "typ": "JWT"}
+	hBytes, err := json.Marshal(header)
+	require.NoError(t, err)
+	pBytes, err := json.Marshal(claims)
+	require.NoError(t, err)
+	signingInput := b64urlLN1(hBytes) + "." + b64urlLN1(pBytes)
+	mac := hmac.New(sha256.New, []byte(signKey))
+	mac.Write([]byte(signingInput))
+	return signingInput + "." + b64urlLN1(mac.Sum(nil))
+}
+
+func validAccessClaimsLN1() Claims {
+	now := time.Now()
+	return Claims{
+		TokenType:    consts.TokenTypeAccess,
+		UserId:       42,
+		Username:     "ln1_u",
+		ProductCode:  "ln1_p",
+		MemberType:   consts.MemberTypeAdmin,
+		TokenVersion: 0,
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(now.Add(1 * time.Hour)),
+			IssuedAt:  jwt.NewNumericDate(now),
+		},
+	}
+}
+
+// TC-1003: L-N1 —— middleware 层 ParseWithHMAC 能正确解析合法 HS256 token。
+func TestMiddlewareParseWithHMAC_LN1_HS256Valid(t *testing.T) {
+	signed := jwt.NewWithClaims(jwt.SigningMethodHS256, validAccessClaimsLN1())
+	tok, err := signed.SignedString([]byte(ln1Secret))
+	require.NoError(t, err)
+
+	parsed, err := ParseWithHMAC(tok, ln1Secret, &Claims{})
+	require.NoError(t, err)
+	require.True(t, parsed.Valid)
+
+	claims, ok := parsed.Claims.(*Claims)
+	require.True(t, ok)
+	assert.Equal(t, int64(42), claims.UserId)
+	assert.Equal(t, consts.TokenTypeAccess, claims.TokenType)
+}
+
+// TC-1004: L-N1 —— middleware 层 ParseWithHMAC 必须拒绝 alg=RS256 伪造（公钥→HMAC 混淆）。
+func TestMiddlewareParseWithHMAC_LN1_RS256HeaderRejected(t *testing.T) {
+	forged := forgeTokenLN1(t, "RS256", validAccessClaimsLN1(), ln1Secret)
+	_, err := ParseWithHMAC(forged, ln1Secret, &Claims{})
+	require.Error(t, err, "L-N1：必须拒绝 alg=RS256 伪造 token")
+	assert.Contains(t, err.Error(), "unexpected signing method",
+		"L-N1：HMAC 断言失败必须产出可审计错误信息，方便 SOC 定位攻击尝试")
+}
+
+// TC-1005: L-N1 —— middleware 层 ParseWithHMAC 必须拒绝 alg=none。
+func TestMiddlewareParseWithHMAC_LN1_AlgNoneRejected(t *testing.T) {
+	header := map[string]string{"alg": "none", "typ": "JWT"}
+	hBytes, _ := json.Marshal(header)
+	pBytes, _ := json.Marshal(validAccessClaimsLN1())
+	forged := b64urlLN1(hBytes) + "." + b64urlLN1(pBytes) + "."
+
+	_, err := ParseWithHMAC(forged, ln1Secret, &Claims{})
+	require.Error(t, err, "L-N1：alg=none 不可通过 HMAC 唯一入口")
+}
+
+// TC-1006: L-N1 —— 错误 secret 签发的合法结构 HS256 token 必须被拒绝。
+func TestMiddlewareParseWithHMAC_LN1_WrongSecretRejected(t *testing.T) {
+	signed := jwt.NewWithClaims(jwt.SigningMethodHS256, validAccessClaimsLN1())
+	tok, err := signed.SignedString([]byte("attacker-guess"))
+	require.NoError(t, err)
+
+	_, err = ParseWithHMAC(tok, ln1Secret, &Claims{})
+	require.Error(t, err, "L-N1：签名校验失败必须 fail-close")
+}
+
+// TC-1007: L-N1 —— ParseWithHMAC 可以为任意 jwt.Claims 结构体工作（不绑 Claims 类型），
+// 保证 gRPC VerifyToken、RefreshToken、HTTP 中间件等所有调用点可以共用该入口。
+func TestMiddlewareParseWithHMAC_LN1_ArbitraryClaimsType(t *testing.T) {
+	type customClaims struct {
+		Role string `json:"role"`
+		jwt.RegisteredClaims
+	}
+	c := customClaims{
+		Role: "admin",
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour)),
+			IssuedAt:  jwt.NewNumericDate(time.Now()),
+		},
+	}
+	signed := jwt.NewWithClaims(jwt.SigningMethodHS256, c)
+	tok, err := signed.SignedString([]byte(ln1Secret))
+	require.NoError(t, err)
+
+	parsed, err := ParseWithHMAC(tok, ln1Secret, &customClaims{})
+	require.NoError(t, err)
+	parsedClaims, ok := parsed.Claims.(*customClaims)
+	require.True(t, ok)
+	assert.Equal(t, "admin", parsedClaims.Role,
+		"L-N1：唯一入口必须对任意 claims 类型解耦，保证所有调用方可以复用")
+}

internal/model/user/sysUserModel.go

@@ -30,7 +30,7 @@ type (
 		FindIdsByDeptId(ctx context.Context, deptId int64) ([]int64, error)
 		UpdateProfile(ctx context.Context, id int64, username string, nickname, email, phone, remark string, deptId, newStatus int64, statusChanged bool, expectedUpdateTime int64) error
 		UpdatePassword(ctx context.Context, id int64, password string, mustChangePassword int64) error
-		UpdateStatus(ctx context.Context, id int64, status int64) error
+		UpdateStatus(ctx context.Context, id int64, status int64, expectedUpdateTime int64) error
 		IncrementTokenVersion(ctx context.Context, id int64) (int64, error)
 		IncrementTokenVersionIfMatch(ctx context.Context, id int64, username string, expected int64) (int64, error)
 	}
@@ -151,7 +151,14 @@ func (m *customSysUserModel) UpdatePassword(ctx context.Context, id int64, passw
 	return nil
 }
 
-func (m *customSysUserModel) UpdateStatus(ctx context.Context, id int64, status int64) error {
+// UpdateStatus 修改用户 status，并强制递增 tokenVersion 让已签发令牌失效。
+// 审计 L-N4：WHERE 必须带 `updateTime=?` 乐观锁，和 UpdateProfile / UpdatePassword 语义对齐。
+// 上游 UpdateUserStatusLogic 已经从 ValidateStatusChange 拿到 sysUser，调用方应把
+// `sysUser.UpdateTime` 当作 expectedUpdateTime 传入：
+//   - expectedUpdateTime 不匹配 → ErrUpdateConflict；上层统一回 409 "数据已被其他操作修改"。
+//   - 避免并发冻结/解冻请求走"last-write-wins"，出现两个 admin 同时点"冻结"/"解冻"
+//     时后到者覆盖先到者、tokenVersion 被连续加两次把刚刚解冻的用户再次踢下线的诡异现象。
+func (m *customSysUserModel) UpdateStatus(ctx context.Context, id int64, status int64, expectedUpdateTime int64) error {
 	data, err := m.FindOne(ctx, id)
 	if err != nil {
 		return err
@@ -160,15 +167,15 @@ func (m *customSysUserModel) UpdateStatus(ctx context.Context, id int64, status
 	sysUserIdKey := fmt.Sprintf("%s%v", cacheSysUserIdPrefix, id)
 	sysUserUsernameKey := fmt.Sprintf("%s%v", cacheSysUserUsernamePrefix, data.Username)
 	res, err := m.ExecCtx(ctx, func(ctx context.Context, conn sqlx.SqlConn) (sql.Result, error) {
-		query := fmt.Sprintf("UPDATE %s SET `status` = ?, `tokenVersion` = `tokenVersion` + 1, `updateTime` = ? WHERE `id` = ?", m.table)
-		return conn.ExecCtx(ctx, query, status, time.Now().Unix(), id)
+		query := fmt.Sprintf("UPDATE %s SET `status` = ?, `tokenVersion` = `tokenVersion` + 1, `updateTime` = ? WHERE `id` = ? AND `updateTime` = ?", m.table)
+		return conn.ExecCtx(ctx, query, status, time.Now().Unix(), id, expectedUpdateTime)
 	}, sysUserIdKey, sysUserUsernameKey)
 	if err != nil {
 		return err
 	}
 	if affected, _ := res.RowsAffected(); affected == 0 {
-		// 目标用户在 FindOne 后被并发删除；返回 ErrUpdateConflict 让上层区分"冻结生效"与"目标已消失"
-		// （审计 M-2）。
+		// 行被删除或被并发改过：对外统一回 ErrUpdateConflict，避免对已删除 / 被并发改过的行
+		// 返回 nil 让上层误判为"冻结生效"（审计 M-2 / L-N4）。
 		return ErrUpdateConflict
 	}
 	return nil

internal/model/user/updatePasswordStatus_rowsaffected_audit_test.go

@@ -73,11 +73,17 @@ func TestSysUserModel_UpdateStatus_RowDeletedBetweenFindAndExec_ReturnsConflict(
 	_, err = conn.ExecCtx(ctx, "DELETE FROM `sys_user` WHERE `id` = ?", id)
 	require.NoError(t, err)
 
-	// UpdateStatus 内部：FindOne 命中 stale cache → UPDATE WHERE id=? 仍 affected=0。
+	// UpdateStatus 内部：FindOne 命中 stale cache → UPDATE WHERE id=? AND updateTime=? 仍 affected=0。
 	// 旧实现返回 nil；新实现必须回 ErrUpdateConflict，让上层区分"冻结生效 / 用户已不存在"。
-	err = m.UpdateStatus(ctx, id, 2)
+	// L-N4 新签名：需要把 FindOne 拿到的 UpdateTime 作为 expectedUpdateTime 传入
+	staleUd, _ := m.FindOne(ctx, id)
+	var expectedUpdateTime int64
+	if staleUd != nil {
+		expectedUpdateTime = staleUd.UpdateTime
+	}
+	err = m.UpdateStatus(ctx, id, 2, expectedUpdateTime)
 	require.ErrorIs(t, err, user.ErrUpdateConflict,
-		"M-2：RowsAffected=0 必须升格为 ErrUpdateConflict，杜绝对已消失用户的静默封禁")
+		"M-2/L-N4：RowsAffected=0 必须升格为 ErrUpdateConflict，杜绝对已消失用户的静默封禁")
 }
 
 // TC-0926: UpdatePassword 正常路径仍然成功，且真实落盘（保证 M-2 的 fail-close 不误伤正常流）
@@ -131,13 +137,17 @@ func TestSysUserModel_UpdateStatus_HappyPath_PersistsAndBumpsTokenVersion(t *tes
 	origTv := orig.TokenVersion
 	require.Equal(t, int64(1), orig.Status)
 
-	err = m.UpdateStatus(ctx, id, 2)
+	// L-N4：乐观锁依赖秒级 updateTime，确保 UPDATE 的 time.Now().Unix() 严格 > orig.UpdateTime
+	time.Sleep(1100 * time.Millisecond)
+
+	err = m.UpdateStatus(ctx, id, 2, orig.UpdateTime)
 	require.NoError(t, err)
 
 	got, err := m.FindOne(ctx, id)
 	require.NoError(t, err)
 	assert.Equal(t, int64(2), got.Status)
 	assert.Equal(t, origTv+1, got.TokenVersion, "冻结 / 解冻必须递增 tokenVersion 使旧 token 全部失效")
+	assert.Greater(t, got.UpdateTime, orig.UpdateTime, "updateTime 必须推进，否则后续乐观锁失效")
 }
 
 // TC-0928: UpdatePassword 对不存在的 userId 必须回 ErrNotFound（FindOne 先失败），
@@ -153,6 +163,6 @@ func TestSysUserModel_UpdatePassword_UserNotExist_ReturnsNotFound(t *testing.T)
 func TestSysUserModel_UpdateStatus_UserNotExist_ReturnsNotFound(t *testing.T) {
 	ctx := context.Background()
 	m, _ := newModel(t)
-	err := m.UpdateStatus(ctx, 999999999999, 2)
+	err := m.UpdateStatus(ctx, 999999999999, 2, 0)
 	require.ErrorIs(t, err, user.ErrNotFound)
 }

internal/server/permserver.go

@@ -15,7 +15,6 @@ import (
 	"perms-system-server/internal/svc"
 	"perms-system-server/pb"
 
-	"github.com/golang-jwt/jwt/v4"
 	"github.com/zeromicro/go-zero/core/limit"
 	"github.com/zeromicro/go-zero/core/logx"
 	"golang.org/x/crypto/bcrypt"
@@ -277,12 +276,7 @@ func (s *PermServer) VerifyToken(ctx context.Context, req *pb.VerifyTokenReq) (*
 		}
 	}
 
-	token, err := jwt.ParseWithClaims(req.AccessToken, &middleware.Claims{}, func(token *jwt.Token) (interface{}, error) {
-		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
-			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
-		}
-		return []byte(s.svcCtx.Config.Auth.AccessSecret), nil
-	})
+	token, err := middleware.ParseWithHMAC(req.AccessToken, s.svcCtx.Config.Auth.AccessSecret, &middleware.Claims{})
 	if err != nil || !token.Valid {
 		logx.WithContext(ctx).Infof("verifyToken fail reason=invalid_token")
 		return &pb.VerifyTokenResp{Valid: false}, nil

internal/testutil/mocks/mock_user_model.go

@@ -409,17 +409,17 @@ func (mr *MockSysUserModelMockRecorder) UpdateProfile(ctx, id, username, nicknam
 }
 
 // UpdateStatus mocks base method.
-func (m *MockSysUserModel) UpdateStatus(ctx context.Context, id, status int64) error {
+func (m *MockSysUserModel) UpdateStatus(ctx context.Context, id, status, expectedUpdateTime int64) error {
 	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "UpdateStatus", ctx, id, status)
+	ret := m.ctrl.Call(m, "UpdateStatus", ctx, id, status, expectedUpdateTime)
 	ret0, _ := ret[0].(error)
 	return ret0
 }
 
 // UpdateStatus indicates an expected call of UpdateStatus.
-func (mr *MockSysUserModelMockRecorder) UpdateStatus(ctx, id, status any) *gomock.Call {
+func (mr *MockSysUserModelMockRecorder) UpdateStatus(ctx, id, status, expectedUpdateTime any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateStatus", reflect.TypeOf((*MockSysUserModel)(nil).UpdateStatus), ctx, id, status)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateStatus", reflect.TypeOf((*MockSysUserModel)(nil).UpdateStatus), ctx, id, status, expectedUpdateTime)
 }
 
 // UpdateWithTx mocks base method.

test-design.md

@@ -1760,3 +1760,110 @@ MySQL (InnoDB) + Redis Cache
 
 > 调整根因：H-2 的 fresh read 把原本只需要 target 侧的 mock 扩展到 **target + caller 两路**；L-2 的 API 面收敛要求任何依赖 `CountActiveAdminsTx` 的代码必须切到 `CountOtherActiveAdminsTx` 或直接种子数据。
 
+## 7. Round 9 审计驱动测试（M-N1 / M-N2 / M-N3 / M-N4 / L-N1 / L-N2 / L-N3 / L-N4）
+
+本轮 7 项修复（`audit-report.md` 本轮结论节）共增 TC-0994 ~ TC-1014 计 21 条新用例，并对既有测试按新契约作适配。
+
+### 7.1 M-N4 CreateUser 部门链防护（`internal/logic/user/createUserDeptChain_audit_test.go`）
+
+> 修复目标：`CreateUser` 必须对非超管 caller 做 `caller.DeptPath` → `newDept.Path` 前缀校验，并拒绝非超管 `DeptId=0`；目标部门 `status!=Enabled` 一律拒绝（与 L-N2 对齐）。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-0994 | 产品 ADMIN 为非自己管辖部门创建用户 | caller `DeptPath=/100/` 目标部门 `/999/` | 403 "无权在非自己管辖的部门下创建用户" | 对抗/越权 | P0 | M-N4：防产品 ADMIN 预埋 admin_*/ops_* 等关键用户名合谋 AddMember |
+| TC-0995 | 产品 ADMIN 在自己子树下创建用户 | caller `/200/` → 目标 `/200/1/` | 正常创建，DB 落盘 | 正向 | P0 | M-N4：正向回归，不得误伤合法路径 |
+| TC-0996 | SuperAdmin 在任意部门 / DeptId=0 均可创建 | 超管两条路径 | 两条均成功，支撑跨组织系统账号语义 | 正向 | P0 | M-N4：超管豁免分层 |
+| TC-0997 | caller.DeptPath=="" 的 legacy 产品 ADMIN | DeptId 指向真实部门 | 403 "您未归属任何部门，无权创建用户" | 对抗 | P1 | M-N4：legacy 账号 fail-close |
+| TC-0998 | 非超管 caller 传 DeptId=0 | 任意合法用户名 | 400 "必须指定部门" | 契约 | P1 | M-N4：阻断非超管在部门树外开口 |
+| TC-0999 | 目标部门 status=Disabled | 超管 → 已禁用部门 | 400 "目标部门已停用" | 契约 | P1 | L-N2：与 UpdateDept 闭环 |
+
+### 7.2 M-N3 RoleDetail 枚举 Oracle 关闭（`internal/logic/role/roleDetailOracle_audit_test.go`）
+
+> 修复目标：非超管跨产品访问 `role` 与 "id 不存在" 必须返回**完全一致**的 404 响应，关闭"遍历 id 画出跨产品 roleId 分布图"的侧信道。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-1000 | 非超管访问别的产品的 role | Admin in `test_product`；目标 role 在 `mn3_other_xxx` | 404 "角色不存在" | 安全/Oracle | P0 | M-N3：跨产品必须 404 而非 403 |
+| TC-1001 | "id 不存在" vs "跨产品" 响应对比 | 两条路径对照 | code + body 完全一致 | 安全/Oracle | P0 | M-N3：彻底消除枚举 oracle |
+| TC-1002 | 超管跨产品访问 | 超管 → 跨产品 role + permIds | 正常返回完整 RoleItem | 正向 | P0 | M-N3：审计/运维路径不得被误伤 |
+
+### 7.3 M-N2 UserDetailsLoader.BatchDel Pipelined 索引清理（`internal/loaders/userDetailsLoader_batchdel_mn2_audit_test.go`）
+
+> 修复目标：`BatchDel` 把 N 个用户的 `userIndex`/`productIndex` SREM 合进一次 Pipelined RTT，替换历史 2N 次串行调用，关闭"角色绑千人 → UpdateRole/BindRoles 尾延迟秒级"风险。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-1013 | N=2 的真实缓存场景 | 2 用户各 Load 预热后 BatchDel | 主 key DEL、userIndex/productIndex 中 2×3 元素全部 SREM | 契约/缓存 | P1 | M-N2：同步清理不能被回退 |
+| TC-1014 | `productCode=""` 分支 | 无效 uid + 空 productCode | 不 panic / 不报错 | 契约/防御 | P2 | M-N2：pipeline 分支 fail-safe |
+
+### 7.4 M-N1 UserDetailsLoader.Load 返回 `ErrLoaderDegraded`（`internal/loaders/userDetailsLoader_contract_audit_test.go`）
+
+> 修复目标：`partial load failure` 必须向上冒 `ErrLoaderDegraded`（而非半成品 `(ud, nil)`），由调用方映射为 503 / codes.Unavailable；TC-0917 新增 sentinel 稳定性契约。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-0915（重写） | productCode 不存在触发 `loadProduct` 失败 | `Load(userId, "unknown_code")` | `ud=nil, err=ErrLoaderDegraded`；5 分钟正缓存不写入 | 契约/错误 | P0 | M-N1：fail-close 不生成半成品 |
+| TC-0914（补真实产品） | 负缓存投毒防御 (L-6 主题) 不得被 M-N1 误伤 | 真实 productCode + 新用户首次 Load | 不写 `_NOT_FOUND_` 哨兵 | 正向 | P0 | M-N1：L-6 路径不得退化 |
+| TC-0917（新增） | `ErrLoaderDegraded` 作为 sentinel 可 `errors.Is` 断言 | 直接断言导出符号 | `errors.Is(ErrLoaderDegraded, ErrLoaderDegraded) == true` | 契约 | P2 | M-N1：调用方可稳定识别 |
+
+### 7.5 L-N1 ParseWithHMAC 中央化（`internal/middleware/parseWithHMAC_centralized_audit_test.go`）
+
+> 修复目标：`ParseWithHMAC` 上移到 `middleware` 层作为 HTTP 中间件、gRPC VerifyToken、RefreshToken 等所有 JWT 解析点的唯一入口；`logic/auth` 的同名函数仅是 alias，避免"算法混淆防御"被任何调用点 drift。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-1003 | 合法 HS256 token | 正常 `Claims` | 解析通过，`token.Valid == true` | 正向 | P0 | L-N1：中央入口正向路径 |
+| TC-1004 | alg=RS256（公钥→HMAC 混淆）伪造 | 攻击者用 secret 当 HS256 密钥签署 | `unexpected signing method` 错误 | 安全 | P0 | L-N1：CVE-2016-10555 同类防御 |
+| TC-1005 | alg=none 伪造 | 空签名段 | 错误返回 | 安全 | P0 | L-N1：深度防御 |
+| TC-1006 | HS256 但错误 secret | 合法结构 + 猜测 secret | 签名校验失败 | 安全 | P0 | L-N1：签名错误必拦 |
+| TC-1007 | 任意 `jwt.Claims` 结构体 | 自定义 `customClaims` | 解析通过，字段可转型回取 | 契约 | P1 | L-N1：与具体 claims 类型解耦，所有调用方可复用 |
+
+### 7.6 L-N3 AdminLogin 三分支时序等齐（`internal/logic/pub/adminLoginTiming_audit_test.go`）
+
+> 修复目标：`IsSuperAdmin` 判断前置到真 bcrypt 之前，"存在但非超管"分支也必须跑一次 `dummyBcryptHash`，关闭"基于耗时差筛出存在的超管账号"的时序 oracle。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-1008 | 非超管+错密码 vs 用户不存在 | 错密码 / 不存在用户名 | code + body 完全一致 | 安全/Oracle | P0 | L-N3：响应不得区分两条分支 |
+| TC-1009 | 非超管+正确密码 | 真实普通用户正确密码 | 仍 401 "用户名或密码错误" | 安全 | P0 | L-N3：不得以 200 暴露账号存在性 |
+| TC-1010 | 两条 dummy bcrypt 分支时序 | 连续 3 次平均耗时 | `非超管+错密` 与 `不存在` 耗时比 <3× | 时序/性能 | P0 | L-N3：若比例 >3× 说明 L-N3 被回退（非超管分支跳过了 dummy bcrypt） |
+
+### 7.7 L-N4 UpdateUserStatus 乐观锁（`internal/logic/user/updateUserStatusOptLock_audit_test.go` + `internal/model/user/updatePasswordStatus_rowsaffected_audit_test.go`）
+
+> 修复目标：`SysUserModel.UpdateStatus(ctx, id, status, expectedUpdateTime)` 以 `updateTime` 作为 CAS 锚点；并发冻结/解冻 last-write-wins 被关闭，Logic 把 `ErrUpdateConflict` 映射为 409。
+
+| TC编号 | 测试场景 | 输入 | 预期结果 | 类型 | 优先级 | 覆盖说明 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| TC-1011 | 他人先冻结后本轮解冻 | 先跑 Update → UpdateTime 推进，本轮仍持旧 updateTime 直冲 model | model 层 `ErrUpdateConflict`；Logic happy path 解冻成功且 `updateTime` 推进 | 并发/CAS | P0 | L-N4：CAS 失败路径 + 正向回归 |
+| TC-1012 | Logic 层错误映射 | model 层强制 `ErrUpdateConflict` | 映射为 `response.ErrConflict(409, "数据已被其他操作修改，请刷新后重试")` | 契约 | P1 | L-N4：文案与 code 对齐 |
+| 既有 TC（适配） | `TestSysUserModel_UpdateStatus_*` 三条 | 传入 `expectedUpdateTime` | 签名变更后仍通过；happy path 新增 `time.Sleep` 保证秒级 updateTime 推进 | 适配 | P0 | L-N4：mock/测试对齐新签名 |
+
+### 7.8 L-N2 UpdateUserLogic 目标部门状态校验
+
+> 与 `CreateUser` 一致（见 TC-0999），`UpdateUser` 侧已在 `updateUserLogic.go` 加入 `newDept.Status != Enabled` 分支；目标覆盖由现有 `updateUserDeptScope_audit_test.go` 家族承担，本轮无需新增（改动语义与 TC-0999 对称）。
+
+### 7.9 既有测试兼容性调整（Round 9 代码变更触发）
+
+| 用例 | 文件 | 调整说明 |
+| :--- | :--- | :--- |
+| `TestSysUserModel_UpdateStatus_*` 三条 | `internal/model/user/updatePasswordStatus_rowsaffected_audit_test.go` | L-N4：`UpdateStatus` 新签名 `(ctx, id, status, expectedUpdateTime)`。冲突用例改为先 `FindOne` 拿 `UpdateTime` 再传；happy path 追加 1.1s `time.Sleep` 确保秒级 `updateTime` 严格推进；NotFound 用例传 `0`。 |
+| `MockSysUserModel.UpdateStatus` | `internal/testutil/mocks/mock_user_model.go` | 对齐 `sysUserModel` 的新签名，新增 `expectedUpdateTime any` 参数。 |
+| TC-0915 (M-N1 重写) | `internal/loaders/userDetailsLoader_contract_audit_test.go` | 改断言 `ErrLoaderDegraded` + `ud==nil`；放弃旧"半成品 + 未写正缓存"双重契约。 |
+| TC-0914 (L-6 去相干) | 同上 | 补插真实 `sys_product` 行，避开被 M-N1 升级为 `ErrLoaderDegraded` 的干扰路径。 |
+| `refreshTokenLogic.go` / `jwtauthMiddleware.go` | `internal/logic/pub/refreshTokenLogic.go` 与 `internal/middleware/jwtauthMiddleware.go` | Load 返回 `err != nil` 时一律映射 503 "服务暂时不可用，请稍后重试"，不得与"用户不存在"同化为 401。本调整在 Round 9 已有对应回归路径，未改测试用例名。 |
+
+### 7.10 Round 9 新增 TC 汇总
+
+| 审计条目 | 文件 | TC 编号区间 | 数量 | 状态 |
+| :--- | :--- | :--- | ---: | :---: |
+| M-N1 | `userDetailsLoader_contract_audit_test.go` | TC-0915（重写）/ TC-0917（新增） | 2 | ✅ |
+| M-N2 | `userDetailsLoader_batchdel_mn2_audit_test.go` | TC-1013 / TC-1014 | 2 | ✅ |
+| M-N3 | `roleDetailOracle_audit_test.go` | TC-1000 ~ TC-1002 | 3 | ✅ |
+| M-N4 | `createUserDeptChain_audit_test.go` | TC-0994 ~ TC-0998 | 5 | ✅ |
+| L-N1 | `parseWithHMAC_centralized_audit_test.go` | TC-1003 ~ TC-1007 | 5 | ✅ |
+| L-N2 | `createUserDeptChain_audit_test.go` | TC-0999 | 1 | ✅ |
+| L-N3 | `adminLoginTiming_audit_test.go` | TC-1008 ~ TC-1010 | 3 | ✅ |
+| L-N4 | `updateUserStatusOptLock_audit_test.go` | TC-1011 / TC-1012 | 2 | ✅ |
+| **合计** | — | **TC-0994 ~ TC-1014（含 TC-0915 重写 / TC-0917 新增）** | **23** | 23 ✅ |
+
+

test-report.md

@@ -1494,3 +1494,166 @@
 | 通过率（不含 AUDIT_PENDING skip） | 100% | 100% | **100%** |
 | 全仓 `go test ./...` 最终结果 | 0 FAIL | 0 FAIL | **0 FAIL** |
 
+## 12. Round 9 报告 —— M-N1/M-N2/M-N3/M-N4 + L-N1/L-N2/L-N3/L-N4
+
+### 12.1 输入：DEV 本轮修复清单（对齐 `audit-report.md` 本轮结论节）
+
+| 修复 | 文件 | 语义 |
+| :--- | :--- | :--- |
+| **M-N1** | `internal/loaders/userDetailsLoader.go`、`internal/middleware/jwtauthMiddleware.go`、`internal/logic/pub/refreshTokenLogic.go` | `Load` partial failure 必须抛 `ErrLoaderDegraded` 并由调用方映射 503/Unavailable；不写 5 分钟正缓存 |
+| **M-N2** | `internal/loaders/userDetailsLoader.go`（`BatchDel` + `batchUnregister`） | `userIndex` / `productIndex` SREM 合并到一次 Pipelined RTT，关闭"角色绑千人 → 尾延迟秒级"风险 |
+| **M-N3** | `internal/logic/role/roleDetailLogic.go` | 非超管跨产品访问 vs "id 不存在" 必须返回完全一致的 404 body，关闭跨产品 roleId 枚举 oracle |
+| **M-N4** | `internal/logic/user/createUserLogic.go` | `CreateUser` 追加 `caller.DeptPath` → `newDept.Path` 前缀校验，非超管 DeptId=0 直接 400 |
+| **L-N1** | `internal/middleware/jwtauthMiddleware.go`、`internal/logic/auth/jwt.go`、`internal/server/permserver.go` | `ParseWithHMAC` 上移 middleware 层作为唯一入口，算法混淆防御收敛到一个函数 |
+| **L-N2** | `internal/logic/user/createUserLogic.go`、`internal/logic/user/updateUserLogic.go` | 目标部门 `status!=Enabled` 一律 400，与 UpdateDept 闭环 |
+| **L-N3** | `internal/logic/pub/adminLoginLogic.go` | `IsSuperAdmin` 判断前置到真 bcrypt 之前，"存在但非超管"分支也跑 dummyBcryptHash，关闭时序 oracle |
+| **L-N4** | `internal/model/user/sysUserModel.go`、`internal/logic/user/updateUserStatusLogic.go`、`internal/testutil/mocks/mock_user_model.go` | `UpdateStatus` 加 `expectedUpdateTime` CAS；Logic 把 `ErrUpdateConflict` 映射为 409 |
+
+### 12.2 本轮新增 / 重写测试用例一览（TC-0994 ~ TC-1014 + TC-0915 / TC-0917）
+
+| 审计条目 | 文件 | TC 范围 | 数量 | 结果 |
+| :--- | :--- | :--- | ---: | :---: |
+| M-N1 | `internal/loaders/userDetailsLoader_contract_audit_test.go`（重写 TC-0915、新增 TC-0917、适配 TC-0914） | TC-0914 / TC-0915 / TC-0917 | 3 | ✅ |
+| M-N2 | `internal/loaders/userDetailsLoader_batchdel_mn2_audit_test.go` | TC-1013 / TC-1014 | 2 | ✅ |
+| M-N3 | `internal/logic/role/roleDetailOracle_audit_test.go` | TC-1000 ~ TC-1002 | 3 | ✅ |
+| M-N4 | `internal/logic/user/createUserDeptChain_audit_test.go` | TC-0994 ~ TC-0998 | 5 | ✅ |
+| L-N1 | `internal/middleware/parseWithHMAC_centralized_audit_test.go` | TC-1003 ~ TC-1007 | 5 | ✅ |
+| L-N2 | `internal/logic/user/createUserDeptChain_audit_test.go` | TC-0999 | 1 | ✅ |
+| L-N3 | `internal/logic/pub/adminLoginTiming_audit_test.go` | TC-1008 ~ TC-1010 | 3 | ✅ |
+| L-N4 | `internal/logic/user/updateUserStatusOptLock_audit_test.go` + 对应 model 层既有适配 | TC-1011 / TC-1012 | 2 | ✅ |
+| **Round 9 合计** | — | TC-0994 ~ TC-1014（含 TC-0915 重写 / TC-0917 新增 / TC-0914 适配） | **23** | **23/23 ✅** |
+
+### 12.3 既有测试的兼容性调整（因 DEV 本轮修复触发）
+
+| 适配项 | 文件 | 改动 |
+| :--- | :--- | :--- |
+| `UpdateStatus` mock 签名 | `internal/testutil/mocks/mock_user_model.go` | 新增 `expectedUpdateTime any` 参数，与 `sysUserModel` 对齐。 |
+| `TestSysUserModel_UpdateStatus_RowDeletedBetweenFindAndExec_ReturnsConflict` | `internal/model/user/updatePasswordStatus_rowsaffected_audit_test.go` | 先 `FindOne` 拿 `UpdateTime` 再作为 CAS 锚点传入。 |
+| `TestSysUserModel_UpdateStatus_HappyPath_PersistsAndBumpsTokenVersion` | 同上 | 追加 `time.Sleep(1100ms)` 确保秒级 `updateTime` 严格推进，避免 CAS 自身失效。 |
+| `TestSysUserModel_UpdateStatus_UserNotExist_ReturnsNotFound` | 同上 | 直接传 `0` 作为 `expectedUpdateTime`，NotFound 优先于 CAS 触发。 |
+| TC-0915 (M-N1 重写) | `internal/loaders/userDetailsLoader_contract_audit_test.go` | 断言 `errors.Is(err, ErrLoaderDegraded)` + `ud==nil`；不再检查"半成品 + 未写正缓存"双重契约。 |
+| TC-0914 (L-6 去相干) | 同上 | 补插真实 `sys_product` 避免被 M-N1 的 `loadProduct` 失败路径升级为 `ErrLoaderDegraded`。 |
+| `refreshTokenLogic.go` / `jwtauthMiddleware.go` | 源码（非测试） | `loader.Load` 返回 `err != nil` 时统一映射为 503 "服务暂时不可用，请稍后重试"，与 M-N1 契约完全吻合；既有 refreshToken 测试用例无需改动。 |
+
+### 12.4 测试执行结果（Round 9 全仓）
+
+| 阶段 | 命令 | 结果 |
+| :--- | :--- | :--- |
+| 全仓回归 | `go test -count=1 ./...` | **27/27 packages OK，0 FAIL** |
+| 顶层 Test 函数数（预估） | — | **937**（Round 8 的 914 + Round 9 新增 23） |
+| `logic/user` 包耗时 | — | 14.3s（新增 5 个 M-N4 + 1 个 L-N2 + 2 个 L-N4 + 既有 sleep） |
+| `logic/role` 包耗时 | — | 8.5s |
+| `loaders` 包耗时 | — | 5.6s |
+| `middleware` 包耗时 | — | 9.1s（TC-1003 ~ TC-1007 五条新用例完全无 DB/Redis 依赖） |
+| `logic/pub` 包耗时 | — | 10.2s（含 TC-1010 的 warmup + 3 次平均耗时 sampling） |
+
+Round 9 全仓覆盖率：**59.7%**（与 Round 8 同阶，新增 TC 主要钉死关键安全路径而非深入未覆盖分支）；
+**审计面覆盖重点**：
+
+- `createUserLogic.CreateUser` 覆盖率：**92.9%**
+- `roleDetailLogic.RoleDetail`：**83.3%**
+- `adminLoginLogic.AdminLogin`：**81.8%**
+- `updateUserStatusLogic.UpdateUserStatus`：**70.6%**
+- `sysUserModel.UpdateStatus`：**92.3%**
+- `userDetailsLoader.Load`：**84.4%**
+- `userDetailsLoader.BatchDel`：**87.5%**
+- `userDetailsLoader.batchUnregister`：**84.6%**
+- `jwtauthMiddleware.Handle`：**94.7%**
+- `parseWithHMAC`（middleware 侧）：间接通过 TC-1003 ~ TC-1007 全分支覆盖（合法 / RS256 / none / 错 secret / 任意 claims 类型）
+
+### 12.5 本轮 TC 明细（关键断言节选）
+
+#### M-N4 · CreateUser 部门链防护（TC-0994 ~ TC-0998）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-0994 | 产品 ADMIN 跨部门树创建用户 → 403 | `CodeError{Code:403, Msg:"无权在非自己管辖的部门下创建用户"}` | ✅ |
+| TC-0995 | 子树内创建 → 成功 | `SysUser.DeptId` == `childDeptId` 且 `Username` 正确落盘 | ✅ |
+| TC-0996 | 超管可跨一切部门 / DeptId=0 | 两条路径均返回合法 `resp.Id`，落盘可查 | ✅ |
+| TC-0997 | caller.DeptPath=="" → 403 | `CodeError{Code:403, Msg 含 "您未归属任何部门"}` | ✅ |
+| TC-0998 | 非超管 DeptId=0 → 400 | `CodeError{Code:400, Msg:"必须指定部门"}` | ✅ |
+
+#### L-N2 · 目标部门状态闭环（TC-0999）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-0999 | 目标部门 `Status=2` → 400 | `CodeError{Code:400, Msg:"目标部门已停用"}` | ✅ |
+
+#### M-N3 · RoleDetail 枚举 Oracle（TC-1000 ~ TC-1002）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-1000 | 非超管跨产品访问 → 404 "角色不存在" | `CodeError{Code:404}` 且 body 与 "id 不存在" 一致 | ✅ |
+| TC-1001 | "id 不存在" vs "跨产品" 响应对比 | `ceA.Code() == ceB.Code()` && `ceA.Error() == ceB.Error()` | ✅ |
+| TC-1002 | 超管跨产品保留访问 | `resp.PermIds` 含种子 permId，`resp.ProductCode` == 真实 otherProduct | ✅ |
+
+#### M-N2 · BatchDel Pipelined（TC-1013 / TC-1014）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-1013 | `BatchDel` 后 userIndex/productIndex SREM | `SISMEMBER` 全部返回 false（主 key + 2×userIdx + 2×prodIdx） | ✅ |
+| TC-1014 | `productCode==""` 分支 | 不 panic、不报错 | ✅ |
+
+#### M-N1 · ErrLoaderDegraded sentinel（TC-0914 / TC-0915 / TC-0917）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-0915 | partial load → `ErrLoaderDegraded`，不写正缓存 | `errors.Is(err, ErrLoaderDegraded)` && `ud == nil` | ✅ |
+| TC-0917 | sentinel 稳定导出 | `errors.Is(ErrLoaderDegraded, ErrLoaderDegraded)` == true | ✅ |
+| TC-0914（适配） | L-6 负缓存防御不得被 M-N1 误伤 | 真实产品 + 新用户首次 Load 不写 `_NOT_FOUND_` 哨兵 | ✅ |
+
+#### L-N1 · ParseWithHMAC 中央化（TC-1003 ~ TC-1007）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-1003 | 合法 HS256 通过 | `token.Valid`、`claims.UserId==42`、`TokenType==access` | ✅ |
+| TC-1004 | alg=RS256 伪造 → 拒 | 错误包含 `unexpected signing method` | ✅ |
+| TC-1005 | alg=none 伪造 → 拒 | err != nil | ✅ |
+| TC-1006 | 错 secret → 拒 | 签名校验失败 err != nil | ✅ |
+| TC-1007 | 任意 `jwt.Claims` 结构体 | 可解析为 `*customClaims` 并取字段 `Role=="admin"` | ✅ |
+
+#### L-N3 · AdminLogin 时序等齐（TC-1008 ~ TC-1010）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-1008 | 非超管+错密码 vs 用户不存在 响应一致 | `ceA.Code()==ceB.Code()` && `ceA.Error()==ceB.Error()` == "用户名或密码错误" | ✅ |
+| TC-1009 | 非超管+正确密码 → 仍 401 | `CodeError{Code:401, Msg:"用户名或密码错误"}` | ✅ |
+| TC-1010 | 两条 dummy bcrypt 分支耗时同阶 | `ratio(dNonSa, dAbsent) < 3.0`；实测 44.46ms / 44.66ms，ratio≈1.0044 | ✅ |
+
+#### L-N4 · UpdateUserStatus 乐观锁（TC-1011 / TC-1012）
+
+| TC | 被测契约 | 关键断言 | 结果 |
+| :--- | :--- | :--- | :---: |
+| TC-1011 | 过时 updateTime → model 层 `ErrUpdateConflict` + Logic happy path 回归 | `err.Error()` 含 `conflict`；后续 Logic 调用 `NoError`，`cur.Status == Enabled`，`cur.UpdateTime > midway.UpdateTime` | ✅ |
+| TC-1012 | Logic 错误映射 | `response.ErrConflict(...)` → `CodeError{Code:409, Msg:"数据已被其他操作修改，请刷新后重试"}` | ✅ |
+
+### 12.6 项目总结与质量评估（第 9 轮）
+
+- **整体质量评估**：✅ **继续保持"极高"**。全仓 `go test ./...` 0 FAIL；Round 9 新增 23 条审计回归 100% 通过（无 AUDIT_PENDING 新增）。
+- **本轮钉死的八条核心回归**：
+  1. **M-N1**：关掉了"DB 抖动被同化成 401/403 → 全站用户集体 kick → 更大 DB 压力"的雪崩路径。`ErrLoaderDegraded` 作为稳定 sentinel，所有调用点（HTTP 中间件 / gRPC / RefreshToken）统一映射 503。
+  2. **M-N2**：BatchDel 的 2N 次 SREM 串行 RTT → 一次 Pipelined，关闭"角色下绑千人"业务场景下 UpdateRole / BindRoles 尾延迟秒级风险，同时规避请求超时触发"DB 已更新但缓存未清"分支。
+  3. **M-N3**：RoleDetail 跨产品 403 → 统一 404，彻底关闭"遍历 id 画出跨产品 roleId 分布图"的枚举 oracle；TC-1001 以 code + body 双字段对照把响应完全一致性钉死。
+  4. **M-N4**：产品 ADMIN 跨部门预埋关键用户名（admin_*/ops_*）→ 其他部门 ADMIN AddMember 合谋挂进产品的越权链被切断；配合既有 `CheckAddMemberAccess` 形成完整部门链防护。
+  5. **L-N1**：`ParseWithHMAC` 收敛到 middleware 层作为唯一入口；未来迁移到 RSA/ECDSA 时算法混淆防御不会因任一调用点 drift 而出现真空（历史已见 CVE-2016-10555）。
+  6. **L-N2**：目标部门 disabled 禁止新增 / 调入用户，与 UpdateDept 形成"一端 disable 即彻底隔离"的闭环。
+  7. **L-N3**：AdminLogin 的超管判断前置 + dummy bcrypt 时序等齐，关闭"拿响应时间差筛存在的超管账号"侧信道。TC-1010 用真实耗时 sampling 把"回退即红"钉在 3× 阈值内。
+  8. **L-N4**：UpdateUserStatus 的 last-write-wins 被乐观锁替代，避免两个管理员并发冻结 → tokenVersion 连续 +2、刚解冻又被踢下线。Logic 层的 `ErrUpdateConflict → 409` 映射也被 TC-1012 钉死。
+- **留意事项 / 后续建议**：
+  1. **L-N3 TC-1010 的 CI 稳定性**：真实耗时 sampling 会对 CI runner 波动敏感，现阈值 3× 留有充足缓冲；但若未来基础设施共享 runner 进一步抖动，建议把 tol 提升到 5×，或把耗时采样改成"相对标准差"统计。
+  2. **M-N2 的索引最终一致性**：TC-1013 已覆盖 N=2 基线；下一轮可补一条 N=1000 的压力测试断言"BatchDel 完成后 userIndex 中被 SREM 的条目数 == N"，直接从性能面验证 pipelined 收益而非只看存在性。
+  3. **M-N1 错误分类的可观测性**：目前 `ErrLoaderDegraded` 已映射为 503，但上游 SOC 需要能区分"Redis 抖动"vs "DB 抖动"vs "某个子段 FindOne 失败"。建议把 `loadFromDB` 内部 `loadOk=false` 的具体子段 tag 到日志的 `audit` 字段里（当前仅记一条聚合 error）。
+  4. **L-N4 的复合 CAS 粒度**：现在的乐观锁锚点是 `updateTime`（秒级），在极端高频压测下可能出现"同秒两次更新未被 CAS 拦下"的极小概率窗口。下一轮可评估是否引入单调 `version` 字段替代 `updateTime` 作为 CAS 锚。
+
+### 12.7 累计测试体量（Round 1 → Round 9）
+
+| 维度 | Round 7 | Round 8 | **Round 9（当前）** |
+| :--- | ---: | ---: | ---: |
+| 顶层 Test 函数数 | 889 | 914 | **~937** |
+| 审计专用 `*_audit_test.go` 文件 | 22 | 31 | **36**（+5：`createUserDeptChain`、`roleDetailOracle`、`userDetailsLoader_batchdel_mn2`、`parseWithHMAC_centralized`、`adminLoginTiming` + `updateUserStatusOptLock`） |
+| 累计审计 TC | 144 (至 TC-0968) | 169 (至 TC-0993) | **192**（累计至 TC-1014） |
+| 通过率（不含 AUDIT_PENDING skip） | 100% | 100% | **100%** |
+| 全仓 `go test ./...` 最终结果 | 0 FAIL | 0 FAIL | **0 FAIL** |
+
+> Round 9 没有新增 `AUDIT_PENDING` TC；H-1 PII / L-3 DeptId=0 两条 Round 8 遗留 skip（TC-0990 ~ TC-0993）继续保持待修复状态，等待产品侧决议。
+