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 成员间转让	—
AdminCfRateTierController	/api/admin/cf-rate-tier	CF 返佣阶梯配置（admin）	—

---

三、已废弃接口清单

标记 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	更新成员信息	—
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	行为	返回字段
cart	自动加购，返回加购结果	execution.extra 含 cartAdded=true、productId、quantity
order	先加购，再创建 pending 订单	execution.extra 含 orderId、orderNo（成功时）或 orderFailed=true、orderError（失败时）

下单失败常见原因： 缺默认收货地址、商品已下架、库存不足、配送方式校验失败。失败时加购结果保留，任务状态正常置 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/health-status/get	健康现状档案获取
POST /api/health-status/save	健康现状档案保存

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/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	餐食配置

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	区块列表

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/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/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	佣金转化漏斗

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	删除商品

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。

路径	说明
POST /api/admin/coupon/list	优惠券模板列表（admin）
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? }（admin，返回 family_coupon_grant_log）
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	结算页可兑换未拥有券

---

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

CF 值（平台积分）统一分佣体系：普通订单双返（当前消费人 + 推荐人按团队规模阶梯分润），会员/订阅只返推荐人，同家庭互推跳过本人上溯。

路径	说明
POST /api/commission/cf/rate	我的团队规模 + 当前返佣比例 + 档位名。返回 { totalTeamSize, ratePercent, tierName }（未入档时 ratePercent=0、tierName="未入档"）
POST /api/commission/cf/summary	我的 CF 钱包汇总，返回 PlatformBalanceService.getBalance(userId) 结果
POST /api/commission/cf/list	我的 CF 流水（分页），请求 { page, size }，返回 Page<PlatformBalanceLog>

阶梯档位（cf_rate_tier，管理端可配置）：

团队规模（min_team_size）	档位	返佣比例
0~2	铜牌	5%
3~9	银牌	10%
10~29	金牌	15%
30~99	铂金	20%
100+	钻石	25%

匹配语义：enabled=1 AND min_team_size <= teamSize ORDER BY min_team_size DESC LIMIT 1。

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。

---

六、待清理的废弃接口

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	可删除

---

文档最后更新：2026-09-02