# 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