cfc/docs/superpowers/api/API_REFERENCE.md

浠艾福（XAF）后端接口参考文档

维护规范：

1. 新增接口前必须先查阅本文档，确认是否已有可复用或可修改的接口
2. 有相似功能但需调整 → 评估修改成本，必要时新增（标注依赖）
3. 实在没有 → 才新增接口，并在此文档同步记录
4. 废弃接口保留注释，不直接删除，待确认无调用后清理

---

一、接口规范

1.1 统一约定

项目	规范
请求方法	统一 @PostMapping，禁止 @GetMapping/@PutMapping/@DeleteMapping（仅支付回调等第三方 webhook 例外）
响应格式	Result<T> — { code, message, data }
认证	JWT Bearer Token，Header: Authorization: Bearer {token}
角色校验	Controller 内手动检查 @RequestAttribute("role")
DI	@Resource，字段名与 Bean Name 一致
公开路径（免鉴权）	/api/auth/*、/api/config/public/*、/api/media/upload、/api/articles/*（部分）

1.2 新增接口检查清单

# 1. 搜索现有相似接口
grep -rn "功能关键词" cfc-backend/src/main/java/com/etotem/cfc/controller/ --include="*.java"

# 2. 检查路由冲突
grep -rn '@PostMapping("' cfc-backend/src/main/java/com/etotem/cfc/controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u

# 3. 检查 Bean 命名冲突（新增 Service/Controller 时）
find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController.java" | xargs grep -l "class Xxx"

---

二、Controller 总览

Controller	路由前缀	说明	废弃状态
AuthController	/api/auth	登录/注册/角色切换	—
UserController	/api/user	用户信息/头像/吉祥物	—
FamilyController	/api/family	家庭基础操作	部分废弃见下
FamilyMembersController	/api/family/member	家庭成员 CRUD/切换/可见性	—
FamilyInviteController	/api/family/invite	邀请码/二维码/申请加入	—
FamilyUserController	/api/family/user	家长端家庭成员管理	部分废弃见下
PointsController	/api/points	积分余额/流水	—
TaskController	/api/tasks	任务 CRUD/完成/审核	—
WishController	/api/wishes	心愿 CRUD/审批/兑换	—
RewardController	/api/rewards	奖励模板/兑换	—
AssessmentAppointmentController	/api/assessment/appointment	测评预约	—
DanAssessmentController	/api/dan-assessment	DAN 测评全链路	—
EnergyController	/api/energy	五维能量概览/流水/配置	—
GrowthController	/api/growth	成长记录	—
GrowthPlanController	/api/growth/plan	成长计划	—
HealthCheckinController	/api/health/checkin	健康打卡（行为记录）	—
DailyCheckinController	/api/daily/checkin	每日健康打卡（饮食/运动/心情）	—
EmotionCheckinController	/api/mind/checkin	情绪日记（心情打卡同步目标）	—
HealthStatusController	/api/health-status	健康现状档案	—
ProductController	/api/product	商品	—
ProductOrderController	/api/product/order	商品订单	—
CartController	/api/cart	购物车	—
MembershipController	/api/membership	会员	—
SubscriptionController	/api/subscription	订阅	—
AIChatController	/api/ai	AI 对话	—
InnatePortraitController	/api/mind/innate	先天画像（画像/AI解读/数字能量/成长轨迹）	—
ArticleController	/api/articles	文章	—
NotificationController	/api/notification	通知	—
StatsController	/api/stats	统计	—
CfCommissionController	/api/commission/cf	CF 分佣（团队规模/比例/钱包/流水）	—
CfTransferController	/api/cf/transfer	CF 成员间转让	—
CfBalanceController	/api/cf	C 端 CF 查询（余额快照/流水/家庭券，只读）	F-7a
AdminCfRateTierController	/api/admin/cf-rate-tier	CF 返佣阶梯配置（admin）	—
ContactController	/api/contact	联系人 CRUD/互动/邀请入家庭	—
ContactMatchController	/api/contact/match	联系人对接（send/accept/reject/列表）	—
OctopusController	/api/octopus	章鱼图（帮助记录/触手聚合）	—
PearlController	/api/pearl	珍珠图（25 类社会连接聚合 + 互动/提醒/优先级）	—
AbilityController	/api/ability	能力图（SKILL 帮助记录聚合为能力节点）	—
ServiceRoleApplicationController	/api/service-role	统一服务角色申请（多角色合一 + 管理端审批）	—
GuideTeamController	/api/guide/team	规划师团队/邀请码/上下级	—
GuideFamilyTaskController	/api/guide/families	规划师侧家庭任务管理 + 家庭解绑	—
PlannerCertificationController	/api/planner	规划师培训认证中心（我的认证/课程/线下课打卡/考核）	—
XiaoeWebhookController	/api/xiaoe	小鹅通 webhook 回调（线上课时事件）	—
AdminPlannerCertCategoryController	/api/admin/planner-cert-categories	管理端-学习种类 CRUD	—
AdminPlannerCourseController	/api/admin/planner-courses	管理端-线上课程 CRUD	—
AdminPlannerOfflineCourseController	/api/admin/planner-offline-course-map	管理端-线下课↔类别映射 CRUD	—
AdminActivityCheckinController	/api/admin/activity-checkins	管理端-签到记录/手动补录	—
AdminPlannerExamController	/api/admin/planner-exam	管理端-试卷/题库 CRUD	—
AdminPlannerCertificationController	/api/admin/planner-certifications	管理端-认证看板/同步课时/存量补登	—

---

三、已废弃接口清单

标记 410 Gone 响应，前端已迁移至新接口。可考虑在确认无调用后清理。

3.1 FamilyController — 邀请码系统（已废弃）

路径	说明	替代接口
POST /api/family/invite-code	获取邀请码（已废弃）	POST /api/family/invite/generate
POST /api/family/invite-code/generate	生成邀请码（已废弃）	POST /api/family/invite/generate

3.2 FamilyUserController — 角色切换（已废弃）

路径	说明	替代接口
POST /api/family/user/switch-mode	切换家长/孩子模式（已废弃）	POST /api/family/member/switch
POST /api/family/user/switch-to-child	切换到孩子身份（已废弃）	POST /api/family/member/switch
POST /api/family/user/switch-back-to-parent	切回家长身份（已废弃）	POST /api/family/member/switch
POST /api/family/user/switch-back-verify	切换验证（已废弃）	—

3.3 ButlerController — 服务记录/佣金（已废弃）

路径	说明	替代接口
POST /api/butler/service-records	服务记录（已废弃）	—
POST /api/butler/commissions	佣金记录（已废弃）	—

3.4 TeacherController — 教学任务（已废弃）

路径	说明	替代接口
POST /api/teacher/tasks	创建教学任务（已废弃）	POST /api/guide/families/{familyId}/tasks/{taskId}
其余 /api/teacher/* 多个接口均标注 @Deprecated	—	—

3.5 DanAssessmentController — 当前测评（已废弃）

路径	说明	替代接口
POST /api/dan-assessment/current	获取当前测评（已废弃）	—

3.6 NoticeController — 公告列表（已废弃）

路径	说明	替代接口
GET /api/notices/list	使用 GET 方法，违反统一 POST 规范	—

---

四、接口详细清单

4.1 认证与用户（/api/auth, /api/user）

路径	说明	参数	废弃
POST /api/auth/send-code	发送验证码	phone	—
POST /api/auth/phone-login	手机号登录	phone, code	—
POST /api/auth/wechat-phone-login	微信一键绑定手机号	code	—
POST /api/auth/silent-login	静默登录（仅获取 token）	—	—
POST /api/auth/auto-login	自动登录（refresh token）	—	—
POST /api/auth/register-with-idcard	身份证注册	—	—
POST /api/auth/wechat-login	微信授权登录	code	—
POST /api/auth/info	获取当前用户信息	—	—
POST /api/auth/set-password	设置密码	password	—
POST /api/auth/verify	验证密码	password	—
POST /api/auth/check-phone	检查手机号是否存在	phone	—
POST /api/auth/direct-register	直接注册（无邀请码）	—	—
POST /api/auth/register-with-invite	邀请码注册	inviteCode	—
POST /api/auth/switch-role	切换角色	role	—
POST /api/user/address/list	收货地址列表	—	—
POST /api/user/address/get	获取地址详情	id	—
POST /api/user/address/create	创建地址	—	—
POST /api/user/address/update	更新地址	—	—
POST /api/user/address/delete	删除地址	id	—
POST /api/user/address/setDefault	设为默认	id	—
POST /api/user/mascot/set	设置吉祥物	mascotId	—
POST /api/user/mascot/get	获取吉祥物	—	—

4.2 家庭与成员（/api/family/*, /api/family/member/*）

路径	说明	废弃
POST /api/family/invite-code	获取邀请码	✅ 废弃
POST /api/family/invite-code/generate	生成邀请码	✅ 废弃
POST /api/family/guide-bind	绑定规划师	—
POST /api/family/member/add	添加成员	—
POST /api/family/member/list	成员列表（统一入口）	—
POST /api/family/member/switch	切换成员视角	—
POST /api/family/member/kick	移除成员	—
POST /api/family/member/leave	主动退出家庭（微信用户；创建者需先转让管理员）	—
POST /api/family/member/recycle	从回收箱回收成员（管理员操作）	—
POST /api/family/member/update	更新成员信息；body 可含 isChild（1=孩子/0=非孩子，仅家庭管理员可设置，落库到 users.is_child；非管理员返回 403）	—
POST /api/family/member/rename-family	修改家庭名称（仅家庭管理员）；body {name}，返回新名称	—
POST /api/family/member/editable	检查是否可编辑	—
POST /api/family/member/logs	成员变更日志	—
POST /api/family/invite/qrcode	生成邀请二维码	—
POST /api/family/invite/request-join-by-code	申请加入（token 路径绑定邀请人，等待邀请人确认；旧码路径管理员兜底）	inviteCode 或 token + familyRole
POST /api/family/invite/approve-request	同意加入申请（审批人=邀请人且仍为目标家庭成员；旧数据无邀请人时家庭管理员兜底）	—
POST /api/family/invite/reject-request	拒绝加入申请（权限规则同上）	—
POST /api/family/invite/pending-requests	待我处理的申请列表（按邀请人查询；旧数据由目标家庭管理员兜底可见）	—
POST /api/family/invite/my-request	我的申请	—
POST /api/family/invite/cancel-request	取消申请	—
POST /api/family/invite/generate	生成邀请令牌（复用同家庭未过期未用尽的有效令牌；仅未过期记录计入 10 条额度）	—
POST /api/family/invite/validate	验证邀请令牌	—
POST /api/family/invite/accept	接受邀请	—
POST /api/family/invite/check-family	检查家庭状态	—
POST /api/family/invite/revoke	撤销邀请	—
POST /api/family/invite/transfer-admin	转让管理员	—
POST /api/family/invite/validate-family-code	验证家庭短邀请码（落地页展示用，不创建请求）	inviteCode
POST /api/family/invite/bind-inviter	绑定家庭邀请人（仅首次注册调用）	familyInviteCode

4.2 Family Member 接口详细（切换/回收箱）

POST /api/family/member/leave — 主动退出家庭

说明：微信登录用户主动退出当前家庭，回到自己的初始家庭（自己创建的家庭 families.creator_id = userId）；若无初始家庭则自动创建新家庭。退出时成员资产（测评/报告/能量值/档案属性）随成员迁移到目标家庭，CF 值（system_points）清零丢弃留在原家庭。

约束：

• 仅微信登录用户可退出（openid 非 phone: 前缀）；非微信用户调用返回错误
• 家庭创建者禁止退出，需先通过 POST /api/family/invite/transfer-admin 转让管理员
• 退出后该用户自动归属初始家庭（或新建家庭），不会处于"无家庭"状态

请求体：无（空 body 或 {}）

响应：

{
  "code": 200,
  "message": "退出成功",
  "data": null
}

错误码： | code | message | 处理建议 | |------|---------|----------| | 500 | 您是家庭创建者，请先转让管理员权限后再退出 | 先转让管理员 | | 500 | 非微信登录用户不能自主退出家庭 | 非微信用户不支持主动退出 | | 500 | 用户未加入家庭 / 家庭不存在 / 未找到该用户的家庭成员记录 | 提示用户状态异常 |

---

POST /api/family/member/kick — 移除成员（含回收箱分流）

说明：家庭管理员将成员移出家庭。行为按成员类型分流：

• 微信登录用户：资产迁移回其初始家庭（无则自动创建），CF 值（system_points）随成员带走，同时收回该家庭发放给该成员的人口券（POPULATION，来源 member:{id}，仅作废 AVAILABLE 状态的券）
• 非微信登录用户：进入回收箱（family_members.status = recycled），users.family_id 置空，资产保留在原家庭记录上，后续可通过 POST /api/family/member/recycle 回收
• 无关联用户的手动成员：直接删除记录

约束：仅家庭创建者可踢出；不能踢出家庭创建者本人。

请求体：

{
  "memberId": 12345
}

响应：

{
  "code": 200,
  "message": "踢出成功",
  "data": null
}

---

POST /api/family/member/recycle — 从回收箱回收成员

说明：目标家庭管理员将回收箱中的成员（非微信用户，status=recycled）重新加入指定家庭，资产（测评/报告/能量值/档案属性）迁移到目标家庭，关联用户 family_id 归位到目标家庭。

约束：仅目标家庭创建者可回收；成员必须在回收箱中。

请求体：

{
  "memberId": 12345,
  "targetFamilyId": 67890
}

响应：

{
  "code": 200,
  "message": "回收成功",
  "data": null
}

错误码： | code | message | 处理建议 | |------|---------|----------| | 500 | 该成员不在回收箱中 | 仅回收箱成员可回收 | | 500 | 只有目标家庭管理员才能回收成员 | 权限不足 |

---

4.2 Family Invite 接口详细

POST /api/family/invite/request-join-by-code — 申请加入家庭

说明：用户通过邀请码/令牌提交加入家庭的申请，等待邀请人审批。

请求体：

{
  "inviteCode": "fam_abc123",      // 必填，邀请码或令牌
  "familyRole": "爸爸"              // 可选，用户在目标家庭中的身份
}

响应：

{
  "code": 200,
  "message": "申请已提交，等待邀请人确认",
  "data": {
    "requestId": 12345,
    "familyName": "张三的家庭"
  }
}

---

POST /api/family/invite/bind-inviter — 绑定家庭邀请人

说明：新用户首次注册时调用，建立「被邀请人 → 邀请人」关系，用于追踪邀请来源。仅首次注册调用，已有家庭邀请人的用户调用会返回失败。

请求体：

{
  "familyInviteCode": "fam_abc123"
}

响应：

{
  "code": 200,
  "message": "绑定成功",
  "data": null
}

错误码： | code | message | 处理建议 | |------|---------|----------| | 400 | 用户已有家庭邀请人 | 跳过，已在目标家庭中 | | 404 | 邀请码无效 | 提示用户链接无效 |

---

POST /api/family/invite/validate — 验证邀请令牌

说明：邀请落地页使用，验证 token 有效性并返回家庭信息（仅供展示）。

请求体：

{
  "token": "abc123def456"
}

响应：

{
  "code": 200,
  "data": {
    "familyId": 100,
    "familyName": "张三的家庭",
    "inviterName": "张三",
    "inviterAvatar": "/static/avatar.jpg",
    "memberCount": 3
  }
}

---

POST /api/family/invite/check-family — 检查用户家庭状态

请求体：无额外参数（从 JWT 取 userId）

响应：

{
  "code": 200,
  "data": {
    "inFamily": true,
    "familyId": 100,
    "familyName": "张三的家庭",
    "isAdmin": true
  }
}

---

POST /api/family/invite/pending-requests — 查询待我处理的申请

说明：邀请人视角，查询他人提交给自己的加入申请。

请求体：无额外参数

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1001,
      "requesterUserId": 200,
      "requesterNickname": "李四",
      "requesterAvatar": "/static/avatar.jpg",
      "familyRole": "妈妈",
      "status": "pending",
      "createdAt": "2026-08-31T10:00:00"
    }
  ]
}

---

POST /api/family/invite/approve-request — 批准加入申请

请求体：

{
  "requestId": 1001,
  "comment": ""
}

响应：

{
  "code": 200,
  "message": "已同意"
}

---

POST /api/family/invite/reject-request — 拒绝加入申请

请求体：

{
  "requestId": 1001,
  "comment": "不符合条件"
}

响应：

{
  "code": 200,
  "message": "已拒绝"
}

---

POST /api/family/invite/my-request — 查询我的申请

请求体：无额外参数

响应：

{
  "code": 200,
  "data": {
    "id": 1001,
    "targetFamilyId": 100,
    "targetFamilyName": "张三的家庭",
    "familyRole": "爸爸",
    "status": "pending",
    "createdAt": "2026-08-31T10:00:00"
  }
}

status 枚举：pending | approved | rejected

4.3 任务（/api/tasks）

路径	说明
POST /api/tasks/minigame-options	小游戏选项
POST /api/tasks/create	创建任务
POST /api/tasks/today	今日任务（memberId 查单成员；familyWide=true 查全家庭今日任务）
POST /api/tasks/{id}/start	开始任务（两阶段入口，含购物任务自动加购/下单）
POST /api/tasks/{id}/complete	完成任务
POST /api/tasks/{id}/review	审核任务
POST /api/tasks/history	历史任务
POST /api/tasks/pending-review	待审核
POST /api/tasks/today-parent	家长今日任务
POST /api/tasks/{id}	任务详情
POST /api/tasks/{id}/complete-minigame	小游戏完成
POST /api/tasks/batch-complete	批量完成
POST /api/tasks/batch-delete	批量删除
POST /api/tasks/my-pending	我的待办
POST /api/tasks/accept	接受任务
POST /api/tasks/reject/{id}	拒绝任务

4.3.1 购物任务联动（actionType = cart/order）

任务创建时通过 actionType + actionConfig 声明购物联动；调用 POST /api/tasks/{id}/start 时，后端自动执行加购/下单。

actionConfig JSON 格式：

字段	必填	说明
productId	✅	商品ID
quantity	❌	数量，默认 1
skuId	❌	SKU ID（可选）
consigneeId	❌	收货地址ID（order 模式下可选；未提供时取用户默认地址）
deliveryMethod	❌	配送方式：1=快递/2=自提/4=线上可选人/5=线上单人

actionType 行为：

actionType	行为	返回字段
minigame	跳转小游戏页	—
focus	跳转专注计时器页	—
survey	跳转问卷填写页	—
article	跳转文章中心页	—
activity	跳转活动列表页	—
cart	自动加购，返回加购结果	execution.extra 含 cartAdded=true、productId、quantity
order	先加购，再创建 pending 订单	execution.extra 含 orderId、orderNo（成功时）或 orderFailed=true、orderError（失败时）
diet	跳转饮食打卡页（/pages/growth/diet-checkin?taskId={id}）	—
sleep	跳转睡眠打卡页（/pages/growth/sleep-checkin?taskId={id}）	—
exercise	跳转运动打卡页（/pages/growth/exercise-checkin?taskId={id}）	—

下单失败常见原因： 缺默认收货地址、商品已下架、库存不足、配送方式校验失败。失败时加购结果保留，任务状态正常置 in_progress，前端可引导用户去购物车/结算页手动完成。

4.4 心愿（/api/wishes）

路径	说明
POST /api/wishes/create	创建心愿
POST /api/wishes/{id}/set-price	设置价格
POST /api/wishes/{id}/reject	拒绝心愿
POST /api/wishes/{id}/exchange	兑换心愿
POST /api/wishes/{id}/approve-exchange	审批兑换
POST /api/wishes/{id}/fulfill	完成心愿
POST /api/wishes/{id}/confirm	确认心愿
POST /api/wishes/{id}/cancel	取消心愿
POST /api/wishes/list	心愿列表
POST /api/wishes/pending	待审批心愿
POST /api/wishes/{id}	心愿详情

4.5 能量与积分（/api/energy, /api/points）

路径	说明
POST /api/energy/overview	能量概览
POST /api/energy/logs	能量流水
POST /api/energy/config	能量配置
POST /api/energy/dimension	五维详情
POST /api/points/balance	积分余额
POST /api/points/logs	积分流水
POST /api/points/adjust	手动调整
POST /api/points/system-balance	系统余额
POST /api/points/logs-by-category	分类流水

4.6 成长档案（/api/growth/*）

路径	说明
POST /api/growth/record/create	创建记录
POST /api/growth/record/create-with-order	下单关联创建
POST /api/growth/record/list	记录列表
POST /api/growth/record/child/{memberId}	指定成员记录
POST /api/growth/record/{id}	记录详情
POST /api/growth/record/{id}/delete	删除记录
POST /api/growth/record/external/sync	外部同步
POST /api/growth/record/upload-and-parse	上传解析
POST /api/growth/record/create-from-upload	从上传创建
POST /api/growth/record/supplement	补充记录
POST /api/growth/plan/create	创建计划
POST /api/growth/plan/child/{memberId}	成员计划
POST /api/growth/plan/{id}	计划详情
POST /api/growth/plan/{id}/review	审核计划

4.7 健康打卡（/api/health/*, /api/daily/checkin, /api/mind/checkin）

路径	说明
POST /api/health/checkin/list	行为打卡列表
POST /api/health/checkin/create	创建行为打卡
POST /api/daily/checkin/list	每日打卡列表（饮食/运动/睡眠/心情）
POST /api/daily/checkin/create	创建每日打卡
POST /api/daily/checkin/update	更新打卡
POST /api/daily/checkin/delete	删除打卡
POST /api/mind/checkin/create	情绪日记创建
POST /api/mind/checkin/list	情绪日记列表
POST /api/mind/checkin/latest	最新情绪日记
POST /api/mind/checkin/trend	情绪趋势
POST /api/mind/checkin/stats	情绪统计
POST /api/mind/checkin/weekly-report	周报
POST /api/mind/checkin/emotion/recognize	情绪识别（URL方式，走Dify） — 已废弃
POST /api/mind/emotion/analyze	照片情绪识别（文件上传，走 LangGraph DeepFace）
POST /api/mind/emotion/analyze-url	照片情绪识别（URL方式，走 LangGraph DeepFace）
POST /api/health-status/get	健康现状档案获取
POST /api/health-status/save	健康现状档案保存
POST /api/health-status/signature	提交手签名（仅更新 signature + signed_at 列，不影响其他字段；body: {memberId, signature}，signature 为 base64 PNG data URL）
POST /api/health/exercise/sync-wechat-steps	同步微信运动步数（传 encryptedData+iv，返回当日步数与近30天数据）
POST /api/health/meal/list	饮食打卡列表
POST /api/health/meal/create	创建饮食打卡（支持 taskId 任务联动 + isBackfill 补打）
POST /api/health/meal/daily	获取某天的饮食记录
POST /api/health/meal/weekly	获取某周食材频次与营养汇总
POST /api/health/meal/alerts	获取食材摄入预警
POST /api/health/sleep/list	睡眠打卡列表
POST /api/health/sleep/create	创建睡眠打卡（支持 taskId 任务联动）
POST /api/health/exercise/list	运动打卡列表
POST /api/health/exercise/create	创建运动打卡（支持 taskId 任务联动 + stepCount 微信步数）

健康打卡任务联动（taskId 参数）

饮食/睡眠/运动打卡接口均支持可选 taskId 参数（Long），用于将打卡记录与任务系统联动。

请求体新增参数：

参数	类型	必填	说明
taskId	Long	❌	关联任务ID；为 null 时仅存打卡记录，不触发任务逻辑

联动逻辑：

场景	行为
taskId 指向 tasks.is_daily_progress=1 的任务	调用 TaskService.updateProgress(userId, taskKey, 1) 累加进度，达标后自动 completed + 发放积分/能量
taskId 指向普通任务（is_daily_progress=0）	调用 TaskService.completeTask(taskId, memberId, ...) 直接完成
taskId 为 null	仅存打卡记录 + 发放 5CF 打卡积分，不触发任务逻辑
补打（isBackfill=1）	忽略 taskId，不触发任何任务逻辑

taskKey 约定（每日进度型任务）：

actionType	taskKey	匹配方式
diet	"DIET"	title 精确匹配 OR title 以 "[DIET]" 前缀匹配
sleep	"SLEEP"	同上
exercise	"EXERCISE"	同上

前端跳转路径：/pages/growth/{type}-checkin?taskId={id}（由 tasks.vue 的 navigateByAction() 自动构造）

4.8 商品与订单（/api/product/*）

路径	说明
POST /api/product/list	商品列表
POST /api/product/detail	商品详情
POST /api/product/create	创建商品
POST /api/product/update	更新商品
POST /api/product/my	我的商品
POST /api/product/shelve	上下架
POST /api/product/order/create	创建订单
POST /api/product/order/pay	支付
POST /api/product/order/cancel	取消订单
POST /api/product/order/my	我的订单
POST /api/product/order/detail	订单详情
POST /api/product/order/confirm	确认收货
POST /api/product/order/refund/apply	申请退款
POST /api/product/order/vendor	服务商查询收到的订单
POST /api/product/order/vendor-confirm	服务商确认发出/服务完成
POST /api/product/order/ship	服务商/管理端发货（填物流单号+快递公司）。发货成功后自动调用微信「小程序交易管理服务」upload_shipping_info 同步物流到微信订单管理（用户在微信侧收发货通知/查物流/确认收货）；自提订单或无单号跳过；失败只记日志不阻塞（fail-open）；wechat.test-mode=true 或 wechat.fulfillment-enabled=false（环境变量 WECHAT_FULFILLMENT_ENABLED）时跳过
POST /api/product/order/review/update	供应商审核修改待支付订单（修改价格/配送方式/添加优惠券/赠品）
POST /api/cart/add	加入购物车
POST /api/cart/list	购物车列表
POST /api/cart/update	更新数量
POST /api/cart/remove	移除商品
POST /api/cart/count	购物车数量
POST /api/consignee/list	收货地址列表
POST /api/consignee/save	保存地址
POST /api/consignee/delete	删除地址

4.9 AI 对话（/api/ai/*）

路径	说明
POST /api/ai/chat/send	发送消息
POST /api/ai/chat/conversations	对话列表
POST /api/ai/chat/messages	消息列表
POST /api/ai/chat/conversations/{id}/delete	删除对话
POST /api/ai/nutrition/send	营养对话
POST /api/ai/health-coach/send	健康教练（请求体可选字段 coach_id 由服务端自动注入，客户端无需传；LangGraph 按 xibao/fubao 三级回退路由话术）
POST /api/ai/butler/send	管家对话
POST /api/ai/context	上下文管理
POST /api/butler/sessions/create	创建会话
POST /api/butler/sessions/update-conversation	更新会话
POST /api/butler/sessions/archive	归档会话
POST /api/butler/sessions/list	会话列表
POST /api/butler/sessions/detail	会话详情
POST /api/butler/sessions/delete	删除会话

4.10 测评（/api/assessment/*, /api/dan-assessment/*）

路径	说明
POST /api/assessment/appointment/create	预约测评
POST /api/assessment/appointment/confirm/{id}	确认预约
POST /api/assessment/appointment/cancel/{id}	取消预约
POST /api/assessment/appointment/my-list	我的预约
POST /api/assessment/latest-result	最新测评结果
POST /api/assessment/history	测评历史
POST /api/dan-assessment/result/upload	上传报告
POST /api/dan-assessment/result/{resultId}/guidance/save	保存指导建议
POST /api/dan-execution/complete	完成测评执行
POST /api/dan-execution/confirm	确认执行
POST /api/dan-execution/rate	评分
POST /api/dan-execution/my-list	我的执行记录

4.11 饮食推荐（/api/diet/*）

路径	说明
POST /api/diet/preferences/current-member	当前成员饮食偏好
POST /api/diet/preferences/save	保存饮食偏好
POST /api/diet/recommendation/today	今日推荐（返回 data.id / data.menu / data.nutritionSummary / data.status）
POST /api/diet/recommendation/generate	生成推荐（body: date, meal_type, selected_foods JSON string；返回 data.id / data.menu / data.nutritionSummary）
POST /api/diet/recommendation/complete	完成推荐
POST /api/diet/record/save	保存饮食记录
POST /api/diet/record/daily	每日记录
POST /api/diet/ingredients/suggest	食材推荐（返回 data.ingredients 列表）
POST /api/diet/ingredients/recommend	换一批（返回 data.ingredients，每次不同）
POST /api/diet/ingredients/search	搜索食材（body {keyword}，返回 data.foods:[{id, name, category}]）
POST /api/diet/meals/config	餐食配置（body: date_type + meal_type，返回 data.participantMemberIds 等）
POST /api/diet/meals/config/save	保存餐食配置，批量格式（推荐，单次调用）：body {date_type:"weekday", configs:{breakfast:"[1,2]", lunch:"[]", dinner:"[3]"}}（各餐次值为成员ID数组的 JSON 字符串）；亦兼容单条格式：body {date_type, meal_type, participant_member_ids, notes?}。前端 saveMealConfig 位于 cfc-frontend/utils/api.js（2772行）

4.12 内容（/api/articles, /api/content/*）

路径	说明
POST /api/articles/list	文章列表
POST /api/articles/detail	文章详情
POST /api/articles/featured	精选文章
POST /api/articles/record-read	记录阅读
POST /api/articles/report-reading-time	上报阅读时长（按 articleId+childId+日期累加，首次上报递增 view_count）
POST /api/articles/reading-stats	阅读统计
POST /api/articles/daily-tip	每日提示
POST /api/articles/ai-questions	AI 生成问题
POST /api/articles/submit-answers	提交答案
POST /api/articles/my-posts	我的文章
POST /api/articles/comments/list	评论列表
POST /api/articles/comments/create	创建评论
POST /api/articles/comments/audit	审核评论
POST /api/articles/quiz/generate	生成测验
POST /api/articles/quiz/submit	提交测验
POST /api/content-sections/visible	可见区块
POST /api/content-sections/list	区块列表
POST /api/content/related-items	内容关联推荐：以活动/文章/商品任一为源（sourceType+sourceId），按共享标签一次返回 data.articles / data.activities / data.products 三组（支持 size/page 分页，游客可访问）

4.13 管理员接口（/api/admin/*）

管理员接口需 role=admin，详见 AdminInterceptor。

路径前缀	说明
/api/admin/articles/*	文章管理
POST /api/admin/articles/move	调整精选文章的推荐顺序（`{ id, direction: 'up'
/api/admin/articles/reading-records	按文章查询阅读记录明细（分页，含孩子昵称/时长）
/api/admin/assessment/*	测评材料管理
/api/admin/bazi-config/*	八字配置
/api/admin/blood-type-config/*	血型配置
/api/admin/butler/*	管家分配管理（分配列表/强制解绑/停接开关）
/api/admin/commission/*	佣金管理
/api/admin/dimension/*	维度配置
/api/admin/dimension-config/*	维度权重
/api/admin/energy/*	能量配置
/api/admin/energy-config/*	五行能量来源/每日限制配置
/api/admin/ecom-supplier/*	电商供应商管理
/api/admin/file-record/*	后台素材库（上传入库/检索/标签字典/统计，见 §4.56）
/api/admin/guide/*	成长规划师管理（申请/套餐）
/api/admin/growth-archive-product/*	成长档案关联商品
/api/admin/health-plan/*	健康方案管理（跨家庭列表/详情）
/api/admin/knowledge-base/*	知识库管理
/api/admin/notices/*	公告管理
/api/admin/innate-portrait-config/*	先天画像来源权重配置（list/update/invalidate）
/api/admin/numsoul-detail-config/*	数字能量详细配置（list/create/update/delete）
/api/admin/package-templates/*	套餐模板
/api/admin/ppoint-config/*	P点配置（品类级比例+商品级固定值）
/api/admin/product/*	商品管理
/api/admin/report-parser/*	报告解析配置
/api/admin/report-template/*	报告展示模板管理
/api/admin/supply-*	供应链相关
/api/admin/system/*	系统配置
/api/admin/unlock-gates/*	通关配置
/api/migration/run	数据迁移

4.14 先天画像（/api/mind/innate/*）

五维能量体系"心维度"先天画像聚合接口，基于星座/八字/血型/数字能量生成，AI 解读失败时自动降级模板文案。

路径	说明
POST /api/mind/innate/portrait	先天画像（聚合 mind_base_score + 数字能量详情 + 来源贡献明细）
POST /api/mind/innate/reading	AI 解读（缓存到 innate_portrait_report，失败降级模板）
POST /api/mind/innate/numsoul	数字能量计算（生命灵数/天赋数/生日数/命运数）
POST /api/mind/innate/trajectory	先天+后天成长轨迹（EnergyBalance 后天能量对比）

请求参数（portrait/reading/trajectory）：

{ "memberId": 123, "memberType": "child", "familyId": 1 }

numsoul 请求参数：

{ "year": 1990, "month": 5, "day": 15 }

4.15 统计与通知（/api/stats, /api/notification）

路径	说明
POST /api/stats/dashboard	统计仪表盘
POST /api/stats/overview	总览
POST /api/stats/revenue	收入统计
POST /api/stats/membership	会员统计
POST /api/stats/trend	趋势
POST /api/notification/list	通知列表
POST /api/notification/read	标记已读

4.16 报告模板管理（/api/admin/report-template）

路径	说明
POST /api/admin/report-template/list	模板列表，支持 reportType/isActive 过滤
POST /api/admin/report-template/get	按 reportType 获取模板，参数 reportType
POST /api/admin/report-template/save	保存模板（创建或更新），body 含 id/name/reportType/config
POST /api/admin/report-template/delete	删除模板，参数 id
POST /api/admin/report-template/toggle	启停模板，body { id, isActive }
POST /api/admin/report-template/indicators	获取可选指标列表，支持 domain 过滤

config JSON 结构：

{
  "fixedBlocks": [
    { "type": "score", "title": "健康评分", "items": ["overallScore","gutHealthScore"] },
    { "type": "indicator", "title": "血脂指标", "groupLabel": "血脂", "indicatorNames": ["总胆固醇","甘油三酯"] },
    { "type": "list", "title": "菌种详情", "listKey": "flora" },
    { "type": "text", "title": "评语", "content": "..." }
  ],
  "freeDisplay": { "enabled": true, "groupName": "其他指标" }
}

4.17 其他接口

路径	说明
POST /api/config/public/value	公开配置值
POST /api/media/upload	媒体上传（免鉴权）
POST /api/recommend/search	推荐搜索
POST /api/recommend/repurchase-reminders	复购提醒
POST /api/task-reminders/upcoming/{memberId}	即将到期提醒
POST /api/tianpan/dashboard	天盘概览
POST /api/tianpan/member/{memberId}	成员详情
POST /api/tianpan/compatibility	兼容性分析
POST /api/tianpan/annual-energy	年度能量
POST /api/tianpan/daily-fortune	每日运势
POST /api/tianpan/related-items	相关事项
POST /api/tianpan/recalibrate	重算五维基础分（管理员）
POST /api/wisdom/gut-cognition	肠道认知
POST /api/wealth/checkin/*	财富打卡
POST /api/insurance/*	保险规划

4.18 日常任务聚合（/api/daily-task/*）

路径	说明
POST /api/daily-task/overview	今日任务总览（打卡/任务/阅读活动/测评报告四类聚合）

4.19 健康维度评分（/api/dimension/*）

路径	说明
POST /api/dimension/overview	获取健康维度概览（七维评分+百分位）
POST /api/dimension/upload	手动录入维度评分
POST /api/dimension/questionnaire	问卷提交维度评分
POST /api/dimension/history	获取维度历史记录

4.20 家庭成员关系质量（/api/family/relationship/*）

路径	说明
POST /api/family/relationship/scores	获取家庭成员关系质量评分
POST /api/family/relationship/calculate	计算并保存关系质量评分
POST /api/family/relationship/health-alerts	获取健康预警列表
POST /api/family/relationship/milestones	获取即将到来的里程碑
POST /api/family/relationship/pairwise	获取以指定成员为中心的所有成员关系

4.21 佣金管理（/api/commission/*）

路径	说明
POST /api/commission/summary	获取佣金汇总
POST /api/commission/list	佣金流水列表
POST /api/commission/team	团队统计（L1/L2）
POST /api/commission/stats	佣金统计面板
POST /api/commission/balance	可提现余额详情
POST /api/commission/team/list	团队成员列表
POST /api/commission/funnel	佣金转化漏斗
POST /api/commission/team/list	扩展：返回中每个成员新增 memberConsumption（该成员已完成履约订单总额，分）、myCfEarnedFromMember（我从该成员消费获得的 CF 总额，分）
POST /api/commission/team/consumption	团队总消费额分级汇总，请求 {maxLevel}（默认 3），返回 {totalConsumption: 分, levelBreakdown[{level, memberCount, consumption}], totalMembers, maxLevel}
POST /api/commission/my-referrer	获取我的直推人信息，返回 {hasReferrer, referrerId, nickname, avatar, referralCode, bindTime}，无推荐人时 hasReferrer=false
POST /api/commission/team/tree	团队树形扁平数据（不含根节点），请求 {maxLevel}（默认 3），返回 {nodes[{userId, nickname, avatar, level, parentId, referrerId, memberConsumption, myCfEarnedFromMember}], totalMembers, maxLevel}

4.22 管理端-能量配置（/api/admin/energy-config/*）

路径	说明
POST /api/admin/energy-config/source-list	能量来源配置列表
POST /api/admin/energy-config/source-save	保存能量来源配置（新增/更新）
POST /api/admin/energy-config/source-delete	删除能量来源配置
POST /api/admin/energy-config/daily-limits	获取每日能量限制
POST /api/admin/energy-config/daily-limit-save	保存每日能量限制
POST /api/admin/energy-config/overview	能量配置总览（来源+限制）

4.23 管理端-公告（/api/admin/notices/*）

路径	说明
POST /api/admin/notices/list	公告列表（分页）
POST /api/admin/notices/all	全量公告列表
POST /api/admin/notices/create	创建公告
POST /api/admin/notices/update	更新公告
POST /api/admin/notices/delete	删除公告（软删）
POST /api/admin/notices/pin	置顶公告

4.24 管理端-成长规划师（/api/admin/guide/*）

路径	说明
POST /api/admin/guide/applications/pending	待审批规划师申请
POST /api/admin/guide/applications/{id}/approve	审批通过
POST /api/admin/guide/applications/{id}/reject	驳回申请
POST /api/admin/guide/guides	获取所有成长规划师列表
POST /api/admin/guide/guides/level/{level}	按级别获取规划师
POST /api/admin/guide/guides/approved	获取已入驻（approved）的服务商列表
POST /api/admin/guide/packages	获取所有套餐模板
POST /api/admin/guide/packages/create	创建套餐
POST /api/admin/guide/packages/{id}/update	更新套餐
POST /api/admin/guide/packages/{id}/status	更新套餐状态

4.25 管理端-商品（/api/admin/product/*）

路径	说明
POST /api/admin/product/list	商品列表（分页/筛选/搜索）
POST /api/admin/product/review	审核商品（approve/reject）
POST /api/admin/product/shelve	商品上下架
POST /api/admin/product/detail	商品详情
POST /api/admin/product/create	创建商品
POST /api/admin/product/update	更新商品
POST /api/admin/product/copy	复制商品
POST /api/admin/product/delete	删除商品
POST /api/admin/product/batch-shelve	批量上下架（body: {productIds, shelve}）

4.26 管理端-成长档案关联商品（/api/admin/growth-archive-product/*）

路径	说明
POST /api/admin/growth-archive-product/save	保存关联商品规则
POST /api/admin/growth-archive-product/detail	关联商品规则详情
POST /api/admin/growth-archive-product/delete	删除关联商品规则

4.27 管理端-电商供应商（/api/admin/ecom-supplier/*）

路径	说明
POST /api/admin/ecom-supplier/list	供应商列表（分页/搜索）
POST /api/admin/ecom-supplier/all	所有供应商（下拉选择）
POST /api/admin/ecom-supplier/save	创建供应商
POST /api/admin/ecom-supplier/update	更新供应商
POST /api/admin/ecom-supplier/delete	删除供应商

4.28 管理端-测评材料（/api/admin/assessment/*）

路径	说明
POST /api/admin/assessment/materials	测评资料列表
POST /api/admin/assessment/materials/{id}	测评资料详情
POST /api/admin/assessment/materials/create	创建测评资料
POST /api/admin/assessment/materials/{id}/update	更新测评资料
POST /api/admin/assessment/materials/{id}/delete	删除测评资料（软删）
POST /api/admin/assessment/config	获取积分配置
POST /api/admin/assessment/config/update	更新积分配置

4.29 管理端-P点配置（/api/admin/ppoint-config/*）

路径	说明
POST /api/admin/ppoint-config/category/list	品类级P点比例列表
POST /api/admin/ppoint-config/category/save	保存品类级P点比例
POST /api/admin/ppoint-config/category/delete	删除品类级P点比例
POST /api/admin/ppoint-config/category/by-category	按品类ID获取P点比例
POST /api/admin/ppoint-config/product/list	商品级P点列表
POST /api/admin/ppoint-config/product/save	保存商品级P点
POST /api/admin/ppoint-config/product/delete	删除商品级P点
POST /api/admin/ppoint-config/product/by-product	按商品ID获取P点
POST /api/admin/ppoint-config/effective	获取商品综合有效P点值

4.30 管理端-报告解析（/api/admin/report-parser/*）

路径	说明
POST /api/admin/report-parser/types	报告类型列表
POST /api/admin/report-parser/types/save	保存/更新报告类型
POST /api/admin/report-parser/types/toggle	启用/停用报告类型
POST /api/admin/report-parser/types/delete	删除报告类型
POST /api/admin/report-parser/fingerprints/list	指纹规则列表
POST /api/admin/report-parser/fingerprints/save	保存指纹规则
POST /api/admin/report-parser/fingerprints/delete	删除指纹规则
POST /api/admin/report-parser/imports	导入记录列表
POST /api/admin/report-parser/imports/import	上传导入包
POST /api/admin/report-parser/imports/approve	审批导入
POST /api/admin/report-parser/imports/reject	驳回导入
POST /api/admin/report-parser/unknown-clusters	未知报告聚类列表
POST /api/admin/report-parser/unknown-uploads	聚类上传记录
POST /api/admin/report-parser/generate-type	自学习生成报告类型

---

五、新增接口流程

1. 搜索现有接口：grep -rn "关键词" cfc-backend/src/main/java/com/etotem/cfc/controller/
2. 检查路由冲突：grep -rn '@PostMapping("' cfc-backend/src/main/java/com/etotem/cfc/controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u
3. 检查 Bean 冲突：find ... -name "*XxxService.java" | xargs grep "class Xxx"
4. 如有相似接口：评估修改成本，必要时扩展
5. 如确需新增：
   a. 创建 Entity（如需要新表）
   b. 创建 Mapper
   c. 创建 Service
   d. 创建 Controller（放在合适子目录）
   e. 数据库迁移（DatabaseInitializer + schema.sql）
   f. 更新本文档
6. mvn clean compile 验证

4.31 家庭管家选择（/api/butler/*）

路径	说明
POST /api/butler/available-list	可选管家列表（浏览开放，脱敏；仅 L2 有效订阅家庭可绑定）
POST /api/butler/my-butler	我家当前管家绑定信息（含管家昵称/等级/分配时间）
POST /api/butler/select	绑定/更换管家（校验 L2 订阅、管家容量与接单状态；换绑自动解绑旧关系）

4.32 优惠券（家庭维度，/api/coupon/* + /api/admin/coupon/*）

2026-08-31 起，优惠券由「用户维度」全链路改为「家庭维度」。user_coupon 保留历史数据，新发放与消费统一走 family_coupon。

---

4.33 CF 值分佣（/api/commission/cf/*）

CF 值（平台积分）统一分佣体系（F-4 分佣收口，2026-10-25）：普通订单双返（当前消费人 F02 + 推荐人两级销售奖），会员/订阅只返推荐人，同家庭互推跳过本人上溯。 推荐人返佣收口为 F03a 直接销售奖 + F03b 间接销售奖，共同基数 = 本单消费产生的 P 点；旧「团队规模阶梯 cf_rate_tier」已废弃（表保留只读，仅等级展示/历史查询使用）。

路径	说明
POST /api/admin/coupon/list	优惠券模板分页列表（admin），{ page, size, keyword?, sort? }，返回 Page<Coupon>（records/total/current/size），keyword 对名称/ID 模糊匹配
POST /api/admin/coupon/create	新建优惠券模板（admin）
POST /api/admin/coupon/update	更新优惠券模板（admin）
POST /api/admin/coupon/issue	批量发放到家庭，{ couponId, familyIds: [Long] }（admin）
POST /api/admin/coupon/issue-family	单家庭发放，{ familyId, couponId, quantity }（admin，家庭管理页使用）
POST /api/admin/coupon/grant-log	家庭发券流水查询，{ familyId?, couponId?, grantType?, source? }（admin，返回 family_coupon_grant_log，每行含批量填充的 familyName，消除前端逐条查家庭名 N+1）
POST /api/admin/coupon/grant-user	管理员定向发放「会员升级券」给指定用户，{ userId, amountYuan \| amount, validUntil?, remark? }（admin，自动创建 applicableTo=MEMBERSHIP 无门槛券模板并发放到该用户家庭，落 grantType=MANUAL 流水）
POST /api/admin/coupon/toggle-status	启用/停用优惠券模板（admin）
POST /api/coupon/list	当前家庭可用优惠券（小程序）
POST /api/coupon/my	我的（家庭）优惠券（小程序）
POST /api/coupon/apply	下单抵扣（家庭券）
POST /api/coupon/claim	领取优惠券（发到家庭）
POST /api/coupon/checkout-list	结算页可兑换未拥有券
POST /api/coupon/available-templates	领券中心可取券模板：上架（status 空/ACTIVE）、有效期内、未领完（total_count 空/≤0 视为不限量，否则 used_count（字段为id等模板字段），与/claim` 去重口径对齐（COUPON-C3）

路径	说明
POST /api/commission/cf/rate	我的团队规模 + 两级销售奖档位。返回 { totalTeamSize, ratePercent, tierName, teamDepth, teamAnnualPpoints, selfAnnualPpoints, directRatePercent, directTierName, indirectRatePercent, indirectTierName }；legacy 字段 ratePercent/tierName 取 F03a 值供旧端兼容（未入档时 ratePercent=0、tierName="未入档"）
POST /api/commission/cf/summary	我的 CF 钱包汇总，返回 PlatformBalanceService.getBalance(userId) 结果
POST /api/commission/cf/list	我的 CF 流水（分页），请求 { page, size }，返回 Page<PlatformBalanceLog>

两级销售奖档位（迁移418 种子，管理端可配置）：

共同基数 = 本单消费产生的 P 点（商品：实付元 × 有效 P 点 / 100；非商品：实付元 × cf.commission.service_rate(bps) / 10000）。第 1 个非同家庭引荐人拿 F03a，第 2 个拿 F03b，最多两级。

F03a 直接销售奖（cf_direct_sales_tier，按团队 8 层内滚动一年累计 P 点）：

团队年度 P 点下限	档位	比例
100	青铜	10%
500	白银	25%
2000	黄金	40%
5000	铂金	55%
10000	钻石	70%

F03b 间接销售奖（cf_indirect_sales_tier，按自身滚动一年累计消费 P 点）：

自身年度 P 点下限	档位	比例
100	青铜	2%
500	白银	5%
2000	黄金	10%
5000	铂金	15%
10000	钻石	20%

匹配语义：enabled=1 AND min_xxx <= 值 ORDER BY min_xxx DESC LIMIT 1，无匹配档位不发放；比例按 cf_earn_rule.params_json.max_rate_percent（F03a=70、F03b=20）封顶。 金额由 cf_earn_rule.formula = floor(base_ppoints * rate_percent / 100) 计算，发放统一走 CfBalanceService.earnByRule（幂等键复用 F-2 uk_ref_type），只写 cf_balance + cf_balance_log。 滚动一年口径：消费支付成功时落 ppoint_consumption_log 一行（唯一键 order_type + order_id 幂等），按 created_at >= now() - 365d 聚合（迁移420）。

4.34 CF 成员间转让（/api/cf/transfer/*）

路径	说明
POST /api/cf/transfer/send	成员间转让 CF，请求 { toUserId, amount }。仅限同一家庭（校验 familyId 一致）；amount 必须为正数。转出扣减 + 转入增加在同一事务
POST /api/cf/transfer/list	转让记录（分页，按当前用户家庭过滤），请求 { page, size }，返回 Page<CfTransferRecord>

4.35 CF 返佣阶梯配置（admin，/api/admin/cf-rate-tier/*）

路径	说明
POST /api/admin/cf-rate-tier/list	阶梯列表（按 sort_order 升序），返回 List<CfRateTier>
POST /api/admin/cf-rate-tier/save	新增/更新阶梯，请求体为 CfRateTier（含 id 则更新，否则新增，默认 enabled=1），返回 "已保存"
POST /api/admin/cf-rate-tier/delete	删除阶梯，请求 { id }，返回 "已删除"

CfRateTier 字段： id / tierName（档位名）/ minTeamSize（团队规模下限含）/ ratePercent（返佣比例%）/ sortOrder（排序，越大越高）/ enabled（1启用/0停用）/ createdAt / updatedAt。

注意：家庭券接口为 POST /api/coupon/my 与 POST /api/coupon/list（见 4.32），不存在 /api/coupon/family/list 路由。

4.36 健康报告异步采集（/api/health/report/*, /api/report-parser/*）

健康报告上传后进入异步采集流程：后端解析 PDF（先 pdftotext 提取文本内联，避免依赖代理工具执行），指纹判定报告类型 → 已知类型走专用采集脚本，未知类型交本地 opencode 服务（模型 agnes-ai/agnes-2.5-flash，在 session body 中显式指定）。前端提示「数据采集中」，完成后自动入库，列表页轮询刷新，无需用户等待。

路径	说明
POST /api/health/report/upload-only	生产小程序上传入口：上传 PDF → 落草稿 health_report_drafts（parse_status=collecting）→ 异步触发采集 → 返回草稿 ID（前端留意 data.draftId 后轮询）
POST /api/report-parser/upload	专用采集接口：同 async 流程，统一进异步采集
POST /api/health/report/collect/status	查询单草稿采集状态，请求 { draftId }，返回 { status, parseError }（collecting/completed/failed）
POST /api/health/report/collecting-list	当前用户「采集中」草稿列表，返回 List<Draft>（前端轮询用）

采集流程状态机：

• collecting：指纹判定 + 异步解析中
• completed：解析成功 + 已自动入库（指标/菌群/疾病风险/食材）
• failed：解析失败，parse_error 记录原因

专属采集脚本路径（在 HealthReportDraftService）： getDraftById / markCollecting / updateParseMethod / markCollectCompleted / markCollectFailed / listCollectingByUser。

4.36.1 报告归属管理（/api/health/report/*）

报告归属由 health_reports.subject_id 字段表示（关联家庭成员 ID，可为 null）。无归属的报告不参与方案生成，但可在管理端或小程序手动绑定/重新分配。

路径	说明
POST /api/health/report/reassign	重新分配报告归属（含维度重算），请求 { reportId, subjectId? }，subjectId 为 null 表示解绑
POST /api/health/report/unlinked	获取家庭内所有未绑定归属的报告，请求 { familyId }，返回 List<HealthReport>
POST /api/health/report/bind	绑定报告到成员（仅绑定，不可解绑），请求 { reportId, subjectId }

/api/health/report/reassign 请求体：

{
  "reportId": 123,
  "subjectId": 456       // 可为 null 表示解除绑定
}

响应： Result<String>，"归属已更新"

归属变更触发联动：

• 旧归属成员（若有）：五维能量重算 + 食材推荐指数刷新
• 新归属成员（若有）：五维能量重算 + 食材推荐指数刷新
• 方案生成：subject_id IS NULL 的报告自动跳过（triggerAutoPlanAfterConfirm 已有此逻辑）

权限检查： 通过 familyId（JWT 注入）验证报告属于当前家庭，跨家庭操作抛出 RuntimeException("报告不属于该家庭")。

---

4.36.2 舌诊 AI 集成（/api/health/report/*）

舌诊功能已集成 aikanshe.com（愛看舌）开放 API，作为首选方案；当 aikanshe.com 不可用时回退至 LangGraph Python 服务。调用流程如下：

请求路径：POST /api/health/report/parse-preview（type=tongue）

请求体示例：

{
  "type": "tongue",       // 必填：指定舌诊流程
  "memberId": 12345,      // 可选：家庭成员 ID
  "filePath": "/data/...",// 可选：图片路径（auto模式会先检测}
}

响应结构：

{
  "code": 200,
  "message": "success",
  "data": {
    "recordId": 67890,               // 舌诊记录 ID
    "imageUrl": "http://...",        // 图片访问 URL
    "overallAssessment": "舌象基本正常...", // 整体评估
    "indicators": [                  // 7类舌诊指标
      {"code": "tongue_color", "value": "淡红"},
      {"code": "coating_color", "value": "薄白"},
      {"code": "coating_texture", "value": "润"},
      {"code": "fissure", "value": "无"},
      {"code": "teeth_mark", "value": "无齿痕"},
      {"code": "sublingual_vein", "value": "无点刺"},
      {"code": "constitution", "value": "平和质"}
    ],
    "createTime": "2026-10-08T..."
  }
}

优先级方案（aikanshe.com 优先，LangGraph 兜底）：

1. 首选：调用 aikanshe.com API（POST /agency/quanxi，基于 AI 视觉模型）
2. 兜底：若 aikanshe.com 超时/失败，自动回退至 LangGraph Python 服务（/api/v1/tongue/diagnose）
3. 最终兜底：两者均失败时返回默认 mock 数据，确保业务不中断

置信度阈值：默认 0.2，可通过 application.yml 的 aikanshe.confidence 配置。

相关配置：

aikanshe:
  appkey: ${AIKANSHE_APPKEY:}
  base-url: ${AIKANSHE_BASE_URL:https://api.aikanshe.com}
  token: ${AIKANSHE_TOKEN:}
  confidence: ${AIKANSHE_CONFIDENCE:0.2}
  lang: ${AIKANSHE_LANG:zh-CN}

已废弃接口（保留，待清理）：

• POST /api/health/report/upload-only（PDF流程入口，已被 /api/health/report/parse-preview?type=tongue 部分取代）

4.37 报告反馈与 AI 解答（/api/health/feedback/*）

用户对健康报告提交疑问/建议，后端持久化到 report_feedback 表并调用 AI 解答（经 AiGateway，免费版每日 1 次，付费版不限）。反馈记录含 aiAnswer/aiStatus，前端可据此展示 AI 解答结果。

路径	说明
POST /api/health/feedback/submit	提交报告反馈（持久化 + AI 解答），请求 { reportId?, draftId?, memberId?, type, content }，返回 Result<ReportFeedback>
POST /api/health/feedback/list	我的报告反馈列表（含 AI 解答），请求 { reportId? }，返回 Result<List<ReportFeedback>>（按创建时间倒序，最多 50 条）

/api/health/feedback/submit 请求体：

{
  "reportId": 123,              // 可选，关联健康报告ID
  "draftId": null,              // 可选，关联解析草稿ID（reportId 与 draftId 二选一，均可为空）
  "memberId": 456,              // 可选，关联家庭成员ID（默认当前成员）
  "type": "question",           // question=疑问 / suggestion=建议，其他值默认 question
  "content": "这份报告里菌群多样性偏低是什么意思？"
}

响应示例（Result<ReportFeedback>，data 字段）：

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 1,
    "userId": 1001,
    "memberId": 456,
    "reportId": 123,
    "draftId": null,
    "feedbackType": "question",
    "content": "这份报告里菌群多样性偏低是什么意思？",
    "aiAnswer": "菌群多样性反映肠道微生物的丰富程度……",
    "aiStatus": "answered",
    "conversationId": "conv_abc123",
    "createdAt": "2026-09-22 14:30:00"
  }
}

• aiStatus 取值：pending（待解答）/ answered（AI 已解答）/ failed（AI 调用失败，仍会落库，aiAnswer 为空）。
• 免费版每日仅限 1 次反馈解答（Redis 计数 report:feedback:free:{userId}:{date}，memberLevel=FREE 或为空时生效），超限返回 Result.error("免费版每日仅限 1 次反馈解答，升级会员解锁更多")；Redis 异常时 fail-open 放行。
• content 必填且不超过 500 字。

---

4.38 认知维度（/api/cognitive/*）

六维认知体系：感知(perception) / 专注(focus) / 记忆(memory) / 逻辑(logic) / 空间(spatial) / 加工速度(processingSpeed)。

路径	说明
POST /api/cognitive/child	获取孩子最新六维认知得分
POST /api/cognitive/family	获取家庭所有孩子最新六维认知得分
POST /api/cognitive/update	更新认知维度得分（由规划师录入，需已有 completed 行）
POST /api/cognitive/self-test	提交认知自测结果（自动创建档案，写入六维认知档案，综合分自动计算）
POST /api/cognitive/norms	获取认知维度百分位常模
POST /api/cognitive/trend	获取认知维度历史趋势
POST /api/cognitive/recommendations	获取认知训练建议（按薄弱维度生成）
POST /api/cognitive/recommendations/create-task	从建议创建每日任务

/api/cognitive/self-test 请求体：

{
  "memberId": 12345,
  "dimension": "memoryScore",
  "score": 85
}

dimension 取值：memoryScore / logicScore / perceptionScore / spatialScore / processingSpeedScore score 范围：0-100（整数）

响应： Result<String>，成功返回 "提交成功"，失败返回错误原因。

行为： 若该孩子尚无任何 status=completed 的 DanAssessmentResult 行，自动创建（source='self_test'），写入对应维度分，重新计算综合分（7 维度非空均值）。

已记录认知自测 API 端点 — 禁止重复注册。

4.39 珍珠图/能力图（/api/pearl/*, /api/ability/*）

关系三图体系：章鱼图（谁帮过我）→ 珍珠图（我有什么）→ 能力图（谁会什么）。珍珠图聚合 25 类社会连接（12 必备内圈 + 13 理想外圈），附带互动日志、价值分级、定期提醒。

路径	说明
POST /api/pearl/resources	珍珠图聚合：25 组（ESSENTIAL 内圈 + IDEAL 外圈）+ legacyGroups（历史资源）
POST /api/pearl/connection-types	获取 25 类连接类型列表（code/label/category/suggestIntervalMonth）
POST /api/pearl/item/add	登记珍珠图资源（connectionType 必填，type 可选，name 必填，contactId 可选）
POST /api/pearl/item/delete	删除登记的珍珠图资源（itemId）
POST /api/pearl/item/update-priority	手动覆盖优先级（itemId/priority 1-3），同步 valueScore
POST /api/pearl/interaction/add	记录互动（itemId/interactionType/content），更新价值分并关闭 PENDING 提醒
POST /api/pearl/interaction/list	互动历史分页（itemId/page/size）
POST /api/pearl/reminder/list	待办提醒列表（PENDING）
POST /api/ability/map	能力图：SKILL 帮助记录按联系人聚合为能力节点

/api/pearl/resources 响应结构：

{
  "code": 200,
  "data": {
    "groups": [
      {
        "type": "MEDICAL", "typeName": "医疗", "category": "ESSENTIAL", "ring": "inner",
        "items": [
          {
            "id": 1, "name": "社区王医生", "description": "儿科主治", "avatar": null,
            "valueScore": 72, "priority": 1, "contactId": 5,
            "lastInteractionAt": "2026-08-15T10:30:00",
            "interactionCount": 8, "daysSinceLast": 26
          }
        ]
      }
      // ... 共 25 组，为空时 items=[]
    ],
    "legacyGroups": [
      { "type": "PERSON", "typeName": "人脉", "items": [...] },
      { "type": "SKILL", "typeName": "技能", "items": [...] },
      { "type": "INFO", "typeName": "信息", "items": [...] },
      { "type": "PLACE", "typeName": "场所", "items": [...] }
    ]
  }
}

价值分算法（/api/pearl/interaction/add 后自动重算）：

• 类型基础权重：ESSENTIAL=30，IDEAL=20
• 近 90 天互动次数 × 5，上限 30
• 最近互动时效性：≤30天=+20，≤90天=+10，≤180天=+5
• 互动总量 × 2，上限 20
• 总分 0-100，priority=1（高/大珍珠）→ valueScore≥70，priority=2（中）→ 40-69，priority=3（低/小珍珠）→ <40

/api/ability/map 响应结构： data 为数组，元素结构同 SKILL 组 items（contactId/name/avatar/relationshipType/skillCount/skills/lastHelpedAt）。

珍珠图前端组件： PearlDiagram.vue（Canvas 2D，两层同心圆，内圈 radiusPct=0.28 / 外圈 0.55，珍珠半径按 priority/valueScore 映射 8-26px）。

珍珠图定时提醒： PearlReminderScheduledTask 每日 08:00 执行，遍历 connection_type 非空资源，daysSinceLast ≥ suggestIntervalMonth×30 时生成 PENDING 提醒。

珍珠图交互流程： 打开页 → 加载 resources → 渲染两层同心圆 → 点击珍珠弹窗（联系/优先级/删除）→ 记录互动 → 重算价值分 → 逾期角标红点。

/api/pearl/interaction/add 请求体： { "itemId": 1, "interactionType": "WECHAT", "content": "咨询过敏问题" } interactionType 取值：PHONE / WECHAT / MEETING / OTHER。

/api/pearl/item/update-priority 请求体： { "itemId": 1, "priority": 1 }（1=高/大珍珠，2=中，3=低/小珍珠）。

珍珠图前端页面：

• 珍珠图：pages/action-detail/index.vue（内嵌 PearlDiagram.vue 组件）
• 登记资源：pages/action-detail/pearl-add-resource.vue（25 类类型分组选择器）
• 互动提醒：pages/pearl-reminders/index.vue（PENDING 提醒列表）

前端 API（utils/api.js）：

• getPearlResources()
• getConnectionTypes()
• addPearlResource(data) （data.connectionType 必填）
• deletePearlResource(data)
• addPearlInteraction(data)
• getPearlInteractionList(data)
• getPearlReminders()
• updatePearlPriority(data)

已记录珍珠图/能力图 API 端点 — 禁止重复注册。

4.40 关键人拓展章鱼图（/api/octopus/*）

替代旧章鱼图（help_logs）。核心：成效记录 → 关键人画像 → 高频词分析 → 拓展方向。

路径	说明
POST /api/octopus/tentacles	⚠️ 已废弃（410） 旧章鱼图：触手榜
POST /api/octopus/add	⚠️ 已废弃（410） 旧章鱼图：新增帮助记录
POST /api/octopus/delete	⚠️ 已废弃（410） 旧章鱼图：删除帮助记录
POST /api/octopus/records	⚠️ 已废弃（410） 旧章鱼图：帮助记录明细
POST /api/octopus/effect/list	成效记录分页列表（支持 effect_type 筛选）
POST /api/octopus/effect/add	新增成效（member_order_id + effect_type bitmask + amount + desc）
POST /api/octopus/effect/delete	删除成效（级联关系）
POST /api/octopus/key-person/add	新增关键人（姓名/单位/部门/职务/初识场合/如何认识）
POST /api/octopus/key-person/update	修改关键人画像
POST /api/octopus/key-person/delete	删除关键人（级联关系）
POST /api/octopus/effect/key-persons	某成效的关键人列表
POST /api/octopus/analysis/keywords	高频词统计（单位/部门/职务/场合/路径）
POST /api/octopus/analysis/summary	高频词提炼 ≤8 个拓展方向
POST /api/octopus/expansion/suggest	基于分析推荐关键人画像模板（预填）

已记录关键人拓展 API 端点 — 禁止重复注册。

4.41 DOA 个人目标（家庭打卡个人目标模块）

路径	说明
POST /api/doa/stage/create	创建阶段（memberId?+title+durationWeeks+goals[1-3]）
POST /api/doa/overview	家庭总览：各成员当前 active 阶段
POST /api/doa/stage/detail	阶段详情：stage + goals + weeks
POST /api/doa/stage/cancel	取消阶段（仅 active 可取消）
POST /api/doa/week/plan	提交周计划（A表周行动宣告）
POST /api/doa/week/review	提交周复盘（B表五问）
POST /api/doa/week/list	周记录列表（按阶段查周记录）

已记录 DOA 个人目标 API 端点 — 禁止重复注册。

4.42 引导弹窗配置化管理

路径	说明
POST /api/guide/popup/list	查询当前用户应展示的激活弹窗列表
POST /api/guide/popup/trigger	上报触发行为，返回匹配弹窗
POST /api/guide/popup/consume	消费弹窗（点击/关闭上报，防止重复弹出）
POST /api/admin/guide/popup/list	管理端：列表（分页筛选 status/slug）
POST /api/admin/guide/popup/create	管理端：创建弹窗（含触发条件+步骤）
POST /api/admin/guide/popup/update	管理端：更新弹窗（全量覆盖步骤和条件）
POST /api/admin/guide/popup/status	管理端：启用/禁用（toggle）
POST /api/admin/guide/popup/delete	管理端：软删除
POST /api/admin/guide/popup/stats	管理端：数据看板（曝光/点击/完成率/分时段趋势）

设计文档：docs/superpowers/specs/2026-09-22-guide-popup-config-design.md

实施计划：docs/superpowers/plans/2026-09-22-guide-popup-config.md

说明：本功能将小程序弹窗引导页从硬编码改为配置化管理，支持管理员在后台配置弹出条件与内容。旧方案（sys_config onboarding_guide_config）保留，新方案通过 4 张新表 + 9 接口实现。

---

六、待清理的废弃接口

Controller	废弃接口	替代方案	当前状态	清理条件
------------	----------	----------	----------	----------
FamilyController	/invite-code, /invite-code/generate	/api/family/invite/generate	@Deprecated + 410 ✓	确认前端无调用
FamilyUserController	/switch-mode, /switch-to-child	/api/family/member/switch	@Deprecated + 410 ✓	确认前端无调用
FamilyUserController	/switch-back-to-parent, /switch-back-verify	/api/family/member/switch	已修复：@Deprecated + 410	确认前端无调用
ButlerController	/service-records, /commissions	—	@Deprecated + 410 ✓	可删除
TeacherController	全部 /api/teacher/* 方法	/api/guide/families/*	@Deprecated + UnsupportedOperationException	确认规划师端无调用
DanAssessmentController	/current	—	需验证	无前端调用方
NoticeController	GET /list（违反 POST 规范）	/api/admin/notices/list	已修复：@Deprecated + 410	可删除
OctopusController	/tentacles, /add, /delete, /records	/api/octopus/effect/*, /api/octopus/key-person/*	@Deprecated + 410 ✓（2026-09-10 替换为关键人拓展）	确认前端无调用（旧页面已删除）

---

4.37 情绪识别（/api/mind/emotion/*）

基于 DeepFace 的人脸情绪识别，通过 LangGraph /api/v1/emotion/recognize 调用。

路径	说明
POST /api/mind/emotion/analyze	上传照片进行情绪识别（multipart 文件）
POST /api/mind/emotion/analyze-url	通过 URL 进行情绪识别（兼容旧调用方）

POST /api/mind/emotion/analyze

请求：multipart/form-data，字段 file（JPEG/PNG，最大 10MB）

返回：

{
  "code": 200,
  "data": {
    "dominant_emotion": "happy",
    "dominant_label_zh": "开心",
    "emotions": [
      { "emotion": "happy", "confidence": 0.85 },
      { "emotion": "neutral", "confidence": 0.10 },
      { "emotion": "sad", "confidence": 0.03 },
      { "emotion": "surprise", "confidence": 0.01 },
      { "emotion": "angry", "confidence": 0.005 },
      { "emotion": "fear", "confidence": 0.003 },
      { "emotion": "disgust", "confidence": 0.002 }
    ],
    "all_emotions": {
      "happy": 0.85,
      "neutral": 0.10,
      "sad": 0.03,
      "surprise": 0.01,
      "angry": 0.005,
      "fear": 0.003,
      "disgust": 0.002
    }
  }
}

POST /api/mind/emotion/analyze-url

请求体：

{ "image_url": "https://cdn.example.com/photo.jpg" }

返回：同上。

---

4.43 商品赠送会员（/api/membership/gift-membership-progress）

家庭维度累计「赠会员商品」原价实付金额，达到阈值后自动赠送会员。

路径	说明
POST /api/membership/gift-membership-progress	获取当前家庭的赠会员累计进度

POST /api/membership/gift-membership-progress

请求：无（familyId 由 JWT userId 反查）

返回：

{
  "code": 200,
  "data": {
    "familyId": 12,
    "accumulatedAmount": 158000,
    "granted": 0,
    "grantedLevel": null,
    "grantedOrderNo": null,
    "grantedAt": null,
    "threshold": 198000,
    "remaining": 40000
  }
}

字段	类型	说明
accumulatedAmount	Integer	累计赠会员商品原价金额（分），仅统计无积分/无券/无折扣的实付订单
granted	Integer	1=已赠送 0=未赠送
grantedLevel	String	已赠送的会员等级（当前全局配置默认 FAMILY）
threshold	Integer	阈值（分），由 sys_config.gift_membership_threshold 动态填入
remaining	Integer	还差多少达标（分）= max(0, threshold - accumulatedAmount)，已达标为 0

注意：threshold、remaining 为 @TableField(exist = false) 非数据库列，仅接口返回用。 无家庭时：接口返回空对象，threshold/remaining/accumulatedAmount 均为 null（此时不存在赠会员累计口径），前端据此隐藏进度条。 阈值单位为分（1980 元 = 198000 分），实际生效值以 sys_config 表中 gift_membership_threshold 为准（insertSysConfigSeed 仅在缺失时插入，不覆盖已有配置）。

---

4.44 统一服务角色申请（/api/service-role/*）

多角色（规划师/营养师/管家/供应商/内容管理员/活动策划）统一申请入口，一次提交可含多个角色，管理端审批通过后回写 users.roles 并按角色初始化附属记录。

路径	说明
POST /api/service-role/apply	提交服务角色申请（roles 必填）
POST /api/service-role/my-apply	查询我的最新申请记录
POST /api/service-role/upload-image	上传身份证/资质证书图片（multipart，字段名 file）
POST /api/service-role/admin/list	管理端：申请列表（status 查询参数，默认 0）
POST /api/service-role/admin/approve	管理端：批准（{ id }）
POST /api/service-role/admin/reject	管理端：驳回（{ id, reason }）

权限：admin/list、admin/approve、admin/reject 三个端点校验 @RequestAttribute("role")，仅 role=admin 或 role=operator 可访问（与 AdminHealthPlanController 审核类端点口径一致），其他角色返回「无权限」。前端菜单由 perm: 'audit:service-role' 控制。

状态语义（service_role_applications.status）

值	含义
0	待审核（同一 userId 仅允许一条待审，重复提交返回「您已提交过申请，请等待审核」）
1	已通过
2	已驳回（原因存 reject_reason）

POST /api/service-role/apply 请求体（ServiceRoleApplyDTO）

字段	类型	说明
roles	List<String>	申请角色，@NotEmpty 至少一个
idCard	String	身份证号
idCardImages	List<String>	身份证图片 URL 数组（落库转 JSON 字符串）
certificateImages	List<String>	资质证书图片 URL 数组
province / city / district / street	String	四级地址
addressDetail	String	详细地址

审批通过后的角色落地规则（ServiceRoleApplicationServiceImpl.approve）

申请角色	副作用
planner	guides 新增一行（status=active）+ users.roles 追加 teacher
nutritionist	users.nutritionist_status=approved + roles 追加 nutritionist
butler	users.butler_status=approved + butler_profiles 新增一行 + roles 追加 butler
vendor	users.vendor_status=approved + roles 追加 supplier
article_admin	users.article_admin_status=approved + roles 追加 knowledge_admin
activity_provider	users.activity_provider_status=approved + roles 追加 activity_manager

注意：approve/reject 仅对 status=0 的记录生效，已处理返回「该申请已处理」。 upload-image 对图片类型文件先走 wechatService.checkImage() 内容安全检测，未通过直接拒绝。

---

4.45 规划师解除家庭绑定（POST /api/guide/families/unbind）

路径	说明
POST /api/guide/families/unbind	规划师解除自己名下的家庭绑定（请求体 { id }，即 guide_families.id）

• 角色校验：仅 role=teacher 可调用，否则返回 Access denied。
• 归属校验：GuideFamilyService.unbindByGuide() 按 id + guide_id + status='binding' 定位，只能解除属于自己的绑定。
• 副作用：将 guide_families.status 置为 cancelled。
• 家长侧解绑为独立接口 POST /api/bind/unbind（按 familyId 定位，并通知规划师）。

注意：前端 unbindFamily(id) 需传 guide_families.id（绑定记录 ID），不是 familyId。

---

4.46 规划师方案审核（/api/health/plan/pending-review/*）

路径	说明
POST /api/health/plan/pending-review/list	待审核方案列表（teacher 取当前登录人；admin 可传 teacherId 过滤，不传则返回该家庭全部）
POST /api/health/plan/pending-review/update	编辑方案内容（仅 status 为 draft/pending_review 允许）
POST /api/health/plan/pending-review/approve	审核通过并发布
POST /api/health/plan/pending-review/reject	驳回

• 角色校验：仅 role=teacher 或 role=admin，且必须携带 familyId，否则返回 familyId不能为空。
• 未分配池规则：listPendingReviewPlans() 在 teacherId 非空时按 (teacher_id = ? OR teacher_id IS NULL) 过滤 —— 规划师既能看到分配给自己的方案，也能看到本家庭内尚未指定规划师的方案（health_plans.teacher_id 为 NULL），避免用户未选规划师时保存的 pending_review 方案成为无人可见的孤儿记录。
• 入选范围限定 status IN ('draft','pending_review')，按 created_at 倒序。

注意：health_plans.teacher_id 列由迁移 251 建立（DatabaseInitializer），schema.sql 已同步。 前端 getPendingReviewPlans()（utils/api.js）目前尚无页面消费，规划师审核页未接通；新审核工作台改用 4.47 的 plans/pending 端点，本节 4 个端点保留但不再被前端调用。

⚠️ 2026-10-04：/pending-review/approve 响应由 Result<HealthPlan> 改为 Result<PlanApproveResultDTO>（新增 taskGenerated / taskCount / message 字段）。该端点无前端调用点（health-plan-summary.vue 仅有未调用的死导入），变更安全。

✅ 2026-10-04：/{familyId}/overview、/{familyId}/children/{memberId}/tasks、/{familyId}/children/{memberId}/pending-review、/{familyId}/tasks/{taskId}/review、/{familyId}/tasks/batch-review、/{familyId}/tasks/{taskId}、/{familyId}/tasks/{taskId}/delete 共 7 个端点已接入 guide_families 绑定校验，修复跨家庭越权。

---

4.47 规划师审核工作台（/api/guide/families/*）

规划师侧审核工作台的统一入口，授权源为 guide_families.status='binding'（与 GuideFamilyService.isBound(guideId, familyId) 同源），不使用 users.teacher_family_ids。

端点	权限
POST /api/guide/families/my-families	teacher / admin
POST /api/guide/families/{familyId}/members	teacher 需 isBound；admin 放行
POST /api/guide/families/{familyId}/plans/pending	teacher 需 isBound；admin 可传 teacherId 过滤
POST /api/guide/families/{familyId}/plans/{planId}/update	同上 + planId IDOR 反查
POST /api/guide/families/{familyId}/plans/{planId}/approve	同上 + planId IDOR 反查；返回 PlanApproveResultDTO
POST /api/guide/families/{familyId}/plans/{planId}/reject	同上 + planId IDOR 反查

• my-families 不走 checkFamilyAccess(role, userId, null) —— 该路径下 familyId == null 会把 teacher 直接拒掉，故改为显式角色判断 + 按 guide_id 查本人绑定家庭，返回体含 familyName（取自 Family.name，注意字段名不是 familyName）。
• members 返回该家庭可审核成员，供工作台「成员」选择器使用。
• 未分配池规则：plans/pending 复用 listPendingReviewPlans()，teacherId 非空时按 (teacher_id = ? OR teacher_id IS NULL) 过滤；teacher 无需传该参数，admin 可显式传以过滤。
• IDOR 防护：{planId} 类端点先 checkFamilyAccess(role, userId, familyId)，再用 getPlanForFamily(planId, familyId) 按 familyId 反查，返回 null 即 403。控制器内 resolvePlan 的第二次 recheck 仅为纵深防御，getPlanForFamily 已按 familyId 过滤，该 recheck 永不单独拦截请求，不可依赖它替代首道校验。
• approve 返回 PlanApproveResultDTO：planId / status / taskGenerated / taskCount / message。任务生成器 generateDailyTasksFromPlan 返回 void，故实现改为生成后按 source_type='health_plan' AND source_id=planId 统计实际条数；生成异常或计数为 0 时方案仍发布并返回 taskGenerated=false，属部分成功，前端须与失败区分提示。

注意：配套前端为 pages/teacher/review-workbench.vue、review-family.vue、plan-detail.vue，入口在 pages/teacher/families.vue。

---

4.47.1 成长规划师咨询消息（/api/guide/messages/*）

家长（家庭主账号）与成长规划师之间的咨询消息接口。

端点	权限	说明
POST /api/guide/messages/send	家长（需 familyId）	发送咨询，请求体 { teacherId, content }
POST /api/guide/messages/{messageId}/reply	仅 role=teacher + 认证闸门	规划师回复，请求体 { replyContent }
POST /api/guide/messages/list	仅 role=teacher	规划师获取咨询列表（分页 { page, size }），响应条目在 content 尾部追加 [家庭主账号:<昵称>]
POST /api/guide/messages/unread-count	仅 role=teacher	规划师未读消息数
POST /api/guide/messages/my	家长（按自身 parentId 查询，无 role 限制）	家庭主账号获取自己的咨询记录，响应 TeacherMessage 列表

• POST /api/guide/messages/my：家庭主账号获取自己的咨询记录。响应 TeacherMessage 列表，每条含 teacherName（规划师昵称，按 teacherId 从 users 表回填，查不到时留空由前端兜底「规划师」）。不新增路由、不改鉴权（/my 无 role 限制，按 parentId 查自己的记录）。

文档更新：2026-11-01（/my 新增 teacherName 回显，见 specs/2026-11-01-home-greet-shortcut-and-my-messages-design.md）。

---

4.48 指标统一层（/api/indicator/* + /api/admin/indicator/*）

指标变化曲线 / 指标速查 / 指标关联的统一读接口与管理端接口。读接口 subjectId 必填且做家庭归属校验（family_members.id = subjectId AND family_id = 当前用户家庭，由 JwtInterceptor 注入 @RequestAttribute("familyId")）；管理端接口校验 @RequestAttribute("role")，仅 role=admin 可访问，否则「无权操作」。

视图接口（IndicatorController，/api/indicator）

端点	请求要点	用途
POST /api/indicator/trend	{subjectId, definitionIds:[...]}	指标曲线（按 definitionId 分组、report_date 升序点序列）
POST /api/indicator/change-ranking	{subjectId, reportType?, category?, scope:adjacent\|first-vs-latest, orderBy:up\|down\|magnitude, limit}	变化幅度排名（含 overall.improvedCount/worsenedCount/flatCount 汇总）
POST /api/indicator/quick-lookup	{subjectId, category?, page, pageSize}	指标速查（分类分页 + 类别汇总 + dimensionScores 五/七维评分小节）
POST /api/indicator/correlation/list	{subjectId, definitionId}	指标关联查询（含 subjectEvidence 成员级配对证据）

管理端接口（/api/admin/indicator/correlation/*、/api/admin/indicator/mapping/*）

端点	请求要点	用途
POST /api/admin/indicator/correlation/save	{definitionIdA, definitionIdB, direction, manualStrength, description, manualLocked, sourceNote}	关联对定义/编辑（写入前按 indicator_definitions.code 字典序强制对序，保证唯一键对称）
POST /api/admin/indicator/correlation/list	{page, size}	关联对分页（按 updated_at 倒序，含校准状态）
POST /api/admin/indicator/correlation/calibrate	{pairId?}	手动触发校准（返回「校准完成，共更新 N 对」）
POST /api/admin/indicator/mapping/import	{sourceType, seeds:[{rawName, definitionId?}]}	映射种子批量导入（返回「导入完成，共 N 条」）
POST /api/admin/indicator/mapping/list	{page, size, status?, sourceType?}	映射规则分页/review（status=0 为 ai_fallback 待确认）

关联校准：save 时 effective_strength = manual_strength；每日 03:00 IndicatorCalibrationJob（@Scheduled(cron = "0 0 3 * * ?")）对 status=active 且 manual_locked=0 的关联对按 subject 分组做 Spearman + Fisher z 聚合，有效样本 >=30 才用 computed_strength 覆盖 manual_strength。correlation/calibrate 手动触发同一逻辑（pairId 传入时仍走全量逐对幂等）。 统一指标层写入（单一写者）：报告入库 / 报告编辑 / 食材推荐刷新三处流程由 NormalizeIndicatorPipeline 幂等写入 indicator_values（唯一键 source_type + source_id + definition_id，upsertMapping ON DUPLICATE KEY）。本层读接口只读 indicator_values，不写时序；五维/七维评分在速查接口按原表 join，不进时序。 关联表：indicator_correlations（迁移 360）、indicator_mapping_rules（迁移 359）。

文档更新：2026-10-09（指标统一层新增，见 specs/2026-10-09-indicator-change-curve-design.md）

⚠️ /api/health/indicator/list 已被取代：老接口返回裸 List<HealthIndicator>（无上一期对照、无 summary）。新接口 /api/health/report/indicators 返回同一批指标 + previous / change / summary 五档形态数据。/api/health/indicator/list 保留不动（cfc-web views/nutritionist/HealthIndicators.vue 仍在调），新接入一律走 /api/health/report/indicators。

---

4.48.1 指标多期展示 · 后端接口（/api/health/report/indicators、/api/indicator/periods、/api/admin/indicator/backfill）

本节为 §4.48 指标统一层的多期展示增量。所有 change 计算统一由 IndicatorChangeService.computeChange 单点产出（trendCode 五档：improved / worsened / flat / first_record / pending_backfill），读路径一律过滤 indicator_definitions.status=1，拿不到 active definition 的观测直接剔除，不降级为「指标」+id 假名称（QP17）。

① POST /api/health/report/indicators — 报告指标明细（含上一期对照，D12 报告详情页接入点）

端点	权限	请求	返回
POST /api/health/report/indicators	登录（JWT；管理员/本人/被授权成员，校验逻辑同 /api/health/report/detail）	{reportId, withPrevious?}	{reportId, reportType, subjectId, reportDate, dateSource, olderReportCount, summary, items}

• 入参：reportId（必填）；withPrevious（选填，默认 true，false 时跳过 previous/change 计算，供编辑模式快速返回单期）。
• 权限：无 subjectId 的报告（历史未绑定成员）仅本人上传者或家庭管理员可见；有 subjectId 时走 ReportMemberPermissionService.canViewMemberReports。
• items[] 每项含：指标原字段（indicatorId/definitionId/category/indicatorName/indicatorValue/numericValue/unit/refRange/status）+ 字典字段（goodDirection/valueType）+ previous（上一期观测，无则 null）+ change（{delta, deltaPct, movement, trendLabel, trendCode, skipGaps, unitMismatch, comparable}，首期时为 first_record，报告日期未知时为 pending_backfill）。
• summary：totalCount / abnormalCount（status 非「正常」）/ abnormalDelta（预留字段，当前固定 0，单报告视角无法直接算）/ changedCount（trendCode 为 improved/worsened 的条数）/ comparableCount / firstRecordCount / pendingCount / dataIncomplete（存在 pending_backfill 时为 true，驱动残缺横幅组件）。
• 与 withPrevious=false：返回单期 items（每项含 indicatorId/category/indicatorName/indicatorValue/unit/refRange/status，不含 definitionId/previous/change/goodDirection/valueType）。
• olderReportCount：该成员在本报告之前（同 sourceType）的历史报告数，用于 first_record 档区分「真的首期」与「更早报告未回填」。
• N+1 约束：42 项指标一次请求的 SQL ≤ 5 次（指标行 1 + 上期批量解析 1 + 字典/定义 1 + 报告 1）；IndicatorMappingService.resolveBatch 用 indicator_mapping_rules JOIN indicator_definitions 单查询批量解析，严禁逐指标查库。

② POST /api/indicator/periods — 期次列表（双期对比页 picker 数据源）

端点	权限	请求	返回
POST /api/indicator/periods	登录（JWT；subjectId 须属于当前家庭）	{subjectId, sourceType?}	{subjectId, sourceType, items}

• items[]：{reportDate, reportId, dateSource, indicatorCount}，按 reportDate 倒序；reportDate=null（日期未知期）恒定排最后，picker 显示「日期未知」。
• dateSource：该期所有观测中最差的一个（unknown < confirm < upload < real），诚实口径——只要有一项来源是上传推断，整期就标 upload。
• indicatorCount：该期有有效值（value 非空）的指标数，picker 显示「2026-10-08（42 项）」。
• 不分页（单人单类型期次数实测 < 30）；只读幂等。

③ POST /api/admin/indicator/backfill — 存量时序回填（admin）

端点	权限	请求	返回
POST /api/admin/indicator/backfill	admin（@RequestAttribute("role") 校验，非 admin 返回「权限不足」）	{subjectId?, reportId?, limit?, dryRun?, fixReportDates?}	{scanned, eligible, written, skippedNoSubject, skippedNoPayload, failed, dryRun, fixReportDates, dateFixable, dateFixed, details[]}

• 用途：把 confirm 链路补写之前的历史报告补进 indicator_values（P0-3 数据面补全），并可顺带用 ReportDateExtractor 修复被 new Date() 污染的历史报告日期。
• 入参：subjectId（选填，指定成员；不传扫全部 status=active 报告）；reportId（选填，只回填指定报告，灰度验证用）；limit（选填，默认 200，上限 500）；dryRun（默认 true）；fixReportDates（默认 false）。
• dryRun=true：预演只统计不写入，返回 eligible/dateFixable 计数，且不触发 mappingService.resolve（避免惰性建定义这类副作用）；首次执行必须 dryRun，核对无误后传 false。
• 顺序红线：先修日期、再补时序（污染日期若固化进 indicator_values 再修就晚了）。日期修复判定条件：能提取到真实日期 且 report_date != extracted 且 report_date >= created_at 当天（new Date() 污染特征签名）；修后需连带 refreshMemberIndicatorCurrent。
• 幂等：NormalizeIndicatorPipeline 按唯一键 source_type + source_id + definition_id upsert，已覆盖报告返回 already_covered，重复执行不产生重复时序。

④ 升级改造的既有端点（IndicatorController）

端点	变更
POST /api/indicator/trend	新增可选入参 {sourceType, fromDate, toDate, granularity: raw\|month, sourceKind: all\|report\|device}；出参新增 refLow/refHigh/goodDirection/valueType/pointsCount/totalReportCount/olderReportCount/chartMode/unitMismatch/latest/change/points/missingPeriods。破坏性：无
POST /api/indicator/change-ranking	新增可选入参 {scope: pair, fromReportDate, toReportDate, filter: improved\|worsened\|flat\|incomparable\|all, page, pageSize}；scope=pair 缺 fromReportDate/toReportDate 返回明确错误；magnitude 排序口径从 \|Δ\| 改为 \|Δ%\| 降序（视觉有变化，属预期修正，见 §4.48 变更汇总）；deltaPct=null 的项恒定排最后且不参与 improved/worsened 筛选（Q14）。破坏性：无
POST /api/indicator/quick-lookup	新增可选入参 {withSparkline, sparkLimit}；出参每项新增 previous/change/latestDateSource/latestReportId/goodDirection/valueType/sparkline；修复 reportDate=null 观测被当作最新值的 bug。破坏性：无
POST /api/indicator/source-types	出参新增 periodCount / latestReportDate（曲线页类型筛选用，原只返回类型名）。破坏性：无

chartMode 判定表（后端单点定义，IndicatorChangeService.chartModeOf）：pointsCount=0 → empty；=1 → single；=2 → pair；<20 → line；≥20 → line_aggregated（granularity=month 时强制 line_aggregated）。 SQL 预算（严禁 N+1，均有单测锁死）：/report/indicators 42 项指标 → 服务层恒 3 次协作调用（控制器另加 2 次，合计 ≤ 5）；/quick-lookup 与 /source-types 均恒 1 次 indicator_values 查询（上一期与 periodCount 全部内存计算）。 IndicatorService.listDefinitions：status 传 null 时默认按 status=1 过滤（防止 P1-6 自动创建的 status=0 definition 冒进管理端字典列表，QP17）。 missingPeriods：该成员有报告、但本指标无有效值的期次，IndicatorTimelineService 固定 2 次查询算完（原 1+缺失期数，会 N+1）。 老接口兼容矩阵见 specs/2026-10-25-indicator-timeline-display-design.md §4.7。

文档更新：2026-10-27（指标多期展示 T02 后端接口，见 specs/2026-10-25-indicator-timeline-display-design.md）

---

4.48.2 指标收藏 · 后端接口（/api/indicator/favorite/*）

本节为 T04「关注指标收藏」后端化（方案A）增量。收藏从 localStorage（方案B）升级为后端持久化，可跨设备同步、跨端一致。全部 @PostMapping；JWT Bearer 鉴权；@Resource 注入；userId/familyId 由 JwtInterceptor 注入 @RequestAttribute，服务端不信任前端传值。

① POST /api/indicator/favorite/toggle — 收藏/取消（存在则删、不存在则插，幂等于单次调用）

端点	权限	请求	返回
POST /api/indicator/favorite/toggle	登录（JWT；已加入 LOGIN_REQUIRED_PATHS，无 token 直接 401；memberId 须属于当前家庭）	{memberId, sourceType, definitionId}	{definitionId, added}

• 入参：memberId/definitionId（必填 Long）、sourceType（必填 String，非空）。
• 返回：added=true 本次加入收藏（新插入）；added=false 本次取消收藏（已删除）。
• 错误码：400（缺参/成员不属家庭/definitionId 非法）、401（未登录）。

② POST /api/indicator/favorite/list — 查已收藏集合

端点	权限	请求	返回
POST /api/indicator/favorite/list	登录（JWT；memberId 须属于当前家庭）	{memberId, sourceType}	{memberId, sourceType, definitionIds}

• definitionIds：该成员×该报告类型下已收藏的指标定义 ID 列表（升序，按 id）；空集合返回 []。
• 查询范围限定 user_id = userId AND family_id = familyId AND member_id AND source_type（家庭/用户隔离）。

③ POST /api/indicator/favorite/remove — 移除收藏（显式删除）

端点	权限	请求	返回
POST /api/indicator/favorite/remove	登录（JWT；memberId 须属于当前家庭）	{memberId, sourceType, definitionId}	{definitionId, removed}

• removed=true：该条收藏已删除（不存在则视作已删除，幂等）。供前端「清空对比/切换成员」等需显式删除而非 toggle 语义的场景使用。

文档更新：2026-10-30（T04 指标收藏后端化，见 specs/2026-10-30-indicator-favorite-backend-design.md）

---

4.49 健康方案删除（/api/health/plan/delete、/api/admin/health-plan/delete）

已生成的健康方案可删除，级联删除其产生的全部任务（含每日实例）。

端点	权限	请求	返回
POST /api/health/plan/delete	登录用户（JWT）	{planId}	{planId, taskCount}
POST /api/admin/health-plan/delete	admin/teacher/butler/nutritionist/operator	{planId}	{planId, taskCount}

• 级联范围：health_plans 方案行 + tasks 中 source_type='health_plan' AND source_id=planId 的直接任务（周期模板/一次性任务/购买锚点）+ tasks 中 template_id IN 直接任务ID 的每日实例（RepeatTaskGenerator 生成，只透传 template_id 不带 source_id，必须二次删除，否则任务删后次日仍被再生产）。
• 保留不删：points_log（积分流水，已完成任务的积分保留不撤回）、task_executions / growth_task_log（执行历史）。
• 事务：HealthPlanServiceImpl.deletePlanCascade 标注 @Transactional(rollbackFor = Exception.class)，任一步失败整体回滚，不留无方案的孤儿任务。
• IDOR：用户端接口从 @RequestAttribute("familyId") 取家庭做归属校验，方案不属于该家庭返回「无权删除该方案」；管理端传 familyId=null 跳过归属校验。
• 状态：任何状态（draft/pending_review/published/rejected）均可删除；前端以确认弹窗兜底提醒。

文档更新：2026-10-17（健康方案级联删除，见 specs/2026-10-17-health-plan-deletion-design.md）

4.50 活动海报模板（/api/admin/poster-template/* + /api/poster-template/*）

Web 管理端定义活动海报模板（迁移381 activity_poster_templates 表），小程序端活动详情页「生成海报」拉取可用模板渲染画布。管理端接口校验 @RequestAttribute("role")，仅 admin/operator 可访问；templateKey 限定 gradient（渐变）/minimal（深色）/card（白底卡片），name 全局唯一。

端点	权限	用途
POST /api/admin/poster-template/list	admin/operator	模板列表（含停用，按 sort_order + id 升序）
POST /api/admin/poster-template/save	admin/operator	新增/更新（body 为实体字段：id/name/templateKey/mainColor/darkColor/lightColor/bgColors/qrSize/sortOrder/status；id 为空为新增；色板须为合法 JSON 数组，空则按主色生成，qrSize 默认 100）
POST /api/admin/poster-template/delete	admin/operator	删除（body: {id}）
POST /api/poster-template/list	登录	小程序端可用模板（status=1；生成海报场景本身要求登录）

文档更新：2026-10-17（活动海报模板管理，见 specs/2026-10-17-activity-poster-template-design.md）

---

4.50 会员权益对比表（/api/membership/compare）

购买页（pages/membership/upgrade.vue）与会员中心（pages/membership/index.vue）的权益对比表数据源。全部权益值由后端聚合实际逻辑后返回展示文本，前端不再硬编码权益文案，避免出现「文案说不限量 / 实际 20 个」这类偏差。

路径	说明
POST /api/membership/compare	返回 {columns, rows}，无需请求参数

返回值结构

{
  "code": 200,
  "data": {
    "columns": ["FREE", "BASIC", "FAMILY", "PREMIUM"],
    "rows": [
      { "name": "商品价格", "free": "普通价格", "basic": "会员价", "family": "会员价", "premium": "会员价" },
      { "name": "家庭成员上限", "free": "1人", "basic": "3人", "family": "6人", "premium": "10人" },
      { "name": "每日任务上限", "free": "5个/日", "basic": "3个/日", "family": "20个/日", "premium": "50个/日" }
    ]
  }
}

行值口径（事实源）

权益行	数据来源
商品价格	FREE=普通价格，BASIC/FAMILY/PREMIUM 统一=会员价。实际结算由 MemberPriceResolver 取 products.member_price，仅按 products.min_discount_level 判定是否达门槛，不存在按等级递增的额外折扣
家庭成员上限	membership_levels.max_children（0/空视为无该权益 → —）
每日任务上限	membership_levels.max_tasks_per_day
AI健康顾问 / 报告解读 / 测评预约 / 食材图片解析	BasicQuotaService.QUOTA_LIMITS 月度配额常量（BASIC 限次）+ canUseFeature 判定（FAMILY/PREMIUM 不限）
优惠券权益	普通券面向所有登录用户（discount_purchase feature，BASIC 起可用）；会员专享券仅 FAMILY/PREMIUM（CouponService.canUseMemberCoupon）
会员专属活动	member_activities feature，BASIC 及以下为部分活动
邀请佣金 / 消费返佣	referral_commission / purchase_commission feature
专属管家、规划师咨询	membership_levels.priority_support / teacher_consultation 对应的产品权益设定

列口径：仅 FREE/BASIC/FAMILY/PREMIUM 四列。LIFETIME 为赠送/特殊发放、不可购买，不作为列展示；PROVIDER 是服务商角色，不属于会员权益体系（level_order=1 与 FREE 同级，features 为 NULL），不参与本表。 /api/membership/plans 同步变更：除 LIFETIME 外再过滤 PROVIDER，并附加 maxChildren / maxTasksPerDay 两个字段，前端档位卡片可直接引用。

文档更新：2026-10-18（会员权益对比表动态化 + PROVIDER 退出会员权益体系）；2026-11-06（「商品折扣」行改为「商品价格」：FREE=普通价格，其余付费档统一=会员价，去除按等级 9折/8折 的表述）

---

文档最后更新：2026-10-04

---

5.0 减脂专题（/api/fatloss/*）

减脂专题（xiaofat-miniprogram）新增接口，与主系统用户体系共享（JWT 认证，需登录）。 所有接口统一 @PostMapping，响应格式 Result<T>。

端点	权限	说明
POST /api/fatloss/weight/list	登录	体重记录列表（params: memberId/startDate/endDate，memberId 优先取 params，fallback currentMemberId）
POST /api/fatloss/weight/create	登录	创建体重记录（body: memberId/weight/bodyFatPercent/waistCircumference/measureDate/remark）
POST /api/fatloss/weight/update	登录	更新体重记录（body: id/weight/bodyFatPercent/waistCircumference）
POST /api/fatloss/weight/delete	登录	删除体重记录（body: id）
POST /api/fatloss/diet/list	登录	饮食记录列表（params: memberId/startDate/endDate）
POST /api/fatloss/diet/create	登录	创建饮食记录（body: memberId/mealType/foodName/foodWeight/calories/protein/fat/carbs/eatDate/remark）
POST /api/fatloss/diet/delete	登录	删除饮食记录（body: id）
POST /api/fatloss/diet/calories-summary	登录	当日总热量（params: memberId/date，date 默认今日）
POST /api/fatloss/exercise/list	登录	运动记录列表（params: memberId/startDate/endDate）
POST /api/fatloss/exercise/create	登录	创建运动记录（body: memberId/exerciseType/durationMin/distanceKm/caloriesBurned/exerciseDate/remark）
POST /api/fatloss/exercise/delete	登录	删除运动记录（body: id）
POST /api/fatloss/goal/active	登录	获取当前活跃目标（params: memberId，返回最新 status=active 的目标）
POST /api/fatloss/goal/create	登录	创建目标（body: memberId/startWeight/targetWeight/targetBodyFat/targetDate/startDate，targetWeight/startWeight/startDate 必填）
POST /api/fatloss/goal/update	登录	更新目标（body: id/targetWeight/targetBodyFat/targetDate）
POST /api/fatloss/goal/complete	登录	完成目标（body: id，status → completed）
POST /api/fatloss/goal/abandon	登录	放弃目标（body: id，status → abandoned）

新增表： fat_weight_record、fat_diet_record、fat_exercise_record、fat_goal（迁移 355–358，DatabaseInitializer）

文档更新：2026-10-09（减脂专题新增）

---

4.53 限时特价（扫码闪购）

设计规格：specs/2026-10-20-limited-time-special-price-design.md； 新建 special_price_deals 表（迁移 389）+ product_orders.special_deal_id 列（迁移 390）。

用户端（公开接口，无需登录）

路径	说明
POST /api/special-price/info	查询活动详情（白名单，JwtInterceptor 公开路径；userPurchased/userRemaining 恒 0，每人限购由下单接口兜底）

请求体：{ "dealId": 1 } 响应 data 字段：

{
  "id": 1, "productId": 10, "productName": "示例商品",
  "name": "开售闪购", "specialPrice": 500, "productPrice": 990,
  "startTime": "2026-10-20 12:00:00", "endTime": "2026-10-21 12:00:00",
  "totalQuantity": 100, "soldQuantity": 23, "remainingQuantity": 77,
  "perUserLimit": 2, "allowCoupon": 0, "runStatus": "ACTIVE",
  "userPurchased": 0, "userRemaining": 0
}

runStatus 枚举：ACTIVE（进行中）/NOT_STARTED（未开始）/SOLD_OUT（已售罄）/ENDED（已结束）/DISABLED（已停用）/DRAFT（草稿）/INVALID（活动不存在）。白名单路径不写 request attribute，每人限购由下单接口最终校验。

下单（特价路径）

POST /api/product/order/create 请求体新增 specialDealId（Long，可选）。若 specialDealId != null 走特价下单分支：

1. 校验活动存在、status=active、NOW() ∈ [start_time, end_time]、商品一致
2. 每人限购校验（countByDeal 累计 < perUserLimit）
3. allowCoupon=0 且 couponId 非空 → 拒绝
4. 原子扣量 consumeQuota(id, qty)（失败按 runStatus 返回明确原因）
5. insert 订单行 special_deal_id = dealId，unit_price = specialPrice
6. 回滚挂载点：cancel（用户取消）、approveRefund（退款完成）、OrderTimeoutCancelTask（超时取消），三处调用 releaseQuota（GREATEST(sold_quantity - qty, 0) 防负）

供应商改价拒绝：reviewUpdate 开头若 order.specialDealId != null 直接 Result.error("特价订单不允许修改价格")。

管理端（admin 角色）

路径	权限	说明
POST /api/admin/special-price/list	admin	分页列表（body: {page,size,keyword,runStatus}；runStatus 可传 ACTIVE/NOT_STARTED/SOLD_OUT/ENDED 或 draft/disabled，空=全部；响应 data.records[] + data.total）
POST /api/admin/special-price/create	admin	新建（body: {productId,name,specialPrice,startTime,endTime,totalQuantity,perUserLimit,allowCoupon}；specialPrice/productPrice/totalQuantity 单位均为分；同商品互斥 active）
POST /api/admin/special-price/update	admin	修改（body 同 create + id；仅 draft/disabled 可修改）
POST /api/admin/special-price/status	admin	启停（body: {id, action}；action ∈ {enable, disable}；启用时再次校验互斥）
POST /api/admin/special-price/delete	admin	删除（body: {id}；已有特价订单时拒绝）
POST /api/admin/special-price/qrcode	admin	生成小程序码（body: {id}；scene=id={productId}&sp={dealId}，落地页 product-detail；返回 data:{qrCodeBase64, scene, note?}；测试模式 note 提示无法生成真实码）

文档更新：2026-10-20（限时特价/扫码闪购新增）

4.54 活动报名情况（POST /api/activity/registration-roster）

活动详情页「报名情况」区块数据源。面向所有访客（含游客，/api/** 下无需登录），返回脱敏的报名统计与最近已通过报名人，用于社交证明与名额紧迫感展示。姓名经 DataMaskUtil.maskName 脱敏（如"张小明"→"张某"），不返回手机号。

请求体： { "activityId": 1 }（兼容 id）

响应 data 字段：

{
  "activityId": 1,
  "maxParticipants": 50,
  "approvedCount": 12,
  "pendingCount": 3,
  "remaining": 38,
  "registrants": [
    { "name": "张某", "registeredAt": "2026-10-22T10:00:00" }
  ]
}

字段	说明
maxParticipants	人数上限（0 = 不限制）
approvedCount	已通过报名人数
pendingCount	待审核报名人数
remaining	剩余名额 = max - approved（不限制时为 null，下限 0）
registrants	最多 20 条已通过报名人（按报名时间倒序，姓名脱敏）

前端使用：activity-detail.vue 加载详情后并行拉取；报名成功/取消报名后重新拉取。区块仅当 activity.requireRegistration === 1 时展示，含统计列、进度条（限人数时）与最近报名人列表。

文档更新：2026-10-22（活动详情页新增报名情况）

4.55 活动报名/签到/问卷（本次回归补登记）

以下接口在 2026-10-23 的 T15/T16/T17 任务链路中新增或变更，此前未在本文档登记，此处统一补录。

4.55.1 活动报名（ActivityController，前缀 /api/activity）

路径	说明
POST /api/activity/register	活动报名（body: activityId；批量报名历史字段 registrants）。活动 requireReview=1（默认免审）→ 报名记录为 pending 不占名额；免审即 approved 并原子占用名额

4.55.2 活动签到与签到审核（ActivityController）

路径	说明
POST /api/activity/checkin	活动签到（body: activityId）。活动级 requireCheckinReview=1 时签到进入 pending_review，审核通过才发奖励；免审直接发放
POST /api/activity/checkin-review	签到审核（仅活动管理员/平台管理员）。通过发放积分/能量/CF，驳回不发放

4.55.3 管理端签到（AdminActivityCheckinController，前缀 /api/admin/activity-checkins）

路径	说明
POST /api/admin/activity-checkins/list	按活动分页查询签到记录
POST /api/admin/activity-checkins/add	手动补录签到（幂等，桥接触发课时入账）
POST /api/admin/activity-checkins/review	修改签到审核状态（通过发放课时/奖励）

与规划师课时桥接：签到审核通过会触发课时发放，与 AdminPlannerOfflineCourseController 的活动↔类别映射联动（见第五章）。

4.55.4 家庭关系问卷（RelationshipQuestionnaireController，前缀 /api/family/questionnaire）

路径	说明
POST /api/family/questionnaire/generate	AI 生成关系问卷快照（body: memberId；respondentId 由后端按登录用户覆盖，校验调用人与目标成员同家庭），返回题目集与 snapshotId
POST /api/family/questionnaire/submit	提交答卷（body: snapshotId + 答案），写入响应记录
POST /api/family/questionnaire/snapshot/{memberId}	查询某成员当前快照
POST /api/family/questionnaire/history/{memberId}	某成员问卷历史提交记录

4.55.5 报名名册数据口径（2026-10-23 本次回归涉及）

POST /api/activity/registration-roster 的 approvedCount 现直接读 activities.approved_count（迁移回填），不再实时统计；剩余名额 = max - approved，下单/退款链路（register/cancel/OrderTimeoutCancelTask）通过原子 SQL 维护该计数，防超卖。

4.55.6 审核中心统计口径变更（2026-10-23）

ReviewCenterController 的 guidePending / nutritionistPending 统计新增 real_name IS NOT NULL 过滤，与列表接口口径一致（commit f61547a21）；前端 ArticleAudit.vue 驳回原因字段由 row.reason 修正为 row.rejectReason。

文档更新：2026-10-23（T15/T16/T17 回归补登记：活动报名、签到与签到审核、管理端签到、家庭关系问卷、名册口径、审核中心统计口径）

---

4.56 活动管理团队（ActivityTeamController，前缀 /api/activity/team）—— T35

T35 规格 §2.2/§5：新增「活动管理团队」类型，activities.team_id 关联 activity_team；团队成员可协作运营团队名下活动，复用服务指派机制（service_type=ACTIVITY_SUPPORT，见 T34）。团队数据独立于 supply_system（供应体系），避免活动运营人员误入商品分销同体系判定。

权限规则：

• 平台活动角色（admin / activity_admin / activity_manager）可管理全部团队；
• 团队团长/运营主管（owner/manager）可管理本团队；
• 普通在团成员可查看与协作（编辑活动/报名审核/签到等）。

路径	说明
POST /api/activity/team/create	创建活动团队（body: {name, description?}，管理员可指定 ownerId；普通用户以自己 userId 建团，自动成为团长 owner）
POST /api/activity/team/list	我的团队列表（管理员返回全部；普通用户返回在团团队），含 id/name/description/ownerId/status
POST /api/activity/team/detail	团队详情（body: {teamId}），返回 team + members
POST /api/activity/team/member/list	团队成员列表（body: {teamId}）
POST /api/activity/team/member/add	添加成员（body: {teamId, userId, role?}，role 可选：owner/manager/operator，默认 operator；幂等：已在团则更新角色）
POST /api/activity/team/member/remove	移出成员（body: {teamId, userId}，团长不可被移出；移出时级联撤销该成员在团内的 ACTIVITY_SUPPORT 指派）
POST /api/activity/team/assign	服务指派（ACTIVITY_SUPPORT，body: {teamId, targetType, targetId, assigneeId, role, remark?}，targetType: ACTIVITY/ACTIVITY_TEAM，role: lead/support/checkin/content；被指派人须为团队在团成员）
POST /api/activity/team/assign/list	服务指派列表（body: {teamId, targetType?, targetId?}）
POST /api/activity/team/assign/revoke	撤销服务指派（body: {id, teamId?}）
POST /api/activity/team/activities	团队名下活动列表（body: {teamId}）

ActivityController 权限扩展（T35 协作判定）：

• /api/activity/create：团队活动（teamId 非空）须由团队在团成员创建；
• /api/activity/update：团队活动的编辑权限扩展到团队在团成员 + 该活动（或其团队）的 ACTIVITY_SUPPORT 被指派人。

文档更新：2026-11-01（T35 活动管理团队：活动团队创建/成员管理/服务指派、ActivityController 协作权限扩展）

---

4.48 组织管理（机构/企业组织）

平台角色（admin/operator/finance）可管理所有组织并查看全量统计；组织管理员（users.roles 含 org_admin）登录管理端后默认跳转自身组织统计大屏，仅能访问本组织数据。实现方案见规格 docs/superpowers/specs/2026-10-22-org-admin-management-design.md。

数据模型：

• organizations：组织主表（name/type/code/admin_userid/contact*/description/status）
• org_members：组织成员关联表（org_id/user_id/member_type/role_in_org/status），唯一键 (org_id, user_id)

权限规则：

• 平台角色（admin/operator/finance）→ 全量访问
• org_admin → 仅能访问自身组织（organizations.admin_user_id = userId 且 status='active'），返回 403「无权访问该组织」/「组织已停用」
• 组织管理员身份登录复用现有 /api/admin/auth/login 流（AdminRoles.RESIDENT_ROLES 新增 org_admin）

接口列表（13 个，全部 @PostMapping）

路径	说明
/api/admin/org/list	组织列表（分页/筛选；org_admin 只返回自己组织）
/api/admin/org/create	创建组织（同步创建管理员账号；仅平台角色）
/api/admin/org/update	更新组织信息
/api/admin/org/disable	停用/启用组织（仅平台角色）
/api/admin/org/detail	组织详情
/api/admin/org/my-org	组织管理员获取自身组织（登录跳转目标）
/api/admin/org/user/search	按手机号/昵称搜索平台用户（添加成员下拉选人）
/api/admin/org/member/list	成员列表（含家庭数/订单数/消费额摘要）
/api/admin/org/member/add	添加成员（软删成员复活为 active 并更新类型）
/api/admin/org/member/remove	移除成员（软删 status=inactive）
/api/admin/org/member/change-type	变更成员类型（planner ↔ user，复活 inactive）
/api/admin/org/stats/overview	总览卡片（成员/规划师/家庭/订单/消费）
/api/admin/org/stats/families	家庭维度（活跃家庭/任务完成率/打卡率）
/api/admin/org/stats/active	活跃度趋势（任务完成/打卡/报告上传，按天）
/api/admin/org/stats/revenue	营收（订单金额/会员订阅/佣金，按天）
/api/admin/org/stats/trend	趋势图（活跃成员数/订单数/收入，按天）

请求参数： 成员/统计接口统一从 body 取 orgId；stats 可选 startDate/endDate（yyyy-MM-dd，默认近 30 天）。

统计口径：

• 成员范围：org_members 中 status='active' 的 user_id 集合
• 家庭数：families.creator_id IN (成员userId) 去重计数
• 订单：product_orders.buyer_id IN (成员userId) AND status IN ('PAID','COMPLETED')
• 消费：上述订单 total_amount 求和（单位分）
• 打卡：health_checkins.user_id + daily_checkin（经 family_members.user_id 关联）+ emotion_checkin
• 报告：dan_report_uploads.uploader_user_id
• 佣金：commission_records.referrer_id（受益人）commission_amount 求和
• 订阅：member_subscription_order.status='paid'

前端入口： cfc-web 新增 /org 路由四页面（List/Form/Detail/Dashboard）；菜单「组织管理」挂在系统配置分组下。组织管理员登录后自动跳 /org/:id/dashboard，不展示组织列表页。

文档更新：2026-10-22（组织管理功能上线）

---

4.57 成长规划师域（planner-zone，32 SC 契约核对）

契约文档：docs/superpowers/specs/2026-11-07-planner-zone-contract.md（EVD-10，32 个 SC 端点核验表 + 建议能力键映射 + 实现缺口清单） 开工包：docs/tdd/orchestration/planner-zone-kickoff-20261107.md 前置：O-7 契约补建工作流（主理人 2026-11-06 23:59 追认生效）——契约核对 = 文档核对 + 端点比对（防假 RED），产出契约文档后转测试侧（TR-13）补契约 JUnit + 三类流证据，渐进而非全量。 角色：成长规划师（role=teacher）双角色，可登录规划师端，也可切换回家长视角（POST /api/auth/switch-role）。

核对结论：32/32 SC 均有端点载体锚定（29 个完全满足；3 个存在子能力缺口 G-1/G-2/G-3，见契约文档 §4），0 个实现级硬缺失。

SC	场景	端点载体（回填实测）
SC-T-01	规划师登录 + 切回家长	AuthController /api/auth/*（switch-role）
SC-T-02	绑定测试家庭	GuideFamilyQueryController /api/guide/families/my-families；BindInviteController /api/guide/bind；TeacherFamilyBindingController /api/family/teacher-bindings/*（pending/approve/reject/my-requests/cancel）
SC-T-03	代传报告 + 确认入库 ⭐	HealthReportController /api/health/report/proxy-parse、/proxy-confirm（L2775/L2945），/transfer/*
SC-T-04	方案审核列表 + 批准	GuidePlanReviewController /api/guide/families/{familyId}/plans/*（pending/approve/reject/update）；PlanReviewController /api/guide/plans/*（family-list/review/detail）；ReviewCenterController /api/admin/review-center/summary
SC-T-05	激活方案拆任务（幂等）⭐	PlanReviewController POST /api/guide/plans/activate → PlanActivationService.activate（PlannerCertificationGuard 认证闸门 + IllegalStateException 状态守卫）
SC-T-06	家庭任务审核	GuideFamilyTaskController /api/guide/families/{familyId}/tasks/{taskId}/review、/tasks/batch-review、/children/{memberId}/pending-review
SC-T-07	录入测评结果触发方案 ⭐	DanAssessmentController /api/dan-assessment/result/record、/record/create、/record/complete、/report/parse-preview
SC-T-08	成长计划 / 套餐创建	TrainingPlanController /api/guide/training-plans/*（create/update/list/detail/delete）；GrowthPlanController /api/growth/plan/create
SC-T-09	测评预约确认（状态守卫）	AssessmentAppointmentController /api/assessment/appointment/*（create/confirm/{id}/cancel/{id}/my-list/guide-list/assessor-list）；DanAssessmentController /appointment/confirm
SC-T-10	测评预约完成/未到	完成 DanAssessmentController /appointment/complete；未到（status=4）无独立端点 → 缺口 G-1
SC-T-11	DAN 报告上传与解析	DanReportController /api/dan-report/*（upload/{id}/confirm/{id}/discard/{id}/complete-analysis/list/compare）
SC-T-12	DAN 八类报告查看	AssessmentReportController /api/dan-assessment/result/*（plans/list/upload/{resultId}/guidance）；DanAssessmentController /result/{id}/my-results/child-results
SC-T-13	规划师视角数据隔离	授权源 guide_families.status='binding'（GuideFamilyService.isBound）+ JwtInterceptor 角色隔离；GuideFamilyQueryController /my-families、GuideFamilyTaskController /bound-families、PlanReviewController family-list（JWT familyId 过滤）
SC-T-14	方案编辑（规划师侧）	GrowthPlanController /api/growth/plan/update、/create；HealthPlanController /api/health/plan/save、/generate
SC-T-15	套餐任务项管理	TrainingPlanController /api/guide/training-plans/items/*（add/update/delete）
SC-T-16	客户健康总览	GuideFamilyTaskController /{familyId}/overview、/dashboard-stats；GuideFamilyQueryController /my-families
SC-T-17	成长计划进度跟踪	GuideFamilyTaskController /{familyId}/children/{memberId}/tasks；GrowthPlanController /child/{memberId}/active
SC-T-18	批量任务下发	TrainingPlanController /api/guide/training-plans/deploy；PlanReviewController /activate；GuideFamilyTaskController /tasks/batch-review
SC-T-19	消息推送客户	TeacherMessageController /api/guide/messages/*（send/reply/list/unread-count/my）；UserNotificationController /api/notification/*
SC-T-20	退出/切换账号	AuthController /api/auth/switch-role；退出为前端清 JWT（无服务端 logout，观察项）
SC-T-21	报告对比分析	AssessmentComparisonController /api/assessment/compare/*（by-child/by-child-dimension/by-family/narrative）；DanReportController /compare
SC-T-22	方案归档	无 archive 专用端点 → 缺口 G-2（HealthReportController /report/archive 为报告归档参考）
SC-T-23	报告代传（规划师代客户传）⭐	HealthReportController /report/proxy-parse、/proxy-confirm、/report/reassign、/transfer/*
SC-T-24	解绑/重分配客户家庭	GuideFamilyTaskController POST /api/guide/families/unbind（4.45 已登记）；TeacherFamilyBindingController 绑定审批流
SC-T-25	舌诊/情绪测评录入（规划师）⚠	舌诊：HealthReportController /report/parse-preview（type=tongue）+ /report/confirm（type=tongue）+ /report/discard；情绪：EmotionCheckinController /api/mind/checkin/*（create/list/latest/trend/stats/weekly-report/emotion/recognize）
SC-T-26	精准营养方案制定	DietRecommendationController /api/diet/recommendation/*（today/generate/update/regenerate/complete）；HealthReportController /api/health/nutrition/*；NutritionProductController /api/nutrition/product/*
SC-T-27	家庭天盘解读（规划师）⚠	TianpanController /api/tianpan/*（dashboard/member/{memberId}/compatibility/annual-energy/daily-fortune/related-items/recalibrate）；TraditionalMirrorController /api/mind/traditional/*；MindFortuneController /api/mind/fortune/export；AdminFamilyOverviewController /api/admin/families/{id}/overview
SC-T-28	AI 方案内容安全复核	PlanReviewController /review；GuidePlanReviewController approve/reject；ReviewCenterController /summary；ContentFilterController /api/content/*
SC-T-29	客户档案数据导出（合规）⚠	UserController POST /api/user/data-export（个保法可携带权，AccountCleanupService.exportUserData）；AdminOrgMemberController /api/admin/org/member/* 无 export → 缺口 G-3
SC-T-30	测评录入触发五维维度变化	DanAssessmentController /result/record；EnergyController /api/energy/*（overview/logs/grant/score-history/family-score-history）
SC-T-31	手动维度打分覆盖/调整	ManualDimensionScoreController /api/family/manual-score/*（submit/latest/history）
SC-T-32	五维自评录入与变化	FiveDimensionSelfCheckController /api/family/self-check/*（questions/submit/latest/history/status/ignore/generate-plan/trend-analysis/ai-generate-questions）；EnergyController

建议能力键映射（16 键，O-2 方案 A 定稿）：teacher.login.switch（T-01/20）、teacher.family.bind（T-02/24）、teacher.report.proxy（T-03/23）、teacher.plan.review（T-04/28）、teacher.plan.activate（T-05）、teacher.task.review（T-06/18）、teacher.assessment.record（T-07/11/12）、teacher.plan.create（T-08/14）、teacher.appointment.guard（T-09/10）、teacher.data.isolation（T-13）、teacher.family.overview（T-16/17/21/27）、teacher.message.push（T-19）、teacher.mind.record（T-25）、teacher.nutrition.plan（T-26）、teacher.export（T-29）、teacher.dimension.score（T-30/31/32）。已核对与 guide.* / family.parent.* / energy.* 既有键无冲突。

实现缺口（3 项，回传研发侧，见契约文档 §4）：G-1 预约未到（no-show）无独立端点（SC-T-10）；G-2 方案归档无专用端点（SC-T-22）；G-3 管理端/规划师侧客户档案导出缺失（SC-T-29）。

转测试侧：研发负责人登记 TR-13 补契约 JUnit + 三类流执行证据，重点 SC-T-13 数据隔离权限流 / SC-T-05 幂等 / SC-T-09 预约状态守卫（详见契约文档 §5）。

---

五、规划师培训认证（/api/planner/*, /api/admin/planner-*, /api/xiaoe/*）

设计文档：docs/superpowers/specs/2026-10-22-planner-learning-assessment-gate-design.md 核心链路：身份审核通过 → Guide.status=pending_cert + 按类别初始化 planner_certifications → 线上课时（小鹅通 webhook/手动同步）+ 线下课时（activities 打卡桥接）→ 考核通过 → 类别 certified（基础类别 planner 通过时同步翻 Guide.status=active）→ 接单闸门放行。

5.1 规划师端（/api/planner/*）

路径	说明
POST /api/planner/certification/my	我的全部类别认证状态（线上/线下课时拆分、考核分、证书号、是否可考）
POST /api/planner/courses	某类别线上课程列表（含小鹅通跳转/H5 链接；body: categoryCode）
POST /api/planner/training-activities	可报名/签到的培训活动列表（复用 activities，过滤映射表+规划师可见）
POST /api/planner/training-activities/check-in	扫码/手动签到（body: qr_token 或 activityId+admin）→ 桥接发放课时
POST /api/planner/exam/start	开始某类别考核（前置校验课时达标；body: categoryCode）
POST /api/planner/exam/submit	提交判分（body: attemptId+答案，写入 exam_score/exam_passed）
POST /api/planner/exam/result	考核结果

5.2 管理端（/api/admin/*）

路径	说明
POST /api/admin/planner-cert-categories/list	学习种类列表
POST /api/admin/planner-cert-categories/create	创建学习种类（含 required_hours、is_base，首批种子：planner/nutritionist/assessor）
POST /api/admin/planner-cert-categories/update	更新学习种类
POST /api/admin/planner-cert-categories/delete	删除学习种类
POST /api/admin/planner-courses/list	线上课程列表
POST /api/admin/planner-courses/create	创建线上课程（挂类别）
POST /api/admin/planner-courses/update	更新线上课程
POST /api/admin/planner-courses/delete	删除线上课程
POST /api/admin/planner-offline-course-map/list	培训活动↔类别映射列表
POST /api/admin/planner-offline-course-map/create	创建映射（activities 建课后关联类别与计课时）
POST /api/admin/planner-offline-course-map/update	更新映射
POST /api/admin/planner-offline-course-map/delete	删除映射
POST /api/admin/activity-checkins/list	签到记录查询
POST /api/admin/activity-checkins/add	手动补录签到（桥接触发课时入账）
POST /api/admin/activity-checkins/review	签到审核
POST /api/admin/planner-exam/papers	试卷列表（按类别）
POST /api/admin/planner-exam/paper/create	创建试卷
POST /api/admin/planner-exam/paper/update	更新试卷
POST /api/admin/planner-exam/paper/delete	删除试卷
POST /api/admin/planner-exam/questions	题库列表
POST /api/admin/planner-exam/questions/save	保存题目（新建/更新）
POST /api/admin/planner-certifications/list	认证看板（按类别：课时进度、考核分、证书号、有效期）
POST /api/admin/planner-certifications/sync-hours	手动同步线上课时（小鹅通 webhook 兜底，body: userId+categoryCode+课时）
POST /api/admin/planner-certifications/sync-hours/batch	批量同步线上课时
POST /api/admin/planner-certifications/init-by-user	按用户初始化各类别认证记录
POST /api/admin/planner-certifications/backfill	存量补登（迁移401 幂等重跑）

5.3 小鹅通回调（/api/xiaoe/*）

路径	说明
POST /api/xiaoe/webhook	线上学习进度/课程完成事件（签名校验、幂等；课时入账 + 认证记录更新）
POST /api/xiaoe/webhook/test	webhook 联调用测试入口

5.4 接单闸门（PlannerCertificationGuard）

• 中央守卫 assertCertified(userId, categoryCode[, baseRequired])：查询该类别 planner_certifications.status == certified（且 Guide.status == active）方可放行，否则返回 Result.error("规划师未完成【类别名】培训认证，暂不可提供该类服务")（null=放行，非 null=拒绝）。
• 已注入闸门的服务入口（设计 §9 映射表）：

服务动作	入口	所需类别
上架/修改服务套餐	GuideManagementController package/add、package/{packageId}/update	planner
家庭绑定（开始服务）	BindController.accept	planner
激活成长方案（下发任务）	PlanReviewController.activate	planner
咨询响应/接单	TeacherMessageController.reply	planner
订单中心（列表/统计/详情）	GuideOrderController /list、/stats、/detail	planner
测评录入/解读	GuideAssessmentController family/enable	assessor

• 待建设入口（当前代码不存在，预留）：营养方案/饮食建议（nutritionist）。

---

六、CF 值体系统一 · 配置治理接口（F-1 / W0.1）

口径：docs/superpowers/plans/2026-10-24-cf-value-unification-plan.md §3.6.6 / §3.7 W0.1 本批只提供 数据层 + 配置层 接口，发放/扣减接口在 F-2/F-3 批新增。

6.1 服务配置中心（/api/admin/service-config）

唯一配置中心（service_config 表）：CF 通用运营参数（key 前缀 cf.，product_key 为空）+ product 侧配置（product_key 非空，key 形如 product.{productKey}.{key}，W0.2 由 product_config 并入）。保存后自动 CfConfigCache.invalidate()（本地缓存 TTL 60s）+ cf.version 自增。

路径	说明
POST /api/admin/service-config/list	配置列表，body 可选 {"groupKey":"cf.rate","productKey":"gut_health"}，不传返回全部（productKey 为产品维度筛选，W0.2 新增）
POST /api/admin/service-config/save	保存配置（upsert），body {"configKey":"cf.rate.points_multiplier","configValue":"1.0","updatedBy":1}；传 productKey 则写入 product 侧配置（自动加 product.{productKey}. 前缀并回填 product_key，W0.2 新增），可另传 description
POST /api/admin/service-config/invalidate	手动失效 CF 配置缓存（排障用）

已登记配置项：cf.rate.points_multiplier、cf.rate.repeat_rate_default、cf.commission.settle_days、cf.invite.valid_days、cf.price.default_factor、cf.stock.deduction_mode、cf.rate.share_read_reward_points、cf.commission.service_rate、cf.product.gut_health_price、cf.product.platform_points_share、cf.version。

6.2 CF 值获取规则（/api/admin/cf-earn-rule）

24 条规则（F02–F24，F03 拆 F03a/F03b）配置入口；每次保存/开关写 cf_earn_rule_history 并失效配置缓存。

路径	说明
POST /api/admin/cf-earn-rule/list	规则列表，body 可选 {"category":"behavior","enabled":1}
POST /api/admin/cf-earn-rule/save	新建/编辑（按 code 判重），body 含 code/name/category/ruleType/amount/formula/paramsJson/dailyLimitPerMember/totalLimitPerMember/cooldownSeconds/dedupRefType/remark/changedBy/changeReason
POST /api/admin/cf-earn-rule/toggle	启停，body {"code":"F07","enabled":0,"changedBy":1,"changeReason":"..."}
POST /api/admin/cf-earn-rule/history	变更历史，body 可选 {"code":"F07","limit":100}

读取封装：ConfigService.getConfig(key)（缓存 60s → DB → 兜底常量）；product 侧配置读取：ConfigService.getProductConfig(productKey, key)（W0.2）；规则读取：CfEarnRuleService.getByCode(code)。

6.3 产品配置中心（/api/admin/product-config，已废弃 410 Gone）

W0.2 双配置中心合并：product_config 已并入 service_config（唯一配置中心），product 侧配置通过 product_key 关联产品；本控制器写接口统一返回 410 Gone（HTTP 410 + body code=410），保留 30 天只读窗口后由运维删表。

路径	说明
POST /api/admin/product-config/list	【410 Gone】已废弃，改用 POST /api/admin/service-config/list（body 传 productKey 筛选）
POST /api/admin/product-config/save	【410 Gone】已废弃，改用 POST /api/admin/service-config/save（body 传 productKey）

时间线：2026-10-24 起写接口下线（product_config 只读保留 30 天回滚用）；2026-11-23 起确认无回滚需求后删表并移除本控制器。

6.4 F-6 存量账本迁移（迁移417，无新增接口）

启动时由 DatabaseInitializer → CfLegacyLedgerMigrationService 一次性执行，无 REST API。迁移只读旧表、不回写旧表：

来源	目标成员	cf_balance_log.ref_type	ref_id	口径
family_platform_balance	家庭 families.creator_id 对应的 family_members	migration_family_pool	0	available + frozen 合入新 available，withdrawn/exchanged 原样带入
family_members.system_points > 0	当前成员	migration_system_points	family_members.id	system_points 合入新 available
user_platform_balance	该用户本人对应的 family_members	migration_user_wallet	user_platform_balance.id	available + frozen 合入新 available，withdrawn/exchanged 原样带入

幂等键为 (member_id, type='adjust', ref_type, ref_id)（对齐 F-2 迁移416 升级后的唯一键 uk_ref_type）；重复启动按三类 ref_type 逐笔跳过，余额与流水同事务提交。三套旧账本保留为只读历史，写接口 410 Gone 由 F-8 收口。

6.5 F-4 分佣收口 + F03a/F03b 发放接入（迁移418 / 迁移420，无新增接口）

口径：计划 §四 / §3.1 / §4.2 / §4.4。发放链路由 CfCommissionService 统一承载，无新增 REST 接口；/api/commission/cf/rate 返回值扩展两级档位字段（见 4.33）。

迁移内容：

迁移	内容	幂等键
418	cf_direct_sales_tier / cf_indirect_sales_tier 各补 5 档种子（青铜/白银/黄金/铂金/钻石，缺行才补、不覆盖）+ cf_earn_rule.dedup_ref_type 对齐为规则编码（F03a→'F03a'、F03b→'F03b'）	按 min_annual_ppoints / min_self_ppoints 判重；UPDATE 带 WHERE dedup_ref_type <> code
420	新建 ppoint_consumption_log（滚动一年档位聚合数据源：消费支付成功落一行，created_at >= now()-365d 聚合）。注：迁移419 已被 membership_levels.max_daily_analyze 占用，本表顺延为 420	UNIQUE uk_order (order_type, order_id) 同一订单重复触发只记一行

发放链路（CfCommissionService.settle / settleReferrerOnly）：

本单 P 点基数（商品: 元×有效P点/100；非商品: 元×service_rate bps/10000）
  → 落 ppoint_consumption_log（幂等）
  → referral_tree 按 level 升序上溯，跳过同家庭（D5）
  → 第1个非同家庭引荐人 → getTeamAnnualPpoints(referrerId, 8) → matchDirectSalesTier → F03a
  → 第2个非同家庭引荐人 → getSelfAnnualPpoints(referrerId)      → matchIndirectSalesTier → F03b
  → cfBalanceService.earnByRule(memberId, "F03a"/"F03b", orderId, {base_ppoints, rate_percent})
      （公式 floor(base_ppoints*rate_percent/100)，幂等键复用 F-2 uk_ref_type，只写 cf_balance + cf_balance_log）
  → F03a 且非幂等命中时 autoCreateGratitudeEffect（感恩记录）

• 数量与比例零硬编码：比例来自档位表，上限来自 cf_earn_rule.params_json.max_rate_percent，金额由公式计算。
• 与 F-3a 共存：CfCommissionService 同时承载两条链路 —— 当前消费人 F02（CfEarnDispatchService.earnConsumeCf，按实付金额，商品订单实付与分润基数分离）与推荐人 F03a/F03b（本节）；两条链路都只写 cf_balance + cf_balance_log，cf_transfer_record 不再由本服务写入。
• 旧分佣写接口 CommissionDistService.distribute 已废弃：抛 IllegalStateException（消息含 "410 Gone"，经 GlobalExceptionHandler 转 Result.error(400, ...)），无调用方；commission_dist_log 转只读历史表，管理端读取接口（/api/admin/commission-dist/*）保留不变。
• cf_rate_tier 表保留只读，仅供等级展示（PromotionTierService / 管理端档位配置）使用。

文档更新：2026-10-24（CF 值体系统一 F-1 数据层 + W0.1 配置归口：8 张新表/迁移407-412 + service_config 与 cf_earn_rule 管理端接口）；同日补登 W0.2 双配置中心合并（service_config 收编 product_config：迁移413 + product_key 维度 + product-config 接口 410 Gone + 配置中心统一入口）；同日补登 F-6 存量迁移（迁移417 + 三套旧账本幂等迁入 cf_balance）；2026-10-25 补登 F-4 分佣收口（迁移418/420 + 两级销售奖档位 + /rate 扩展字段 + CommissionDistService.distribute 410 Gone）

6.6 C 端 CF 查询接口（F-7a，只读）

口径：计划 §七 F-7a。个人 CF 值账本为成员维度（family_members.id），登录 userId → memberId 解析与 CfEarnDispatchService.resolveMemberId（F-3a）口径一致：user_id 匹配 + 按 id 升序 LIMIT 1；未找到对应家庭成员时返回 Result.error(404, "未找到当前用户对应的家庭成员，...")，不返回空数据。

控制器：CfBalanceController，前缀 /api/cf（GET，需登录；注：本项目接口惯例为 POST，本组 只读接口按 F-7a 任务要求采用 GET，若团队统一要求 POST 可一行改回）。

路径	说明
GET /api/cf/balance	我的 CF 值快照。按登录用户解析 memberId 后读 cf_balance，返回 CfBalanceView：memberId / available(可用) / frozen(冻结) / totalEarned(累计获得) / totalWithdrawn(已提现) / exchanged(已兑换消费)。无 cf_balance 记录时返回全 0
GET /api/cf/logs?page=1&size=20	我的 CF 流水分页（时间倒序），复用 CfBalanceService.getLogs(memberId, page, size)，输出转 CfBalanceLogVO：id / type(earn/spend/freeze/unfreeze/withdraw/adjust/skip) / refType(规则编码或迁移标识) / amount(带符号变动) / balanceAfter(变动后可用余额) / remark / createdAt(ISO 8601)。返回 MyBatis-Plus Page 结构（current/size/total/pages/records）
GET /api/cf/family-coupons	家庭共享优惠券列表（N3 口径）。复用 CouponService.listMyCoupons(userId)：按登录用户所属家庭查 family_coupon + coupon 联合数据（券家庭化全链路已切换至 family_coupon，user_coupon 为只读历史表），返回 userCouponId / couponId / name(券名) / type / value(面额,分) / discountRate / minSpend / applicableTo / status(AVAILABLE/USED/EXPIRED/DISABLED) / validFrom / validUntil(有效期) / receivedAt / usedAt / orderId / productId，家庭内成员共享可见

• 实现走统一账本 CfBalanceService / CouponService，本控制器不直接写库、不提供任何写接口。
• 流水/余额响应结构单测：cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceControllerTest.java（memberId 解析命中/未命中 + balance/logs 字段映射）。

4.56 管理端-素材库（/api/admin/file-record/*）

控制器：FileRecordController（controller/admin/FileRecordController.java），前缀 /api/admin/file-record。 服务层：FileRecordService；文件存储复用 StorageService.storeFileRecord(MultipartFile, category) （JdCloudStorageService / LocalDiskStorageService 实现），统一写入 file_record 并推导 file_type。 权限：全部 @PostMapping，控制器内 @RequestAttribute("role") == "admin" 守卫（无 token 时为 anonymous，直接拒绝）。 数据表：file_record（唯一键 uk_hash 去重）、file_tag（uk_name）、file_tag_rel（uk_file_tag），均为既有表，无新增迁移。

file_type 口径（与 util/FileTypeResolver.java 一致）：

file_type	判定
image	content_type LIKE 'image/%'
video	content_type LIKE 'video/%'
audio	content_type LIKE 'audio/%'
document	content_type LIKE 'text/%' 或 PDF/Office/RTF/ODF 白名单
other	其它（含 application/octet-stream、content_type 缺失）

写入侧（新数据）：content_type 缺失或为 application/octet-stream 时按扩展名兜底；历史回填见 docs/migrations/20261025_asset_library_file_type_backfill.sql（严格按 content_type 分类，不用扩展名兜底）。

接口清单：

路径	说明
POST /api/admin/file-record/list	分页检索。Body：{ page, pageSize, category, fileType, search, dateFrom, dateTo, tagIds }；tagIds 为数组或逗号分隔字符串，前置过滤（先按标签 JOIN 过滤再分页，保证 total 正确）。返回 { records, total, page, pageSize }，records 元素含 id/hash/url/fileSize/contentType/originalFilename/category/fileType/description/createdAt/updatedAt/tags
POST /api/admin/file-record/upload	统一上传入库。multipart 字段：file（必填）、category（选填，默认 general）、tagIds（选填，数组或逗号分隔）。存储 → 写 file_record（SHA-256 去重，命中返回既有记录并补打本次标签）→ 关联标签。图片（contentType 以 image 开头）先过微信内容安全检测（WechatServiceInterface.checkImage，fail-open，与旧 AdminArticleController#uploadImage 保持一致）。返回素材记录 map
POST /api/admin/file-record/update	更新描述/标签。Body：{ id, description?, tagIds? }；tagIds 传空数组表示清空标签，不传表示不改动
POST /api/admin/file-record/delete	删除素材。Body：{ id }；先删 OSS 文件（失败仅告警）再删记录及其标签关联
POST /api/admin/file-record/tags	标签字典列表（按 sortOrder 排序）
POST /api/admin/file-record/tag/create	新建标签。Body：{ name, color?, sortOrder? }，name 唯一
POST /api/admin/file-record/tag/update	更新标签。Body：{ id, name?, color?, sortOrder? }
POST /api/admin/file-record/tag/delete	删除标签。Body：{ id }（级联清理 file_tag_rel）
POST /api/admin/file-record/stats	统计。返回 { total, totalBytes, byFileType: [{file_type, cnt}], byCategory: [{category, cnt}] }

上传响应示例（data 为素材记录）：

{
  "id": 1024,
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "url": "https://bucket.endpoint/uploads/general/xxx.png",
  "fileSize": 102400,
  "contentType": "image/png",
  "originalFilename": "cover.png",
  "category": "articles",
  "fileType": "image",
  "description": null,
  "createdAt": "2026-10-25T12:00:00",
  "updatedAt": "2026-10-25T12:00:00",
  "tags": []
}

前端配套： cfc-web/src/utils/asset.js（API 封装 + resolveAssetUrl）、cfc-web/src/components/AssetPicker.vue（素材选择弹窗，image/video/document 三类）、cfc-web/src/views/admin/AssetLibrary.vue（素材库管理页，路由 /admin/asset-library）、cfc-web/src/utils/editorAssetUpload.js（wangEditor 上传配置公共封装，端点统一指向本组 upload）。

上传点接入范围与跳过说明（cfc-web/src 全量 el-upload 排查结果）：

页面	处理
ArticleEdit / ActivityEdit / ProductEdit	接入：富文本 MENU_CONF.uploadImage/uploadVideo.server 改指本组 upload（fieldName=file + Bearer），customInsert 统一 resolveAssetUrl；新增「从素材库选择图片/视频」按钮
HomeBannerManage / ProductSkuEditor / GuidePackages	接入：封面上传改指本组 upload，并加「从素材库选择」
KnowledgeDialog	接入：文档可从素材库选取（assetType=document），原有的本地知识文件上传通道保留不变
Activities / ArticleManage / SupplierProductManage	跳过：仅列表展示页，无上传控件
RecommendationRules / IndicatorMappings	跳过：无文件上传控件（后者为文本批量导入）
ProxyReportUpload / teacher/ProxyReport / ReportParserImport / ReportCollectorTrainer / ReportUnknownCluster / teacher/GrowthRecords	跳过：业务报告/JSON 解析包上传，走报告解析专用端点（/api/admin/report-parser/* 等），非 jdcloud 媒体资产，纳入素材库会污染 file_record 分类语义
ReportTemplateManage	跳过：仅表单 tab，无图片字段

旧端点 POST /api/admin/articles/upload/image|video 保留可用（兼容既有调用方），但后台页面已统一改走素材库 upload，以便自动入库与打标签。

存量回填： docs/migrations/20261025_asset_library_file_type_backfill.sql（备份 → 按 content_type 回填 file_type → 修正列注释 → 校验），不占用 DatabaseInitializer 迁移编号（407-421 为 CF 体系保留）。

文档更新：2026-10-25（后台素材库：/api/admin/file-record/ 上传入库 + 标签字典 + 统计；file_type 口径统一为 image/video/audio/document/other）*

---

4.49 家庭归因核心闭环（/api/attribution/* + /api/survey/attribution/*）

阶段二（ATT-S2，B1–B4）：「归因分析 → 条件问卷 → 自然语言调整 → 七章干预方案」。 E12 合规后置：全流程由 app.attribution.enabled（默认 false）开关控制，仅测试/mock 数据环境开启； 真实用户放行 = 阶段四 D1 完成日。未开启时返回 Result.error(4001, …)。 合规即服务：红线 RL01–RL10 由规则层硬注入，AI 只产叙述/调整，不负责合规判定（§1.3）。

POST /api/attribution/analyze — ③ 归因分析（十节结构报告）

• Body：{ familyId?, memberIds[], gutReportIds[], danResultIds[], confirmSurveyRecordId?, planId?, mock?, mockFlags? } （mockFlags 仅 E12 测试环境，可显式注入中间态键）
• Resp data：AttributionReportVO { id, familyId, status, reportJson, intermediateState, redlineHits, conclusionLocked, createdAt }
  • reportJson：十节结构（一结论先行/二四人数据速览/三逐人归因/四家庭系统归因/五应对方案/六12周可检验目标/七教练提问序列/八问诊清单/九红线与转介/十一句话收尾）
  • intermediateState：含 l.reuteriAbnormal/ironLow/hasDan/isFemaleTeen/hasDiabetes 等键（B1 中间态）
  • redlineHits：RL01–RL08（阶段③④注入）；RL09/RL10 属方案阶段⑤
  • 状态流转：ANALYZING（插入）→ READY（回填报告后更新）
• 前置：常模缺失指标 → 「待补」，不猜值（warnings 携带说明）

POST /api/survey/attribution/confirm-questions — ② 条件问卷路由

• Body：{ familyId, memberId, attributionId, answeredSummary? }
• Resp data：ConfirmQuestionVO { templateId, questions[], hasHighRisk, highRiskQuestionIds }
  • questions[]：按 对象×年龄×结论 条件下发 family_attribution 模板子集（16 条中）
  • 对象级题目只下发给该对象；家庭级（四人/全家）恒发
  • Q11–Q13 携带 riskLevel=high；命中 → hasHighRisk=true（E4 弱提示，不阻断）

POST /api/survey/submit — ② 提交（B2 扩展：riskHits）

• Body：{ userId, memberId, templateId, answersJson, periodStart?, periodEnd?, riskHits? }
  • riskHits（Q11/Q12/Q13 命中标记）并入 answersJson._attributionRiskHits 落库，供 B1 红线检测
  • E4：高风险命中不阻断提交，仅标记「建议专业评估」

POST /api/attribution/adjust — ④ 自然语言调整

• Body：{ attributionId, message, conversationId? }
• Resp data：AdjustResult { attributionId, status, answer, fieldDeltas, intermediateState, redlineHits, redlineTerminate, blocking, referral, planInvalidated }
  • AI 回答可携带 [ATTR_DELTA]{"键":新值} 结构化增量 → 回填 intermediate_state（七层 Socratic，PRD §C ④）
  • RL02 命中 → redlineTerminate=true、blocking=false（E4 弱提示不阻断）、referral 露出转介信息 + 家长确认
  • 若已关联方案且 status=GENERATED → 作废为 INVALIDATED（⑤ 失效重生成）
  • AI 不可用 → 规则兜底话术，流程不阻断

POST /api/attribution/confirm-adjust — ④ 确认调整

• Body：{ attributionId }
• Resp data：AdjustResult { status=CONFIRMED, conclusionLocked=true }（结论锁定，B4 前置条件）

POST /api/attribution/plan — ⑤ 七章干预方案

• Body：{ attributionId }
• 前置：归因结论须 CONFIRMED（否则 Result.error(4000, …)）
• Resp data：FamilyPlanVO { planId, planJson, totalDays, status }
  • planJson：header + 7 章（数据速览/主线产品/分人方案/家庭共享/12周节奏/红线与转介/附录）
  • 人范围：仅 妈妈/女儿/儿子（E6，爸爸链外）；每动作带 level(P0/P1/daily/P2) + reviewHook（复盘钩子）
  • 儿童补剂动作仅写「医生定」，无剂量数字（RL03）；产品品牌级（Enagic 还原水/姜黄、PHGG、菌株名）且带 RL05 合规口径
  • 落库 health_plans，plan_type=family_attribution_plan，status=GENERATED（⑤）

文档更新：2026-10-28（家庭归因核心闭环 B1–B4：/api/attribution/analyze、/api/attribution/adjust、/api/attribution/confirm-adjust、/api/attribution/plan、/api/survey/attribution/confirm-questions；/api/survey/submit 扩展 riskHits）

---

4.57 家庭指标聚合方式配置 + 珍珠图/章鱼图家庭汇集

五维能量页（身/智/富/行/心）三视角：① 个人看自己各维度；② 家庭管理员看家庭成员各维度；③ 看整个家庭各维度汇总。 家庭各维度汇总方式可配置：SUM=合计 / AVG=平均 / COLLECT=汇集（如行页面珍珠图、章鱼图）。 配置作用域 = 平台级全局一份（family_metric_agg_config 表，按数据项一行一条，迁移433）。 默认五维 AVG 保持既有页面数值表现不变（向后兼容）；SUM/COLLECT 由后台配置页调整即生效。

数据表 family_metric_agg_config：

字段	说明
metric_key (UNIQUE)	数据项唯一标识：energy.body/energy.mind/energy.wisdom/energy.action/energy.wealth/energy.overall/pearl.resources/octopus.effects
metric_name	中文名
dimension_code	所属维度：body/mind/wisdom/action/wealth/common
agg_type	SUM=合计 / AVG=平均 / COLLECT=汇集
value_type	NUMBER（数值）/ COLLECTION（集合）
display_mode	number/bar/radar/merge_graph
sort_order / status / remark	排序 / active

配置 CRUD（/api/admin/family-metric-agg/*，供 cfc-web 管理端，admin 角色守卫）：

路径	说明
POST /api/admin/family-metric-agg/list	全量配置列表（配置项 < 50，无需分页）。返回 [ { id, metricKey, metricName, dimensionCode, aggType, valueType, displayMode, sortOrder, status, remark } ]
POST /api/admin/family-metric-agg/save	新增/更新（body 带 id 则更新，否则新增）。Body：{ id?, metricKey, metricName, dimensionCode, aggType, valueType, displayMode?, sortOrder?, status?, remark? } → true
POST /api/admin/family-metric-agg/delete	Body { id } → true
POST /api/admin/family-metric-agg/update-status	Body { id, status } → true

家庭汇集数据（供小程序行页面，全 POST）：

路径	说明
POST /api/pearl/family/resources	珍珠图家庭汇集。data：{ members: [ { memberId, memberName, memberType, colorKey, items: [原珍珠资源项结构 + groupType/groupTypeName/ring] } ] }
POST /api/octopus/effect/family/list	章鱼图家庭汇集。data：{ members: [ { memberId, memberName, memberType, colorKey, effects: [原章鱼成效项结构] } ] }

• memberType：user（家庭主账号，memberId=users.id）/ member（家庭成员，memberId=family_members.id）
• colorKey：稳定色值键（0..n-1 索引，同一成员前后一致），供前端按成员着色
• 成员收集与 EnergyService.doCalculateFamilyEnergy 一致（家庭主账号 role=parent + getActualChildren 去重）；个人数据查询复用既有逻辑（ResourceService.getPearlResources / KeyPersonService.listEffects），不重写业务规则

五维聚合改造（EnergyService.doCalculateFamilyEnergy 第 4 步）：按 metric_key（energy.body…）查配置取 agg_type：

• AVG → 既有平均逻辑（默认，行为不变）
• SUM → 合计（sum，不再除以 count）
• COLLECT → 数值维度不适用，回落 AVG + 日志记录
• 读不到配置 → 回落 AVG（保证兼容）

文档更新：2026-10-31（家庭数据汇总方式配置（后端）：family_metric_agg_config 表 + 配置 CRUD 4 接口 + 珍珠图/章鱼图家庭汇集 2 接口 + 五维聚合读配置）

---

4.58 供应商团队邀请（/api/admin/supply-team/*）—— T38

需求来源：廖总 2026-11-02「在我的团队加一个邀请功能，邀请其他用户加入团队」。规格：docs/superpowers/specs/2026-11-01-team-system-design.md §3.5 / §4.2 / §4.3（任务 T38）。

语义：团队成员 = 邀请加入（与 referral_tree 推广返佣是两套独立模型，不在此范围）。凭邀请码加入者成为团队成员（非客户），且以邀请人为上级（supply_hierarchy.parent_id=邀请人，level=父级level+1）→ 成员子树 = 该成员自己的团队，与 §0.5「唯一负责人整体结算、平台不拆分」口径一致。

数据模型：supply_system_member 扩列 invite_code VARCHAR(50)（个人专属邀请码，迁移444 幂等 ensureColumn + 唯一索引 uk_supply_member_invite_code；schema.sql 已同步）。

接口列表（3 个，全部 @PostMapping）

路径	说明
POST /api/admin/supply-team/invite-code	生成/获取我的邀请码（幂等）。body：{ systemId, refresh? }；refresh=true 重置旧码（旧码立即失效）。返回 { inviteCode, systemId, teamName, shareText }。越权防护：须为该体系的 admin/active 成员
POST /api/admin/supply-team/invite/info	邀请码信息（确认页展示）。body：{ inviteCode } → { systemId, teamName, inviterId, inviterNickname, inviterAvatar, memberCount, active }。仅展示团队名/邀请人昵称头像/成员数，不泄露其他隐私
POST /api/admin/supply-team/invite/join	凭邀请码加入团队（挂邀请人为上级）。body：{ inviteCode } → 加入后的团队/邀请人信息（同 invite/info 结构）

边界规则

• 同一 (systemId, userId) 仅加入一次：已 active 加入 → 报错「您已在该团队中，无需重复加入」；被移除（status=inactive）→ 可再次申请（自动恢复 active）。
• 自助加入即生效（默认口径），团队负责人可随时移除；role=member 不可自助变更（沿用 member/change-role 管理员权限）。
• 邀请码永久有效 + 唯一（唯一索引兜底）；refresh 可重置为新码。
• 邀请不与资金/佣金直接挂钩：结算走唯一负责人口径（§0.5），平台不拆分团队内部分配。
• 团队 status != active 时不可生成邀请码、不可加入。

前端

• cfc-frontend/pages/vendor/team-system/team-system.vue：团队成员区新增「邀请成员」按钮 → 弹窗（邀请码 + 复制 + 刷新重置；小程序码可后置）。
• cfc-frontend/pages/vendor/team-invite/team-invite.vue（新增，已注册 pages.json）：受邀确认页——展示邀请人/团队 → 点「加入团队」→ 成功态 → 跳转「我的团队」；支持 ?code=XXX 带参进入，也可手动输入邀请码。
• cfc-frontend/utils/api.js：getVendorInviteCode / getVendorInviteInfo / joinVendorTeamByInvite（各 URL 唯一规范入口）。

文档更新：2026-11-02（T38 团队邀请功能：supply_system_member 扩 invite_code + 邀请码生成/信息/凭码加入 3 接口 + 前端邀请入口与受邀确认页）

---

4.59 报告闭环批次契约补写（B-2，2026-11-06 开工包核对）

来源：docs/tdd/orchestration/report-closedloop-kickoff-20261106.md（23 SC → 19 能力键）。 本批为契约核对补全：对照 origin/cfclub 实际 Controller 源码（git show origin/cfclub:<路径>）， 将开工包「契约接口范围」映射到实际已存在端点，补齐 API_REFERENCE 缺失条目。 统一 @PostMapping、响应 Result<T>、JWT 鉴权（JwtInterceptor 拦截 /api/**）。 未实现端点（/api/search/global、/api/provider/report-parse/connect、/api/health/report/{compare,trend,diet,share,refresh-dim}） 见 4.59.10 契约缺口。

4.59.1 管理端-报告解析进度 / 解析中台（SC-A-02 admin.reportParse.typeList）

Controller：ReportParseAdminController（/api/admin/report-parse）+ ReportParserAdminController（/api/admin/report-parser）。 鉴权：JwtInterceptor 对 /api/** 统一拦截；管理员角色校验在 JwtInterceptor 之后（admin 登录态）。

路径	请求	响应 data	说明
POST /api/admin/report-parse/list	{page=1, size=20, parseStatus?, reportType?, keyword?}（keyword 匹配 originalFilename/userId）	{total, records[]}；records 元素：draftId/userId/reportType/originalFilename/fileHash/parseStatus/parseMethod/parseError/parseAttempt/nextRetryAt/parseStartedAt/parseFinishedAt/collectValidation/draftStatus/confirmedReportId/createdAt/updatedAt	草稿解析进度分页查询（按 updatedAt 倒序）
POST /api/admin/report-parse/retry	{draftId}	{draftId, parseStatus:"collecting"}	手动重试：重置解析进度（resetForManualRetry）并重新提交异步采集（submitAsyncCollect）
POST /api/admin/report-parse/backfill-food	{reportId}	{reportId, foodCount}；失败返回 Result.error(e.getMessage())	食材回填：重新解析报告并覆盖写入 foods（失败保留旧载荷）；IllegalArgumentException/IllegalStateException 转错误
POST /api/admin/report-parser/dan/reparse	{uploadId, dimension}（均必填）	danReportUploadService.reparseUpload(...) 结果	DAN 报告按维度重新解析（ReportParserAdminController）

ReportParserAdminController 其余端点（types/types/save/types/toggle/types/delete/fingerprints/list/fingerprints/save/fingerprints/delete/imports/imports/import/imports/approve/imports/reject/unknown-clusters/unknown-uploads/generate-type）已在 4.30 登记。

4.59.2 健康报告全链路契约（SC-C-06 health.report.view / SC-X-02 health.report.closedLoop）

Controller：HealthReportController（前缀 /api/health）。报告归属由 health_reports.subject_id（family_members.id，可 null）表示； 无归属报告不参与方案生成。成员级查看权限（管理员 / 本人 / 被授权成员）在 list/detail/payload 逐接口校验。 两阶段入库：Phase 1 上传建草稿（/upload-only 或 /report/parse）→ Phase 2 确认入库（/report/confirm）。

路径	请求	响应 data	说明
POST /api/health/report/create	body：{memberId?, reportType, overallScore?, gutHealthScore?, chronicDiseaseScore?, nutritionScore?, gutAge?, gutType?, gutBalanceScore?, gutDiversityScore?, beneficialBacteriaScore?, harmfulBacteriaScore?, ...}（reportType 必填：physical_exam/gut_flora）	HealthReport（含 id）	创建健康报告（含指标明细）。付费墙：未购买「健康启航计划」返回 code=4001「请先购买健康启航计划体验包」；memberId 缺省取 currentMemberId
POST /api/health/report/latest	{memberId?}（缺省 currentMemberId）	HealthReport（无则 null）	获取成员最新健康报告
POST /api/health/report/list	{memberId?, page?, size?}	page 未传 → List<HealthReport>（兼容小程序）；page 传 → 分页结构 {total, records[]}	报告列表。未传 memberId 返回当前家庭全部报告（按 visibleIdentityIds 权限过滤；管理员全部可见）；传 memberId 且无查看权限 → 空列表
POST /api/health/report/detail	{reportId}	Map：报告详情（含指标明细 + 菌群数据 + 疾病风险评估）	完整详情；权限校验（本人/管理员/被授权成员），无权返回「无权查看该报告」
POST /api/health/report/payload	{reportId}	Map：报告 payload（编辑回填用，按需加载）	同 detail 权限校验
POST /api/health/report/edit	{reportId, subjectId?, payload}	"已更新"	编辑已发布报告（修正 AI 解析错误值）；subjectId 可 null 表示解绑，变更时重算旧/新成员维度分
POST /api/health/report/delete	{reportId}	"已删除"	删除报告
POST /api/health/report/download	{reportId}	{fileUrl, fileName}（本地相对路径 /uploads/** 自动拼当前域名）	报告文件下载信息（供 uni.downloadFile）
POST /api/health/report/upload	multipart file（仅 PDF）	兼容接口：自动执行「解析→确认」两阶段（内部 pdfParseService.parse）	向后兼容旧调用；新链路走 /upload-only + /report/parse + /report/confirm
POST /api/health/report/parse	{draftId}	解析结果（draftId/payload/matchedMemberId/extracted/needBind 等）	Phase 1 按草稿 ID 触发解析：LangGraph 优先（/api/v1/report/parse），失败回退本地 Java 解析
POST /api/health/report/confirm	{type="pdf", draftId, subjectId?, payload?}；type=tongue 时 {recordId, subjectId?, indicators?}	{reportId, ...}	Phase 2 确认草稿入库：写正式表 → 归一化指标管道 → 绑定成员 → 刷新 7 维评分/指标当前值/食材推荐 → 自动生成方案（非 tongue 类型）。payload 可回传修改后指标（用户在线编辑后整体提交）
POST /api/health/report/discard	{type="pdf", draftId}；type=tongue 时 {recordId}	"草稿已放弃"	放弃草稿（仅草稿创建者本人）
POST /api/health/report/archive	{reportId}	"报告已归档"	归档报告（软删除）
POST /api/health/report/archive-batch	{reportIds:[Long]}	"已归档 N 份报告"	批量归档（管理端选中删除）
POST /api/health/report/audit/pending	{page=1, size=20}	List<HealthReportDraft>	管理端：待审核报告草稿列表
POST /api/health/report/audit/confirm	{draftId, subjectId?}	{reportId, subjectId, ...}	管理端：审核确认入库。B2-3：平台角色（admin/AdminRoles）可确认任意草稿，非平台角色仅确认自己创建草稿；确认后刷新食材推荐
POST /api/health/report/audit/discard	{draftId}	"报告已丢弃"	管理端：审核丢弃

报告归属（reassign/unlinked/bind）见 4.36.1；报告跨家庭转移（transfer/request、approve、deny、list）为本链路的跨家庭归属场景，已实现（reportTransferService），契约随 4.36.1 口径（{reportId} → {requestId, status}）。

4.59.3 报告代传闭环（SC-P-67 / SC-T-03 / SC-T-23 health.report.proxyUpload / SC-X-13 health.report.proxyClosedLoop）

开工包建议路径 /api/health/report/proxy-upload，实际实现为两阶段：/api/health/report/proxy-parse（预览，仅解析不入库）+ /api/health/report/proxy-confirm（确认入库）。 Controller：HealthReportController。

路径	请求	响应 data	说明
POST /api/health/report/proxy-parse	multipart/query：file（新上传）或 fileUrl（草稿过期后基于原文件重新解析，B3-2 降级），familyId（必填），subjectId?，reportType=auto（空/auto→gut_flora），note?	预览结果：{draftId, payload, matchedMemberId, extracted*, needBind, fileUrl, proxyUploaderId, proxyUploadNote, reparse, parseMethod("langgraph"/"local"), parseFallback}	代上传报告（预览模式）。权限三层校验：① isProxyUploader（admin/teacher/approved 营养师/approved 规划师，否则 code=500「无权限代上传报告…」）② canProxyForFamily（B2-2，非平台角色须 familyId ∈ 有效家庭集，否则「无权为该家庭代传报告」，不建草稿不写文件）③ FamilyAccessInterceptor 兜底（HTTP 403 {"code":403,"message":"无权访问该家庭数据"}）。建草稿拿 draftId → LangGraph 解析（失败回退本地 Java，parseFallback=true/parseMethod="local"）
POST /api/health/report/proxy-confirm	{draftId, subjectId?}	{reportId, subjectId, aiAnalysis?, aiAnalysisStatus("success"/reason), aiAnalysisMessage?}	代确认报告（入库）。B2-3：仅草稿创建者本人或平台角色可确认（auditConfirm(draftId, subjectId, userId, isAdmin)）；确认后写入 health_reports.proxy_uploader_id/proxy_upload_note（取草稿 remark）→ 刷新食材推荐 → 触发 AI 解读（T29-B1-5：失败不静默吞错，aiAnalysisStatus/aiAnalysisMessage 回传）

代传与自传共用同一「归属校验」口径：subjectId 绑定成员 + health_reports.subject_id 落库，跨角色闭环（家长/规划师代传 → 归属校验 → 确认入库）经 proxy-parse/proxy-confirm 完成，无独立 proxy-upload 端点。

4.59.4 报告查看权限 / 分享（SC-P-84 health.report.share）

开工包建议路径 /api/health/report/share，实际实现为「报告成员级权限管理」（ReportMemberPermissionController + HealthReportController /report/permission/*）+ 通用内容分享（ShareController /api/share）。

4.59.4.1 报告查看权限（/api/health/report/member-permission/*）

路径	请求	响应 data	说明
POST /api/health/report/member-permission/list	无 body	List<Map>：家庭全部授权记录	家庭管理员操作；IllegalArgumentException 转 Result.error
POST /api/health/report/member-permission/members/{memberId}	path memberId	List<Long>：已授权用户 ID 列表	查询某成员的已授权用户
POST /api/health/report/member-permission/grant	{targetMemberId, granteeUserId}	Boolean	授权：让指定用户可查看某成员的报告
POST /api/health/report/member-permission/revoke	{targetMemberId, granteeUserId}	Boolean	撤销授权
POST /api/health/report/member-permission/visible-members	无 body	Set<Long>（null=管理员全部可见）	查询用户可见的成员 ID 集合

4.59.4.2 报告级权限（HealthReportController /report/permission/*）

路径	请求	响应 data	说明
POST /api/health/report/permission/add	{reportId, userId}	"权限添加成功"	添加报告查看权限（授权家庭成员查看该报告）
POST /api/health/report/permission/remove	{reportId, userId}	"权限移除成功"	移除报告查看权限
POST /api/health/report/permission/check	{reportId, userId}	Boolean	检查用户是否有该报告查看权限

4.59.4.3 通用内容分享（ShareController /api/share）

路径	请求	响应 data	说明
POST /api/share/create	{targetType, targetId, shareChannel="wechat", title=""}（需登录）	ShareEvent	创建分享记录（报告/方案/文章/商品统一入口，targetType 区分）
POST /api/share/click	{shareEventId}	null	记录分享点击
POST /api/share/read	{shareEventId, duration=0}	{rewarded:Boolean}	记录分享阅读；首次阅读且登录 → 发放阅读奖励积分
POST /api/share/my	无 body（需登录）	List<ShareEvent>（最多 50 条）	我的分享记录
POST /api/share/stats	无 body（需登录）	Map：分享统计	分享统计
POST /api/share/family-footprint	无 body（familyId 由 JWT 注入）	Map：家庭健康足迹	P3 分享页：家庭健康足迹
POST /api/share/qrcode	{page, scene?}（scene ≤32 字符，需登录）	{qrCodeBase64:"data:image/png;base64,..."}	生成分享小程序码（商品/活动/文章详情页海报）

4.59.5 DAN 报告模块（SC-C-07 / SC-T-12 dan.assessment.viewReport、SC-T-11 dan.assessment.uploadReport、SC-P-39 dan.assessment.viewResult、SC-P-24 / SC-T-21 health.report.compare）

4.59.5.1 DAN 报告独立流程（DanReportController /api/dan-report）

路径	请求	响应 data	说明
POST /api/dan-report/upload	multipart：file（PDF）、dimension、memberId	Map：uploadAndParse 结果（预览 + 解析字段）	Phase 1 上传并预览 DAN PDF
POST /api/dan-report/{id}/edit	body DanReportEditDTO	DanReportUploadVO	编辑草稿
POST /api/dan-report/{id}/confirm	{childName?, assessmentDate?}	DanReportUploadVO	Phase 2 确认入库
POST /api/dan-report/{id}/discard	无 body	null	放弃草稿
POST /api/dan-report/{id}/complete-analysis	无 body	null	完成分析（标记）
POST /api/dan-report/{id}	path id	DanReportUploadVO	详情（权限：有归属成员须 canViewMemberReports；无归属仅上传者本人/家庭管理员）
POST /api/dan-report/list	{memberId?, dimension?}	List<DanReportUploadVO>	列表。未传 memberId 按可见身份过滤该家庭全部；传 memberId 校验 canViewMemberReports（无权限返回空列表）
POST /api/dan-report/compare	{uploadIdA, uploadIdB}	uploadService.compareUploads 结果	DAN 报告两版对比（按 uploaded_at 对齐 parsed/edited_items 算 delta）

4.59.5.2 测评对比（AssessmentComparisonController /api/assessment/compare）

路径	请求	响应 data	说明
POST /api/assessment/compare/by-child	{memberId?}（缺省 currentMemberId）	CompareResult（首次 vs 最新测评对比）	至少两次完成测评，否则 Result.error("至少需要两次完成测评才能对比")
POST /api/assessment/compare/by-child-dimension	{memberId, dimensionCode}	DimensionDelta（单维度变化）	数据不足 → "暂无足够数据"
POST /api/assessment/compare/by-family	无 body（familyId JWT 注入）	List<CompareResult>	家庭所有成员首次 vs 最新；无家庭 → Result.noFamily
POST /api/assessment/compare/narrative	{memberId?}	String（进步叙事）	获取进步叙事

4.59.5.3 测评结果 / 报告查询（guide/AssessmentController /api/assessment + AssessmentResultController）

路径	请求	响应 data	说明
POST /api/assessment/result/{id}	path id	DanAssessmentResult	测评报告详情。仅 role=teacher 可查看（否则「只有指导师可以查看测评报告」）；canViewAssessment 权限校验
POST /api/assessment/my-results	无 body	List<DanAssessmentResult>	指导师自己的测评报告列表（仅 teacher）
POST /api/assessment/child-results	无 body	List<DanAssessmentResult>	下级指导师的测评报告列表（仅 teacher，getAccessibleAssessments）
POST /api/assessment/latest-result	{memberId?}（缺省 currentMemberId）	AssessmentResultDTO（无则 null）	成员最新认知测评结果（已在 4.10 登记，此处补 DTO 字段：memberId/childName/overallScore/attentionScore/focusScore/memoryScore/logicScore/perceptionScore/spatialScore/processingSpeedScore/analysisReport/growthSuggestions/assessmentDate）
POST /api/assessment/history	{memberId, size=5}	List<AssessmentHistoryItemDTO>（assessmentDate/overallScore）	成员测评历史（status=completed，按 assessmentDate 倒序）

4.59.5.4 测评报告上传 / 指导意见 / 方案（AssessmentReportController /api/dan-assessment/result）

路径	请求	响应 data	说明
POST /api/dan-assessment/result/plans/list	query/body {familyId?, childId?}（缺省 JWT familyId）	List<TaskPlanInstance>（按 createdAt 倒序）	家庭/成员已生成的测评方案列表；缺 familyId → "缺少familyId参数…"
POST /api/dan-assessment/result/upload	multipart file（仅 PDF）、memberId、notes?	DanAssessmentResult（status=draft，异步解析）	家庭主账号上传测评报告（已在 4.10 登记）；非 PDF → HTTP 415 {code:415}
POST /api/dan-assessment/result/{resultId}/guidance/save	{items:[GrowthGuidance]}（非空）	List<GrowthGuidance>	保存结构化指导意见（已在 4.10 登记）
POST /api/dan-assessment/result/{resultId}/guidance	无 body	List<GrowthGuidance>	获取结构化指导意见
POST /api/dan-assessment/result/{resultId}/confirm-inbox	{overallScore?}	DanAssessmentResult（status=completed）	用户确认报告入库并自动生成测评方案（无需规划师审核）

4.59.6 报告趋势 & 饮食推荐闭环（SC-P-25 health.report.trend、SC-P-26 health.report.dietRecommend、SC-X-10 health.report.trendClosedLoop）

开工包建议路径 /api/health/report/trend、/api/health/report/diet；实际实现：趋势走 /api/health/nutrition/trend（报告营养趋势）与 /api/food/recommendation/trend（食材推荐趋势）；饮食推荐走 /api/food/recommendation/*、/api/meal/*、/api/diet/*（4.11 已登记）。

4.59.6.1 报告趋势（HealthReportController /api/health/nutrition/trend）

路径	请求	响应 data	说明
POST /api/health/nutrition/trend	{memberId}	Map（childNutritionProfileService.getReportTrendData）	报告趋势数据（营养档案多期序列）

4.59.6.2 食材推荐（FoodRecommendController /api/food/recommendation）

路径	请求	响应 data	说明
POST /api/food/recommendation/index	{memberId?}	当前食材推荐指数列表	按成员取推荐（foodRecommendService）
POST /api/food/recommendation/history	{memberId?}	历史推荐	食材推荐历史
POST /api/food/recommendation/by-family	{familyId?}（JWT）	家庭成员食材推荐汇总	家庭维度汇总
POST /api/food/recommendation/caution	{memberId?}	慎用/忌口清单	食材提醒
POST /api/food/recommendation/members	{familyId?}	家庭内参与成员	推荐参与成员列表
POST /api/food/recommendation/trend	{memberId?}	推荐趋势	食材推荐多期趋势

报告确认/代确认后 foodRecommendService.recalculateForUser(subjectId) 自动刷新食材推荐指数（见 4.59.2 /report/confirm 与 4.59.3 /proxy-confirm）。

4.59.6.3 餐食推荐（MealRecommendController /api/meal）

路径	请求	响应 data	说明
POST /api/meal/recommend	{...}	推荐菜单	基于报告/偏好推荐餐食
POST /api/meal/replace	{...}	替换后菜单	换一道菜
POST /api/meal/log	{...}	保存结果	记录食用
POST /api/meal/logs	{memberId?, date?}	记录列表	食用记录列表
POST /api/meal/nutrition-summary	{memberId?, date?}	营养汇总	营养摄入汇总

4.59.7 报告类型链接 / 检测（ReportParserController /api/report-parser，4.36 补充）

路径	请求	响应 data	说明
POST /api/report-parser/types/links	无 body	List<{typeId, displayName, linkedProductId, productName}>	小程序公开：返回已激活且配置了商城商品链接的报告类型（is_active=1 AND linked_product_id IS NOT NULL），供「查看商品」入口；未配置链接的类型不出现在结果中
POST /api/report-parser/detect	{...}	指纹检测结果	报告指纹检测（同步返回，供调用方识别类型）

4.59.8 报告摘要（ReportSummaryController / ReportSummaryAdminController）

路径	请求	响应 data	说明
POST /api/report-summary/list	{...}	摘要列表	报告摘要列表（C 端）
POST /api/report-summary/detail/{id}	path id	摘要详情	报告摘要详情
POST /api/report-summary/download/{id}	path id	下载信息	报告摘要下载
POST /api/admin/report-summary/list	{page?, size?, ...}	分页摘要	管理端摘要列表
POST /api/admin/report-summary/sync	{...}	同步结果	管理端手动同步报告摘要

4.59.9 LangGraph 报告解读依赖登记（SC-B-04 coach.growthReport.interpret / SC-B-11 coach.growthReport.ask）

本批仅登记依赖，不做实现（契约在 cfc-langgraph 侧）。Java 侧通过 HealthReportController 内 restTemplate 调用， langgraph.base-url（报告解析）/ python.base-url（通用 AI）由 application.yml 配置。

LangGraph 端点	请求	用途	Java 侧触发点
POST {langgraph}/api/v1/report/parse	{file_path, user_id, family_id?}	报告解析（PDF → 结构化载荷）	/api/health/report/parse、/proxy-parse（callLangGraphParse）；失败回退本地 Java 解析
POST {langgraph}/api/v1/analyze	{report_id, user_id, focus}	报告 AI 解读（growthReport.interpret）	/proxy-confirm 的 triggerAiAnalysis（REPORT_READING 配额：BASIC 1 次/月，FAMILY 及以上不限；失败回传 aiAnalysisStatus）
POST {langgraph}/api/v1/chat	会话上下文	报告细节追问（growthReport.ask）	对话链路（AIChatController / 报告反馈 /api/health/feedback/*，见 4.37）

依赖边界：报告解读/追问能力不在 cfc-backend 实现，由 cfc-langgraph graph 提供；本批只登记调用契约，不新增 Java 端点。

4.59.10 契约缺口（开工包建议路径与现状不符，待实现 / 等价物替代）

开工包建议路径	现状	说明
POST /api/search/global	不存在（无 SearchController）	SC-P-82 misc.globalSearch 全局搜索（报告/方案/任务/商品）未实现；搜索需求当前分散：/api/diet/ingredients/search（食材）、文章/商品搜索各自接口。待实现时在本节登记
POST /api/provider/report-parse/connect	不存在（无 ProviderController）	SC-S-09 provider.reportParse.connect 商品服务商报告解析接入未实现；服务商（PROVIDER 角色）当前经 /api/vendor/*、/api/admin/supply-* 体系管理，无独立报告解析对接端点
POST /api/health/report/compare	不存在	SC-P-24/T-21 health.report.compare 报告对比由等价物承载：/api/dan-report/compare（DAN 两版对比）+ /api/assessment/compare/*（测评首次 vs 最新）。如需跨报告类型统一对比，待实现
POST /api/health/report/trend	不存在	SC-P-25 health.report.trend 由等价物承载：/api/health/nutrition/trend + /api/food/recommendation/trend（+ 既有 /api/indicator/trend、/api/cognitive/trend）
POST /api/health/report/diet	不存在	SC-P-26 health.report.dietRecommend 由等价物承载：/api/food/recommendation/* + /api/meal/* + /api/diet/*（4.11）
POST /api/health/report/share	不存在	SC-P-84 health.report.share 由等价物承载：/api/share/*（通用分享）+ /api/health/report/member-permission/*（成员级授权，4.59.4）
POST /api/health/report/refresh-dim	不存在	SC-P-91 health.report.refreshFiveDim 无显式端点：五维能量重算在 /report/confirm、/proxy-confirm、/report/reassign 链内自动触发（dimensionScoreService.refreshFromGutReport + refreshMemberIndicatorCurrent + recalculateForUser）；如需手动重算入口待实现

文档更新：2026-11-06（B-2 报告闭环开工包契约核对补全：4.59.1 报告解析中台 /api/admin/report-parse/* + dan/reparse；4.59.2 健康报告全链路；4.59.3 代传闭环 proxy-parse/proxy-confirm；4.59.4 报告权限/分享；4.59.5 DAN 报告模块；4.59.6 趋势与饮食推荐；4.59.7 报告类型链接/检测；4.59.8 报告摘要；4.59.9 LangGraph 依赖登记；4.59.10 契约缺口与等价物映射）

---

4.60 平台运营能力（SC-A-01~22、A-25~27，EVD-11 契约核对增补）

平台运营 = Web 管理端（cfc-web）与运营治理端点。以下为 2026-11-07 契约核对（EVD-11，开工包 docs/tdd/orchestration/admin-ops-kickoff-20261107.md）实测回填的端点存在性。完整核验表与实现缺口见 docs/superpowers/specs/2026-11-07-admin-ops-contract.md。 约定：所有端点 POST；管理端端点需 role=admin（JwtInterceptor + 控制器内角色检查）。

4.60.1 管理端登录（AdminAuthController，类级前缀 /api/admin-auth）

⚠ 注意：类级前缀是 /api/admin-auth，不是 /api/admin/auth（开工包初核曾写后者，实测为准）。

路径	说明
POST /api/admin-auth/login	账号密码登录（获取 JWT）
POST /api/admin-auth/login-by-password	密码登录（备选）
POST /api/admin-auth/send-code	发送验证码
POST /api/admin-auth/info	当前管理员信息
POST /api/admin-auth/change-password	修改密码
POST /api/admin-auth/reset-password	重置密码
POST /api/admin-auth/update-info	更新管理员信息
POST /api/admin-auth/account-roles	账号角色列表
POST /api/admin-auth/wechat-scan-qr	微信扫码登录二维码
POST /api/admin-auth/wechat-scan-poll	微信扫码登录轮询

4.60.2 全局统计（StatsController /api/stats）

路径	说明
POST /api/stats/dashboard、/overview、/trend、/revenue、/traffic、/membership	全局统计大盘（概览/趋势/营收/流量/会员）
POST /api/stats/family/summary	家庭维度汇总
POST /api/stats/child/overview、/child-completion、/family-completion	孩子/家庭完成度
POST /api/stats/points/ranking、/product-view	积分排行 / 商品浏览统计

4.60.3 报告解析中台（ReportParseAdminController /api/admin/report-parse，SC-A-02/A-16）

类名注意：源码类名为 ReportParseAdminController（非 AdminReportParseController），前缀 /api/admin/report-parse。

路径	说明
POST /api/admin/report-parse/list	解析任务列表
POST /api/admin/report-parse/types、/types/save、/types/delete、/types/toggle	报告类型 CRUD
POST /api/admin/report-parse/unknown-clusters、/unknown-uploads、/generate-type	未知类型聚类 / 待标注 / 生成类型（自学习）
POST /api/admin/report-parse/fingerprints/list、/save、/delete	指纹管理
POST /api/admin/report-parse/imports、/imports/import、/imports/approve、/imports/reject、/retry	解析导入审批链（SC-A-16 标注链）
POST /api/admin/report-parse/dan/reparse、/backfill-food	DAN 重解析 / 食物回填

4.60.4 文章发布-审核（AdminArticleController /api/admin/articles，SC-A-03）

路径	说明
POST /api/admin/articles/list、/detail、/create、/update、/delete、/move	文章 CRUD + 排序
POST /api/admin/articles/publish、/{id}/publish、/submit-review、/audit、/withdraw、/re-draft	发布-审核流
POST /api/admin/articles/categories/list、/create、/update、/delete	文章分类管理
POST /api/admin/articles/comments/list、/reading-records	评论/阅读记录
POST /api/admin/articles/upload/image、/upload/video、/toggle-featured、/backfill-tags	素材上传 / 精选 / 标签回填

4.60.5 勋章配置 CRUD（BadgeController /api/badges + AdminChallengeScoreConfigController，SC-A-05）

路径	说明
POST /api/badges/all、/list、/detail、/create、/update、/delete	勋章字典 CRUD
POST /api/badges/grant、/statistics/member、/member/list、/ranking/family、/favorite	发放 / 统计 / 成员视角 / 排行 / 收藏
POST /api/admin/challenge-score-config/list、/update	挑战分规则配置

4.60.6 供应商管理（SupplyManageController /api/admin/supply-manage + SupplyHierarchyController /api/admin/supply-hierarchy + AdminSupplierController /api/admin/supplier，SC-A-06）

路径	说明
POST /api/admin/supply-manage/list、/detail、/create、/update、/delete、/add-role、/remove-role、/adjust-tier	供应商 CRUD + 角色/层级调整
POST /api/admin/supply-hierarchy/tree、/my、/parent、/parent-chain、/direct-children、/all-children、/set、/remove	供应层级树
POST /api/admin/supply-hierarchy/change/apply、/change-requests、/change/review	层级变更审批
POST /api/admin/supplier/list、/save、/update、/delete	供应商主体管理

4.60.7 活动配置（AdminActivityController /api/admin/activity + AdminActivityCheckinController，SC-A-07）

路径	说明
POST /api/admin/activity/list、/detail、/audit、/review、/submit-review、/withdraw、/re-draft、/backfill-tags	活动审核流
POST /api/admin/activity-checkins/list、/add、/review、/export	活动打卡配置与审核

4.60.8 知识库管理（KnowledgeBaseController /api/admin/knowledge-base，SC-A-08）

载体为 KnowledgeBaseController（非开工包猜测的 AdminKnowledgeController）。

路径	说明
POST /api/admin/knowledge-base/list、/get、/save、/delete、/upload-file、/fetch-url	知识条目 CRUD / 导入
POST /api/admin/knowledge-base/bind-tags、/bind-dimensions、/backfill-tags	标签/维度关联
POST /api/admin/knowledge-base/vector/documents、/stats、/sync、/delete-source、/update-document	向量库管理（KnowledgeBaseVectorController）
POST /api/admin/knowledge-tag/list、/save、/delete	知识标签字典（KnowledgeTagController）
POST /api/admin/knowledge-base/unified/overview、/section、/update、/reset	统一知识库（AdminUnifiedKnowledgeController）

4.60.9 维度配置与维度注册（DimensionAdminController /api/admin/dimension + DimensionConfigController + DimensionRegistryController，SC-A-09/A-25）

路径	说明
POST /api/admin/dimension/data-source/list、/save、/delete、/detail	维度数据源配置
POST /api/admin/dimension/norm/list、/save、/delete	维度参考标准配置
POST /api/admin/dimension-config/list、/get、/save、/delete、/tree	维度配置 CRUD + 树
POST /api/dimension-registry/*	维度注册表查询（DimensionRegistryController）

4.60.10 数据迁移 / 参数校验（DataMigrationController /api/migration + MigrationController + SysConfigController，SC-A-10）

路径	说明
POST /api/migration/run	手动触发数据迁移（DataMigrationController）
POST /api/migrate/guide-packages、/migrate/knowledge-base-to-articles	专项迁移（MigrationController）
POST /api/admin/config/list、/update、/all	系统参数/配置校验与维护（SysConfigController）

补充载体：DatabaseInitializer 为启动期自动迁移（非 HTTP），report-parse 参数校验在内置校验逻辑内。

4.60.11 用户/家庭查询治理（AdminController /api/admin + AdminOrgMemberController，SC-A-11）

路径	说明
POST /api/admin/users、/users/create、/user/search、/users/{id}、/users/{id}/update、/users/{id}/delete、/users/{id}/reset-password	用户治理
POST /api/admin/families、/families/{id}、/families/{id}/update、/families/{id}/delete、/families/{id}/members、/families/{id}/members/set-admin	家庭治理
POST /api/admin/children、/children/{id}、/children/{id}/update、/children/{id}/adjust-points	孩子视角管理
POST /api/admin/org/member/list、/add、/remove、/change-type	组织成员治理（AdminOrgMemberController）
POST /api/admin/families/{id}/overview、/families/{id}/tasks	家庭概览（AdminFamilyOverviewController）

4.60.12 订单/退款人工处理（AdminProductOrderController /api/admin/product/order，SC-A-12）

路径	说明
POST /api/admin/product/order/list、/detail、/ship、/update-express、/close	订单人工处理
POST /api/admin/product/order/refund/approve、/refund/reject	退款人工审批

4.60.13 内容安全审核（ReviewCenterController /api/admin/review-center + 业务 audit 端点，SC-A-13/A-18）

路径	说明
POST /api/admin/review-center/summary	待审聚合队列（13 类：文章/商品/规划师/服务商/管家/套餐/活动/报名/提现/退款/层级变更/营养师/知识）
POST /api/admin/articles/audit、/api/admin/activity/audit	文章 / 活动审核动作
POST /api/admin/articles/comments/list	评论审核列表

4.60.14 操作审计日志（OperationLogController /api/admin/logs + AdminAuditController，SC-A-15）

路径	说明
POST /api/admin/logs/operations	操作日志分页查询（按用户/类型/日期过滤）
POST /api/admin/logs/recent	近期操作日志
POST /api/admin/audit/list	审计列表（AdminAuditController）

4.60.15 优惠券/活动配置管理（AdminCouponController /api/admin/coupon，SC-A-17）

路径	说明
POST /api/admin/coupon/list、/create、/update、/delete、/toggle-status	券模板 CRUD
POST /api/admin/coupon/issue、/issue-family	发放（个人 / 家庭）
POST /api/admin/coupon/grant-log、/grant-user、/family-coupons、/family-coupon-usage、/gift-transfers	发放记录 / 家庭券 / 转赠

4.60.16 能量配置治理（AdminEnergyConfigController /api/admin/energy-config + AdminEnergyRuleController /api/admin/energy-rule，SC-A-25/A-26）

路径	说明
POST /api/admin/energy-config/overview、/daily-limits、/daily-limit-save	每日上限配置
POST /api/admin/energy-config/source-list、/source-save、/source-delete	能量来源比例配置（SC-A-26）
POST /api/admin/energy-rule/list、/dimensions、/create、/update、/delete、/toggle	归因权重规则（SC-A-26）
POST /api/admin/dimension-weight/list、/save	维度权重配置（DimensionWeightController，SC-A-25）

4.60.17 睡眠选项维护（SysConfigController + PublicConfigController + HealthSleepController，SC-A-27）

路径	说明
POST /api/admin/config/list、/update、/all	管理端维护 sleep.config.tags（状态机键 sleep.config.tags，YELLOW）
POST /api/config/public/value	小程序端拉取 sleep.quality.tags（PublicConfigController）
POST /api/health/sleep/list、/create	睡眠记录（C 端，HealthSleepController）

SC-A-27 已在状态机（YELLOW），本批只登记映射不新建任务（见契约文档 §2）。

4.60.18 契约缺口（无端点载体，需产品侧确认验收方式）

SC	场景	现状	处置
SC-A-04	关系类型 CRUD	无 /api/admin/relationship-types；relationship_types 表已废弃 DROP，关系由 family_relationships（`/api/family/member/add	update+FamilyRelationshipService`）承载
SC-A-14	系统监控/告警	仅 POST /api/system/health（JVM/内存/CPU 探活），无告警规则/记录端点	无端点载体，需产品侧确认
SC-A-19	账号注销/数据导出工单处理	无运营工单端点；用户侧自助 POST /api/user/deactivate、POST /api/user/data-export 已实现	无端点载体，需产品侧确认
SC-A-20	限流/熔断配置	无 HTTP 配置端点；RateLimitInterceptor（Redis 滑动窗口）+ AiGateway 熔断为代码内置	无端点载体，需产品侧确认
SC-A-21	舌诊/情绪模型管理	POST /api/admin/innate-portrait-config/{list,update,invalidate} + POST /api/mind/emotion/{analyze,analyze-url} 存在；舌诊模型无独立 admin 端点（内联报告解析链）	端点载体部分存在，需产品侧确认

文档更新：2026-11-07（EVD-11 平台运营 25 SC 契约核对增补「平台运营能力」段落 4.60：管理端登录 / 统计 / 报告解析中台 / 文章审核 / 勋章 / 供应商 / 活动 / 知识库 / 维度 / 迁移 / 用户家庭治理 / 订单退款 / 审核队列 / 审计日志 / 优惠券 / 能量配置 / 睡眠选项 + 契约缺口。完整核验表见 docs/superpowers/specs/2026-11-07-admin-ops-contract.md）

4.61 孩子端（不能登录用户视角）接口（EVD-9 契约核对，2026-11-07）

来源：EVD-9 孩子端 26 SC 契约核对，依据开工包 docs/tdd/orchestration/child-zone-kickoff-20261107.md（26 SC，6 个 ⚠ 待核实项已全部实测关闭）。 本节端点由 cfc-backend 源码全量提取（1935 个 @PostMapping）后逐条比对得出；场景口径另参 tests/user-scenarios/应用场景总览.md § 四。 完整核验表 / 能力键建议 / 缺口清单见 docs/superpowers/specs/2026-11-07-child-zone-contract.md。 开工包候选载体与实测不一致的 6 处（C-07/C-08/C-12/C-14/C-22/C-24）在下方按实测路径登记。 覆盖 SC-C-01 ~ SC-C-26。统一 @PostMapping、响应 Result<T>、JWT 鉴权（JwtInterceptor 拦 /api/**）。 "不能登录用户"没有自己的 JWT：孩子端写操作都发生在家长会话下，通过 memberId / currentMemberId 指定被代管成员。

4.61.1 身份与视角切换（SC-C-01 / SC-C-17 / SC-C-18）

路径	请求	响应 data	说明
POST /api/auth/silent-login	{code}（WechatLoginDTO）	LoginResultDTO（token/userId/role/...）	微信静默登录
POST /api/auth/wechat-login	{code,...}（WechatLoginDTO）	LoginResultDTO	微信授权登录
POST /api/auth/phone-login	{phone, code}	LoginResultDTO	手机号验证码登录
POST /api/auth/auto-login	{openid,...}	LoginResultDTO	自动登录
POST /api/auth/verify	无 body，Header Authorization: Bearer <token>	{userId, role}；token 无效或用户不存在 → 401	会话校验（前端启动探活）
POST /api/family/member/switch	{memberId, source?}	SwitchMemberVO{memberId, source, effectiveRole, nickname, isSwitchable}	现行切视角端点：家长切到孩子视角（孩子端入口）
POST /api/family/user/switch-back-verify	{password}	Boolean	密码校验后切回家长视角
POST /api/family/user/switch-to-child	{memberId}	410	已废弃，返回"请使用 /api/family/member/switch"
POST /api/family/user/switch-back-to-parent	无	410	已废弃，同上
POST /api/family/invite/check-family	无	家庭绑定状态	账号是否已绑定家庭
POST /api/family/invite/validate	{token}	校验结果	家庭邀请令牌校验
POST /api/family/invite/validate-family-code	{inviteCode}	校验结果	家庭邀请码校验

缺口：无 logout 端点（JWT 无状态，退出=前端清 token，G-03）；无任何设备维度（无 deviceId/设备表/异常设备二次验证，G-04）。 路径缺陷：前端 utils/api.js 仍调 /api/user/switch-to-child、/api/user/switch-back-to-parent、/api/user/switch-mode、/api/user/roles、/api/user/switch-role，这些 /api/user/* 在 UserController 中无映射（404）（G-08）。

4.61.2 任务 / 打卡 / 方案进度（SC-C-02 / C-05 / C-08 / C-14）

路径	请求	响应 data	说明
POST /api/tasks/today	{memberId?, dimensionCode?, category?}	Task[]	今日任务
POST /api/tasks/my-pending	{memberId?}	Task[]	待接受任务
POST /api/tasks/accept	{taskId, memberId}	Boolean	⚠ 参数绑定错误：后端 @PathVariable Long id 但路径无 {id} → 必抛 MissingPathVariableException（G-12）
POST /api/tasks/reject/{id}	{memberId?}	Boolean	孩子拒接任务
POST /api/tasks/{id}/start	{memberId?}	Boolean／Task	开始任务
POST /api/tasks/{id}/complete	CompleteTaskDTO{memberId?, photoUrl, content, contentType}	Map（奖励/状态）	打卡提交
POST /api/tasks/{id}/complete-minigame	{memberId?, completionTime?, score?}	Map	以小游戏结果完成任务
POST /api/tasks/{id}/review	{approved? , result?, reason?}	Boolean	家长审核；approved=false → status 回 pending，孩子可重做（C-14）
POST /api/tasks/history	{memberId?, page, size}	Page<Task>	任务历史
POST /api/daily/checkin/create	DailyHealthCheckin（饮食/运动/睡眠/饮水/心情）	记录	通用每日打卡
POST /api/daily/checkin/list	{memberId?, date?}	DailyHealthCheckin[]	打卡列表
POST /api/health/plan/list	{memberId?, page, size}	Page<HealthPlan>	成长方案列表
POST /api/health/plan/detail	{planId}	HealthPlan	方案详情
POST /api/health/plan/tasks	{planId}	Task[]	方案任务与进度（含 plan.getFamilyId() 归属校验）
POST /api/growth-task/list	{type?, dimension?}	GrowthTask[]	成长任务（今日/周期）
POST /api/growth-task/claim	{taskId?}	String	领取成长任务（奖励在完成时自动发放）

4.61.3 小游戏与五维能量（SC-C-03 / C-24 / C-25）

路径	请求	响应 data	说明
POST /api/mini-game/list	{}（familyId 取自会话）	MiniGame[]	启用的小游戏
POST /api/mini-game/complete	CompleteGameDTO{memberId, gameCode, completionTime, score}	{pointsEarned, ...}	成绩上报：加积分 + 写流水 + 写 game_record + 能量
POST /api/game/record	{memberId, gameCode, score, completionTime, difficulty?, pointsEarned?}	Map	直接写游戏记录（pointsEarned 由客户端传入，存在刷分风险）
POST /api/game/history / /best / /stats / /leaderboard	{memberId, gameCode?, page?, size?}	记录/最高分/统计/排行榜	游戏数据查询
POST /api/energy/sandbox	`{view: "personal"	"family", memberId?}`	{locked, view, personalData, familyData, familyUnlocked, familyGate?}
POST /api/energy/overview	{memberId?}	Map（五维分值/变化）	五维概览
POST /api/energy/logs	{memberId?, dimensionCode?, page?, size?}	Page<EnergyLog>	能量流水
POST /api/energy/score-history	{memberId?, dimensionCode?, page?, size?}	Page（历史快照）	分值历史

缺口：/api/mini-game/complete 无幂等、score 无上限（score=999999 可换巨额积分并污染 Redis 排行榜，G-09）；/api/game/record 的 pointsEarned 由前端决定。 能量写入只落 energy_balance + energy_log，不写 five_dimension_score 快照；overview/logs 未校验 memberId 归属（跨家庭可读，G-10）。

4.61.4 勋章（SC-C-09 / C-10）

路径	请求	响应 data	说明
POST /api/badges/list	无	Badge[]	启用勋章定义（勋章墙底图）
POST /api/badges/member/list	{memberId}	[{memberBadge, badge}]	成员已得勋章（收藏优先、获得时间倒序）
POST /api/badges/statistics/member	{memberId}	统计（已得数/分类等）	勋章统计
POST /api/badges/ranking/family	无（familyId 取自会话）	家庭排行	成员勋章排行
POST /api/badges/detail	{id}	Badge	勋章详情（达成条件）
POST /api/badges/favorite	{memberId, badgeId}	Boolean	收藏/取消收藏
POST /api/badges/grant	{memberId?, badgeId}	String	授予勋章（管理端/家长）；不写通知

缺口：BadgeService.grantBadge 只写 member_badges，无 user_notification、无推送 → C-10「解锁提醒」未实现（G-01）； 无"任务/打卡自动聚合授予"逻辑（场景要求"勋章来自任务/打卡聚合"）。判重已满足（重复授予直接 return）。

4.61.5 报告与成长档案（SC-C-06 / C-07 / C-11 / C-20）

路径	请求	响应 data	说明
POST /api/health/report/list	{memberId?, reportType?, page, size}	Page	健康报告列表（详见 4.59.2）
POST /api/health/report/latest	{memberId?, reportType?}	最新报告	最新报告
POST /api/health/report/detail	{id}	报告详情	详情（含 member-permission 校验）
POST /api/dan-report/list	{memberId?, page, size}	Page	DAN 测评报告列表（详见 4.59.5.1）
POST /api/dan-report/{id}	路径参数	报告详情	详情（canViewMemberReports 校验）
POST /api/dan-report/compare	{memberId, id1, id2}	对比结果	两版对比
POST /api/growth/record/list	无（取 userId）	GrowthRecord[]	本人成长档案
POST /api/growth/record/child/{memberId}	路径参数	GrowthRecord[]	指定成员档案（⚠ 无归属校验，G-11）
POST /api/growth/record/child-records	body 为裸 Long memberId	GrowthRecord[]	同上（带 currentMemberId 缺省逻辑）
POST /api/growth/record/{id}	路径参数	GrowthRecord	记录详情（⚠ 无归属校验，G-11）
POST /api/user/data-export	无	Map（userInfo/children/assessmentResults/healthReports/tasks）	仅导出登录用户本人；无 memberId 入参 → 无"家长代导出孩子"（G-05）

4.61.6 商城 / 心愿 / 积分（SC-C-04 / C-22）

路径	请求	响应 data	说明
POST /api/wishes/create	CreateWishDTO{title, description?, category?, imageUrl?, linkUrl?, estimatedPrice?, memberId?, pointsRequired?}	Long（心愿 id）	提心愿
POST /api/wishes/list	{memberId?, status?, page?, size?}	Wish[]	心愿列表
POST /api/wishes/{id}	路径参数	Wish	心愿详情
POST /api/wishes/{id}/cancel	路径参数	Boolean	撤销心愿
POST /api/wishes/pending	无	Wish[]	家长待审批
POST /api/wishes/{id}/price	{pointsRequired}	Boolean	家长定价
POST /api/wishes/{id}/approve-exchange	{approved}	Boolean	审批兑换
POST /api/wishes/{id}/reject	{reason}	Boolean	驳回（驳回后不可兑）
POST /api/wishes/{id}/fulfill / /{id}/confirm / /{id}/exchange	路径参数	Boolean	兑现/确认/兑换
POST /api/product/list	{page, size, domain?, keyword?}	Page<Product>	商城浏览
POST /api/product/detail	{id}	Product	商品详情
POST /api/points/exchange/product/list	{category?, pageNum?, pageSize?}	Page<PointsExchangeProduct>	积分兑换商品列表
POST /api/points/exchange/product/detail	{id}	PointsExchangeProduct	兑换商品详情
POST /api/points/exchange/submit	{productId, memberId, quantity?}	PointsExchangeRecord	提交兑换（积分不足/重复由 Service 拦截）
POST /api/points/exchange/records	无（取 userId）	PointsExchangeRecord[]	兑换记录
POST /api/points/exchange/stats	无（取 userId）	{todayCount}	兑换统计
POST /api/points/balance	{memberId?}	{balance, ...}	积分余额
POST /api/points/logs	{memberId, page?, size?}	Page<PointsLog>	积分流水

4.61.7 消息 / 反馈 / 资料（SC-C-15 / C-16 / C-19 / C-23）

路径	请求	响应 data	说明
POST /api/notification/list	无（取 userId）	UserNotification[]（未读优先，LIMIT 100）	站内通知
POST /api/notification/read	{id?} / {ids?} / 空（全部已读）	Boolean	标记已读
POST /api/guide/messages/my	无（取 userId）	TeacherMessage[]	规划师消息
POST /api/guide/messages/unread-count	无	Long	未读数
POST /api/user/info / /api/auth/info / /api/family/user/info	无（取 userId）	完整 User（仅 password 置空）	个人资料（无受限投影，G-02）
POST /api/user/update / /api/family/user/update	UpdateUserDTO／User	Boolean	修改资料
POST /api/health/feedback/submit	报告反馈 DTO	—	报告反馈（仅报告维度）
POST /api/activity/feedback/submit	活动评价 DTO	—	活动评价（仅活动维度）
POST /api/feedback/today / /read / /recent	无／{id}／{limit?}	每日反馈	家长→孩子方向，与"孩子提意见"相反

缺口：无通用"意见反馈"端点/表/管理端受理（G-06）。

4.61.8 饮食 / AI / 舌诊情绪 / 睡眠（SC-C-12 / C-13 / C-21 / C-26）

路径	请求	响应 data	说明
POST /api/diet/recommendation/today	{date}（必填，空→Result.error("date不能为空")）	今日食谱	饮食推荐
POST /api/diet/recommendation/generate	{date, ...}	食谱	生成/重新生成
POST /api/diet/recommendation/complete	{date, ...}	Boolean	完成标记
POST /api/health/meal/daily / /weekly / /list	{memberId?, date?}	餐次数据	餐次记录
POST /api/ai/chat/send	{query, conversationId?}	Map（answer/conversationId/...）	AI 对话（会员门禁 checkGate）
POST /api/ai/chat/conversations / /chat/messages	{conversationId?}	会话/消息列表	多轮上下文
POST /api/health/report/upload-only	multipart(file, memberId?, type=tongue)	{type:"tongue", ...}	舌诊拍照上传 + 预览（含 aiGateway.detectTongue 自动识别分支）
POST /api/health/report/parse-preview	{recordId?, memberId?, type=tongue}	舌诊指标预览	解析预览
POST /api/health/report/confirm	{recordId, subjectId/memberId, indicators, type=tongue}	入库结果	舌诊确认
POST /api/health/report/discard	{recordId, type=tongue}	Boolean	放弃草稿
POST /api/mind/emotion/analyze / /analyze-url	图片/URL	情绪识别结果	情绪自拍识别
POST /api/mind/checkin/create / /list / /latest / /trend	身心打卡 DTO	记录/列表/趋势	情绪打卡记录
POST /api/health/sleep/list	{memberId?}（缺省 currentMemberId）	HealthSleepRecord[]	睡眠记录
POST /api/health/sleep/create	HealthSleepRecord{memberId?, sleepTime:"HH:mm", wakeTime:"HH:mm", durationMinutes?, qualityScore?, remark?, taskId?}	HealthSleepRecord	睡眠打卡（taskId 透传自动完成/累计任务）
POST /api/config/public/value	{key}	String	配置读取；睡眠标签应为 key=sleep.quality.tags

缺口：sleep_record 无 tags 列，标签被前端拼进 remark 文本；/api/health/sleep/tags、/api/admin/sleep/tags 均未实现；key 命名 sleep.quality.tags（需求/用例）与 sleep.config.tags（sc-key-map）不一致；sleep-checkin.vue 仍硬编码 8 项、无「正常」（G-07）。 AI 对话无适龄过滤入参；舌诊 confirm 需家长会话代传 memberId。

4.61.9 契约缺口汇总（详见 docs/superpowers/specs/2026-11-07-child-zone-contract.md § 5）

ID	关联 SC	一句话
G-01	C-10	勋章解锁无通知/推送（grantBadge 不写 user_notification）
G-02	C-16	个人资料无受限投影（三处 info 返完整 User）
G-03	C-17	无服务端 logout（JWT 无状态）
G-04	C-18	无设备绑定/异常设备二次验证
G-05	C-20	无"家长代导出指定成员"；exportUserData 只认 userId
G-06	C-23	无通用意见反馈端点/表/管理端
G-07	C-26	睡眠标签无 tags 列/无专用端点/无管理端/前端硬编码
G-08	C-01/C-17	前端 /api/user/switch-* 无映射（404）；旧 /api/family/user/switch-to-child 已 410
G-09	C-02/C-03/C-24	小游戏上报无幂等、分数无上限、pointsEarned 前端可控
G-10	C-06/C-24	energy/overview、energy/logs 未校验 memberId 归属（可跨家庭读）
G-11	C-11/C-20	growth/record/child/{memberId}、/record/{id} 无归属校验
G-12	C-02	/api/tasks/accept 的 @PathVariable id 与路径不匹配 → 调用必失败

统计：26/26 有承载端点；场景完整闭环 19/26；场景级缺口 7（C-10/C-16/C-17/C-18/C-20/C-23/C-26）；跨切面缺陷 5（G-08 ~ G-12）。 文档更新：2026-11-07（EVD-9 孩子端 26 SC 契约核对：4.61.1 身份与视角切换；4.61.2 任务/打卡/方案进度；4.61.3 小游戏与五维能量；4.61.4 勋章；4.61.5 报告与成长档案；4.61.6 商城/心愿/积分；4.61.7 消息/反馈/资料；4.61.8 饮食/AI/舌诊情绪/睡眠；4.61.9 缺口汇总 G-01~G-12）

4.62 商品服务商域（SC-S-01/05/07/08/10/11，EVD-12R2 契约核对增补）

归属：契约补建计划 P0「商品服务商域」· 核对 2026-11-07（EVD-12R2） 核对方法：类级 @RequestMapping + 方法级 @PostMapping 实测定位（防假 RED）。SC-S-02/03/04/06 由 EVD-4 商城-会员覆盖；SC-S-09 由 EVD-7R 报告闭环覆盖。 完整核验表见 docs/superpowers/specs/2026-11-07-service-provider-contract.md。

4.62.1 服务商入驻申请（SupplySystemController /api/admin/supply-system，SC-S-01 supplier.apply）

⚠ 载体置换：开工包候选 AdminSupplierController /api/admin/supplier、EcomSupplierController /api/admin/ecom-supplier 均标注「【已废弃】请使用 /api/admin/supply-system/list」，活跃载体为 SupplySystemController。 | 路径 | 说明 | |------|------| | POST /api/admin/supply-system/list | 服务商体系分页（keyword/status/page/size） | | POST /api/admin/supply-system/create | 服务商体系建档（入驻申请提交） | | POST /api/admin/supply-system/update | 服务商体系更新 | | POST /api/admin/supply-system/detail | 服务商体系详情 | | POST /api/admin/supply-system/toggle-status | 启停审核（入驻审核动作） | | POST /api/admin/supply-system/list-all | 全量体系（下拉选择） | | POST /api/admin/supply-system/my-system | 当前用户所属体系 | | POST /api/admin/supply-system/my-teams | 一人多团队（顶部切换器） | | POST /api/admin/supply-system/member/list | 体系成员列表 | | POST /api/admin/supply-system/member/add | 添加体系成员 | | POST /api/admin/supply-system/member/remove | 移除体系成员 | | POST /api/admin/supply-system/member/change-role | 成员角色变更 | 边界：体系层级/团队治理（SupplyManageController /api/admin/supply-manage：list/detail/create/update/delete/add-role/remove-role/adjust-tier）由 EVD-11 SC-A-06 覆盖，不重复登记。

4.62.2 库存管理（AdminInventoryController /api/admin/inventory + SupplierProductController /api/admin/supplier/product，SC-S-05 supplier.inventory.manage）

AdminInventoryController /api/admin/inventory | 路径 | 说明 | |------|------| | POST /api/admin/inventory/inbound/create | 入库单创建 | | POST /api/admin/inventory/inbound/list | 入库单列表 | | POST /api/admin/inventory/inbound/detail | 入库单详情 | | POST /api/admin/inventory/inbound/confirm | 入库确认 | | POST /api/admin/inventory/inbound/cancel | 入库取消 | | POST /api/admin/inventory/outbound/create | 出库单创建 | | POST /api/admin/inventory/outbound/list | 出库单列表 | | POST /api/admin/inventory/transactions/list | 库存流水列表 | | POST /api/admin/inventory/counting/create | 盘点单创建 | | POST /api/admin/inventory/counting/confirm | 盘点确认 | | POST /api/admin/inventory/counting/list | 盘点单列表 | | POST /api/admin/inventory/alert/list | 库存告警列表 | | POST /api/admin/inventory/product/stock | 商品库存查询 | | POST /api/admin/inventory/combo/items | 组合商品项 | | POST /api/admin/inventory/combo/items/list | 组合商品项列表 | SupplierProductController /api/admin/supplier/product | 路径 | 说明 | |------|------| | POST /api/admin/supplier/product/list | 服务商商品列表 | | POST /api/admin/supplier/product/create | 服务商商品创建 | | POST /api/admin/supplier/product/update | 服务商商品更新 | | POST /api/admin/supplier/product/detail | 服务商商品详情 | | POST /api/admin/supplier/product/delete | 服务商商品删除 | | POST /api/admin/supplier/product/shelve | 服务商商品上/下架 |

4.62.3 营销活动报名（ActivityController /api/activity + AdminActivityController /api/admin/activity + ActivityOrderController /api/activity/order，SC-S-07 supplier.activity.signup）

ActivityController /api/activity | 路径 | 说明 | |------|------| | POST /api/activity/list | 活动列表 | | POST /api/activity/detail | 活动详情 | | POST /api/activity/create | 活动创建 | | POST /api/activity/update | 活动更新 | | POST /api/activity/publish | 活动发布 | | POST /api/activity/end | 活动结束 | | POST /api/activity/submit-review | 提交审核 | | POST /api/activity/register | 活动报名 | | POST /api/activity/cancel-registration | 取消报名 | | POST /api/activity/my-registrations | 我的报名列表 | | POST /api/activity/registration-roster | 报名名单/核销 | | POST /api/activity/checkin | 活动签到 | | POST /api/activity/checkin-review | 签到审核 | AdminActivityController /api/admin/activity | 路径 | 说明 | |------|------| | POST /api/admin/activity/list | 活动管理列表 | | POST /api/admin/activity/review | 审核 | | POST /api/admin/activity/detail | 详情 | | POST /api/admin/activity/submit-review | 提交审核 | | POST /api/admin/activity/audit | 审核动作 | | POST /api/admin/activity/backfill-tags | 标签回填 | | POST /api/admin/activity/withdraw | 撤回 | | POST /api/admin/activity/re-draft | 退回草稿 | ActivityOrderController /api/activity/order | 路径 | 说明 | |------|------| | POST /api/activity/order/create | 报名订单创建 | | POST /api/activity/order/pay | 报名订单支付 | | POST /api/activity/order/handlePaymentSuccess | 支付成功回调处理 | | POST /api/activity/order/notify | 支付通知 | | POST /api/activity/order/status | 订单状态查询 |

4.62.4 对账/结算（AdminSettlementController /api/admin/dan-settlement + SupplySettlementController /api/admin/supply-settlement，SC-S-08 supplier.settlement.reconcile）

AdminSettlementController /api/admin/dan-settlement | 路径 | 说明 | |------|------| | POST /api/admin/dan-settlement/list | DAN 结算列表 | | POST /api/admin/dan-settlement/detail/{settlementId} | DAN 结算详情 | | POST /api/admin/dan-settlement/confirm/{settlementId} | DAN 结算确认 | | POST /api/admin/dan-settlement/stats | DAN 结算统计 | SupplySettlementController /api/admin/supply-settlement | 路径 | 说明 | |------|------| | POST /api/admin/supply-settlement/list | 供货结算列表 | | POST /api/admin/supply-settlement/detail | 供货结算详情 | | POST /api/admin/supply-settlement/detail-items | 供货结算明细 | | POST /api/admin/supply-settlement/create | 供货结算创建 | | POST /api/admin/supply-settlement/confirm | 供货结算确认 |

4.62.5 营养/食谱数据供给（NutritionProductController /api/nutrition/product + BeijingNutritionController /api/nutrition/beijing + UserNutritionProfileController /api/nutrition/profile，SC-S-10 supplier.nutrition.supply）

NutritionProductController /api/nutrition/product | 路径 | 说明 | |------|------| | POST /api/nutrition/product/category/list | 营养品分类列表 | | POST /api/nutrition/product/brand/list | 营养品品牌列表 | | POST /api/nutrition/product/search | 营养品搜索 | | POST /api/nutrition/product/detail | 营养品详情 | | POST /api/nutrition/product/recommend | 营养品推荐 | | POST /api/nutrition/product/price-compare | 营养品价格对比 | | POST /api/nutrition/product/from-product | 从商品转换 | BeijingNutritionController /api/nutrition/beijing | 路径 | 说明 | |------|------| | POST /api/nutrition/beijing/bacteria/save | 北京食谱菌群保存 | | POST /api/nutrition/beijing/recommend | 北京食谱推荐 | | POST /api/nutrition/beijing/recommend/custom | 北京食谱自定义推荐 | | POST /api/nutrition/beijing/kb/query | 食谱知识库查询 | | POST /api/nutrition/beijing/kb/list | 食谱知识库列表 | | POST /api/nutrition/beijing/kb/info | 食谱知识库详情 | | POST /api/nutrition/beijing/analysis | 食谱分析 | UserNutritionProfileController /api/nutrition/profile | 路径 | 说明 | |------|------| | POST /api/nutrition/profile/get | 营养画像查询 | | POST /api/nutrition/profile/save | 营养画像保存 |

4.62.6 数据导出合规（UserController /api/user + ReportMemberPermissionController /api/health/report/member-permission，SC-S-11 supplier.export.compliance）

UserController /api/user（用户侧自助，个保法数据可携带权） | 路径 | 说明 | |------|------| | POST /api/user/data-export | 导出用户数据（AccountCleanupService.exportUserData） | | POST /api/user/deactivate | 注销账号（数据匿名化，AccountCleanupService.deactivateAccount） | ReportMemberPermissionController /api/health/report/member-permission（授权使用约束） | 路径 | 说明 | |------|------| | POST /api/health/report/member-permission/list | 报告授权列表 | | POST /api/health/report/member-permission/members/{memberId} | 指定成员的授权详情 | | POST /api/health/report/member-permission/grant | 授予报告查看权 | | POST /api/health/report/member-permission/revoke | 撤销报告查看权 | | POST /api/health/report/member-permission/visible-members | 可见成员列表 | 边界：EVD-11 SC-A-19 的运营工单处理（账号注销/数据导出工单）无端点载体，属平台运营域需产品侧确认；本 SC 为用户侧自助能力。 文档更新：2026-11-07（EVD-12R2 商品服务商域 6 SC 契约核对增补「商品服务商域」段落 4.62：服务商入驻 / 库存管理 / 活动报名 / 对账结算 / 营养食谱数据供给 / 数据导出合规 + 边界归位说明。完整核验表见 docs/superpowers/specs/2026-11-07-service-provider-contract.md）

4.63 家长域剩余（SC-P-02~85，EVD-13 契约核对增补）

家长域 96 个 SC 中已由既有开工包覆盖：家庭-成员（EVD-2）、任务-心愿（EVD-3）、商城-会员（EVD-4）、五维能量（EVD-5）、报告闭环（EVD-7R）、测评-方案（EVD-8R）；本批 = P 域剩余 30 个无键 SC（SC-P-02/04/05/20~23/28~31/49~51/54/61~66/69~71/73/76/78/79/83/85），端点载体逐条实测核验。完整核验表与实现缺口见 docs/superpowers/specs/2026-11-07-parent-rest-contract.md。 约定：所有端点 POST（NoticeController /api/notices/list 为 GET+POST 双方法历史遗留，API_REFERENCE §3.6 已记录）。 已 GREEN 键复用登记（仅登记不新建，O-2 方案 A 防键重复）：health.report.upload（SC-P-20~23）、health.report.createReport（SC-P-23）、growth.history.view（SC-P-50）、langgraph.questionnaire.generate（SC-P-49）。

4.63.1 家庭与成员 / 上下文（SC-P-02/04/05/73）

路径	说明
POST /api/family/member/add、/update、/list、/editable	添加/编辑成员（generationLevel/peerType → FamilyRelationshipService 关系写入）、成员列表（统一入口，visibleOnly/includeFamily）、可编辑检查
POST /api/family/member/switch	切换成员/孩子上下文视角（SwitchMemberVO，替代已废弃 /api/family/user/switch-mode 族）
POST /api/family/invite/generate、/qrcode、/validate、/accept、/bind-inviter、/request-join-by-code	邀请成员（令牌复用/补发，family.invite.reissue 语义）
POST /api/family/relationship/scores、/pairwise	关系质量查询（RelationshipQualityController，命名回填：候选 RelationshipController 不存在）

4.63.2 健康报告上传解析（SC-P-20~23，复用 health.report.upload/createReport）

路径	说明
POST /api/health/report/upload-only	生产上传入口：PDF → 草稿 health_report_drafts（parse_status=collecting）→ 异步采集 → 返回 draftId（前端轮询）
POST /api/health/report/upload	兼容接口：自动执行「解析→确认」两阶段
POST /api/health/report/parse、/parse-preview	异步解析 / 解析预览（type=auto/image/tongue 识别）
POST /api/health/report/collect/status、/collecting-list	采集进度轮询 / 采集中草稿列表
POST /api/health/report/confirm、/discard、/audit/confirm、/audit/discard	确认入库 / 废弃 / 审核确认（SC-P-23 确认入库，health.report.createReport 语义）
POST /api/report-parser/detect、/types/links	报告类型识别（ReportParserController，SC-P-21）

4.63.3 食谱 / 营养（SC-P-28/29/30/69）

路径	说明
POST /api/food/recommendation/index、/caution、/members、/trend、/by-family	食谱推荐 / 忌口（caution）/ 家庭成员 / 趋势（SC-P-28）
POST /api/diet/preferences/current-member、/save	忌口参数（DietPreferencesController，命名回填：候选 UserFoodPreferenceController 不存在）
POST /api/diet/ingredients/suggest、/search、/add、/remove	食材筛选（SC-P-28）
POST /api/meal/replace；POST /api/diet/recommendation/update、/regenerate、/complete	食谱调整（SC-P-29「调整」）；「收藏」无端点 → 缺口 G-1
POST /api/nutrition/profile/get、/save	精准营养目标（SC-P-69，UserNutritionProfileController）
POST /api/diet/recommendation/generate	按营养目标生成/对齐（SC-P-30）
POST /api/health/nutrition/profile、/deficiency、/deficiency-summary、/trend	营养报告段（SC-P-69）

4.63.4 测评类型 / AI 对话（SC-P-31/49）

路径	说明
POST /api/dan-assessment/material/active、/material/list、/points-config、/family/config	测评类型浏览（DAN 材料/积分配置/家庭测评配置，SC-P-31）
POST /api/ai/chat/send、/health-coach/send、/health-coach/gate、/gate	AI 健康管家对话（SC-P-49，AiGateway.chat → LangGraph chat_graph；复用 langgraph.questionnaire.generate，仅登记不新建）

4.63.5 成长记录（SC-P-50/51）

路径	说明
POST /api/growth/record/list、/record/child/{memberId}、/record/child-records、/record/{id}、/record/{id}/supplements、/record/check-duplicate	成长记录查看（SC-P-50，复用 growth.history.view，仅登记不新建）
POST /api/family/relationship/milestones；POST /api/invite/milestone/list、/claim	关系/邀请里程碑（SC-P-51 主场景载体，成长里程碑无独立端点 → 缺口 G-2）

4.63.6 商城加购/下单（SC-P-54，EVD-4 已覆部分）

路径	说明
POST /api/cart/add、/list、/update、/remove、/count、/combo-offer、/replace-combo	购物车（CartController）
POST /api/product/order/create、/pay、/cancel、/my、/my/counts、/detail	商品订单（ProductOrderController；键归属 EVD-4 商城-会员批次 order.* 域，本批不新建键）

4.63.7 联系人 / 社交（SC-P-61~63）

路径	说明
POST /api/contact/create、/list、/detail、/interaction、/invite-to-family	联系人添加/详情/互动/邀请入家庭（SC-P-61/63）
POST /api/contact/import-phone	通讯录导入（SC-P-62，候选 ContactImportController 不存在；分组无端点 → 缺口 G-3）
POST /api/family/user/members/visible、/members/update-visibility	联系人/成员可见性权限（SC-P-63）
POST /api/health/report/member-permission/list、/grant、/revoke、/visible-members	报告查看权限（SC-P-63）

4.63.8 设置与通知（SC-P-64/65/66/78/79）

路径	说明
POST /api/user/update、/info、/profile/backfill、/profile-stats；POST /api/family/user/update；POST /api/profile/my	个人资料编辑（SC-P-64）
POST /api/notification/list、/read	消息中心/通知查看 + 已读（SC-P-65/78，UserNotificationController）
POST /api/task/reminder-config/get、/save	提醒设置（开关/渠道/时机/偏移，SC-P-65/79）
POST /api/consent/record、/withdraw、/status、/check	隐私授权同意（SC-P-66，ConsentController）
POST /api/notices/list	公告（SC-P-78，GET+POST 历史遗留）

4.63.9 舌诊/情绪采集 · 账号 · 活动 · 反馈 · 会话（SC-P-70/71/76/83/85）

路径	说明
POST /api/health/report/parse-preview（type=tongue）、/report/confirm（type=tongue）、/report/discard	舌诊照片采集（SC-P-70，TongueDiagnosisService 链）
POST /api/mind/checkin/create、/list、/latest、/trend、/stats、/emotion/recognize	情绪打卡/照片识别（SC-P-70，EmotionCheckinController）
POST /api/user/deactivate、/data-export	账号注销（AccountCleanupService.deactivateAccount 数据匿名化）+ 个保法可携带权导出（SC-P-71）
POST /api/activity/register、/cancel-registration、/my-registrations、/registration-roster、/checkin	活动报名（名额/并发，SC-P-76，ActivityRegistrationService.occupyQuota 原子占用名额）；POST /api/activity/order/create、/pay 付费活动
POST /api/health/feedback/submit、/list；POST /api/activity/feedback/submit、/list、/my；POST /api/feedback/today、/read、/recent	意见反馈（SC-P-83；在线客服无专用端点 → 缺口 G-4）
POST /api/auth/phone-login、/wechat-login、/silent-login、/auto-login、/sso-login、/sso-ticket	登录族 + SSO 一次性票据（SC-P-85；无单端互斥/旧会话踢出 → 缺口 G-5，JWT 无状态）

4.63.10 契约缺口（无完整端点载体，需产品侧确认验收方式）

SC	场景	现状	处置
SC-P-29	食谱收藏/调整	「调整」已存在（/api/meal/replace、/api/diet/recommendation/update	regenerate）；「收藏」无端点（仅指标收藏 /api/indicator/favorite/* 为异构）
SC-P-51	成长里程碑	GrowthController /api/growth 无里程碑端点；关系/邀请里程碑（/api/family/relationship/milestones、/api/invite/milestone/*）非成长；成长页里程碑为前端聚合	缺口 G-2，需产品侧确认
SC-P-62	联系人分组/导入	导入已存在（/api/contact/import-phone）；分组无端点	缺口 G-3，需产品侧确认
SC-P-83	意见反馈/在线客服	反馈已存在（/api/health/feedback/*、/api/activity/feedback/*、/api/feedback/*）；在线客服无专用端点	缺口 G-4，需产品侧确认
SC-P-85	多端登录/会话互斥	登录族 + SSO 票据存在；无单端互斥/旧 token 踢出（JWT 无状态）	缺口 G-5，需产品侧确认

文档更新：2026-11-07（EVD-13 家长域剩余 30 SC 契约核对增补「家长域剩余」段落 4.63：家庭与成员 / 健康报告上传解析 / 食谱营养 / 测评类型与 AI 对话 / 成长记录 / 商城加购下单 / 联系人与社交 / 设置与通知 / 舌诊情绪·账号·活动·反馈·会话 + 已 GREEN 键复用登记 4 处 + 契约缺口 5 项。完整核验表见 docs/superpowers/specs/2026-11-07-parent-rest-contract.md）

4.64 AI成长教练 + 真人管家域（SC-B-01~12 / SC-H-01~07，EVD-14 契约核对增补）

AI 成长教练（AI 管家）10 SC + 真人管家 7 SC = 17 SC 契约核对（EVD-14，开工包 docs/tdd/orchestration/ai-butler-kickoff-20261107.md）实测回填的端点存在性。完整核验表、语义偏差与缺口见 docs/superpowers/specs/2026-11-07-ai-butler-contract.md。 约定：所有端点 POST；/api/ai/* 走登录态 + checkGate(userId) 会员门禁（AiGateStatus.UPGRADE_REQUIRED 拦截）；/api/admin/butler/* 需 role=admin/finance（控制器内角色检查）；AI 统一走 AiGateway（熔断 failure-threshold=3 / reset-timeout-ms=30000，不可用时降级返回空或显式错误）。

4.64.1 成长咨询对话（AIChatController /api/ai，SC-B-01/B-11）

路径	说明
POST /api/ai/chat/send	成长咨询对话（会员门禁 + 家庭上下文/画像注入；LangGraph 不可用 → 空 answer/空 tasks 降级）
POST /api/ai/chat/conversations	会话历史列表（追问上下文全链路）
POST /api/ai/chat/messages	指定会话消息列表
POST /api/ai/chat/conversations/{id}/delete	删除会话

SC-B-01 咨询对话、SC-B-11 报告细节追问（同 conversationId 续聊）共用该组端点。

4.64.2 AI 会员门禁与隐私（AIChatController、PiisService、WechatService，SC-B-05）

路径	说明
POST /api/ai/gate	AI 教练会员门禁状态（membershipService.checkAiFeatureGate → status/enabled/canUse/features）
POST /api/ai/health-coach/gate	健康教练会员付费开关状态（兼容保留，前端统一改调 /api/ai/gate）

⚠ 语义口径：上两 gate 为会员付费门禁，非敏感词/内容门控。敏感问题拦截与隐私保护的实际载体 = PiisService PII 脱敏（姓名→化名、手机号/身份证/邮箱/地址→[已脱敏]）接入 AI 输入侧；WechatService.msg_sec_check（文本内容安全检测）仅用于文章/媒体发布链路，不在教练对话链路。无独立敏感词拦截端点（缺口，见契约文档 §2.2）。

4.64.3 健康教练跟进与主动成长提醒（AIChatController /api/ai，SC-B-02/B-12）

路径	说明
POST /api/ai/health-coach/send	健康教练定向跟进：会员门禁 + focus/memberId/画像注入，解析 [RECOMMEND] + [TASK] 标记

⚠ SC-B-12「同步规划师建议主动跟进」当前为用户发起式（health-coach/send focus 定向），无服务端定时推送端点；task/ 包 @Scheduled 仅业务提醒（BASIC 到期/佣金结算等）。验收按用户主动触发口径。

4.64.4 成长报告智能解读（AIChatController /api/ai，SC-B-04）

路径	说明
POST /api/ai/report/analyze	成长报告智能解读（LangGraph 解析；不可用时返回「AI服务暂不可用」显式错误）

4.64.5 营养/任务推荐与采纳（AIChatController /api/ai，SC-B-07）

路径	说明
POST /api/ai/nutrition/send	营养推荐：reportId 必填 → 菌群分析（HealthAnalysisService.analyze）→ 家庭上下文/画像注入 → LangGraph 解析 [RECOMMEND]（parseSimpleJson）+ [TASK] 生成任务列表

推荐采纳载体为 nutrition/send（TASK 即为采纳入口）；/api/butler/commissions 已废弃 410（见 4.64.7 废弃清单）。

4.64.6 真人管家后勤与家庭自助选择（butler/ButlerController、FamilyButlerSelectController /api/butler，SC-B-01/B-10）

路径	说明
POST /api/butler/apply	申请成为真人管家（并 SC-B-01 场景载体之一）
POST /api/butler/profile	管家个人资料详情
POST /api/butler/update-profile	更新管家资料
POST /api/butler/members	管家绑定家庭成员列表（家庭成长看板单体载体）
POST /api/butler/available-list	可选择的管家列表（浏览开放）
POST /api/butler/my-butler	我的管家信息
POST /api/butler/select	家庭自助选择管家（L2 绑定受限校验，ButlerService.selectButler）

⚠ SC-B-09「教练转接成长规划师」实际载体为规划师绑定流：/api/guide/bind/invite → /validate → /confirm（BindInviteController）+ /api/bind/accept、/api/bind/unbind（BindController）；/api/butler/apply|select 是管家申请/选管家，非转接。 ⚠ SC-B-10 聚合台账以 admin 侧为准确认（4.64.8），家庭端复用 /api/butler/members 单体。

4.64.7 已废弃端点（410，本域旧载体）

路径	状态
POST /api/butler/service-records	@Deprecated 410（无替代方案提示）；台账替代 = /api/admin/butler/service-records
POST /api/butler/commissions	@Deprecated 410（无替代方案提示）；结算替代 = /api/admin/butler/settlements

4.64.8 真人管家运营管理（AdminButlerController /api/admin/butler，SC-H-01~05/07）

路径	说明
POST /api/admin/butler/user-list	用户维度管家列表
POST /api/admin/butler/list	管家列表（资源清单载体）
POST /api/admin/butler/review	管家申请审核（升级介入，SC-H-01）
POST /api/admin/butler/assign-member	指派管家到家庭（一对一家长陪跑，SC-H-02）
POST /api/admin/butler/service-records	服务记录台账（多方沟通记录 / 质检台账，SC-H-03/H-07；分页）
POST /api/admin/butler/settlements	佣金结算列表（月结 calculateButlerSettlement，SC-H-07）
POST /api/admin/butler/assignments	管家-家庭分配关系列表（SC-H-01/H-03）
POST /api/admin/butler/unassign	解绑管家-家庭（SC-H-04，⚠ 语义：停接/解绑运维开关，非应急接管）
POST /api/admin/butler/toggle-accepting	管家接单开关（SC-H-04，⚠ 语义间接：应急处理验收口径需产品确认）

服务记录由 ButlerCommissionService.createServiceRecord(butlerId, memberUserId, amount, remark) 落库（butler_service_records），结算由 ButlerCommissionScheduledTask 月结触发。

4.64.9 AI 管家会话（ai/ButlerController /api/ai/butler，SC-H-06 协同的会话底座）

路径	说明
POST /api/ai/butler/sessions/create	创建 AI 管家会话
POST /api/ai/butler/sessions/update-conversation	更新会话绑定 conversationId
POST /api/ai/butler/sessions/archive	归档会话
POST /api/ai/butler/sessions/list	会话列表
POST /api/ai/butler/sessions/detail	会话详情
POST /api/ai/butler/sessions/delete	删除会话

4.64.10 AI→真人管家协同与资源对接（AIChatController、GuideActivityController，SC-H-05/H-06）

路径	说明
POST /api/ai/butler/send	AI→管家协同：会员门禁 + child_id/report_id/focus + 画像注入 → answer/tasks（SC-H-06 主载体）
POST /api/guide/activities/list（及 CRUD 组）	规划师端线下活动创建/编辑/发布（GuideActivityController，SC-H-05 活动对接实际载体）

⚠ SC-H-05「线下资源与活动对接」：/api/ai/gate 为会员门禁，非资源/活动对接；资源清单 = /api/admin/butler/list，活动载体 = /api/guide/activities/*。验收语义需产品确认。

4.64.11 契约缺口与语义待确认（不建伪实现任务）

SC	场景	现状	处置
SC-B-05	敏感词门控	无独立教练对话敏感词拦截端点；隐私载体=PiisService PII 脱敏；msg_sec_check 仅文章/媒体链路	以 PII 脱敏 + 会员门禁验收，敏感拦截需产品确认
SC-B-12	主动跟进	无规划师建议定时推送端点；health-coach/send 为用户发起式	验收按用户主动触发口径
SC-B-06	Fallback	AiGateway 熔断+超时 → null → 空 Map 降级 / report/analyze 显式错误；无内容级 mock 兜底	按空降级+显式错误验收
SC-H-04	升级与应急	unassign/toggle-accepting 为停接/解绑开关，语义间接	需产品确认应急处理验收口径
SC-H-05	资源/活动对接	活动载体在 /api/guide/activities/*（非本域新增）	需产品确认验收语义

文档更新：2026-11-07（EVD-14 AI成长教练 10 SC + 真人管家 7 SC 契约核对增补「AI成长教练 + 真人管家域」段落 4.64：成长咨询对话 / AI 会员门禁与隐私 / 健康教练跟进 / 报告智能解读 / 营养任务推荐 / 真人管家后勤与家庭自助选择 / 已废弃 410 / 真人管家运营管理 / AI 管家会话 / AI→真人管家协同与资源对接 + 契约缺口。完整核验表见 docs/superpowers/specs/2026-11-07-ai-butler-contract.md）

4.65 跨角色域剩余（SC-X-03/08/11/14/15/16/17/18，EVD-15 契约核对增补）

跨角色域 22 个 SC（SC-X-01~22）中已由既有开工包覆盖 13 个（测评-方案 EVD-8R：X-01/06/09；报告闭环 EVD-7R：X-02/10/13；任务-心愿 EVD-3：X-05；五维能量 EVD-5：X-19/20/21；商城-会员 EVD-4：X-07/12；家庭-成员 EVD-2：X-04；CF 值预估 TR-5：X-22）；本批 = 剩余 8 个无键 SC，端点载体逐条实测核验。完整核验表与实现缺口见 docs/superpowers/specs/2026-11-07-cross-role-contract.md。 约定：所有端点 POST；越权语义统一 403（FamilyAccessInterceptor enforcement 模式 + canAccessFamily）。 命名回填：SC-X-03 候选 ParentController 实为心愿单 /api/parent/wishlist*（非视角切换，视角切换 = /api/family/member/switch + /api/auth/switch-role）；SC-X-08 候选 AdminArticleController /api/admin/article/* 实际为 /api/admin/articles（带 s）。

4.65.1 双角色数据隔离越权（SC-X-03）

路径	说明
POST /api/family/member/add、/list、/switch、/kick、/leave、/recycle、/update、/rename-family、/editable、/logs	成员 CRUD/权限（FamilyMembersController，canAccessFamily 校验有效家庭集，越权 403；/switch 切成员/孩子上下文视角 SwitchMemberVO）
POST /api/family/teacher-bindings/pending、/approve、/reject、/my-requests、/cancel	规划师绑定审核（TeacherFamilyBindingController）
POST /api/auth/switch-role	角色切换（switchRoleForLogin 重签 token，权限提升须登录，JwtInterceptor 强制登录）
POST /api/parent/wishlist、/wishlist/list、/wishlist/family、/wishlist/{id}/approve、/wishlist/{id}/exchange	家庭主账号心愿单（ParentController——命名回填：非视角切换）

越权语义载体：FamilyAccessInterceptor（请求携带 familyId 必须属于调用者有效家庭集，enforcement 模式越权 → 403「无权访问该家庭数据」，注册于 WebConfig.addInterceptors）+ FamilyMembersController.canAccessFamily（控制器内 403）。

4.65.2 文章发布闭环（SC-X-08）

路径	说明
POST /api/article/publish、/my-posts、/updated-since、/detail、/list、/featured、/record-read、/related、/related-products、/audio、/report-reading-time、/reading-stats、/daily-tip	文章发布/详情/列表（ArticleController，/api/articles 与 /api/article 双前缀兼容）
POST /api/articles/categories	文章分类（ArticleCategoryController）
POST /api/articles/comments/list、/create、/audit、/pending、/my；/quiz/generate、/quiz/submit	文章评论 + 答题（ArticleCommentController）
POST /api/admin/articles/list、/create、/update、/detail、/delete、/{id}/publish、/publish、/audit、/submit-review、/withdraw、/re-draft、/toggle-featured、/move、/upload/image、/upload/video、/comments/list、/categories/list、/categories/create、/categories/update、/categories/delete、/reading-records	文章管理端审核/上架/下架（AdminArticleController，路径带 s：/api/admin/articles）
POST /api/admin/review-center/summary	审核中心汇总（ReviewCenterController）

闭环 = 发布→审核→上架→评论，端点齐全 ✅。

4.65.3 消息通知闭环（SC-X-11）

路径	说明
POST /api/notification/list、/read	站内消息查看 + 已读（UserNotificationController，已读闭环）
POST /api/admin/notification-template/list、/save、/delete	通知模板/通道配置（AdminNotificationTemplateController）
NotificationDispatchService.sendByTemplate(type,userId,vars,refType,refId,defaultTitle,defaultContent)	通知发送统一入口（W3 五通道：in_app/sms/wechat/gzh/phone；in_app + wechat-webhook 投产，sms/gzh/phone/wechat-订阅 预留禁用）
InAppNotificationChannel（isEnabled=true）	站内通道，写 user_notifications 表
WebhookNotificationChannel（channelType=wechat，isEnabled=true）	微信待办 webhook 通道，复用 WechatWaitMsgService.sendWaitMsg（按用户手机号定向 msgLabel）

事件触发 = 10 个 service 调 sendByTemplate（TaskService/PointsService/EnergyService/CfBalanceServiceImpl/CouponGiftService/DanReportUploadService/ProblemCompletionService/ProcurementTaskService/ReportTransferService/TaskReminderScheduledTask）。⚠ 部分存在：订单/活动/支付事件（ProductOrderController/ActivityOrderController/VirtualPayController）未挂接统一分发；微信订阅消息通道未接入 → 缺口 X-G-1。

4.65.4 解绑/重分配跨角色协同（SC-X-14）

路径	说明
POST /api/bind/accept、/guides、/unbind	家庭绑定/解绑（BindController）
POST /api/family/invite/generate、/validate、/request-join-by-code、/approve-request、/reject-request、/pending-requests、/my-request、/cancel-request、/bind-inviter、/accept、/check-family、/revoke、/transfer-admin	邀请重分配/管理员转移（FamilyInviteController）
POST /api/cf/transfer/send、/list	CF 余额转移（CfTransferController）

协同 = 规划师/成员解绑（/unbind）+ 成员数据重分配（/transfer-admin、/revoke）+ CF 转移。

4.65.5 注销/数据导出跨角色（SC-X-15）

路径	说明
POST /api/user/deactivate	账号注销（AccountCleanupService.deactivateAccount：匿名化主账号 openid 哈希 + realName/idCard/phone/unionid/nickname/avatar/address/sessionKey 清空 + deleted=1，匿名化关联 family_member 记录，处理 PaymentOrder(familyId)/AssessmentOrder(userId)）
POST /api/user/data-export	个保法可携带权导出（AccountCleanupService.exportUserData）

跨角色语义 = 家长注销后家庭成员记录/家庭订单处理。

4.65.6 活动名额并发（SC-X-16）⭐

路径	说明
POST /api/activity/register、/cancel-registration、/my-registrations、/registration-roster、/checkin、/checkin-review	活动报名/取消/名单/签到（ActivityController）
ActivityRegistrationService.occupyQuota	原子占用名额：UPDATE activity SET approved_count=approved_count+1 WHERE id=? AND approved_count<max_participants（返回 rows>0，多端并发报名不超发；releaseQuota 原子回退）
POST /api/activity/order/create、/pay、/notify、/status	付费活动订单（ActivityOrderController）

并发语义 = 同名额多端并发报名不超发，载体 = occupyQuota 条件自增（DB 行锁）。

4.65.7 多端登录会话互斥（SC-X-17）

路径	说明
POST /api/auth/wechat-login、/silent-login、/phone-login、/switch-role、/sso-ticket、/sso-login、/verify、/verifyToken	登录族 + token 签发/校验（AuthController）
POST /api/auth/wechat-web/qr、/scan、/poll	微信 web 登录（WechatWebAuthController）
JwtInterceptor	token 签名/过期校验（无效/过期 → 401，公开路径降级匿名放行）

⚠ 互斥无载体：无 token 互斥/单点踢下线（无 tokenVersion/kickout/blacklist/会话注册表；JWT 无状态；SSO 为一次性免登票据非互斥踢出）→ 缺口 X-G-2（同因 EVD-13 SC-P-85 G-5）。

4.65.8 推送跨端送达（SC-X-18）

路径	说明
WechatService.sendTemplateMessage(toUserOpenid, templateId, keywordMap)	公众号模板消息（/cgi-bin/message/template/send，调用方 WechatAlertTemplateService/PromotionTierEvalService）
WechatWaitMsgService.sendWaitMsg(content, label)	微信待办 webhook 定向推送（调用方 WebhookNotificationChannel）
POST /api/internal/virtual-pay/notify（GET URL 验证 + POST 签名校验）	微信虚拟支付消息推送接收端点（VirtualPayController，非主动推送）

⚠ 部分存在：小程序订阅消息（requestSubscribeMessage/subscribeMessage）前后端全仓 0 命中，WechatNotificationChannel isEnabled=false 预留禁用；cfc-langgraph 无推送载体 → 缺口 X-G-3。

4.65.9 契约缺口（无完整端点载体，需产品侧确认验收方式）

SC	场景	现状	处置
SC-X-11	消息通知闭环（事件挂接/订阅通道）	五通道框架完整（in_app + wechat-webhook 投产）；订单/活动/支付事件未挂接统一分发；微信订阅消息通道 WechatNotificationChannel 预留禁用	缺口 X-G-1，需产品侧确认
SC-X-17	多端登录会话互斥	登录族 + JwtInterceptor token 校验存在；无 token 互斥/单点踢出（JWT 无状态）	缺口 X-G-2，需产品侧确认（同因 EVD-13 SC-P-85 G-5）
SC-X-18	推送跨端送达	公众号模板消息 + 微信待办 webhook 已投产；小程序订阅消息（requestSubscribeMessage/subscribeMessage）前后端 0 命中，WechatNotificationChannel 预留禁用；cfc-langgraph 无推送	缺口 X-G-3，需产品侧确认

本批仅登记缺口不实现，转产品/运维侧确认后由后续批次落地。 文档更新：2026-11-07（EVD-15 跨角色域剩余 8 SC 契约核对增补「跨角色域剩余」段落 4.65：双角色数据隔离越权 / 文章发布闭环 / 消息通知闭环 / 解绑重分配 / 注销数据导出 / 活动名额并发 / 多端登录互斥 / 推送跨端送达 + 命名回填 2 处 + 契约缺口 3 项。完整核验表见 docs/superpowers/specs/2026-11-07-cross-role-contract.md）