chore: record verification report and implementation divergence for rbac-refactor

docs/superpowers/specs/2026-07-02-rbac-refactor-design.md

@@ -701,3 +701,35 @@ User ↔ Role ↔ Permission            User ↔ Organization（数据级）
 - `Permission.code` 保持纯粹的操作定义（`module:action`），不混入数据范围
 - 后续数据级权限通过新增 `DataPolicy` 实体 + `@DataScope` 装饰器实现
 - `Role` 实体预留扩展空间，可关联数据策略
+
+## 12. 实现偏差记录 (Implementation Divergence)
+
+> 本节记录 build 阶段验证时发现的、与原始设计不一致但经确认可接受的实现偏差。
+
+### 12.1 PermissionGuard AND/OR 语义简化
+
+**设计 (Design Doc §4.2)**:
+```typescript
+// 嵌套 AND/OR: getAllAndOverride<string[][]> → 返回 [['A'], ['B','C']]
+// 外层 AND (every)，内层 OR (some)
+requiredPermissions.every(group => group.some(p => user.permissions.includes(p)))
+```
+
+**实现 (PermissionGuard)**:
+```typescript
+// 扁平 OR: getAllAndMerge<string[]> → 返回 ['A', 'B', 'C']
+// 仅 OR 匹配
+requiredPermissions.some(p => user.permissions.includes(p))
+```
+
+**偏差原因**: 当前所有接口均为单一 `@RequirePermission(...)` 调用，不涉及多次装饰器叠加的 AND 场景。扁平 OR 语义足以覆盖"一个接口需要多个权限中的任一即可访问"的需求，同时简化了匹配逻辑和调试成本。装饰器注释已标注"不支持 AND 语义：多次调用装饰器会被全局 PermissionGuard 合并为扁平数组"。
+
+**影响**: 无。当前无接口需要 AND 权限组合。若未来业务需要"同时满足多个权限才可访问"，届时再升级匹配算法（将 `getAllAndMerge` 改为 `getAllAndOverride` + 双层循环），向后兼容。
+
+### 12.2 权限点数量
+
+**设计文档声称** 42 个权限点，**实际实现** 52 个。差异来自：
+- 设计文档手动列举时遗漏 `occupancy:delete` 等权限点
+- 设计文档实际列举 51 个而非 42 个（计数偏差）
+
+所有 52 个权限点均符合 `module:action` 命名规范且与模块目录结构一致，实现正确。