# 测试用例总矩阵 — 用户故事方式（需求驱动）

**文档版本**: v2.0
**编写方式**: 按用户故事（As a... I want to... so that...），基于需求而非已有实现
**覆盖功能**: 家庭管理 · 任务 · 心愿 · 五维能量 · 测评 · 成长档案 · 文章 · 活动 · 商城 · 订单 · 会员 · 供应商 · 规划师 · 后台管理
**测试环境**: `http://cfc.iwintrue.com:80`
**账号体系**: admin(13800138000, id=7) | parent(13701366188, id=8, familyId=2) | vendor(13800138001, id=81069)

---

## 一、用户故事分类索引

| 编号 | 功能域 | 角色 | 故事数 | 优先级 |
|------|--------|------|--------|--------|
| UC-01 | 家庭管理 | 家长 | 7 | P0 |
| UC-02 | 任务管理 | 家长 · 孩子 · 规划师 | 12 | P0 |
| UC-03 | 心愿管理 | 孩子 · 家长 | 6 | P0 |
| UC-04 | 积分系统 | 家长 · 孩子 · 管理员 | 4 | P0 |
| UC-05 | 五维能量 | 全角色 | 6 | P0 |
| UC-06 | 打卡与连续 | 家长 · 孩子 | 6 | P0 |
| UC-07 | 测评流程 | 家长 · 规划师 · 管理员 | 8 | P0 |
| UC-08 | 成长档案 | 家长 · 孩子 | 7 | P0 |
| UC-09 | 文章管理 | 管理员 · 用户 | 8 | P0 |
| UC-10 | 活动报名 | 管理员 · 家长 · 孩子 | 7 | P1 |
| UC-11 | 商城商品 | 供应商 · 管理员 · 用户 | 8 | P1 |
| UC-12 | 订单生命周期 | 用户 · 供应商 · 管理员 | 8 | P1 |
| UC-13 | 会员体系 | 用户 · 管理员 | 5 | P1 |
| UC-14 | 规划师管理 | 规划师 · 管理员 · 家长 | 8 | P1 |
| UC-15 | 供应商入驻 | 供应商 · 管理员 | 4 | P1 |
| UC-16 | 联系人管理 | 家长 | 4 | P2 |
| UC-17 | 能量规则配置 | 管理员 | 4 | P1 |
| UC-18 | 后台管理 | 管理员 | 8 | P0 |
| **合计** | | | **120** | |

---

## 二、用户故事测试用例

---

### UC-01 家庭管理（家长）

> **角色**: 家长（家庭管理员）
> **前置条件**: 已登录，有创建的家庭

---

**US-FAM-01**: 添加家庭成员
> As a **家长**, I want to **选择关系类型、填写信息、添加家庭成员** so that **我可以将家人纳入统一管理**

- 业务流程: 选择关系类型（relationship-types API）→ 填写姓名/手机 → 提交添加
- 端点: `POST /api/family/member/add`
- 预期: 成员添加成功，返回成员ID
- 异常场景: 重复手机号 → 提示"成员已存在"；空参数 → 参数校验失败
- 优先级: P0

**US-FAM-02**: 查看家庭成员列表
> As a **家长**, I want to **查看所有家庭成员及其关系** so that **我可以了解家庭结构**

- 端点: `POST /api/family/member/list`
- 预期: 返回家庭成员列表，含关系类型、capabilityRole
- 优先级: P0

**US-FAM-03**: 切换孩子视图/恢复家长视图
> As a **家长**, I want to **切换到孩子的视角查看系统** so that **我可以以孩子身份完成任务、查看数据**

- 业务流程: 切换(childId) → 孩子视图 → 操作(打卡/任务) → 恢复家长视图
- 端点: `POST /api/family/member/switch` → `POST /api/family/member/switch-back`
- 预期: 切换成功后当前角色变为child，恢复后变回parent
- 异常: 无效childId → 切换失败
- 优先级: P0

**US-FAM-04**: 移除家庭成员
> As a **家长**, I want to **移除指定家庭成员** so that **我可以管理家庭人员变更**

- 端点: `POST /api/family/member/{id}/remove`
- 预期: 成员移除成功，不再出现在家庭列表中
- 异常: 移除自己 → 拒绝；移除不存在的成员 → 提示不存在
- 优先级: P0

**US-FAM-05**: 获取关系类型字典
> As a **家长**, I want to **查看系统支持的所有家庭成员关系类型** so that **我可以选择正确的关系添加成员**

- 端点: `POST /api/family/member/relationship-types`
- 预期: 返回已启用的关系类型列表（如父亲/母亲/儿子/女儿等）
- 优先级: P0

**US-FAM-06**: 生成/使用家庭邀请码
> As a **家长**, I want to **生成家庭邀请二维码并分享给家人** so that **家人可以通过扫码加入我的家庭**

- 业务流程: 生成二维码 → 家人扫码 → 加入家庭
- 端点: `POST /api/invite/qrcode`
- 预期: 返回带令牌的二维码，扫码后可加入指定家庭
- 优先级: P1

**US-FAM-07**: 编辑家庭成员关系
> As a **家长**, I want to **编辑已有成员的关系类型** so that **当家庭关系变化时可以及时更新**

- 业务流程: 选择成员 → 选择新关系类型 → 保存
- 预期: 成员关系类型更新成功
- 优先级: P1

---

### UC-02 任务管理（家长 · 孩子 · 规划师）

> **角色**: 家长创建/审核、孩子执行、规划师下发/审核

---

**US-TASK-01**: 家长创建任务（给孩子）
> As a **家长**, I want to **为孩子创建任务（含可选小游戏）** so that **孩子有明确的成长目标**

- 业务流程: 选择孩子 → 填写任务内容 → 选择分类(category) → 选择小游戏(可选) → 创建
- 端点: `POST /api/tasks/create`
- 请求体: `CreateTaskDTO` (title, category, childId, minigameId, etc.)
- 预期: 任务创建成功，返回taskId
- 异常: 未选择孩子 → "请选择孩子"
- 优先级: P0

**US-TASK-02**: 孩子查看今日任务
> As a **孩子**, I want to **查看今天的待完成任务** so that **我知道今天需要做什么**

- 端点: `POST /api/tasks/today` (含childId, 可选category)
- 预期: 返回今日任务列表，包含状态、分类、能量值
- 优先级: P0

**US-TASK-03**: 孩子完成任务/提交
> As a **孩子**, I want to **完成一项任务并提交（含拍照）** so that **家长/规划师可以审核我的完成情况**

- 端点: `POST /api/tasks/{id}/complete`
- 请求体: childId, photoUrl(可选)
- 预期: 任务状态变为pending_review，记录完成时间和证据
- 异常: 重复提交 → 提示"任务已完成"
- 优先级: P0

**US-TASK-04**: 家长审核任务
> As a **家长**, I want to **审核孩子提交的任务（通过/驳回）** so that **我可以确认任务质量并发放能量**

- 端点: `POST /api/tasks/{id}/review`
- 请求体: `TaskReviewDTO` (approved, energyAward, comment, reviewNote)
- 预期: 审核通过→孩子获得能量；审核驳回→不获得能量，可重做
- 优先级: P0

**US-TASK-05**: 查看待审核任务列表
> As a **家长**, I want to **查看所有待我审核的孩子任务** so that **我及时处理孩子的任务提交**

- 端点: `POST /api/tasks/pending-review`
- 预期: 返回待审核任务列表，按时间排序
- 优先级: P0

**US-TASK-06**: 查看任务历史
> As a **家长/孩子**, I want to **查看历史任务完成记录** so that **我可以了解孩子的任务完成趋势**

- 端点: `POST /api/tasks/history` (childId, page, size, category可选)
- 预期: 分页返回历史任务，含完成状态、审核结果、获得的能量
- 优先级: P1

**US-TASK-07**: 孩子执行小游戏任务
> As a **孩子**, I want to **完成带小游戏的任务并提交成绩** so that **我可以边玩边完成成长目标**

- 端点: `POST /api/tasks/{id}/complete-minigame`
- 请求体: childId, completionTime(可选), score(可选)
- 预期: 游戏成绩记录，任务完成待审核
- 优先级: P1

**US-TASK-08**: 家长今日任务
> As a **家长**, I want to **查看和完成我自己的今日任务** so that **我也能参与家庭成长**

- 端点: `POST /api/tasks/today-parent` → `POST /api/tasks/{id}/complete-parent`
- 预期: 返回家长自己的任务列表，完成后获得能量
- 优先级: P1

**US-TASK-09**: 批量完成任务
> As a **家长**, I want to **批量完成多个任务** so that **我可以快速处理一组同类任务**

- 端点: `POST /api/tasks/batch-complete` (taskIds, userId)
- 预期: 所有指定任务完成，批量发放能量
- 优先级: P2

**US-TASK-10**: 批量删除任务
> As a **家长**, I want to **批量删除不需要的任务** so that **我可以清理过期/无用的任务**

- 端点: `POST /api/tasks/batch-delete` (taskIds, userId)
- 预期: 指定任务被删除
- 优先级: P2

**US-TASK-11**: 获取可选小游戏列表
> As a **家长/规划师**, I want to **查看系统支持的小游戏** so that **我可以创建带游戏的任务**

- 端点: `POST /api/tasks/minigame-options`
- 预期: 返回已启用的小游戏列表（舒尔特方格/猜数字/数独等）
- 优先级: P1

**US-TASK-12**: 规划师下发任务
> As a **规划师**, I want to **为绑定的家庭孩子创建成长任务** so that **我可以远程指导孩子成长**

- 端点: `POST /api/guide/task/create`
- 预期: 任务创建成功，孩子在今日任务中可见
- 优先级: P0

---

### UC-03 心愿管理（孩子 · 家长）

> **角色**: 孩子创建/兑换、家长定价/审核

---

**US-WISH-01**: 孩子创建心愿
> As a **孩子**, I want to **创建自己的心愿（想要的礼物/奖励）** so that **我可以让家长知道我的愿望**

- 端点: `POST /api/wish/create` (role=child)
- 请求体: `CreateWishDTO` (title, description, category, imageUrl)
- 预期: 心愿创建成功，状态为"pending"待家长定价
- 优先级: P0

**US-WISH-02**: 家长查看/定价心愿
> As a **家长**, I want to **为孩子的心愿设定积分价格** so that **孩子可以通过努力积分来兑换**

- 端点: `PUT /api/wish/{id}/set-price`
- 请求体: pointsRequired(正整数值)
- 预期: 积分设置成功，心愿状态变为"priced"
- 异常: pointsRequired≤0 → 提示"请输入有效的积分值"
- 优先级: P0

**US-WISH-03**: 家长拒绝心愿
> As a **家长**, I want to **拒绝不合理的心愿并说明原因** so that **我可以引导孩子建立正确的价值观**

- 端点: `PUT /api/wish/{id}/reject`
- 请求体: reason
- 预期: 心愿被拒绝，状态变为"rejected"，孩子可见拒绝原因
- 优先级: P1

**US-WISH-04**: 孩子申请兑换心愿
> As a **孩子**, I want to **用积累的积分兑换已定价的心愿** so that **我可以通过自己的努力获得奖励**

- 端点: `POST /api/wish/{id}/exchange`
- 预期: 兑换申请提交，扣减积分，状态变为"exchange_requested"
- 异常: 积分不足 → 提示积分不够
- 优先级: P0

**US-WISH-05**: 家长审批兑换
> As a **家长**, I want to **审批孩子的兑换申请** so that **我最终确认是否让孩子获得该奖励**

- 端点: `PUT /api/wish/{id}/approve-exchange`
- 预期: 审批通过 → 心愿状态变为"fulfilled"；拒绝 → 积分退回
- 优先级: P0

**US-WISH-06**: 查看心愿列表/状态
> As a **家长/孩子**, I want to **查看所有心愿及其状态** so that **我可以跟踪心愿的进展**

- 端点: `/api/wish/list` (含筛选条件)
- 预期: 返回心愿列表，含价格/状态/审核意见
- 优先级: P1

---

### UC-04 积分系统（家长 · 孩子 · 管理员）

> **角色**: 孩子持有积分、家长调整、管理员配置

---

**US-POINTS-01**: 查看积分余额
> As a **家长/孩子**, I want to **查看孩子当前的积分余额** so that **我知道可用于兑换心愿的积分**

- 端点: `POST /api/points/balance` (childId)
- 预期: 返回积分余额（含systemPoints和自定义积分）
- 优先级: P0

**US-POINTS-02**: 查看积分流水
> As a **家长/孩子**, I want to **查看积分变动明细** so that **我可以了解积分的来源和去向**

- 端点: `POST /api/points/logs` (childId, page, size)
- 预期: 分页返回积分流水（每笔记录含类型、数量、余额、原因、时间）
- 优先级: P0

**US-POINTS-03**: 家长手动调整积分
> As a **家长**, I want to **手动增加或扣除孩子的积分** so that **我可以在特殊情况下奖励或惩罚**

- 端点: `POST /api/points/adjust`
- 请求体: childId, amount(正=增加/负=扣除), reason, password
- 预期: 积分调整成功，产生相应流水记录
- 异常: 密码错误 → 拒绝操作；积分不足（扣除时）→ 拒绝
- 优先级: P1

**US-POINTS-04**: 按分类查看积分流水
> As a **家长**, I want to **按分类（任务/心愿/打卡等）筛选积分流水** so that **我可以分析孩子的收入结构**

- 端点: `POST /api/points/logs-by-category` (childId, category, page, size)
- 预期: 按分类返回筛选后的流水
- 优先级: P2

---

### UC-05 五维能量系统（全角色）

> **角色**: 所有角色均可查看，管理员可配置

---

**US-ENERGY-01**: 查看能量总览
> As a **任何用户**, I want to **查看家庭/个人的五维能量分布** so that **我了解身/心/智/行/富各维度的健康状态**

- 端点: `POST /api/energy/overview`
- 预期: 返回五维能量值及各维度占比/等级
- 异常: 无数据时返回空值，不报错
- 优先级: P0

**US-ENERGY-02**: 查看能量流水
> As a **任何用户**, I want to **查看能量获取/消耗明细** so that **我了解哪些行为产生了能量变化**

- 端点: `POST /api/energy/logs`
- 预期: 返回能量流水列表（含维度、数量、来源、时间）
- 优先级: P0

**US-ENERGY-03**: 能量按维度分配
> As a **系统**, when **用户完成某个行为（打卡/任务/测评）**, I want to **按规则自动分配能量到对应维度** so that **能量系统自动运转**

- 验证: 完成身体打卡 → 身维度能量增加；完成任务 → 对应维度能量增加
- 端点: 各行为端点的返回中包含能量变化
- 优先级: P0

**US-ENERGY-04**: 查看健康指数（可选）
> As a **家长**, I want to **查看家庭的综合健康指数** so that **我有量化的家庭幸福度指标**

- 端点: 由energy/overview综合分析得出
- 预期: 返回综合指数及每个维度评分
- 优先级: P1

**US-ENERGY-05**: 管理员查看/配置维度参数
> As a **管理员**, I want to **查看和修改五维能量参数的配置** so that **我可以调整能量发放规则**

- 端点: `POST /api/admin/dimension/config`
- 预期: 能量参数可读取和修改
- 优先级: P1

**US-ENERGY-06**: 导入家庭能量（数据迁移）
> As a **管理员**, I want to **从旧系统(sfms)导入家庭能量数据** so that **老用户可以看到历史能量记录**

- 端点: `POST /api/migration/run`
- 预期: 数据从sfms迁移到zxyj，含能量记录
- 优先级: P1

---

### UC-06 打卡与连续打卡（家长 · 孩子）

> **角色**: 家长和孩子均可打卡，系统自动统计连续天数

---

**US-CHECKIN-01**: 身体健康打卡
> As a **家长/孩子**, I want to **每日进行身体健康打卡** so that **我可以记录健康习惯并获取能量**

- 端点: `POST /api/health/checkin/create`
- 请求体: childId(可选), content, dimension=body
- 预期: 打卡成功+5能量，连续天数更新
- 异常: 当日已打卡 → 提示"今日已打卡"
- 优先级: P0

**US-CHECKIN-02**: 查看健康打卡列表
> As a **家长/孩子**, I want to **查看历史健康打卡记录** so that **回顾自己的健康习惯**

- 端点: `POST /api/health/checkin/list`
- 预期: 返回打卡列表（含日期、内容、连续天数）
- 优先级: P1

**US-CHECKIN-03**: 获取打卡统计
> As a **家长**, I want to **查看打卡统计数据（月/周打卡率）** so that **我了解孩子的习惯坚持情况**

- 端点: `POST /api/health/checkin/stats`
- 预期: 返回统计信息（总天数、连续天数、完成率等）
- 优先级: P1

**US-CHECKIN-04**: 查看连续打卡进度
> As a **家长/孩子**, I want to **查看连续打卡天数及奖励** so that **我有动力保持连续打卡**

- 端点: `POST /api/streak/progress/{childId}`
- 预期: 返回当前连续天数、历史最长、下次奖励阈值
- 权限: 孩子属于当前用户家庭方可查看
- 优先级: P0

**US-CHECKIN-05**: 补打卡（漏打卡场景）
> As a **家长**, I want to **为漏打卡的孩子补打卡** so that **偶尔中断不会丢失连续天数**

- 业务流程: 选择日期 → 补打卡
- 端点: `POST /api/health/checkin/create` (带补卡标识)
- 预期: 补打卡成功但连续天数不重置
- 优先级: P1

**US-CHECKIN-06**: 打卡统计覆盖（admin JWT 场景）
> As a **管理员**, I want to **使用admin token也能获取打卡统计** so that **系统运维时能正常验证打卡模块**

- 端点: `POST /api/health/checkin/stats` (admin token + {})
- 预期: 返回200，有统计数据
- 优先级: P2

---

### UC-07 测评流程（家长 · 规划师 · 管理员）

> **角色**: 家长购买/预约、规划师录入结果、管理员管理套餐

---

**US-ASSESS-01**: 家长创建测评订单
> As a **家长**, I want to **为孩子购买DAN认知/心理测评** so that **我可以全面了解孩子的发展状况**

- 业务流程: 选择家庭 → 选择孩子 → 选择套餐(packageId) → 指定规划师(可选) → 创建订单
- 端点: `POST /api/assessment/order/create`
- 预期: 订单创建成功，返回orderNo和待支付金额
- 异常: 必填参数缺失(familyId/packageId) → 提示参数错误
- 优先级: P0

**US-ASSESS-02**: 家长支付测评订单
> As a **家长**, I want to **支付测评订单** so that **测评流程可以继续**

- 端点: `POST /api/assessment/order/pay`
- 请求体: orderNo, payType
- 预期: 支付成功，订单状态变为paid，自动确认预约
- 优先级: P0

**US-ASSESS-03**: 查看测评订单详情
> As a **家长**, I want to **查看已购买的测评订单详情** so that **我了解测评进度**

- 端点: `POST /api/assessment/order/detail` (orderNo)
- 预期: 返回订单信息（金额、状态、支付时间、规划师等）
- 权限: 仅本人订单可查看
- 优先级: P1

**US-ASSESS-04**: 家长取消测评订单
> As a **家长**, I want to **取消未支付的测评订单** so that **我可以在付款前更改决定**

- 端点: `POST /api/assessment/order/cancel` (orderNo)
- 预期: 待支付状态→已取消；已支付订单→不可取消
- 异常: 订单不存在/无权限 → 相应提示
- 优先级: P1

**US-ASSESS-05**: 家长申请测评退款
> As a **家长**, I want to **对已支付的订单申请退款** so that **服务不满意时可以退款**

- 端点: `POST /api/assessment/order/refund` (orderNo)
- 预期: 已支付→已退款
- 异常: 未支付订单→不可退款
- 优先级: P1

**US-ASSESS-06**: 规划师录入测评结果
> As a **规划师**, I want to **录入孩子的测评结果/评分** so that **家长可以看到测评报告**

- 端点: `POST /api/guide/record/create`
- 预期: 测评结果录入成功，家长端可见
- 优先级: P0

**US-ASSESS-07**: 规划师确认预约
> As a **规划师**, I want to **确认家长的测评预约** so that **双方确认测评时间**

- 端点: `POST /api/assessment/appointment/confirm/{id}`
- 预期: 预约状态变为已确认
- 优先级: P0

**US-ASSESS-08**: 家长查看测评结果/历史
> As a **家长**, I want to **查看孩子的最新/历史测评评分** so that **我了解孩子的发展趋势**

- 端点: `POST /api/assessment/result/latest` → 最新评分
- 端点: `POST /api/assessment/result/history` → 历史评分
- 预期: 返回测评评分及各维度细分
- 优先级: P0

---

### UC-08 成长档案（家长 · 孩子）

> **角色**: 家长创建和管理，孩子查看

---

**US-GROWTH-01**: 创建成长档案
> As a **家长**, I want to **为孩子创建成长档案** so that **我记录孩子的成长数据**

- 端点: `POST /api/growth/record/create`
- 请求体: childId, school, grade, academicPerformance, schoolAddress
- 预期: 成长档案创建成功，返回档案详情
- 异常: 未选择孩子 → "请选择孩子"
- 优先级: P0

**US-GROWTH-02**: 上传测评报告PDF并解析
> As a **家长**, I want to **上传孩子的健康/认知测评PDF报告** so that **系统自动解析报告内容生成评分**

- 端点: `POST /api/growth/record/upload-and-parse` (multipart file)
- 预期: 文件上传成功，返回解析结果（含各维度评分）
- 异常: 空文件 → "请选择文件"
- 优先级: P0

**US-GROWTH-03**: 从上传创建成长档案
> As a **家长**, I want to **基于已解析的报告创建成长档案** so that **解析结果与档案关联**

- 端点: `POST /api/growth/record/create-from-upload`
- 请求体: childId, sourceFileUrl, 各维度分数, reportDate
- 预期: 档案创建成功，关联报告数据
- 优先级: P0

**US-GROWTH-04**: 查看成长档案列表
> As a **家长**, I want to **查看孩子的成长档案列表** so that **我了解孩子全部成长记录**

- 端点: `POST /api/growth/record/list` → 家长所有孩子的档案
- 端点: `POST /api/growth/record/child/{childId}` → 指定孩子的档案
- 预期: 返回档案列表（含学校/年级/评分/时间）
- 优先级: P0

**US-GROWTH-05**: 创建补充记录
> As a **家长**, I want to **为已有档案补充材料** so that **可以完善档案信息**

- 端点: `POST /api/growth/record/supplement`
- 请求体: parentRecordId, childId, 各维度补充分数
- 预期: 补充记录创建成功，关联到主档案
- 优先级: P1

**US-GROWTH-06**: 去重检查
> As a **系统**, I want to **检查是否已存在相同日期的档案** so that **防止重复创建**

- 端点: `POST /api/growth/record/check-duplicate` (childId, reportDate, sourceType)
- 预期: 返回是否重复，如重复则返回已有记录
- 优先级: P1

**US-GROWTH-07**: 删除成长档案
> As a **家长**, I want to **删除不需要的成长档案** so that **我可以管理档案的有效性**

- 端点: `POST /api/growth/record/{id}/delete`
- 预期: 档案删除成功
- 权限: 仅本人创建的档案可删除
- 优先级: P1

---

### UC-09 文章管理（管理员 · 用户）

> **角色**: 管理员CRUD，用户浏览阅读

---

**US-ARTICLE-01**: 管理员创建文章
> As a **管理员**, I want to **创建一篇教育内容文章** so that **平台用户可以看到有价值的内容**

- 端点: `POST /api/admin/articles/create`
- 请求体: title, content, categoryId, summary, coverImage, tags, author, readTime, relatedDimensions, visibility, articleType
- 预期: 文章创建成功，返回文章ID
- 优先级: P0

**US-ARTICLE-02**: 管理员发布/下架文章
> As a **管理员**, I want to **将草稿文章发布或下架已发布文章** so that **控制内容可见性**

- 端点: `POST /api/admin/articles/publish` (id, status)
- 业务流程: 创建(草稿) → 发布(published) → 下架(draft)
- 预期: 状态切换成功，前端可见/不可见
- 优先级: P0

**US-ARTICLE-03**: 管理员编辑/删除文章
> As a **管理员**, I want to **编辑已有文章或删除不需要的文章** so that **我维护内容质量**

- 端点: `POST /api/admin/articles/update` → 更新内容
- 端点: `POST /api/admin/articles/delete` → 删除
- 预期: 更新/删除成功
- 优先级: P0

**US-ARTICLE-04**: 管理员管理文章分类
> As a **管理员**, I want to **创建/编辑/删除文章分类** so that **内容有序组织**

- 端点: `POST /api/admin/articles/categories/list` → 查看
- 端点: `POST /api/admin/articles/categories/create` → 创建
- 端点: `POST /api/admin/articles/categories/update` → 编辑
- 端点: `POST /api/admin/articles/categories/delete` → 删除
- 预期: CRUD成功
- 优先级: P1

**US-ARTICLE-05**: 管理员设置文章精选
> As a **管理员**, I want to **将优质文章设为精选** so that **精选文章在推荐位展示**

- 端点: `POST /api/admin/articles/toggle-featured`
- 预期: 精选状态切换成功
- 优先级: P1

**US-ARTICLE-06**: 管理员上传文章配图
> As a **管理员**, I want to **上传文章配图** so that **文章内容更丰富**

- 端点: `POST /api/admin/articles/upload/image` (multipart file)
- 预期: 图片上传成功，返回URL
- 优先级: P1

**US-ARTICLE-07**: 用户浏览文章列表/详情
> As a **普通用户**, I want to **按分类浏览文章列表并查看详情** so that **我可以阅读感兴趣的内容**

- 端点: `POST /api/articles/list` (含筛选/分页)
- 端点: `POST /api/articles/detail` (id)
- 预期: 返回已发布文章列表，仅可见visibility匹配的文章
- 优先级: P0

**US-ARTICLE-08**: 每日成长贴士
> As a **普通用户**, I want to **在首页看到每日成长贴士** so that **我每天都可以学到新知识**

- 端点: `POST /api/articles/daily-tip`
- 预期: 返回每日推荐内容
- 优先级: P1

---

### UC-10 活动报名（管理员 · 家长 · 孩子）

> **角色**: 管理员创建活动，家长为孩子报名，管理员审核

---

**US-ACT-01**: 管理员创建活动
> As a **管理员**, I want to **创建线下/线上活动** so that **家庭可以报名参加**

- 端点: `POST /api/activity/create`
- 请求体: title, description, dimension(关联维度), startTime, endTime, location, maxParticipants, etc.
- 预期: 活动创建成功
- 优先级: P0

**US-ACT-02**: 管理员发布/结束活动
> As a **管理员**, I want to **发布活动或手动结束已发布的活动** so that **控制活动的可见性和可报名状态**

- 端点: `POST /api/activity/publish` → 发布
- 端点: `POST /api/activity/end` → 结束
- 预期: 状态变更成功，前端可见性变化
- 优先级: P0

**US-ACT-03**: 活动列表/详情浏览
> As a **任何用户**, I want to **按维度筛选活动列表并查看详情** so that **我可以找到感兴趣的活动**

- 端点: `POST /api/activity/list` (dimensionCode, page, size)
- 端点: `POST /api/activity/detail` (id)
- 预期: 返回已发布活动列表/详情，含报名人数和余位
- 优先级: P0

**US-ACT-04**: 家长为孩子报名活动
> As a **家长**, I want to **为孩子报名参加活动** so that **孩子可以参与有意义的线下活动**

- 端点: `POST /api/activity/register`
- 请求体: id(活动ID), childId
- 预期: 报名成功，报名列表可见
- 异常: 名额已满 → "活动已满"；孩子已报名 → "已报名"
- 优先级: P0

**US-ACT-05**: 家长取消报名
> As a **家长**, I want to **取消已报名的活动** so that **计划变更时可以释放名额**

- 端点: `POST /api/activity/cancel-registration` (id, childId)
- 预期: 取消成功，名额释放
- 优先级: P1

**US-ACT-06**: 管理员审核报名/签到
> As a **管理员/活动方**, I want to **审核报名申请并进行签到管理** so that **我控制活动参与质量**

- 端点: `POST /api/admin/activity/registration/list` → 查看报名列表
- 端点: `POST /api/admin/activity/registration/approve` → 批准
- 端点: `POST /api/admin/activity/registration/reject` → 拒绝
- 端点: `POST /api/activity/checkin` → 现场签到
- 预期: 审批状态变更；签到记录生成
- 优先级: P1

**US-ACT-07**: 查看我的报名列表
> As a **家长**, I want to **查看我为孩子报名的所有活动及状态** so that **我可以管理活动日程**

- 端点: `POST /api/activity/my-registrations` (childId, page, size)
- 预期: 返回报名列表（含活动详情、审批状态、签到状态）
- 优先级: P1

---

### UC-11 商城商品（供应商 · 管理员 · 用户）

> **角色**: 供应商创建和管理商品，管理员审核，用户浏览购买

---

**US-PROD-01**: 供应商创建商品
> As a **供应商**, I want to **在平台上架商品** so that **家长可以浏览和购买**

- 端点: `POST /api/product/create`
- 请求体: name, description, price, productType, images, specs, etc.
- 预期: 商品创建成功，状态为pending(待审核)
- 优先级: P0

**US-PROD-02**: 供应商编辑商品
> As a **供应商**, I want to **编辑自己已创建的商品信息** so that **我可以更新商品详情**

- 端点: `POST /api/product/update`
- 预期: 商品信息更新成功
- 权限: 仅本人商品可编辑
- 优先级: P0

**US-PROD-03**: 供应商查看/管理自己的商品
> As a **供应商**, I want to **查看我自己创建的所有商品** so that **我可以管理商品列表**

- 端点: `POST /api/product/my`
- 预期: 返回本人创建的所有商品列表
- 优先级: P0

**US-PROD-04**: 供应商上下架自己的商品
> As a **供应商**, I want to **上架或下架自己已审核通过的商品** so that **我可以控制商品的售卖状态**

- 端点: `POST /api/product/shelve` (productId, action=shelve/unshelve)
- 预期: 已审核商品(approved/on_shelf)→上架/下架成功
- 异常: 未审核商品 → "商品未通过审核"
- 优先级: P0

**US-PROD-05**: 供应商更新商品图片
> As a **供应商**, I want to **更新商品的展示图片** so that **商品展示更吸引人**

- 端点: `POST /api/product/images/update` (productId, images)
- 预期: 商品图片更新成功
- 优先级: P1

**US-PROD-06**: 管理员审核商品
> As a **管理员**, I want to **审核供应商提交的商品（通过/拒绝）** so that **平台商品质量有保障**

- 端点: `POST /api/admin/product/review` (productId, action=approve/reject, reason)
- 预期: 审核通过→状态变为approved；拒绝→变为rejected
- 异常: action非approve/reject → 参数校验失败
- 优先级: P0

**US-PROD-07**: 管理员上下架商品
> As a **管理员**, I want to **全局上架或下架商品** so that **我可以控制平台所有商品的展示**

- 端点: `POST /api/admin/product/shelve` (productId, shelve=true/false)
- 预期: 上架→on_shelf；下架→off_shelf
- 优先级: P0

**US-PROD-08**: 用户浏览商品列表/详情
> As a **任何用户**, I want to **按分类浏览已上架商品并查看详情** so that **我可以发现需要的商品**

- 端点: `POST /api/product/list` (含筛选条件)
- 端点: `POST /api/product/detail` (id)
- 预期: 仅返回状态为on_shelf的商品；详情含规格/价格/图片
- 优先级: P0

---

### UC-12 订单生命周期（用户 · 供应商 · 管理员）

> **角色**: 用户下单支付，供应商发货/自提，可退款和自动取消

---

**US-ORDER-01**: 用户创建商品订单
> As a **用户**, I want to **下单购买商品（支持多商品）** so that **我可以获得需要的商品或服务**

- 业务流程: 选择商品SKU → 加入购物车/直接下单 → 创建订单
- 端点: `POST /api/order/create`
- 请求体: items(商品+数量+SkuId), addressId, remark
- 预期: 订单创建成功，状态为pending(待支付)，返回订单号
- 优先级: P0

**US-ORDER-02**: 用户支付订单
> As a **用户**, I want to **支付待支付的订单** so that **商家可以开始发货**

- 端点: `POST /api/order/pay` (orderNo, payType)
- 预期: 支付成功，状态变为paid
- 异常: 重复支付 → 提示"已支付"
- 优先级: P0

**US-ORDER-03**: 用户取消订单
> As a **用户**, I want to **取消未支付的订单** so that **下单后改变主意可以取消**

- 端点: `POST /api/order/cancel` (orderNo)
- 预期: 待支付→已取消
- 异常: 已支付订单→不可取消(需走退款流程)
- 优先级: P1

**US-ORDER-04**: 用户申请退款
> As a **用户**, I want to **对已支付的订单申请退款** so that **商品不满意可以退款**

- 端点: `POST /api/order/refund` (orderNo)
- 预期: 已支付→退款中/已退款
- 异常: 未支付→不可退款
- 优先级: P1

**US-ORDER-05**: 供应商发货
> As a **供应商**, I want to **为已支付的订单发货** so that **用户可以收到商品**

- 端点: `POST /api/order/ship` (orderNo, logisticsNo, logisticsCompany)
- 预期: 已支付→已发货
- 异常: 未支付→不可发货
- 优先级: P0

**US-ORDER-06**: 用户自提确认
> As a **用户**, I want to **选择自提并在提取时确认收货** so that **不需要物流配送**

- 端点: `POST /api/order/confirm-pickup` (orderNo)
- 预期: 已支付/已发货→已完成
- 优先级: P1

**US-ORDER-07**: 系统超时取消订单
> As a **系统**, when **订单创建后30分钟内未支付**, I want to **自动取消该订单** so that **释放库存**

- 业务流程: 定时任务扫描 → 创建时间>30min且未支付 → 自动取消
- 验证: 创建订单→等待30分钟→订单状态变为cancelled
- 优先级: P1

**US-ORDER-08**: 多商品订单含OrderItem
> As a **系统**, when **用户创建含多个SKU的订单**, I want to **为每个商品生成独立的OrderItem** so that **每个商品可独立处理发货/退款**

- 验证: 订单创建后查询OrderItem列表，每个商品一条记录
- 优先级: P1

---

### UC-13 会员体系（用户 · 管理员）

> **角色**: 用户购买会员，管理员配置

---

**US-MEMBER-01**: 用户查看会员等级和权益
> As a **用户**, I want to **浏览平台提供的会员等级和对应权益** so that **我选择适合自己的会员方案**

- 端点: `POST /api/membership/levels`
- 预期: 返回会员等级列表（含价格/权益/有效期）
- 优先级: P0

**US-MEMBER-02**: 用户购买正式会员
> As a **用户**, I want to **选择会员等级并支付购买** so that **我可以享受会员专属权益**

- 业务流程: 选择等级(levelCode) → 选择支付方式 → 支付成功 → 会员激活
- 端点: `POST /api/membership/create-order` → `POST /api/membership/pay`
- 预期: 订单创建→支付→会员激活，状态变为active
- 异常: 已是会员 → 提示"已是会员"
- 优先级: P0

**US-MEMBER-03**: 用户领取入门会员（免费试用）
> As a **新用户**, I want to **免费领取入门会员** so that **我先体验会员权益再决定是否购买**

- 业务流程: 选择"入门会员" → 免费激活 → 会员生效
- 端点: `POST /api/membership/trial` (familyId)
- 预期: 入门会员激活成功，有效期(如7/30天)
- 异常: 已领取过试用 → "试用已领取"
- 优先级: P1

**US-MEMBER-04**: 用户使用优惠券
> As a **用户**, I want to **在购买会员时使用优惠券** so that **我享受折扣**

- 业务流程: 选择等级 → 使用优惠券(userCouponId) → 价格减免 → 支付扣减后金额
- 端点: `POST /api/membership/create-order` (含userCouponId)
- 预期: 实际支付金额=原价-优惠金额
- 优先级: P1

**US-MEMBER-05**: 管理员配置会员费用
> As a **管理员**, I want to **配置会员费用参数（家庭会员/服务商会员年费）** so that **平台灵活调整定价**

- 系统配置: member_fee_family, member_fee_standard
- 端点: 通过系统配置模块设置
- 预期: 修改后下单时按新价格计算
- 优先级: P1

---

### UC-14 规划师管理（规划师 · 管理员 · 家长）

> **角色**: 规划师入驻/服务家庭，管理员审核，家长绑定

---

**US-GUIDE-01**: 规划师入驻申请
> As a **规划师**, I want to **提交入驻申请** so that **我可以成为平台的成长规划师**

- 端点: `POST /api/vendor/apply`
- 预期: 申请提交成功，状态为pending
- 优先级: P0

**US-GUIDE-02**: 管理员审核规划师申请
> As a **管理员**, I want to **审核规划师的入驻申请（批准/拒绝）** so that **平台规划师质量可控**

- 端点: `POST /api/admin/guide/applications/{id}/approve` → 批准
- 端点: `POST /api/admin/guide/applications/{id}/reject` → 拒绝
- 预期: 状态变更，规划师可登录
- 优先级: P0

**US-GUIDE-03**: 家长绑定规划师
> As a **家长**, I want to **通过邀请码或搜索绑定规划师** so that **家庭获得专业的成长指导**

- 端点: `POST /api/guide/bind/invite` → 规划师邀请绑定
- 端点: `POST /api/bind/accept` → 家长确认绑定
- 预期: 绑定关系建立，状态为active
- 优先级: P0

**US-GUIDE-04**: 查看已绑定的规划师列表
> As a **家长**, I want to **查看家庭绑定的所有规划师** so that **我了解谁在为家庭服务**

- 端点: `POST /api/bind/guides`
- 预期: 返回绑定的规划师列表（含服务类型/价格/状态）
- 优先级: P0

**US-GUIDE-05**: 家长解绑规划师
> As a **家长**, I want to **解除与规划师的绑定关系** so that **服务不满意时可以更换**

- 端点: `POST /api/bind/unbind` (id)
- 预期: 解绑成功，通知规划师
- 优先级: P1

**US-GUIDE-06**: 规划师查看服务家庭列表
> As a **规划师**, I want to **查看我服务的所有家庭** so that **我管理我的客户**

- 端点: `POST /api/guide/family/list`
- 预期: 返回绑定的家庭列表
- 优先级: P0

**US-GUIDE-07**: 规划师查看家庭档案总览
> As a **规划师**, I want to **查看指定家庭的成长数据总览** so that **我了解孩子的整体情况**

- 端点: `POST /api/guide/family/{familyId}/overview`
- 预期: 返回家庭五维能量、孩子列表、近期动态
- 优先级: P0

**US-GUIDE-08**: 规划师创建服务套餐/管理
> As a **管理员/规划师**, I want to **创建和管理服务套餐** so that **家长可以购买套餐**

- 端点: `POST /api/admin/guide/packages/create` → 创建
- 端点: 套餐状态管理(上架/下架)
- 预期: 套餐创建/状态变更成功
- 优先级: P1

---

### UC-15 供应商入驻（供应商 · 管理员）

> **角色**: 供应商申请入驻，管理员审核

---

**US-VENDOR-01**: 供应商提交入驻申请
> As a **供应商**, I want to **提交供应商入驻申请** so that **我可以在平台上架商品**

- 端点: `POST /api/vendor/apply`
- 请求体: companyName, contact, businessLicense, serviceType
- 预期: 申请提交成功，状态pending
- 优先级: P0

**US-VENDOR-02**: 供应商查看入驻状态
> As a **供应商**, I want to **查看入驻申请的审核进度** so that **我了解审核是否通过**

- 端点: `POST /api/vendor/status`
- 预期: 返回当前审核状态(pending/approved/rejected)
- 优先级: P0

**US-VENDOR-03**: 管理员审核供应商
> As a **管理员**, I want to **审核供应商入驻申请** so that **有资质的供应商进入平台**

- 端点: `POST /api/admin/vendor/review`
- 预期: 审核通过→供应商可用；拒绝→可重新提交
- 优先级: P0

**US-VENDOR-04**: 管理员查看供应商列表
> As a **管理员**, I want to **查看所有供应商及状态** so that **我管理平台供应商**

- 端点: `POST /api/admin/vendor/list`
- 预期: 返回供应商列表（含审核状态/入驻时间/商品数量）
- 优先级: P0

---

### UC-16 联系人管理（家长）

> **角色**: 家长管理社会联系人

---

**US-CONTACT-01**: 创建联系人
> As a **家长**, I want to **添加社会联系人（朋友/同事/合作伙伴）** so that **我可以维护社交关系网络**

- 端点: `POST /api/contact/create`
- 请求体: name, phone, relationshipType, remark
- 预期: 联系人创建成功
- 优先级: P2

**US-CONTACT-02**: 从手机通讯录导入
> As a **家长**, I want to **从手机通讯录导入联系人** so that **快速批量添加联系人**

- 端点: `POST /api/contact/import-phone`
- 预期: 联系人导入成功
- 优先级: P2

**US-CONTACT-03**: 记录与联系人的互动
> As a **家长**, I want to **记录与某位联系人的互动** so that **维护关系亲密度**

- 端点: `POST /api/contact/interaction` (id)
- 预期: 互动记录成功，亲密度更新
- 优先级: P2

**US-CONTACT-04**: 联系人CRUD
> As a **家长**, I want to **查看/编辑/删除我的联系人** so that **我管理社交关系**

- 端点: `POST /api/contact/list` → 列表
- 端点: `POST /api/contact/detail` → 详情
- 端点: `POST /api/contact/update` → 编辑
- 端点: `POST /api/contact/delete` → 删除
- 预期: CRUD操作成功
- 优先级: P2

---

### UC-17 能量规则配置（管理员）

> **角色**: 管理员配置各维度的能量发放规则

---

**US-ENERGYRULE-01**: 查看所有能量规则
> As a **管理员**, I want to **查看系统所有能量规则** so that **我了解能量发放逻辑**

- 端点: `POST /api/admin/energy-rule/list`
- 预期: 分页返回能量规则列表（含维度/事件类型/能量值/状态）
- 优先级: P1

**US-ENERGYRULE-02**: 创建能量规则
> As a **管理员**, I want to **新增能量规则（如打卡+5能量）** so that **能量系统可扩展**

- 端点: `POST /api/admin/energy-rule/create`
- 请求体: dimensionCode, eventType, energyValue, status
- 预期: 规则创建成功
- 优先级: P1

**US-ENERGYRULE-03**: 启用/禁用能量规则
> As a **管理员**, I want to **开启或关闭某条能量规则** so that **临时调整能量发放策略**

- 端点: `POST /api/admin/energy-rule/toggle` (id)
- 预期: status 1↔0 切换
- 优先级: P1

**US-ENERGYRULE-04**: 编辑/删除能量规则
> As a **管理员**, I want to **修改或删除已配置的能量规则** so that **规则与实际业务匹配**

- 端点: `POST /api/admin/energy-rule/update` → 编辑
- 端点: `POST /api/admin/energy-rule/delete` → 删除
- 预期: 更新/删除成功
- 优先级: P1

---

### UC-18 后台管理（管理员）

> **角色**: 平台运营管理员

---

**US-ADMIN-01**: 创建平台用户
> As a **管理员**, I want to **创建新用户（家长/孩子等角色）** so that **新用户可以登录使用**

- 端点: `POST /api/admin/users/create`
- 请求体: phone, password, name, role, familyId
- 预期: 用户创建成功，返回用户ID
- 优先级: P0

**US-ADMIN-02**: 用户列表/查询
> As a **管理员**, I want to **分页查看和搜索用户** so that **管理平台用户**

- 端点: `POST /api/admin/users` (含筛选条件)
- 预期: 返回用户分页列表
- 优先级: P0

**US-ADMIN-03**: 管理关系类型字典
> As a **管理员**, I want to **管理家庭成员关系类型（新增/编辑/删除/启用）** so that **前端可选择最新的关系类型**

- 端点: `POST /api/admin/relationship-type/list` → 查看
- 端点: `POST /api/admin/relationship-type/save` → 新增/更新
- 端点: `POST /api/admin/relationship-type/delete` → 删除
- 预期: 关系类型CRUD成功
- 优先级: P1

**US-ADMIN-04**: 管理SKU（商品规格）
> As a **管理员**, I want to **为商品创建/编辑/删除SKU（规格）** so that **商品有不同价格和库存**

- 端点: `POST /api/admin/product/sku/list` → 查看某商品的SKU
- 端点: `POST /api/admin/product/sku/create` → 创建
- 端点: `POST /api/admin/product/sku/update` → 编辑
- 端点: `POST /api/admin/product/sku/delete` → 删除
- 预期: SKU管理成功
- 优先级: P1

**US-ADMIN-05**: 查看平台数据看板
> As a **管理员**, I want to **查看全平台关键运营指标** so that **我了解平台整体运行情况**

- 端点: `POST /api/stats/dashboard`
- 预期: 返回统计数据（用户数/订单数/活跃度/收入等）
- 优先级: P1

**US-ADMIN-06**: 数据迁移（sfms→zxyj）
> As a **管理员**, I want to **从旧系统(sfms)迁移数据到新库** so that **历史数据在新平台可用**

- 端点: `POST /api/migration/run`
- 预期: 数据迁移成功，含用户/家庭/评估/成长记录等
- 优先级: P1

**US-ADMIN-07**: 系统健康检查
> As a **管理员**, I want to **检查系统各模块的健康状态** so that **及时发现服务异常**

- 端点: `POST /api/health/check`
- 预期: 返回各模块健康状态
- 优先级: P2

**US-ADMIN-08**: 系统配置管理
> As a **管理员**, I want to **管理系统配置参数** so that **灵活调整平台规则**

- 端点: 通过配置相关接口
- 预期: 配置读取/更新成功
- 优先级: P1

---

## 三、按角色的用户故事总览

### 3.1 家长（家庭管理员）完整故事流

```
登录/注册
├── 家庭管理（US-FAM-01~07）
│   ├── 添加/移除家庭成员
│   ├── 切换孩子视图
│   ├── 关系类型管理
│   └── 邀请二维码
├── 任务管理（US-TASK-01,04~05,08~10）
│   ├── 创建任务（含小游戏）
│   ├── 审核任务
│   ├── 完成家长任务
│   └── 批量操作
├── 心愿管理（US-WISH-02~03,05~06）
│   ├── 定价心愿
│   ├── 拒绝心愿
│   └── 审批兑换
├── 积分管理（US-POINTS-01~04）
│   ├── 查看余额/流水
│   ├── 手动调整积分
│   └── 分类查看
├── 能量查看（US-ENERGY-01~02,04）
│   ├── 五维能量总览
│   └── 能量流水
├── 打卡管理（US-CHECKIN-01~05）
│   ├── 健康打卡
│   ├── 打卡统计
│   └── 补打卡
├── 测评流程（US-ASSESS-01~05,08）
│   ├── 创建/支付测评订单
│   ├── 取消/退款
│   └── 查看结果
├── 成长档案（US-GROWTH-01~07）
│   ├── 创建档案
│   ├── 上传PDF解析
│   ├── 补充记录
│   └── CRUD管理
├── 活动报名（US-ACT-03~05,07）
│   ├── 浏览活动
│   ├── 报名/取消
│   └── 查看我的报名
├── 商城（US-PROD-08, US-ORDER-01~04,06）
│   ├── 浏览商品
│   ├── 下单/支付/取消/退款
│   ├── 自提确认
│   └── 会员购买/试用
├── 规划师绑定（US-GUIDE-03~05）
│   ├── 绑定/查看/解绑规划师
│   └── 确认服务
├── 联系人管理（US-CONTACT-01~04）
│   ├── CRUD联系人
│   └── 通讯录导入/互动
└── 文章浏览（US-ARTICLE-07~08）
    ├── 文章列表/详情
    └── 每日贴士
```

### 3.2 孩子核心故事流

```
登录/切换视图
├── 任务执行（US-TASK-02~03,06~07）
│   ├── 查看今日任务
│   ├── 完成任务（拍照/小游戏）
│   └── 查看任务历史
├── 心愿管理（US-WISH-01,04,06）
│   ├── 创建心愿
│   ├── 申请兑换
│   └── 查看心愿列表
├── 打卡（US-CHECKIN-01~02,04）
│   ├── 健康打卡
│   └── 查看连续打卡
├── 积分查看（US-POINTS-01~02）
│   ├── 积分余额
│   └── 积分流水
├── 能量查看（US-ENERGY-01~02）
│   ├── 五维能量
│   └── 能量流水
├── 文章浏览（US-ARTICLE-07）
└── 成长档案查看（US-GROWTH-04）
```

### 3.3 规划师故事流

```
登录
├── 入驻申请（US-GUIDE-01）
├── 家庭服务（US-GUIDE-06~07）
│   ├── 查看服务家庭
│   └── 查看家庭档案
├── 任务（US-TASK-12）
│   └── 下发任务
├── 测评（US-ASSESS-06~07）
│   ├── 录入测评结果
│   └── 确认预约
├── 训练方案（US-GUIDE相关扩展）
│   ├── 创建训练方案
│   └── 查看方案
└── 佣金/消息（扩展）
    ├── 查看佣金
    └── 回复家长咨询
```

### 3.4 供应商故事流

```
登录/入驻
├── 入驻申请（US-VENDOR-01~02）
├── 商品管理（US-PROD-01~05）
│   ├── 创建/编辑商品
│   ├── 上下架商品
│   ├── 更新图片
│   └── 查看我的商品
├── SKU管理（US-ADMIN-04 委托管理员）
└── 订单处理（US-ORDER-05）
    └── 订单发货
```

### 3.5 管理员故事流

```
登录
├── 用户管理（US-ADMIN-01~02）
│   ├── 创建用户
│   └── 用户列表
├── 文章管理（US-ARTICLE-01~06）
│   ├── CRUD文章
│   ├── 发布/精选
│   ├── 分类管理
│   └── 图片上传
├── 商品管理（US-PROD-06~07, US-ADMIN-04）
│   ├── 审核商品
│   ├── 上下架
│   └── SKU管理
├── 供应商管理（US-VENDOR-03~04）
│   ├── 审核入驻
│   └── 供应商列表
├── 规划师管理（US-GUIDE-02,08）
│   ├── 审核申请
│   └── 套餐管理
├── 活动管理（US-ACT-01~02,06）
│   ├── 创建/发布/结束活动
│   └── 报名管理（审批/签到）
├── 能量配置（US-ENERGYRULE-01~04）
│   ├── CRUD能量规则
│   └── 启用/禁用
├── 会员配置（US-MEMBER-05）
│   └── 配置会员费用
├── 系统管理（US-ADMIN-05~08）
│   ├── 数据看板
│   ├── 数据迁移
│   ├── 健康检查
│   └── 系统配置
├── 关系类型管理（US-ADMIN-03）
└── 维度配置（US-ENERGY-05）
```

---

## 四、跨角色业务流程测试场景

以下为涉及多角色的完整端到端业务流程：

### E2E-01: 任务全生命周期

```
管理员配置能量规则（US-ENERGYRULE-02）→ 家长创建任务（US-TASK-01）
→ 孩子查看并完成任务（US-TASK-02→03）→ 家长审核通过（US-TASK-04）
→ 孩子积分增加（US-POINTS-01）→ 能量变化可查（US-ENERGY-02）
→ 任务历史可查（US-TASK-06）
```

### E2E-02: 心愿全生命周期

```
孩子创建心愿（US-WISH-01）→ 家长设定价格（US-WISH-02）
→ 孩子积累积分（US-POINTS-01）→ 孩子兑换心愿（US-WISH-04）
→ 家长审批（US-WISH-05）→ 心愿实现
```

### E2E-03: 测评完整流程

```
管理员/规划师配置套餐（US-GUIDE-08）→ 家长下单购买（US-ASSESS-01）
→ 支付订单（US-ASSESS-02）→ 预约确认（US-ASSESS-07）
→ 规划师录入结果（US-ASSESS-06）→ 家长查看报告（US-ASSESS-08）
→ 同步到成长档案（US-GROWTH-01）
```

### E2E-04: 商品从入驻到购买

```
供应商入驻（US-VENDOR-01）→ 管理员审核（US-VENDOR-03）
→ 供应商创建商品（US-PROD-01）→ 管理员审核上架（US-PROD-06→07）
→ 用户浏览购买（US-PROD-08 → US-ORDER-01）
→ 用户支付（US-ORDER-02）→ 供应商发货（US-ORDER-05）
→ 用户确认收货/自提（US-ORDER-06）
```

### E2E-05: 活动报名流程

```
管理员创建活动（US-ACT-01）→ 发布活动（US-ACT-02）
→ 家长浏览活动（US-ACT-03）→ 报名（US-ACT-04）
→ 管理员审核通过（US-ACT-06）→ 现场签到（US-ACT-06 checkin）
```

### E2E-06: 会员购买流程

```
用户浏览会员等级（US-MEMBER-01）→ 购买/试用（US-MEMBER-02/03）
→ 支付成功 → 会员激活
→ 会员权益生效
```

---

## 五、测试环境与数据准备

### 5.1 测试账号

| 角色 | 手机号 | userId | 家庭ID | 说明 |
|------|--------|--------|--------|------|
| 管理员 | 13800138000 | 7 | — | Web管理端全权限 |
| 家长(家庭管理员) | 13701366188 | 8 | 2 | 有家庭，有孩子，可切换 |
| 供应商 | 13800138001 | 81069 | — | 商品供应商 |
| 有账号孩子 | 待创建 | 待分配 | 待定 | role=child，可独立登录 |
| 规划师 | 待指定 | 待分配 | — | vendorType=planner |

### 5.2 前置数据要求

| 数据项 | 状态 | 说明 |
|--------|------|------|
| 家庭(familyId=2)有孩子记录 | ❌ 缺失 | children表为空，需先创建至少1个孩子 |
| 供应商81069审核通过 | ❌ pending | 需管理员审核通过 |
| 有已上架商品 | ❌ 缺失 | 需完成商品创建→审核→上架 |
| 有已发布的文章 | ❌ 缺失 | 需管理员创建并发布 |
| 有已发布的活动 | ❌ 缺失 | 需管理员创建并发布 |
| 有能量规则 | ❌ 缺失 | 需管理员至少配置一条规则 |

### 5.3 已发现的问题

| 问题ID | 描述 | 严重度 | 状态 |
|--------|------|--------|------|
| ISSUE-001 | 供应商在管理员上架后无法上下架 | 中 | ⏳ 待验证 |
| ISSUE-002 | 文章发布接口500 | 高 | ✅ 已验证修复 |
| ISSUE-003 | 管理员创建用户500 | 中 | ✅ 已验证修复 |
| ISSUE-004 | children表为空导致打卡统计/能量接口异常 | 低 | ✅ 测试数据问题 |
| ISSUE-005 | children表为空导致财商打卡500 | 中 | ✅ 测试数据问题 |
| ISSUE-006 | children表为空导致能量总览400 | 低 | ✅ 测试数据问题 |

---

## 六、用例优先级与测试策略

| 优先级 | 说明 | 故事数 |
|--------|------|--------|
| **P0** | 核心业务阻塞点，必须优先覆盖 | ~50 |
| **P1** | 重要功能但非阻塞 | ~50 |
| **P2** | 增强功能/边缘场景 | ~20 |

**测试顺序建议**:
1. 先确保前置数据（创建孩子、审核供应商、创建商品）
2. 执行P0故事（登录→家庭管理→任务→心愿→积分→能量→测评）
3. 执行P1故事（活动→商城→会员→规划师→文章管理）
4. 执行P2故事（联系人→边缘场景）

---

## 七、附录：API端点索引

| 模块 | 端点前缀 | 关键端点 |
|------|---------|---------|
| 任务 | `/api/tasks` | create, today, {id}/complete, {id}/review, history, pending-review, batch-complete, minigame-options |
| 心愿 | `/api/wish` | create, list, {id}/set-price, {id}/reject, {id}/exchange, {id}/approve-exchange |
| 积分 | `/api/points` | balance, logs, adjust, system-balance, logs-by-category |
| 能量 | `/api/energy` | overview, logs |
| 打卡 | `/api/health/checkin` | create, list, stats |
| 连续 | `/api/streak` | progress/{childId}, reset |
| 成长档案 | `/api/growth/record` | create, list, upload-and-parse, create-from-upload, supplement, check-duplicate |
| 家庭 | `/api/family/member` | add, list, switch, switch-back, remove, relationship-types |
| 活动 | `/api/activity` | list, detail, create, publish, end, register, cancel-registration, my-registrations, checkin |
| 活动管理 | `/api/admin/activity/registration` | list, approve, reject |
| 商品 | `/api/product` | list, detail, create, update, my, shelve, images/update |
| 商品管理 | `/api/admin/product` | list, review, shelve |
| SKU管理 | `/api/admin/product/sku` | list, get, create, update, delete |
| 订单 | `/api/order` | create, pay, cancel, refund, ship, confirm-pickup |
| 测评订单 | `/api/assessment/order` | create, detail, my-orders, pay, cancel, refund |
| 文章 | `/api/articles` | list, detail, daily-tip |
| 文章管理 | `/api/admin/articles` | list, create, update, detail, delete, publish, toggle-featured, upload/image, categories/* |
| 会员 | `/api/membership` | levels, create-order, pay, trial |
| 规划师绑定 | `/api/bind` | accept, guides, unbind |
| 规划师管理 | `/api/admin/guide` | applications/*, guides, packages/* |
| 供应商 | `/api/vendor` | apply, status |
| 供应商管理 | `/api/admin/vendor` | review, list |
| 能量规则 | `/api/admin/energy-rule` | list, create, update, delete, toggle, dimensions |
| 关系类型 | `/api/admin/relationship-type` | list, save, delete |
| 用户管理 | `/api/admin/users` | create, list, {id}/delete |
| 联系人 | `/api/contact` | create, list, update, delete, detail, import-phone, interaction |
| 数据看板 | `/api/stats` | dashboard |
| 数据迁移 | `/api/migration` | run |

---

*文档生成: 2026-07-02 by Sisyphus*
*版本: v2.0 — 按用户故事方式重写，覆盖120个用户故事*