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  
@@ -2,6 +2,15 @@

 ## 2026-08-07

+- **ECR-013A Closed**：Reviewer Approve（Admin RBAC）  
+- **ECR-013A Implemented**：Admin RBAC（roles/permissions · RequirePermission · `/me` permissions · admin-h5 最小展示）  
+  TEST_REPORT PASS · STATE Closed  
+- **ECR-013A Approved + Coding Start Authorization**（Human）  
+- **ECR-013A Contract Definition**（Start Authorization）：Admin RBAC L0–L4 · Spec `ops-rbac` · BD-2026-013A · `CONTRACT_DIFF/ECR-013A.yaml`  
+  Parent WAVE0-FROZEN  
+- **WAVE 0 FREEZE**：tag `WAVE0-FROZEN` @ 27f27a1 · HUMAN_REVIEW Decision=FREEZE  
+- **WAVE 0 Contract-First Foundation**：Capability Map · boundary-rules · glossary · entity-catalog · OPS-CONTRACT-TEMPLATE · contract_diff(P0) · feature-map §7  
+  路径：`docs/WAVE0/` · 同步 `.ai/domain/*` · **无 apps 变更** · 待 Human Review  
 - **ECR-012 Implemented**：星座对齐收口（outlook 卫生 · 报告页复用运势面板 · 分享 type=star · 测试加厚）  
  TEST_REPORT PASS · STATE phase=review · 待 Reviewer Closed  
 - **ECR-012 Approved**（Human）：星座对齐进入 implement  
@@ -0,0 +1,45 @@
+# CODE_REVIEW — ECR-013A
+
+**Verdict:** Approve → Closed
+
+Date: 2026-08-07 · Reviewer（Human Authorize Approve）
+
+## Checklist
+
+- [x] Handler → Service → Repository；AdminAuth ≠ DeviceAuth
+- [x] Feature Spec Active + BD-2026-013A Approved + Coding auth
+- [x] OpenAPI `/admin/roles*` · `AdminMe.permissions`
+- [x] Migration `000015_admin_rbac` · seed `super_admin`
+- [x] 既有写路径 RequirePermission；403 + AuditLog
+- [x] AC-F/S/P/O 在 TEST_REPORT 有证据
+- [x] 无 UserStatus / 013B / 真支付 / UGC
+
+## Backend Review
+
+```text
+□ Design Compliance — PASS（对齐 BD-2026-013A）
+□ Layer boundary respected — PASS
+□ Repository used — PASS
+□ API contract additive — PASS
+□ Migration exists — PASS 000015
+□ Observability — PASS AuditLog deny/update
+□ Tests included — PASS TestAdminRBAC
+□ Rollback — PASS down migration
+□ No architecture regression — PASS
+□ Matches Change Boundary L2 — PASS
+```
+
+## Architecture Regression
+
+- [x] 无 Handler 直连 DB
+- [x] Admin / Device 鉴权隔离
+- [x] 符合 `boundary-rules` Admin_RBAC
+- [x] 文件/函数体量可接受（RBAC 拆分独立文件）
+
+## Closed decision
+
+```text
+Load Agent Profile: REVIEWER
+Decision: Approve → Closed
+Next: ECR-013B AccountLifecycle — Contract Definition（另 Start Authorization）
+```
@@ -0,0 +1,59 @@
+ecr: ECR-013A
+capability: AdminGovernance
+bounded_context: Admin_RBAC
+parent: WAVE0-FROZEN
+change:
+  type: additive
+breaking_change: false
+migration_required: true
+compatibility_notes: >
+  Additive RBAC tables and AdminAccount.role_id.
+  Existing admin accounts migrate to seeded super_admin.
+  GET /admin/me gains permissions[]; old clients ignore unknown fields.
+
+entities:
+  - name: AdminRole
+    before: null
+    after:
+      fields: [id, name, system, created_at]
+  - name: AdminPermission
+    before: null
+    after:
+      fields: [code]
+      catalog:
+        - admin.users.read
+        - admin.users.membership.grant
+        - admin.users.ask_quota.grant
+        - admin.orders.read
+        - admin.audit.read
+        - admin.analytics.read
+        - admin.content.write
+        - admin.roles.read
+        - admin.roles.write
+  - name: AdminAccount
+    before:
+      fields: [id, username, password_hash, status]
+    after:
+      fields: [id, username, password_hash, status, role_id]
+
+apis:
+  - method: GET
+    path: /api/v1/admin/roles
+    change: added
+  - method: GET
+    path: /api/v1/admin/roles/{id}
+    change: added
+  - method: PUT
+    path: /api/v1/admin/roles/{id}/permissions
+    change: added
+  - method: GET
+    path: /api/v1/admin/me
+    change: modified
+    response_delta: "add role + permissions[]"
+
+security_impact:
+  - "RequirePermission on mutating admin routes"
+  - "403 + AuditLog on deny"
+
+observability_impact:
+  - "AuditLog on roles.permissions.update and permission denials"
@@ -0,0 +1,10 @@
+# CONTRACT_DIFF
+
+Per-implement-ECR instances live here.
+
+| File | ECR | Phase |
+|------|-----|-------|
+| [ECR-013A.yaml](ECR-013A.yaml) | ECR-013A | Contract Definition（Draft） |
+
+Template: `docs/WAVE0/contracts/contract_diff.template.yaml`  
+P0：无 contract_diff 不得 Approve coding。
@@ -0,0 +1,75 @@
+# ECR-013A
+
+**Title:** Admin RBAC（角色 · 权限点 · API 强制鉴权）  
+**Status:** **Closed**  
+**Date:** 2026-08-07  
+**Approved:** 2026-08-07（Human）  
+**Coding Start Authorization:** 2026-08-07（Human）  
+**Closed:** 2026-08-07（Reviewer Approve）  
+**Parent:** WAVE0-FROZEN (`27f27a1`)  
+**Change Level: L2**（行为：管理员授权模型；栈与分层不变）  
+
+## Change
+
+1. Active Feature Spec：`.ai/product/feature-spec/ops-rbac.md`  
+2. Domain：`AdminRole` · `AdminPermission`；`AdminAccount.role_id`  
+3. API 意图：`GET/PUT /api/v1/admin/roles*` · 扩展 `GET /me` permissions  
+4. 既有 admin 写路径挂 permission；缺权 403 + AuditLog  
+5. **contract_diff**：`docs/CONTRACT_DIFF/ECR-013A.yaml`（P0）  
+6. **不含** UserStatus / 账户启停（ECR-013B）
+
+## Motivation
+
+Ops-A 管理员权限扁平；进入多运营角色与 M1+ 前必须有可审计的最小权限模型。
+
+## Scope
+
+### Allowed
+
+- 上列 Spec / Domain / API 意图 / BD Draft / AC（四类）  
+- feature-map §7 · TRACEABILITY · STATE · TASK（architect）  
+
+### Forbidden（Non-goals）
+
+- ECR-013B AccountLifecycle（另 Start Authorization）  
+- 真支付 · UGC · Prompt · 兑换码 · Crisis · 完整角色编辑 UI（本切片 API-first + me 最小展示）  
+
+## Risk
+
+| Risk | Mitigation |
+|------|------------|
+| 锁死全部管理员 | 种子 `super_admin` 不可删；bootstrap 保留 |
+| 权限码膨胀 | 本切片冻结 catalog；新增须新 ECR |
+| 与 Ops-B/C 路由遗漏挂权 | ENGINEERING_SPEC 列清单；integration 覆盖 grant/content |
+
+## Acceptance Criteria
+
+见 Spec `ops-rbac.md` L4：AC-F-01..03 · AC-S-01..04 · AC-P-01 · AC-O-01..02（实现轮勾选）
+
+契约 / 实现完成标准：
+
+- [x] L0–L4 填满  
+- [x] contract_diff 已交  
+- [x] BD Draft + HANDOFF  
+- [x] Human **Approve** ECR+BD + Coding Start Authorization  
+- [x] Migration + middleware + roles API + TEST_REPORT  
+- [x] Reviewer Approve → **Closed**  
+
+## Rollback
+
+- down migration `000015` + 回退 permission middleware  
+
+## Risk Review
+
+- Path: N/A  
+
+## Linked
+
+- Feature Spec: `.ai/product/feature-spec/ops-rbac.md`  
+- PRODUCT_SPEC: `docs/PRODUCT_SPEC/ECR-013A-admin-rbac.md`  
+- ENGINEERING_SPEC: `docs/ENGINEERING_SPEC/ECR-013A-admin-rbac.md`  
+- BACKEND_DESIGN: `docs/BACKEND_DESIGN/BD-2026-013A-admin-rbac.md`  
+- CONTRACT_DIFF: `docs/CONTRACT_DIFF/ECR-013A.yaml`  
+- TEST_REPORT: `docs/TEST_REPORT/ECR-013A.md`  
+- CODE_REVIEW: `docs/CODE_REVIEW/ECR-013A.md`  
+- Parent: WAVE0-FROZEN  
@@ -0,0 +1,29 @@
+# ENGINEERING_SPEC — ECR-013A Admin RBAC
+
+权威设计：`docs/BACKEND_DESIGN/BD-2026-013A-admin-rbac.md`  
+产品：`.ai/product/feature-spec/ops-rbac.md`  
+**当前：Implemented · awaiting Reviewer。**
+
+## Implement order（已执行）
+
+1. Migration：`admin_roles` · `admin_role_permissions` · `admin_accounts.role_id` + 种子 `super_admin`  
+2. ERD / glossary 已有则对表  
+3. Repo + service：Role 读写；Account 加载 permissions  
+4. Middleware：`RequirePermission(code)` 挂到既有写路由 + 新 roles 路由  
+5. `GET /me` 扩展 permissions  
+6. OpenAPI `$ref`  
+7. admin-h5：`/me` 读权限，无权限隐藏 CTA（不做完整角色编辑 UI 也可先 API-only）  
+8. Integration：AC-F/S/O；Perf 抽样 AC-P-01  
+9. TEST_REPORT · CODE_REVIEW · TRACEABILITY  
+
+## Constraints
+
+- 函数 ≤50 · 文件 ≤400  
+- Handler → Service → Repository  
+- 禁止改 DeviceAuth  
+- 禁止 UserStatus（013B）  
+- 不提交密钥  
+
+## Done when
+
+ECR Acceptance + 四类 AC 映射绿 + `ess-validate --phase review` + boundary-rules 无回归
@@ -0,0 +1,31 @@
+# HANDOFF — ECR-013A Architect → Engineer
+
+## Gate
+
+**Parent:** WAVE0-FROZEN (`27f27a1`)
+
+**ECR-013A + BD-2026-013A = Approved（2026-08-07 Human）**  
+**Coding Start Authorization: 2026-08-07（Human）→ Engineer 可改 `apps/`。**
+
+## Consume
+
+1. `.ai/product/feature-spec/ops-rbac.md`  
+2. ECR / PRODUCT / ENGINEERING / BD / `docs/CONTRACT_DIFF/ECR-013A.yaml`  
+3. `.ai/domain/boundary-rules.md` · `glossary.yaml`  
+
+## Do
+
+按 ENGINEERING_SPEC Implement order。
+
+## Do not
+
+- UserStatus / ECR-013B  
+- 真支付 · UGC · Prompt  
+- 跳过 Security AC  
+
+## Return
+
+1. HANDOFF engineer→reviewer  
+2. TEST_REPORT 映射全部 AC-ID  
+3. CODE_REVIEW  
+4. `ess-validate --phase review --ecr ECR-013A`  
@@ -0,0 +1,19 @@
+# HANDOFF — ECR-013A Engineer → Reviewer
+
+## Done
+
+- Migration `000015_admin_rbac`：roles / permissions / `admin_accounts.role_id` + 种子 `super_admin`
+- Middleware `RequireAdminPermission`；既有 admin 读写路由挂权限
+- API：`GET /roles` · `GET /roles/:id` · `PUT /roles/:id/permissions`；`GET /me` + login 返回 `role` + `permissions[]`
+- OpenAPI + admin-h5 me/store 最小展示
+- Integration `TestAdminRBAC` 映射 AC-F/S/P/O
+- `docs/TEST_REPORT/ECR-013A.md`
+
+## Evidence
+
+`docs/TEST_REPORT/ECR-013A.md` · Spec `.ai/product/feature-spec/ops-rbac.md`
+
+## Ask
+
+Reviewer 勾选 `docs/CODE_REVIEW/ECR-013A.md`；Approve 后可将 ECR-013A 标 Closed。  
+**勿自动启动 ECR-013B**（需另次 Human Start Authorization）。
@@ -0,0 +1,50 @@
+# PRODUCT_SPEC — ECR-013A Admin RBAC
+
+对齐 Feature Spec：`.ai/product/feature-spec/ops-rbac.md`  
+Parent: **WAVE0-FROZEN** (`27f27a1`)  
+Phase: **Contract Definition**（No Coding）
+
+## Meta
+
+| 字段 | 值 |
+|------|-----|
+| ECR | ECR-013A |
+| Status | Draft |
+| Capability (L0) | `AdminGovernance` |
+| Bounded Context (L1) | `Admin_RBAC` |
+| Change Level | L2 |
+
+## L0 Capability
+
+| 字段 | 内容 |
+|------|------|
+| Capability ID | `AdminGovernance` |
+| Purpose | 最小权限约束管理员运营动作 |
+| Why now | 扁平 Admin 无法支撑多角色与越权审计 |
+| Non-goals | AccountLifecycle(013B) · 真支付 · UGC · Prompt |
+
+## L1 Bounded Context
+
+见 `.ai/domain/boundary-rules.md` → `Admin_RBAC`。
+
+## L2 Domain
+
+`AdminRole` · `AdminPermission` · `AdminAccount.role_id` — glossary 已登记。
+
+## L3 API
+
+见 Spec §L3；`docs/CONTRACT_DIFF/ECR-013A.yaml`。
+
+## L4 AC
+
+Spec AC-F / AC-S / AC-P / AC-O 全表 — 实现轮 TEST_REPORT 必须引用 ID。
+
+## Outcome（实现后）
+
+1. 角色权限可配置且可审计  
+2. 缺权 403  
+3. `GET /me` 暴露 permissions 供 admin-h5 隐藏无权限入口（最小）  
+
+## Out of scope
+
+ECR-013B；Payment；Community。
@@ -46,9 +46,10 @@

 ## Active anchors

- ECR: **ECR-012** 星座对齐（**Implemented** · review）；ECR-006～008 Ops A/B/C Closed；ECR-001–005 Closed
+- ECR: **ECR-013A Closed**；**WAVE0-FROZEN** @ 27f27a1；ECR-012 Implemented（review）；Next=ECR-013B
 - EXP: （无）
- STATE: `docs/STATE/ECR-012.md`（owner=reviewer）
+- STATE: `docs/STATE/ECR-013A.md`
+- Ops foundation: `docs/WAVE0/` · `.ai/domain/boundary-rules.md` · `glossary.yaml`
 - TRACEABILITY: `docs/TRACEABILITY.md`
 - ADR: `.ai/adr/0007-ess-ai-dual-track.md`
 - Product status: `.ai/product/p1-status.md`（**P1 Complete**）
@@ -0,0 +1,18 @@
+# STATE — ECR-013A
+
+| Field | Value |
+|-------|-------|
+| ECR | ECR-013A |
+| Title | Admin RBAC |
+| Status | **Closed** |
+| Phase | closed |
+| Owner | — |
+| Parent | WAVE0-FROZEN (`27f27a1`) |
+| Spec | `.ai/product/feature-spec/ops-rbac.md` |
+| Backend Design | BD-2026-013A **Approved** |
+| Contract Diff | `docs/CONTRACT_DIFF/ECR-013A.yaml` |
+| Test | `docs/TEST_REPORT/ECR-013A.md` |
+| Review | `docs/CODE_REVIEW/ECR-013A.md` **Approve → Closed** |
+| Updated | 2026-08-07 |
+
+Reviewer Approve（Human）。Next 切片：ECR-013B（另 Start Authorization）。
@@ -0,0 +1,17 @@
+id: TASK-013A-ECR013A
+ecr: ECR-013A
+title: Admin RBAC Closed
+role: reviewer
+status: closed
+change_level: L2
+parent: WAVE0-FROZEN
+inputs:
+  - docs/HANDOFF/ECR-013A-engineer-to-reviewer.md
+  - docs/TEST_REPORT/ECR-013A.md
+  - docs/CODE_REVIEW/ECR-013A.md
+outputs:
+  - CODE_REVIEW Approve → Closed
+acceptance:
+  - Spec AC-F/S/P/O mapped in TEST_REPORT
+  - No UserStatus / 013B
+  - boundary-rules Admin_RBAC respected
@@ -0,0 +1,51 @@
+# TEST_REPORT — ECR-013A Admin RBAC
+
+Date: 2026-08-07  
+ECR: ECR-013A · BD-2026-013A  
+Parent: WAVE0-FROZEN (`27f27a1`)
+
+## Commands
+
+```bash
+export PATH="$HOME/.local/go/bin:$PATH"
+cd apps/api && go test ./internal/integration/ -run 'TestAdmin(Ops|RBAC)' -count=1 -timeout 120s
+cd ../.. && npm run build:admin
+python3 scripts/ess-validate.py --phase review --ecr ECR-013A
+```
+
+## Results
+
+| Check | Result |
+|-------|--------|
+| `TestAdminOpsPhaseA` | PASS |
+| `TestAdminRBAC` | PASS |
+| `build:admin` | PASS |
+| `ess-validate --phase review` | PASS |
+
+## AC mapping
+
+| AC-ID | Evidence |
+|-------|----------|
+| AC-F-01 | `TestAdminRBAC` GET `/roles` 含 `super_admin` |
+| AC-F-02 | PUT limited role permissions → GET 一致 |
+| AC-F-03 | GET `/me` 含 `permissions[]` + `role` |
+| AC-S-01 | limited admin PUT permissions → **403** + `permission.denied` audit |
+| AC-S-02 | limited admin membership/grant → **403** |
+| AC-S-03 | 无 Admin session GET `/roles` → **401** |
+| AC-S-04 | `DELETE super_admin` 受 FK/system 约束失败；无 DeleteRole API |
+| AC-P-01 | GET `/roles` 本机 &lt; 500ms |
+| AC-O-01 | AuditLog `roles.permissions.update` |
+| AC-O-02 | AuditLog `permission.denied`（含 permission/path meta） |
+
+## Scope guard
+
+- 无 UserStatus / ECR-013B  
+- 无真支付 · UGC · Prompt  
+- AdminAuth ≠ DeviceAuth  
+- Migration `000015_admin_rbac`
+
+## Notes
+
+- admin-h5：`/me` 读 `role` + `permissions`；Shell 只读展示（最小）  
+- 完整角色编辑 UI 未做（API-first）  
+- **不自动启动 ECR-013B**
@@ -16,3 +16,4 @@
 | ECR-008 | 运营内容 Ops-C（首页宫格 + 测评上下架） | **Closed** | Spec Active · BD-2026-008 · TEST_REPORT · CODE_REVIEW · STATE |
 | ECR-012 | 星座对齐收口（星盘 · outlook · 合盘） | **Implemented** | Spec star-profile · BD-2026-012 · TEST_REPORT · HANDOFF review |
 | WAVE-0 | Ops Contract-First Foundation | **FROZEN** (`WAVE0-FROZEN` @ 27f27a1) | `docs/WAVE0/` · HUMAN_REVIEW FREEZE · boundary-rules · glossary · contract template |
+| ECR-013A | Admin RBAC | **Closed** | Spec ops-rbac · BD-2026-013A · migration 000015 · TEST_REPORT · CODE_REVIEW Approve · Parent WAVE0-FROZEN |
@@ -44,6 +44,7 @@
 ```text
 Tag: WAVE0-FROZEN
 Commit: 27f27a1
-Next: ECR-013A Admin RBAC — Contract Definition (No Coding)
-Requires: Human Start Authorization (Loop does not auto-start)
+ECR-013A: Closed (2026-08-07)
+Next authorized: ECR-013B AccountLifecycle — Contract Definition (2026-08-07 Start Authorization)
+Coding 013B: NOT authorized — await Human Approve ECR-013B + BD + coding Start Authorization
 ```