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>

.ai/product/feature-spec/README.md

@@ -23,6 +23,7 @@
 | [ops-admin.md](ops-admin.md) | 运营后台 | §7 | `admin-h5` `/` `/users/:id` … | Ops-A |
 | [ops-analytics.md](ops-analytics.md) | 运营行为分析（埋点+数据看板） | §7 | `admin-h5` `/analytics` · H5 track | Ops-B · ECR-007 Closed |
 | [ops-content.md](ops-content.md) | 运营内容（宫格+测评上下架） | §7 | `admin-h5` `/content` · `GET /home/tools` | Ops-C · ECR-008 Closed |
+| [ops-rbac.md](ops-rbac.md) | 运营 RBAC | §7 | `admin-h5` `/me` permissions · `/admin/roles*` | Ops-D · **ECR-013A Closed** |
 
 新功能：复制 `_TEMPLATE.md` → 填满 → 在本表登记 → 再编码。
 

.ai/product/feature-spec/ops-admin.md

@@ -208,5 +208,6 @@ Phase A 可先 `console`/本地；不挡验收。
 | **A（本 ECR）** | 登录 · 用户 · 订单 · 授予会员 · 审计 · admin-h5 壳 |
 | **B（ECR-007 Closed）** | 自有埋点 · 管理端「数据」看板 — Spec `ops-analytics.md` |
 | **C（ECR-008 Closed）** | 首页宫格 CRUD · 测评上下架 — Spec `ops-content.md` |
+| **E（ECR-013A Closed）** | Admin RBAC — Spec `ops-rbac.md` · Parent WAVE0-FROZEN |
 | D | 订单筛选 · 展示价 · 退款只读（另开 ECR） |
-| E | RBAC · 封禁 · 推送占位（另开 ECR） |
+| 后置 | AccountLifecycle = **ECR-013B**；封禁加深 · 推送占位 |

.ai/product/feature-spec/ops-rbac.md

@@ -0,0 +1,151 @@
+# 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 门禁
+
+1. Change Level = **L2** → 已 Approved + Coding auth + Implemented + **Closed**  
+2. ~~Contract Definition only~~ — 已完成  
+3. 实现证据：`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 |

apps/admin-h5/e2e/admin-ops-smoke.spec.ts

@@ -21,7 +21,22 @@ test('admin login users grant and audit with mocked API', async ({ page }) => {
       await ok({
         token: 'adm_e2e_token',
         expires_at: new Date(Date.now() + 3600_000).toISOString(),
-        admin: { id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', username: 'admin' },
+        admin: {
+          id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+          username: 'admin',
+          role: 'super_admin',
+          permissions: [
+            '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',
+          ],
+        },
       })
       return
     }
@@ -55,7 +70,22 @@ test('admin login users grant and audit with mocked API', async ({ page }) => {
       return
     }
     if (url.endsWith('/me') || url.includes('/me?')) {
-      await ok({ id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', username: 'admin' })
+      await ok({
+        id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+        username: 'admin',
+        role: 'super_admin',
+        permissions: [
+          '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',
+        ],
+      })
       return
     }
     if (url.includes(`/users/${userId}/ask-quota/grant`) && method === 'POST') {

apps/admin-h5/src/api/client.ts

@@ -94,14 +94,25 @@ export type UserDetail = {
   }>
 }
 
+export type AdminMe = {
+  id: string
+  username: string
+  role?: string
+  permissions: string[]
+}
+
 export const adminApi = {
   login: (username: string, password: string) =>
-    request<{ token: string; admin: { id: string; username: string } }>('POST', '/auth/login', {
+    request<{ token: string; admin: AdminMe }>('POST', '/auth/login', {
       username,
       password,
     }),
   logout: () => request<{ ok: boolean }>('POST', '/auth/logout'),
-  me: () => request<{ id: string; username: string }>('GET', '/me'),
+  me: () => request<AdminMe>('GET', '/me'),
+  roles: () =>
+    request<{ items: Array<{ id: string; name: string; system: boolean }> }>('GET', '/roles'),
+  role: (id: string) =>
+    request<{ id: string; name: string; system: boolean; permissions: string[] }>('GET', `/roles/${id}`),
   stats: () => request<DashboardStats>('GET', '/stats'),
   users: (q = '') =>
     request<{ items: UserListItem[] }>('GET', `/users?q=${encodeURIComponent(q)}`),

apps/admin-h5/src/layouts/AdminShell.vue

@@ -33,6 +33,7 @@ async function onLogout() {
       </nav>
       <div class="foot">
         <span class="muted">{{ auth.username || '管理员' }}</span>
+        <span v-if="auth.role" class="role">{{ auth.role }} · {{ auth.permissions.length }} 权</span>
         <button class="btn ghost" type="button" @click="onLogout">退出</button>
       </div>
     </aside>
@@ -72,6 +73,7 @@ nav a.router-link-active {
   box-shadow: 0 4px 12px rgba(229, 77, 66, 0.08);
 }
 .foot { margin-top: auto; display: flex; flex-direction: column; gap: 0.5rem; }
+.role { font-size: 0.75rem; color: var(--muted); }
 .main { padding: 1.5rem 1.75rem; }
 @media (max-width: 800px) {
   .shell { grid-template-columns: 1fr; }

apps/admin-h5/src/stores/auth.ts

@@ -5,19 +5,27 @@ import { adminApi, getToken, setToken } from '@/api/client'
 export const useAuthStore = defineStore('auth', () => {
   const token = ref<string | null>(getToken())
   const username = ref<string>('')
+  const role = ref<string>('')
+  const permissions = ref<string[]>([])
+
+  function applyMe(me: { username: string; role?: string; permissions?: string[] }) {
+    username.value = me.username
+    role.value = me.role || ''
+    permissions.value = me.permissions ?? []
+  }
 
   async function login(user: string, password: string) {
     const res = await adminApi.login(user, password)
     setToken(res.token)
     token.value = res.token
-    username.value = res.admin.username
+    applyMe(res.admin)
   }
 
   async function hydrate() {
     if (!token.value) return false
     try {
       const me = await adminApi.me()
-      username.value = me.username
+      applyMe(me)
       return true
     } catch {
       setToken(null)
@@ -35,7 +43,13 @@ export const useAuthStore = defineStore('auth', () => {
     setToken(null)
     token.value = null
     username.value = ''
+    role.value = ''
+    permissions.value = []
   }
 
-  return { token, username, login, logout, hydrate }
+  function can(code: string) {
+    return permissions.value.includes(code)
+  }
+
+  return { token, username, role, permissions, can, login, logout, hydrate }
 })

apps/api/internal/handler/admin.go

@@ -29,19 +29,20 @@ func (h *AdminHandler) Register(api *gin.RouterGroup) {
 	authed.Use(middleware.AdminAuth(h.Svc))
 	authed.POST("/auth/logout", h.Logout)
 	authed.GET("/me", h.Me)
-	authed.GET("/stats", h.Stats)
-	authed.GET("/users", h.ListUsers)
-	authed.GET("/users/:id", h.GetUser)
-	authed.POST("/users/:id/membership/grant", h.GrantMembership)
-	authed.POST("/users/:id/ask-quota/grant", h.GrantAskQuota)
-	authed.GET("/orders", h.ListOrders)
-	authed.GET("/audit-logs", h.ListAudit)
-	authed.GET("/analytics/overview", h.AnalyticsOverview)
-	authed.GET("/analytics/pages", h.AnalyticsPages)
-	authed.GET("/analytics/exits", h.AnalyticsExits)
-	authed.GET("/analytics/clicks", h.AnalyticsClicks)
-	authed.GET("/analytics/funnel", h.AnalyticsFunnel)
+	authed.GET("/stats", middleware.RequireAdminPermission(h.Svc, admin.PermUsersRead), h.Stats)
+	authed.GET("/users", middleware.RequireAdminPermission(h.Svc, admin.PermUsersRead), h.ListUsers)
+	authed.GET("/users/:id", middleware.RequireAdminPermission(h.Svc, admin.PermUsersRead), h.GetUser)
+	authed.POST("/users/:id/membership/grant", middleware.RequireAdminPermission(h.Svc, admin.PermMembershipGrant), h.GrantMembership)
+	authed.POST("/users/:id/ask-quota/grant", middleware.RequireAdminPermission(h.Svc, admin.PermAskQuotaGrant), h.GrantAskQuota)
+	authed.GET("/orders", middleware.RequireAdminPermission(h.Svc, admin.PermOrdersRead), h.ListOrders)
+	authed.GET("/audit-logs", middleware.RequireAdminPermission(h.Svc, admin.PermAuditRead), h.ListAudit)
+	authed.GET("/analytics/overview", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsOverview)
+	authed.GET("/analytics/pages", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsPages)
+	authed.GET("/analytics/exits", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsExits)
+	authed.GET("/analytics/clicks", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsClicks)
+	authed.GET("/analytics/funnel", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsFunnel)
 	h.registerContent(authed)
+	h.registerRBAC(authed)
 }
 
 func (h *AdminHandler) Login(c *gin.Context) {

apps/api/internal/handler/admin_content.go

@@ -14,10 +14,10 @@ import (
 )
 
 func (h *AdminHandler) registerContent(authed *gin.RouterGroup) {
-	authed.GET("/home/tools", h.ListHomeTools)
-	authed.PUT("/home/tools", h.ReplaceHomeTools)
-	authed.GET("/scales", h.ListScales)
-	authed.PATCH("/scales/:id", h.PatchScale)
+	authed.GET("/home/tools", middleware.RequireAdminPermission(h.Svc, admin.PermContentWrite), h.ListHomeTools)
+	authed.PUT("/home/tools", middleware.RequireAdminPermission(h.Svc, admin.PermContentWrite), h.ReplaceHomeTools)
+	authed.GET("/scales", middleware.RequireAdminPermission(h.Svc, admin.PermContentWrite), h.ListScales)
+	authed.PATCH("/scales/:id", middleware.RequireAdminPermission(h.Svc, admin.PermContentWrite), h.PatchScale)
 }
 
 func (h *AdminHandler) ListHomeTools(c *gin.Context) {

apps/api/internal/handler/admin_rbac.go

@@ -0,0 +1,88 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/middleware"
+	"github.com/yuxingu/digital-psychology/apps/api/internal/service/admin"
+	"github.com/yuxingu/digital-psychology/apps/api/pkg/response"
+)
+
+func (h *AdminHandler) registerRBAC(authed *gin.RouterGroup) {
+	authed.GET("/roles", middleware.RequireAdminPermission(h.Svc, admin.PermRolesRead), h.ListRoles)
+	authed.GET("/roles/:id", middleware.RequireAdminPermission(h.Svc, admin.PermRolesRead), h.GetRole)
+	authed.PUT("/roles/:id/permissions", middleware.RequireAdminPermission(h.Svc, admin.PermRolesWrite), h.PutRolePermissions)
+}
+
+func (h *AdminHandler) ListRoles(c *gin.Context) {
+	items, err := h.Svc.ListRoles(c.Request.Context())
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	response.OK(c, gin.H{"items": items})
+}
+
+func (h *AdminHandler) GetRole(c *gin.Context) {
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40000, "invalid id")
+		return
+	}
+	role, err := h.Svc.GetRole(c.Request.Context(), id)
+	if errors.Is(err, admin.ErrRoleNotFound) || role == nil {
+		response.Fail(c, http.StatusNotFound, 40400, "role not found")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	response.OK(c, role)
+}
+
+func (h *AdminHandler) PutRolePermissions(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40102, "admin session invalid")
+		return
+	}
+	roleID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40000, "invalid id")
+		return
+	}
+	var body struct {
+		Permissions []string `json:"permissions"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		response.Fail(c, http.StatusBadRequest, 40000, "invalid body")
+		return
+	}
+	if body.Permissions == nil {
+		body.Permissions = []string{}
+	}
+	err = h.Svc.ReplaceRolePermissions(c.Request.Context(), adminID, roleID, body.Permissions)
+	if errors.Is(err, admin.ErrRoleNotFound) {
+		response.Fail(c, http.StatusNotFound, 40400, "role not found")
+		return
+	}
+	if errors.Is(err, admin.ErrInvalidPerm) {
+		response.Fail(c, http.StatusBadRequest, 40000, err.Error())
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	role, err := h.Svc.GetRole(c.Request.Context(), roleID)
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	response.OK(c, role)
+}

apps/api/internal/integration/admin_rbac_test.go

@@ -0,0 +1,237 @@
+package integration_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/config"
+	"github.com/yuxingu/digital-psychology/apps/api/internal/db"
+	"github.com/yuxingu/digital-psychology/apps/api/internal/httpserver"
+)
+
+func setupAPIPool(t *testing.T) (*gin.Engine, *pgxpool.Pool) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	t.Cleanup(cancel)
+
+	cfg := config.Load()
+	cfg.Admin.BootstrapUsername = "admin"
+	cfg.Admin.BootstrapPassword = "change-me"
+	pool, err := db.Connect(ctx, cfg.DatabaseURL)
+	if err != nil {
+		t.Skipf("postgres unavailable (run npm run deps:up): %v", err)
+	}
+	t.Cleanup(pool.Close)
+
+	migDir := filepath.Join("..", "..", "migrations")
+	if err := db.Migrate(ctx, pool, migDir); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	return httpserver.NewRouter(pool, cfg), pool
+}
+
+func adminLogin(t *testing.T, r http.Handler, user, pass string) string {
+	t.Helper()
+	env, code := doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/auth/login", map[string]string{
+		"username": user, "password": pass,
+	}, "")
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("login %s failed http=%d code=%d msg=%s", user, code, env.Code, env.Message)
+	}
+	var login struct {
+		Token string `json:"token"`
+	}
+	if err := json.Unmarshal(env.Data, &login); err != nil || login.Token == "" {
+		t.Fatalf("login token missing: %v %s", err, env.Data)
+	}
+	return login.Token
+}
+
+func TestAdminRBAC(t *testing.T) {
+	r, pool := setupAPIPool(t)
+	ctx := context.Background()
+	superTok := adminLogin(t, r, "admin", "change-me")
+
+	// AC-S-03: no admin session → 401
+	env, code := doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/roles", nil, "")
+	if code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 without admin token, got http=%d", code)
+	}
+
+	// AC-F-03: /me includes permissions
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/me", nil, superTok)
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("me failed http=%d code=%d", code, env.Code)
+	}
+	var me struct {
+		Permissions []string `json:"permissions"`
+		Role        string   `json:"role"`
+	}
+	if err := json.Unmarshal(env.Data, &me); err != nil || len(me.Permissions) == 0 {
+		t.Fatalf("expected permissions on me: %v %s", err, env.Data)
+	}
+	if me.Role != "super_admin" {
+		t.Fatalf("expected super_admin role, got %q", me.Role)
+	}
+
+	// AC-F-01: list roles
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/roles", nil, superTok)
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("list roles failed http=%d code=%d msg=%s", code, env.Code, env.Message)
+	}
+	var roles struct {
+		Items []struct {
+			ID   string `json:"id"`
+			Name string `json:"name"`
+		} `json:"items"`
+	}
+	if err := json.Unmarshal(env.Data, &roles); err != nil || len(roles.Items) == 0 {
+		t.Fatalf("expected roles: %v %s", err, env.Data)
+	}
+	var superRoleID string
+	for _, it := range roles.Items {
+		if it.Name == "super_admin" {
+			superRoleID = it.ID
+		}
+	}
+	if superRoleID == "" {
+		t.Fatal("super_admin role missing")
+	}
+
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/roles/"+superRoleID, nil, superTok)
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("get role failed http=%d code=%d", code, env.Code)
+	}
+
+	// Seed limited role + account for deny ACs
+	limitedRoleID := uuid.New()
+	_, err := pool.Exec(ctx, `
+		INSERT INTO admin_roles(id, name, system) VALUES ($1, $2, false)
+		ON CONFLICT (name) DO NOTHING`, limitedRoleID, "rbac_limited_"+limitedRoleID.String()[:8])
+	if err != nil {
+		t.Fatalf("insert role: %v", err)
+	}
+	// resolve actual id if conflict
+	var roleName string
+	err = pool.QueryRow(ctx, `SELECT id, name FROM admin_roles WHERE id=$1`, limitedRoleID).Scan(&limitedRoleID, &roleName)
+	if err != nil {
+		t.Fatalf("load limited role: %v", err)
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte("limited-pass"), bcrypt.DefaultCost)
+	if err != nil {
+		t.Fatal(err)
+	}
+	limitedUser := fmt.Sprintf("limited_%d", time.Now().UnixNano())
+	_, err = pool.Exec(ctx, `
+		INSERT INTO admin_accounts(username, password_hash, role_id)
+		VALUES ($1, $2, $3)`, limitedUser, string(hash), limitedRoleID)
+	if err != nil {
+		t.Fatalf("insert limited admin: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_accounts WHERE username=$1`, limitedUser)
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_roles WHERE id=$1`, limitedRoleID)
+	})
+
+	limitedTok := adminLogin(t, r, limitedUser, "limited-pass")
+
+	// AC-S-01: no roles.write → 403
+	env, code = doAdminJSON(t, r, http.MethodPut, "/api/v1/admin/roles/"+limitedRoleID.String()+"/permissions",
+		map[string]any{"permissions": []string{"admin.users.read"}}, limitedTok)
+	if code != http.StatusForbidden {
+		t.Fatalf("expected 403 roles.write, got http=%d code=%d msg=%s", code, env.Code, env.Message)
+	}
+
+	// AC-S-02: no membership.grant → 403
+	_ = mustRegister(t, r)
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/users", nil, superTok)
+	if code != 200 {
+		t.Fatalf("list users: %d", code)
+	}
+	var list struct {
+		Items []struct {
+			ID string `json:"id"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &list)
+	if len(list.Items) == 0 {
+		t.Fatal("need a user for grant deny")
+	}
+	env, code = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+list.Items[0].ID+"/membership/grant",
+		map[string]string{"plan": "month"}, limitedTok)
+	if code != http.StatusForbidden {
+		t.Fatalf("expected 403 membership.grant, got http=%d code=%d", code, env.Code)
+	}
+
+	// AC-F-02 + AC-O-01: super replaces permissions
+	want := []string{"admin.users.read", "admin.roles.read"}
+	env, code = doAdminJSON(t, r, http.MethodPut, "/api/v1/admin/roles/"+limitedRoleID.String()+"/permissions",
+		map[string]any{"permissions": want}, superTok)
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("put permissions failed http=%d code=%d msg=%s", code, env.Code, env.Message)
+	}
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/roles/"+limitedRoleID.String(), nil, superTok)
+	if code != 200 {
+		t.Fatalf("get after put: %d", code)
+	}
+	var roleDetail struct {
+		Permissions []string `json:"permissions"`
+	}
+	if err := json.Unmarshal(env.Data, &roleDetail); err != nil {
+		t.Fatal(err)
+	}
+	if len(roleDetail.Permissions) != 2 {
+		t.Fatalf("expected 2 perms, got %#v", roleDetail.Permissions)
+	}
+
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/audit-logs", nil, superTok)
+	if code != 200 {
+		t.Fatalf("audit: %d", code)
+	}
+	var audit struct {
+		Items []struct {
+			Action string `json:"action"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &audit)
+	foundUpdate, foundDeny := false, false
+	for _, it := range audit.Items {
+		if it.Action == "roles.permissions.update" {
+			foundUpdate = true
+		}
+		if it.Action == "permission.denied" {
+			foundDeny = true
+		}
+	}
+	if !foundUpdate {
+		t.Fatal("expected roles.permissions.update audit")
+	}
+	if !foundDeny {
+		t.Fatal("expected permission.denied audit")
+	}
+
+	// AC-S-04: system role cannot be deleted (FK + system seed; no Delete API)
+	tag, err := pool.Exec(ctx, `DELETE FROM admin_roles WHERE name='super_admin'`)
+	if err == nil && tag.RowsAffected() > 0 {
+		t.Fatal("expected delete super_admin to fail or affect 0 rows")
+	}
+
+	// AC-P-01: list roles under 500ms locally
+	start := time.Now()
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/roles", nil, superTok)
+	if code != 200 || time.Since(start) > 500*time.Millisecond {
+		t.Fatalf("AC-P-01 list roles slow or failed: http=%d dur=%v", code, time.Since(start))
+	}
+}

apps/api/internal/middleware/admin_permission.go

@@ -0,0 +1,42 @@
+package middleware
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"github.com/yuxingu/digital-psychology/apps/api/pkg/response"
+)
+
+// AdminPermissionChecker validates admin permission codes.
+type AdminPermissionChecker interface {
+	HasPermission(ctx context.Context, adminID uuid.UUID, code string) (bool, error)
+	DenyPermission(ctx context.Context, adminID uuid.UUID, code, path string)
+}
+
+// RequireAdminPermission aborts with 403 when the admin lacks code.
+func RequireAdminPermission(checker AdminPermissionChecker, code string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		adminID, ok := AdminIDFromContext(c)
+		if !ok {
+			response.Fail(c, http.StatusUnauthorized, 40102, "admin session invalid")
+			c.Abort()
+			return
+		}
+		okPerm, err := checker.HasPermission(c.Request.Context(), adminID, code)
+		if err != nil {
+			response.Fail(c, http.StatusInternalServerError, 50000, "permission check failed")
+			c.Abort()
+			return
+		}
+		if !okPerm {
+			checker.DenyPermission(c.Request.Context(), adminID, code, c.FullPath())
+			response.Fail(c, http.StatusForbidden, 40301, "forbidden")
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}

apps/api/internal/repository/admin_rbac_repo.go

@@ -0,0 +1,131 @@
+package repository
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// AdminRole is an ops RBAC role.
+type AdminRole struct {
+	ID        uuid.UUID `json:"id"`
+	Name      string    `json:"name"`
+	System    bool      `json:"system"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// ListAdminRoles returns all roles.
+func (r *AdminRepo) ListAdminRoles(ctx context.Context) ([]AdminRole, error) {
+	rows, err := r.Pool.Query(ctx, `
+		SELECT id, name, system, created_at FROM admin_roles ORDER BY name`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []AdminRole
+	for rows.Next() {
+		var a AdminRole
+		if err := rows.Scan(&a.ID, &a.Name, &a.System, &a.CreatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, a)
+	}
+	return out, rows.Err()
+}
+
+// GetAdminRole loads one role.
+func (r *AdminRepo) GetAdminRole(ctx context.Context, id uuid.UUID) (*AdminRole, error) {
+	var a AdminRole
+	err := r.Pool.QueryRow(ctx, `
+		SELECT id, name, system, created_at FROM admin_roles WHERE id=$1`, id,
+	).Scan(&a.ID, &a.Name, &a.System, &a.CreatedAt)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &a, nil
+}
+
+// ListRolePermissions returns permission codes for a role.
+func (r *AdminRepo) ListRolePermissions(ctx context.Context, roleID uuid.UUID) ([]string, error) {
+	rows, err := r.Pool.Query(ctx, `
+		SELECT code FROM admin_role_permissions WHERE role_id=$1 ORDER BY code`, roleID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var c string
+		if err := rows.Scan(&c); err != nil {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+// ReplaceRolePermissions replaces the full permission set for a role.
+func (r *AdminRepo) ReplaceRolePermissions(ctx context.Context, roleID uuid.UUID, codes []string) error {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+	if _, err := tx.Exec(ctx, `DELETE FROM admin_role_permissions WHERE role_id=$1`, roleID); err != nil {
+		return err
+	}
+	for _, code := range codes {
+		if _, err := tx.Exec(ctx, `
+			INSERT INTO admin_role_permissions(role_id, code) VALUES ($1,$2)`, roleID, code); err != nil {
+			return err
+		}
+	}
+	return tx.Commit(ctx)
+}
+
+// ListPermissionsForAdmin returns permission codes for an admin account.
+func (r *AdminRepo) ListPermissionsForAdmin(ctx context.Context, adminID uuid.UUID) ([]string, error) {
+	rows, err := r.Pool.Query(ctx, `
+		SELECT p.code
+		FROM admin_accounts a
+		JOIN admin_role_permissions p ON p.role_id = a.role_id
+		WHERE a.id=$1 AND a.deleted_at IS NULL AND a.role_id IS NOT NULL
+		ORDER BY p.code`, adminID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var c string
+		if err := rows.Scan(&c); err != nil {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+// GetAdminRoleMeta returns role id/name for an account.
+func (r *AdminRepo) GetAdminRoleMeta(ctx context.Context, adminID uuid.UUID) (roleID *uuid.UUID, name string, err error) {
+	var id uuid.UUID
+	err = r.Pool.QueryRow(ctx, `
+		SELECT r.id, r.name
+		FROM admin_accounts a
+		JOIN admin_roles r ON r.id = a.role_id
+		WHERE a.id=$1 AND a.deleted_at IS NULL`, adminID,
+	).Scan(&id, &name)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, "", nil
+	}
+	if err != nil {
+		return nil, "", err
+	}
+	return &id, name, nil
+}

apps/api/internal/repository/admin_repo.go

@@ -32,12 +32,15 @@ func (r *AdminRepo) CountAccounts(ctx context.Context) (int, error) {
 	return n, err
 }
 
-// CreateAccount inserts an admin account.
+// CreateAccount inserts an admin account with seeded super_admin role.
 func (r *AdminRepo) CreateAccount(ctx context.Context, username, hash string) (uuid.UUID, error) {
 	var id uuid.UUID
 	err := r.Pool.QueryRow(ctx, `
-		INSERT INTO admin_accounts(username, password_hash)
-		VALUES ($1,$2) RETURNING id`, username, hash).Scan(&id)
+		INSERT INTO admin_accounts(username, password_hash, role_id)
+		VALUES (
+			$1, $2,
+			(SELECT id FROM admin_roles WHERE name = 'super_admin' LIMIT 1)
+		) RETURNING id`, username, hash).Scan(&id)
 	return id, err
 }
 

apps/api/internal/service/admin/rbac.go

@@ -0,0 +1,135 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+
+	"github.com/google/uuid"
+)
+
+// Permission catalog frozen in ECR-013A Spec.
+const (
+	PermUsersRead         = "admin.users.read"
+	PermMembershipGrant   = "admin.users.membership.grant"
+	PermAskQuotaGrant     = "admin.users.ask_quota.grant"
+	PermOrdersRead        = "admin.orders.read"
+	PermAuditRead         = "admin.audit.read"
+	PermAnalyticsRead     = "admin.analytics.read"
+	PermContentWrite      = "admin.content.write"
+	PermRolesRead         = "admin.roles.read"
+	PermRolesWrite        = "admin.roles.write"
+)
+
+var knownPermissions = map[string]struct{}{
+	PermUsersRead: {}, PermMembershipGrant: {}, PermAskQuotaGrant: {},
+	PermOrdersRead: {}, PermAuditRead: {}, PermAnalyticsRead: {},
+	PermContentWrite: {}, PermRolesRead: {}, PermRolesWrite: {},
+}
+
+var (
+	ErrForbidden     = errString("forbidden")
+	ErrRoleNotFound  = errString("role not found")
+	ErrInvalidPerm   = errString("invalid permission code")
+	ErrProtectSystem = errString("system role protected")
+)
+
+// AdminMe is the public admin profile (with RBAC).
+type AdminMe struct {
+	ID          uuid.UUID `json:"id"`
+	Username    string    `json:"username"`
+	Role        string    `json:"role,omitempty"`
+	Permissions []string  `json:"permissions"`
+}
+
+// RoleDTO is list/detail payload.
+type RoleDTO struct {
+	ID          uuid.UUID `json:"id"`
+	Name        string    `json:"name"`
+	System      bool      `json:"system"`
+	Permissions []string  `json:"permissions,omitempty"`
+}
+
+// HasPermission reports whether admin holds code.
+func (s *Service) HasPermission(ctx context.Context, adminID uuid.UUID, code string) (bool, error) {
+	perms, err := s.Repo.ListPermissionsForAdmin(ctx, adminID)
+	if err != nil {
+		return false, err
+	}
+	for _, p := range perms {
+		if p == code {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// DenyPermission audits a forbidden attempt.
+func (s *Service) DenyPermission(ctx context.Context, adminID uuid.UUID, code, path string) {
+	meta, _ := json.Marshal(map[string]string{"permission": code, "path": path})
+	_ = s.Repo.InsertAudit(ctx, adminID, "permission.denied", "permission", code, meta)
+}
+
+// Me returns the current admin profile with permissions.
+func (s *Service) Me(ctx context.Context, adminID uuid.UUID) (*AdminMe, error) {
+	acc, err := s.Repo.FindAccountByID(ctx, adminID)
+	if err != nil || acc == nil {
+		return nil, errors.New("admin not found")
+	}
+	perms, err := s.Repo.ListPermissionsForAdmin(ctx, adminID)
+	if err != nil {
+		return nil, err
+	}
+	if perms == nil {
+		perms = []string{}
+	}
+	_, roleName, _ := s.Repo.GetAdminRoleMeta(ctx, adminID)
+	return &AdminMe{ID: acc.ID, Username: acc.Username, Role: roleName, Permissions: perms}, nil
+}
+
+// ListRoles returns roles without permissions.
+func (s *Service) ListRoles(ctx context.Context) ([]RoleDTO, error) {
+	roles, err := s.Repo.ListAdminRoles(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]RoleDTO, 0, len(roles))
+	for _, r := range roles {
+		out = append(out, RoleDTO{ID: r.ID, Name: r.Name, System: r.System})
+	}
+	return out, nil
+}
+
+// GetRole returns role + permissions.
+func (s *Service) GetRole(ctx context.Context, id uuid.UUID) (*RoleDTO, error) {
+	role, err := s.Repo.GetAdminRole(ctx, id)
+	if err != nil || role == nil {
+		return nil, ErrRoleNotFound
+	}
+	perms, err := s.Repo.ListRolePermissions(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if perms == nil {
+		perms = []string{}
+	}
+	return &RoleDTO{ID: role.ID, Name: role.Name, System: role.System, Permissions: perms}, nil
+}
+
+// ReplaceRolePermissions updates permissions with audit.
+func (s *Service) ReplaceRolePermissions(ctx context.Context, adminID, roleID uuid.UUID, codes []string) error {
+	role, err := s.Repo.GetAdminRole(ctx, roleID)
+	if err != nil || role == nil {
+		return ErrRoleNotFound
+	}
+	for _, c := range codes {
+		if _, ok := knownPermissions[c]; !ok {
+			return ErrInvalidPerm
+		}
+	}
+	if err := s.Repo.ReplaceRolePermissions(ctx, roleID, codes); err != nil {
+		return err
+	}
+	meta, _ := json.Marshal(map[string]any{"permissions": codes, "role": role.Name})
+	return s.Repo.InsertAudit(ctx, adminID, "roles.permissions.update", "admin_role", roleID.String(), meta)
+}

apps/api/internal/service/admin/service.go

@@ -6,7 +6,6 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"encoding/json"
-	"errors"
 	"time"
 
 	"github.com/google/uuid"
@@ -54,12 +53,6 @@ type LoginResult struct {
 	Admin     AdminMe   `json:"admin"`
 }
 
-// AdminMe is the public admin profile.
-type AdminMe struct {
-	ID       uuid.UUID `json:"id"`
-	Username string    `json:"username"`
-}
-
 var (
 	ErrBadCredentials = errString("invalid credentials")
 	ErrInvalidPlan    = errString("invalid plan")
@@ -90,10 +83,14 @@ func (s *Service) Login(ctx context.Context, username, password string) (*LoginR
 	if err := s.Repo.CreateSession(ctx, acc.ID, token, exp); err != nil {
 		return nil, err
 	}
+	me, err := s.Me(ctx, acc.ID)
+	if err != nil {
+		return nil, err
+	}
 	return &LoginResult{
 		Token:     token,
 		ExpiresAt: exp,
-		Admin:     AdminMe{ID: acc.ID, Username: acc.Username},
+		Admin:     *me,
 	}, nil
 }
 
@@ -110,15 +107,6 @@ func (s *Service) Logout(ctx context.Context, token string) error {
 	return s.Repo.DeleteSession(ctx, token)
 }
 
-// Me returns the current admin profile.
-func (s *Service) Me(ctx context.Context, adminID uuid.UUID) (*AdminMe, error) {
-	acc, err := s.Repo.FindAccountByID(ctx, adminID)
-	if err != nil || acc == nil {
-		return nil, errors.New("admin not found")
-	}
-	return &AdminMe{ID: acc.ID, Username: acc.Username}, nil
-}
-
 // ListUsers lists terminal users.
 func (s *Service) ListUsers(ctx context.Context, q string, limit, offset int) ([]repository.UserListItem, error) {
 	return s.Repo.ListUsers(ctx, q, limit, offset)

apps/api/migrations/000015_admin_rbac.down.sql

@@ -0,0 +1,4 @@
+UPDATE admin_accounts SET role_id = NULL WHERE role_id IS NOT NULL;
+ALTER TABLE admin_accounts DROP COLUMN IF EXISTS role_id;
+DROP TABLE IF EXISTS admin_role_permissions;
+DROP TABLE IF EXISTS admin_roles;

apps/api/migrations/000015_admin_rbac.up.sql

@@ -0,0 +1,42 @@
+-- ECR-013A Admin RBAC
+
+CREATE TABLE IF NOT EXISTS admin_roles (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  name varchar(64) NOT NULL UNIQUE,
+  system boolean NOT NULL DEFAULT false,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS admin_role_permissions (
+  role_id uuid NOT NULL REFERENCES admin_roles(id) ON DELETE CASCADE,
+  code varchar(64) NOT NULL,
+  PRIMARY KEY (role_id, code)
+);
+
+ALTER TABLE admin_accounts
+  ADD COLUMN IF NOT EXISTS role_id uuid REFERENCES admin_roles(id);
+
+INSERT INTO admin_roles(id, name, system)
+VALUES ('00000000-0000-4000-8000-000000000001', 'super_admin', true)
+ON CONFLICT (name) DO NOTHING;
+
+INSERT INTO admin_role_permissions(role_id, code)
+SELECT r.id, p.code
+FROM admin_roles r
+CROSS JOIN (VALUES
+  ('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')
+) AS p(code)
+WHERE r.name = 'super_admin'
+ON CONFLICT DO NOTHING;
+
+UPDATE admin_accounts
+SET role_id = (SELECT id FROM admin_roles WHERE name = 'super_admin')
+WHERE role_id IS NULL AND deleted_at IS NULL;

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

@@ -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  

docs/CHANGELOG.md

@@ -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  

docs/CODE_REVIEW/ECR-013A.md

@@ -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）
+```

docs/CONTRACT_DIFF/ECR-013A.yaml

@@ -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"

docs/CONTRACT_DIFF/README.md

@@ -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。

docs/ECR/ECR-013A-admin-rbac.md

@@ -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  

docs/ENGINEERING_SPEC/ECR-013A-admin-rbac.md

@@ -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 无回归

docs/HANDOFF/ECR-013A-architect-to-engineer.md

@@ -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`  

docs/HANDOFF/ECR-013A-engineer-to-reviewer.md

@@ -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）。

docs/PRODUCT_SPEC/ECR-013A-admin-rbac.md

@@ -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。

docs/PROJECT_PROFILE.md

@@ -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**）

docs/STATE/ECR-013A.md

@@ -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）。

docs/TASKS/TASK-013A-ECR013A.yaml

@@ -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

docs/TEST_REPORT/ECR-013A.md

@@ -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` 本机 < 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**

docs/TRACEABILITY.md

@@ -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 |

docs/WAVE0/HUMAN_REVIEW.md

@@ -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
 ```

proto/openapi.yaml

@@ -74,10 +74,73 @@ paths:
   /api/v1/admin/me:
     get:
       tags: [admin]
-      summary: Current admin
+      summary: Current admin (role + permissions[])
       responses:
         '200':
           description: OK
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/Envelope'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/AdminMe'
+
+  /api/v1/admin/roles:
+    get:
+      tags: [admin]
+      summary: List admin roles
+      description: Requires admin.roles.read
+      responses:
+        '200':
+          description: OK
+        '403':
+          description: Forbidden
+
+  /api/v1/admin/roles/{id}:
+    get:
+      tags: [admin]
+      summary: Role detail with permissions
+      description: Requires admin.roles.read
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      responses:
+        '200':
+          description: OK
+        '403':
+          description: Forbidden
+        '404':
+          description: Not found
+
+  /api/v1/admin/roles/{id}/permissions:
+    put:
+      tags: [admin]
+      summary: Replace role permission set
+      description: Requires admin.roles.write; writes AuditLog
+      parameters:
+        - $ref: '#/components/parameters/Id'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [permissions]
+              properties:
+                permissions:
+                  type: array
+                  items: { type: string }
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Invalid permission code
+        '403':
+          description: Forbidden
+        '404':
+          description: Not found
 
   /api/v1/admin/users:
     get:
@@ -887,6 +950,17 @@ components:
         message: { type: string, example: success }
         data: { type: object }
 
+    AdminMe:
+      type: object
+      required: [id, username, permissions]
+      properties:
+        id: { type: string, format: uuid }
+        username: { type: string }
+        role: { type: string }
+        permissions:
+          type: array
+          items: { type: string }
+
     CreateProfileRequest:
       type: object
       required: [relation, birth_date]