权限三处维护说明

与 permission-api-unification.md、permission-matrix.md、permission-leaf-policy.md 配套。

三处分别是什么

位置	文件	职责
路由登记表	Acc：acc-route-permission-registry.ts（codegen，源为 @AccRoutePermission）；Sys：sys-route-permission-registry.ts（codegen，源为 @SysRoutePermission）	每个 @Post 路径 → read / write / admin 等规则；中间件双保险
Service 断言	assertAccReadPermission、assertAccWritePermission、assertSiteScope、assertAdmin	业务内二次校验；未登记路由仍依赖此处
种子 / 后台树	scripts/seed-sys-admin-permissions.mjs、PermissionsAdminView	Permission.code 与菜单/按钮；角色绑定

新增 Acc/Sys 接口时 至少：

1. Controller 增加 @Post 路由 + @AccRoutePermission（Acc）或 @SysRoutePermission（Sys）
2. 执行 pnpm --filter taskflow-backend run codegen:acc-route-registry / codegen:sys-route-registry；再跑 check:route-registry
3. Service 内 assertAcc* / assertSiteScope（Acc）或 assertAdmin（Sys 管理）
4. 若为新能力码，在 seed 或权限树中增加 Permission 行并给默认角色勾选

代码入口（减少重复查库）

• 权限 code 集合：permission-resolver.ts → resolveUserPermissionCodes
• 网关鉴权头：load-user-gateway-claims.ts；带缓存：user-gateway-claims-cache.ts → loadUserGatewayClaimsCached
• 403 结构：acc-forbidden.ts → PERMISSION_DENIED + requiredPermissions
• 拒绝审计：permission-denied-audit.ts；Acc/Sys 路由中间件 warn 日志

CI

pnpm --filter taskflow-backend run verify 已包含：

• check:route-registry
• test:permission（集成测 + registry 单测 + claims 缓存单测）

预发

未登记路由在生产建议开 ACC_ROUTE_GUARD_STRICT / SYS_ROUTE_GUARD_STRICT；见 permission-staging-checklist.md。

实施：预置角色模板

新租户/预发建议先执行 pnpm --filter taskflow-backend run db:sync-roles-perms，再按 permission-role-templates.md 为用户绑定 MINI_RECORDER_READ / MINI_RECORDER_POST / MINI_WORKER 等，避免只勾目录却无 btn_* 写权限。

改角色或权限树后：用户须 重新登录；API 侧最长等待 GATEWAY_CLAIMS_CACHE_TTL（见 backend/.env.example 中 GATEWAY_CLAIMS_CACHE*）。