jackyu66gitandCursor
de224184a6
新增 crisis_policies、admin.crisis.read、列表/试匹配 API 与 admin-h5「危机」页；禁 CrisisEvent 写/UGC/真支付。 Co-authored-by: Cursor <cursoragent@cursor.com>
225 lines
7.5 KiB
Markdown
225 lines
7.5 KiB
Markdown
# 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 履约） | 真支付渠道配置 |
|
||
| 操作审计日志 | 细粒度 RBAC（多角色矩阵） |
|
||
| `apps/admin-h5` 桌面友好壳 | 小程序后台 |
|
||
|
||
---
|
||
|
||
## 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）· 推送占位 |
|