Files

T

jackyu66gitandCursor b5a05941d9 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

5.0 KiB

Raw Blame History

Feature Spec: 运营后台 RBAC（Ops · ECR-013A）

Status: Active（Closed · Feature Complete）· Map: §7 运营后台 · Phase: Ops-D
Parent: WAVE0-FROZEN (27f27a1)
ESS: docs/ECR/ECR-013A-admin-rbac.md（Closed）
Capability: AdminGovernance · BC: Admin_RBAC
模板：docs/WAVE0/contracts/OPS-CONTRACT-TEMPLATE.md

ESS 门禁

Change Level = L2 → 已 Approved + Coding auth + Implemented + Closed
~~Contract Definition only~~ — 已完成
实现证据：docs/TEST_REPORT/ECR-013A.md · docs/CODE_REVIEW/ECR-013A.md

L0 Capability

字段	内容
Capability ID	`AdminGovernance`
Purpose	以最小权限原则约束管理员可执行的运营动作
Why now	Ops-A 全员等价权限；进入 M1+ 前必须有权限面，否则越权不可治理
Non-goals	用户账户启停（ECR-013B）；兑换码；CMS；Ask Prompt；真支付；UGC

L1 Bounded Context

字段	内容
Primary BC	`Admin_RBAC`
owns	`AdminRole` · `AdminPermission`
does_not_own	`User` · `Profile` · `UserStatus` · `Membership` · `Payment`
allowed	`Admin_Auth_Audit.write_audit`
forbidden	`Payment` · `Membership.write` · `DeviceAuth.user_token_issue`

权威：.ai/domain/boundary-rules.md

1. 功能定义

字段	内容
Name	Admin RBAC
Purpose	角色与权限点绑定；API 级强制鉴权；变更可审计
Business Goal	支撑多运营角色，而不扩大 C 端攻击面

In	Out
Role CRUD（最小：list/get/update permissions）	UserStatus / 封禁（013B）
`GET /admin/me` 返回 permissions	细粒度数据行级 ACL
既有 admin 写操作挂 permission 检查	新业务模块权限爆炸式新增（另 ECR）

L2 Domain

Entity	不变式
`AdminRole`	`name` 唯一；系统角色 `super_admin` 不可删除
`AdminPermission`	稳定字符串码（见下表）；只增不改语义
`AdminAccount.role_id`	每个账号恰好一个角色（本切片）；无角色视为拒绝写操作

Permission catalog（本切片冻结）

Code	覆盖既有能力
`admin.users.read`	GET users / users/:id / stats
`admin.users.membership.grant`	POST membership/grant
`admin.users.ask_quota.grant`	POST ask-quota/grant
`admin.orders.read`	GET orders
`admin.audit.read`	GET audit-logs
`admin.analytics.read`	GET analytics/*（Ops-B）
`admin.content.write`	home tools / scales publish（Ops-C）
`admin.roles.read`	GET roles
`admin.roles.write`	变更角色权限

super_admin 种子拥有上表全部。

L3 API Contract（意图 · 实现轮同步 OpenAPI）

前缀：/api/v1/admin · AdminAuth · 信封 {code,message,data}

Method	Path	权限	语义
GET	`/roles`	`admin.roles.read`	角色列表
GET	`/roles/:id`	`admin.roles.read`	角色 + permissions[]
PUT	`/roles/:id/permissions`	`admin.roles.write`	全量替换权限集；写 AuditLog
GET	`/me`	（已登录）	扩展返回 `role` + `permissions[]`

既有写接口：在实现轮挂上表 permission；缺权 → 403 + AuditLog（尝试记录）。

contract_diff：docs/CONTRACT_DIFF/ECR-013A.yaml

L4 Acceptance Criteria

Functional

ID	Given	When	Then
AC-F-01	super_admin 已登录	GET `/roles`	200，含 `super_admin`
AC-F-02	角色存在	PUT permissions 合法集合	200；再次 GET 一致
AC-F-03	GET `/me`	—	data 含 `permissions` 数组

Security

ID	Given	When	Then
AC-S-01	Admin 无 `admin.roles.write`	PUT `/roles/:id/permissions`	403；AuditLog 有拒绝或尝试记录
AC-S-02	Admin 无 `admin.users.membership.grant`	POST membership/grant	403
AC-S-03	仅 DeviceAuth	访问 `/admin/roles`	401
AC-S-04	删除 `super_admin` 角色	任意 API	拒绝（4xx）

Performance

ID	Given	When	Then
AC-P-01	角色数 N≤100	GET `/roles`	本机 integration 环境下 P95 < 500ms

Observability

ID	Given	When	Then
AC-O-01	PUT permissions 成功	—	AuditLog action 含 `roles.permissions.update`
AC-O-02	AC-S-01 触发	—	AuditLog 可追溯 admin_id + path

Forbidden（本切片）

UserStatus / AccountLifecycle（ECR-013B）
真支付 · UGC · Prompt/RAG · 兑换码 · CMS Banner 新表
改 DeviceAuth / C 端五 Tab

Implementation Notes（实现轮才执行）

项	内容
Migration	YES（roles / permissions 关联；accounts.role_id；种子 super_admin）
Packages	`service/admin` · repo · middleware permission check · admin-h5 只读展示权限（最小）
Parent	WAVE0-FROZEN

5.0 KiB Raw Blame History Unescape Escape