Files

T

jackyu66gitandCursor de224184a6 feat(ECR-022): CrisisCare CrisisPolicy 只读并 Closed

新增 crisis_policies、admin.crisis.read、列表/试匹配 API 与 admin-h5「危机」页；禁 CrisisEvent 写/UGC/真支付。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-08 01:28:45 +08:00

7.5 KiB

Raw Blame History

Feature Spec: 运营后台（Ops Admin）

Status: Active · Map: §7 运营后台 [Ops · Phase A] · Phase: Ops-A
规范：../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. 用户价值

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

3. 用户角色

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

4. 用户流程

打开 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	审计日志

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 开发前检查

有 Active Spec（本文件）
feature-map §7 已挂
ERD / API 意图已写
In/Out 边界清晰（无 UGC/达人）
ECR-006 Approved + BACKEND_DESIGN
实现后过 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）· 推送占位

7.5 KiB Raw Blame History Unescape Escape