digital-psychology/docs/BACKEND_DESIGN/BD-2026-013A-admin-rbac.md

Backend Design: ECR-013A Admin RBAC

Architect 产出；Contract Definition — Status Draft；Approve 前禁止实现。
Parent: WAVE0-FROZEN

Field	Value
ID	BD-2026-013A
ECR	ECR-013A
Change Level	L2
Status	Approved
Approved	2026-08-07（Human） · Coding authorized
Author	Architect
Date	2026-08-07
Risk	Medium

---

Context

• 目标：管理员角色/权限点 + API 强制鉴权 + 审计
• 非目标：UserStatus(013B)；真支付；UGC
• Spec：ops-rbac.md · boundary-rules Admin_RBAC

Architecture Change

• 分层边界：No
• 受影响层：API · Application(service/admin) · Infrastructure(repo+migration) · UI(admin-h5 最小)

Module Changes

Module	Layer	Change	Must NOT
admin repo/service	App/Infra	roles · permissions · account.role_id	改 users.status
middleware	API	RequirePermission	DeviceAuth 混用
admin handlers	API	/roles* · /me 扩展	Handler SQL
admin-h5	UI	读 permissions	直连 DB

Data Flow

Admin login → AdminSession
  → load AdminAccount + Role + Permissions
  → request + RequirePermission(code)
       → allow → service → audit
       → deny  → 403 + audit

API Changes

• 契约意图见 Spec；实现轮写 proto/openapi.yaml
• 兼容：additive；旧 admin 账号迁移到 super_admin

Database Changes

• Migration Required: YES（实现轮）
• 表：admin_roles · admin_role_permissions（或等价）· admin_accounts.role_id
• Wave 0 / Contract 轮：不写 migration 文件

Failure Handling

• 无权限：403
• 无会话：401
• 删 super_admin：4xx

Test Plan

• Integration：AC-F/S/O；AC-P-01 本机抽样
• 禁止跳过 Security AC

Rollback Plan

• down migration；middleware 开关（实现轮详写）

---

Backend Change Boundary

Change Level: L2
Change: Admin RBAC roles + permission gates

Affected:
  Domain: AdminRole, AdminPermission
  Application: service/admin
  Infrastructure: admin_repo + migration (implement phase)
  API: /admin/roles* , /admin/me
  Migration: Required at implement — NOT in contract phase
  Tests: integration admin RBAC
  Risk: Medium

Architecture Regression Check

• 无 Handler 直连 DB
• Admin / Device 鉴权隔离
• 不拥有 UserStatus / Membership 写
• 符合 Admin_RBAC boundary-rules