docs: 家庭成员选择能力分析 — 梳理childId/memberId接口

docs/analysis/member-selection-analysis.md

@@ -0,0 +1,151 @@
+# 家庭成员选择能力分析
+
+## 背景
+
+系统从"亲子互动"模型演变为"独立用户+家庭成员"模型：
+- **家长** 和 **孩子** 都是独立用户（user），各自有自己的账号
+- 孩子作为 **家庭成员**（family_member）出现在家庭中
+- 家长的大部分操作是为自己，不需要选择目标
+- 但部分操作需要 **选择为哪个家庭成员执行**（不限于孩子，可能是配偶、老人等）
+
+## 参数命名规范
+
+| 参数名 | 语义 | 适用范围 |
+|--------|------|---------|
+| `childId` | 孩子用户ID（user.id） | 旧接口，仅限"孩子"角色 |
+| `memberId` | 家庭成员ID（family_member.id） | 新接口，可以是任何家庭成员 |
+| `familyMemberId` | 同 memberId | 少数接口使用 |
+
+## 功能分类分析
+
+### 第一类：已支持选择成员（memberId），无需改动 ✅
+
+这些接口已经使用 `memberId` 参数，可以指定任何家庭成员：
+
+| 功能 | 接口 | 当前参数 | 说明 |
+|------|------|---------|------|
+| 家庭成员切换 | `POST /api/family/member/switch` | `memberId` | 切换到指定成员视图 |
+| 家庭关系问卷 | `POST /api/family/questionnaire/generate` | `memberId` | 为指定成员生成问卷 |
+| 五维分数历史 | `POST /api/energy/score-history` | `memberId, memberType` | 查询指定成员的历史分数 |
+| 维度概览 | `POST /api/dimension/overview` | `memberId` | 指定成员的维度数据 |
+| 维度历史 | `POST /api/dimension/history` | `memberId` | 指定成员的维度历史 |
+| 健康打卡日报 | `POST /api/daily/checkin/list` | `memberId` | 指定成员的打卡记录 |
+| 生长记录 | `POST /api/health/growth/list` | `memberId` | 指定成员生长记录 |
+| 饮食打卡 | `POST /api/health/meal/create` | `memberId` | 指定成员饮食记录 |
+| 睡眠打卡 | `POST /api/health/sleep/create` | `memberId` | 指定成员睡眠记录 |
+| 运动打卡 | `POST /api/health/exercise/create` | `memberId` | 指定成员运动记录 |
+| 喝水打卡 | `POST /api/health/water/create` | `memberId` | 指定成员喝水记录 |
+| 冥想打卡 | `POST /api/health/meditation/create` | `memberId` | 指定成员冥想记录 |
+| 圈子列表 | `POST /api/circle/my-circles` | `memberId` | 指定成员的圈子 |
+| 富维度详情 | `POST /api/energy/wealth-detail` | `memberId, memberType` | 指定成员财富详情 |
+| 商品推荐 | `POST /api/recommend/dimension-products` | `memberId` | 指定成员推荐商品 |
+| 传统镜鉴 | `POST /api/mind/traditional-mirror` | `memberId` | 指定成员传统测评 |
+| 家族属性 | `POST /api/family/attribute` | `memberId` | 指定成员属性 |
+| 家族属性上传 | `POST /api/family/attribute/upload` | `memberId` | 指定成员属性上传 |
+| 天盘运势 | `POST /api/tianpan/fortune` | `memberId` | 指定成员运势 |
+
+### 第二类：使用 childId 但应当支持选择成员 ⚠️
+
+这些接口目前使用 `childId`（仅限孩子），但业务上家长应该可以为 **任何家庭成员** 操作：
+
+| 功能 | 接口 | 当前参数 | 应改为 | 理由 |
+|------|------|---------|--------|------|
+| **健康报告上传** | `POST /api/health/report/upload-and-parse` | `childId` | `memberId` | 家长可以为任何家庭成员上传健康报告（老人、配偶等）|
+| **健康报告列表** | `POST /api/health/report/list` | `childId` | `memberId` | 查看任何家庭成员的健康报告 |
+| **健康指标明细** | `POST /api/health/indicator/list` | `childId` | `memberId` | 查看任何成员的健康指标 |
+| **营养缺乏分析** | `POST /api/health/nutrition/deficiency` | `childId` | `memberId` | 分析任何成员的营养状况 |
+| **活动报名** | `POST /api/activity/register` | `childId` | `memberId` | 家长可以为任何家庭成员报名活动 |
+| **活动我的报名** | `POST /api/activity/my-registrations` | `childId` | `memberId` | 查看任何成员的报名记录 |
+| **活动签到** | `POST /api/activity/checkin` | `childId` | `memberId` | 任何家庭成员签到 |
+| **活动评价** | `POST /api/activity/feedback/submit` | `childId` | `memberId` | 任何家庭成员提交评价 |
+| **测评订单创建** | `POST /api/dan-assessment/order/create` | `childId` | `memberId` | 可以为任何家庭成员购买测评 |
+| **测评最新结果** | `POST /api/assessment/latest-result` | `childId` | `memberId` | 查看任何成员的测评结果 |
+| **测评历史** | `POST /api/assessment/history` | `childId` | `memberId` | 查看任何成员的历史测评 |
+| **家长自评** | `POST /api/parent/assessment/create` | `childId` | `memberId` | 为任何家庭成员创建自评 |
+| **成长档案创建** | `POST /api/growth/record/create` | `childId` | `memberId` | 为任何家庭成员创建档案 |
+| **成长档案列表** | `GET /api/growth/record/list` | `childId` | `memberId` | 查看任何成员的档案 |
+| **成长计划创建** | `POST /api/growth/plan/create` | `childId` | `memberId` | 为任何家庭成员制定计划 |
+| **成长计划列表** | `GET /api/growth/plan/child/{childId}` | `childId` | `memberId` | 查看任何成员的计划 |
+| **每日反馈** | `POST /api/feedback/today` | `childId` | `memberId` | 任何成员的每日反馈 |
+| **健康时间线** | `POST /api/health/timeline/list` | `childId` | `memberId` | 任何成员的健康时间线 |
+| **健康预警** | `POST /api/health/alert/list` | `childId` | `memberId` | 任何成员的健康预警 |
+| **健康积分** | `POST /api/health/score/overview` | `childId` | `memberId` | 任何成员的健康积分 |
+| **健康打卡综合** | `POST /api/daily/checkin/comprehensive` | `childId` | `memberId` | 任何成员的综合打卡 |
+
+### 第三类：使用 childId，适合保持为"孩子" ✅
+
+这些操作是孩子特有的（如游戏、能量、任务执行），不适合扩展到其他家庭成员：
+
+| 功能 | 接口 | 理由 |
+|------|------|------|
+| **能量概览/流水** | `POST /api/energy/overview` | 能量系统是孩子成长体系的一部分 |
+| **能量发放/扣除** | `POST /api/energy/grant` | 能量发放是针对孩子的任务奖励 |
+| **任务创建/执行** | `POST /api/tasks/create` | 任务是亲子任务体系，针对孩子 |
+| **今日任务列表** | `POST /api/tasks/today` | 同上 |
+| **完成任务** | `POST /api/tasks/{id}/complete` | 同上 |
+| **任务历史** | `POST /api/tasks/history` | 同上 |
+| **小游戏** | `POST /api/game/*` | 小游戏是孩子专属功能 |
+| **积分兑换** | `POST /api/points/*` | 积分是孩子奖励体系 |
+| **心愿** | `POST /api/wishes/*` | 心愿是孩子专属功能 |
+| **情绪打卡** | `POST /api/mind/checkin/*` | 情绪管理是孩子成长体系 |
+| **心理筛查** | `POST /api/mind/screening/*` | 心理测评是孩子专属 |
+| **微行动** | `POST /api/micro-action/*` | 微行动是孩子行为养成 |
+| **数学游戏** | `POST /api/wisdom/math/*` | 益智游戏是孩子专属 |
+| **家庭挑战** | `POST /api/family/challenge/*` | 挑战是孩子参与 |
+| **勋章成就** | `POST /api/badge/*` | 勋章是孩子成就体系 |
+
+### 第四类：家长自己操作，不需要选择 ✅
+
+这些操作是家长自己的，不需要选择目标成员：
+
+| 功能 | 理由 |
+|------|------|
+| 认证登录 | 自己的账号 |
+| 家庭管理 | 管理自己的家庭 |
+| 我的信息 | 自己的信息 |
+| 商城购物 | 自己的购物车和订单 |
+| 收货地址 | 自己的地址 |
+| 文章浏览 | 自己的阅读 |
+| AI助手 | 自己的对话 |
+| 会员订阅 | 自己的会员 |
+| 推广邀请 | 自己的推广 |
+| 佣金管理 | 自己的佣金 |
+
+## 建议改造方案
+
+### 第一阶段：高优先级（影响用户体验最大）
+
+| 优先级 | 功能 | 改动量 | 说明 |
+|--------|------|--------|------|
+| 🔴 P0 | 活动报名/签到/评价 | 小 | 将 `childId` → `memberId`，前端增加家庭成员选择器 |
+| 🔴 P0 | 健康报告上传/查看 | 中 | 同上，涉及 PDF 解析逻辑中的 childId 引用 |
+| 🔴 P0 | 测评订单/结果查看 | 中 | 涉及测评订单的 childId 字段 |
+
+### 第二阶段：中优先级
+
+| 优先级 | 功能 | 改动量 | 说明 |
+|--------|------|--------|------|
+| 🟡 P1 | 成长档案/计划 | 中 | 涉及 GrowthRecord/GrowthPlan 实体中的 childId |
+| 🟡 P1 | 每日反馈/健康时间线 | 小 | 参数替换 |
+| 🟡 P1 | 营养缺乏分析 | 小 | 参数替换 |
+
+### 第三阶段：低优先级
+
+| 优先级 | 功能 | 改动量 | 说明 |
+|--------|------|--------|------|
+| 🟢 P2 | 健康打卡系列 | 小 | 已部分使用 memberId，统一规范 |
+| 🟢 P2 | 家长自评 | 小 | 参数替换 |
+
+## 前端改造要点
+
+1. **家庭成员选择器组件**：在需要选择成员的操作前，增加一个通用的家庭成员选择弹窗
+2. **默认行为**：如果用户只有一个孩子，默认选中；如果有多个成员，弹出选择
+3. **缓存选择**：在同一个操作流程中记住上一次选择的成员
+4. **权限控制**：家长可以为所有家庭成员操作；孩子只能为自己操作
+
+## 后端改造要点
+
+1. 统一参数命名：新接口统一使用 `memberId`，废弃 `childId` 参数
+2. 兼容性：旧接口保留 `childId` 参数，内部映射为 `memberId`
+3. 权限校验：校验 `memberId` 是否属于当前用户的家庭
+4. 数据迁移：`growth_records.child_id` → `family_member_id` 等字段对齐