# Feature Spec: 运营后台（Ops Admin）

> Status: `Active` · Map: `§7 运营后台 [Ops · Phase A]` · Phase: `Ops-A`  
> 规范：[../feature-design.md](../feature-design.md)  
> 对标推导参考：`cece-frontend-re/complete-design/40-ops-commerce.md`（IA 全量；本 Spec 只交付 Phase A）

---

## 1. 功能定义

| 字段 | 内容 |
|---|---|
| Name | 运营后台 |
| Purpose | 让内部运营/客服在受控权限下查询用户与商业数据，并做可审计的会员权益干预 |
| Business Goal | 支撑 P1 用户侧交付后的日常运维；避免直接改库 |

| In（Phase A） | Out（后置） |
|---|---|
| 管理员账号登录 / 会话 | UGC 审核 · 达人 · 推送任务 |
| 用户列表 / 详情（档案摘要） | 首页运营位 / 工具配置 CMS |
| 订单列表 | 优惠券 · 退款工单流 |
| 成长会员只读 + **授予/延长**（mock 履约） | 真支付渠道配置 |
| 操作审计日志 | 真支付渠道配置 |
| `apps/admin-h5` 桌面友好壳 | 小程序后台 |

> Phase E（ECR-010）：RBAC / 封禁 / 推送占位见 [ops-system.md](ops-system.md)。

---

## 2. 用户价值

1. **为何需要：** P1 已有用户/会员/订单，无控制台则只能改库，风险高。  
2. **完成后获得：** 可检索用户、看会员与订单、安全授予会员并留痕。  
3. **为何付费：** N/A（内部工具）。

---

## 3. 用户角色

| Actor | 说明 | 本功能能力 |
|---|---|---|
| Guest / Visitor | 终端用户身份 | **无**后台入口 |
| User / VIP | 终端用户 | **无** |
| Admin（Phase A） | `admin_accounts` 账号 | 登录；读写本 Spec In 范围 API |
| 运营/审核/客服分角色 | 后置 | Phase A 全部等同 Admin |

---

## 4. 用户流程

```text
打开 admin-h5
  ↓
未登录 → /login（用户名+密码）
  ↓ POST /api/v1/admin/auth/login
  ↓ 存 token → 壳布局
  ↓
用户列表 / 订单 / 审计
  ↓ 点用户 → 详情（档案数 · 会员 · 近单）
  ↓ [可选] 授予会员 → 写 memberships + audit_logs
失败：401 回登录；403/5xx 页内错误态
```

---

## 5. 页面设计

| 路由 | 页面 | 说明 |
|---|---|---|
| `/login` | LoginPage | 无壳 |
| `/` | UsersPage | 用户列表 |
| `/users/:id` | UserDetailPage | 用户详情 + 授予会员 |
| `/orders` | OrdersPage | 订单列表 |
| `/audit` | AuditPage | 审计日志 |

```text
AdminShell
├── Nav: 用户 | 订单 | 审计 | 退出
└── Outlet
```

对照：不进入 user-h5 `page-tree`；独立 `apps/admin-h5`。

---

## 6. 页面状态

| 页 | Loading | Empty | Error | Normal | Locked |
|---|---|---|---|---|---|
| Login | 提交中 | — | 账号错误 | 表单 | — |
| Users | 表格骨架 | 无用户 | 拉取失败 | 分页列表 | 未登录→登录 |
| UserDetail | 骨架 | 用户不存在 | 失败 | 摘要+操作 | — |
| Orders / Audit | 同 Users | 无记录 | 失败 | 列表 | — |

---

## 7. Business Rules

| ID | Rule |
|---|---|
| R1 | 管理员鉴权与终端 `DeviceAuth` **隔离**；禁止用 `X-Device-Key` 访问 `/admin/*` |
| R2 | 除 `POST /admin/auth/login` 外，admin API 必须带有效 Admin Token |
| R3 | 用户列表默认按 `created_at DESC`；支持 `q` 精确匹配 `users.id`（UUID） |
| R4 | 授予会员：`plan ∈ {month,quarter,year}`；写入/更新 `memberships` 为 `active`，`expires_at` 按套餐延长；**必须**写 `admin_audit_logs` |
| R5 | Phase A **不**提供封禁/注销（避免误伤；后置） |
| R6 | Bootstrap：仅当 `admin_accounts` 为空且配置了 bootstrap 密码时，启动可种子一个超级管理员 |
| R7 | 审计日志只追加，不可通过 API 删除/篡改 |
| R8 | 文案用愈心谷 lexicon；UI 不出现竞品品牌词 |

---

## 8. 数据模型影响

新增表（见 `.ai/domain/erd.md`）：

- `admin_accounts` — 管理员账号（password_hash）
- `admin_sessions` — 会话 token
- `admin_audit_logs` — 操作审计

复用只读：`users` · `profiles` · `memberships` · `orders`

---

## 9. API 需求

前缀：`/api/v1/admin`

| Method | Path | 意图 |
|---|---|---|
| POST | `/auth/login` | 登录，返回 token + account |
| POST | `/auth/logout` | 注销当前会话 |
| GET | `/me` | 当前管理员 |
| GET | `/stats` | 仪表盘概览计数 |
| GET | `/users` | 列表 `?q=` 支持 UUID / 手机 / 昵称 |
| GET | `/users/:id` | 详情（档案 · 报告 · 会员 · 问答额度 · 近订单） |
| POST | `/users/:id/membership/grant` | 授予/延长会员 |
| POST | `/users/:id/ask-quota/grant` | 增加已购问答额度 `{delta}` |
| GET | `/orders` | 订单列表 |
| GET | `/audit-logs` | 审计列表 |

信封仍为 `{code,message,data}`。细节同步 OpenAPI。

---

## 10. 权限设计

| 能力 | Admin Phase A |
|---|---|
| 登录 / me / logout | ✓ |
| 用户读 | ✓ |
| 订单读 | ✓ |
| 授予会员 | ✓ |
| 审计读 | ✓ |
| 改用户 status / 删数据 | ✗ |

---

## 11. 埋点

| event | 属性 |
|---|---|
| `admin_login` | ok / fail_reason |
| `admin_user_view` | user_id |
| `admin_membership_grant` | user_id, plan |
| `admin_page_view` | route |

Phase A 可先 `console`/本地；不挡验收。

---

## 12. 测试验收标准

| # | Given / When / Then |
|---|---|
| T1 | 无 token 调 GET `/admin/users` → 401 |
| T2 | 正确账号登录 → 200 + token；错密 → 非 0 code |
| T3 | 登录后列表可见已有 users |
| T4 | grant membership → memberships active + audit 一条 |
| T5 | admin-h5：登录 → 用户列表 → 详情 → 授予 → 审计页可见 |

---

## 13. AI 开发前检查

- [x] 有 Active Spec（本文件）
- [x] feature-map §7 已挂
- [x] ERD / API 意图已写
- [x] In/Out 边界清晰（无 UGC/达人）
- [x] ECR-006 Approved + BACKEND_DESIGN
- [x] 实现后过 DoD + Review Report

---

## Review Report（Phase A）

- Feature: 运营后台 Phase A  
- Scope label: **Feature Complete**（Ops-A；非 P1 Complete 扩展）  
- Architecture: PASS — admin 与 DeviceAuth 隔离；H→S→R  
- API: PASS — `/api/v1/admin/*` + OpenAPI  
- Security: PASS — bcrypt · session token · 审计  
- Test: PASS — `TestAdminOpsPhaseA` · `TestPlanDays` · `build:admin`  
- Known Issues: SDK 未并入 admin；RBAC/CMS 后置  

---

## 分期

| Phase | 内容 |
|---|---|
| **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 |
| **F（ECR-013B Closed）** | AccountLifecycle — Spec `ops-account-lifecycle.md` |
| **G（ECR-014 Closed）** | MembershipPlan — Spec `ops-membership-plan.md` |
| **H（ECR-015 Closed）** | RedemptionCode — Spec `ops-redemption-code.md` |
| **I（ECR-016 Closed）** | UserIntelligence — Spec `ops-user-intelligence.md` |
| **J（ECR-017 Closed）** | AskOperations — Spec `ops-ask-operations.md` |
| **K（ECR-018 Closed）** | Entitlement — Spec `ops-entitlement.md` |
| **L（ECR-019 Closed）** | ContentSafety FilterRule — Spec `ops-content-safety.md` |
| **M（ECR-020 Closed）** | QualityFeedback — Spec `ops-quality-feedback.md` |
| **N（ECR-021 Closed）** | AICoreConfig SystemPrompt — Spec `ops-ai-core-config.md` |
| **O（ECR-022 Closed）** | CrisisCare CrisisPolicy — Spec `ops-crisis-care.md` |
| 后置 | Knowledge·Tools 写面 / CrisisEvent / 真支付（Loop 续跑） |
| D | 订单筛选 · 展示价 · 退款只读（另开 ECR） |
| 后置 | 封禁加深（Account_Risk）· 推送占位 |