feat(ECR-013A): Admin RBAC 实现并 Closed

角色权限、RequirePermission、/me permissions 与 migration 000015； Reviewer Approve → Closed。Next：ECR-013B Contract Definition。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 17:19:45 +08:00
parent 85ed0901bb
commit b5a05941d9
35 changed files with 1518 additions and 49 deletions
@@ -0,0 +1,98 @@
+# 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
+
+```text
+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
+
+```text
+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