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 对话	—
ArticleController	/api/articles	文章	—
NotificationController	/api/notification	通知	—
StatsController	/api/stats	统计	—

---

三、已废弃接口清单

标记 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/update	更新成员信息	—
POST /api/family/member/editable	检查是否可编辑	—
POST /api/family/member/logs	成员变更日志	—
POST /api/family/invite/qrcode	生成邀请二维码	—
POST /api/family/invite/request-join-by-code	申请加入	inviteCode
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	生成邀请令牌	—
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	转让管理员	—

4.3 任务（/api/tasks）

路径	说明
POST /api/tasks/minigame-options	小游戏选项
POST /api/tasks/create	创建任务
POST /api/tasks/today	今日任务
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	健康教练
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	今日推荐
POST /api/diet/recommendation/generate	生成推荐
POST /api/diet/recommendation/complete	完成推荐
POST /api/diet/record/save	保存饮食记录
POST /api/diet/record/daily	每日记录
POST /api/diet/ingredients/suggest	食材推荐
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/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/*	文章管理
/api/admin/assessment/*	测评材料管理
/api/admin/bazi-config/*	八字配置
/api/admin/blood-type-config/*	血型配置
/api/admin/commission/*	佣金管理
/api/admin/dimension/*	维度配置
/api/admin/dimension-config/*	维度权重
/api/admin/energy/*	能量配置
/api/admin/knowledge-base/*	知识库管理
/api/admin/package-templates/*	套餐模板
/api/admin/product/*	商品管理
/api/admin/report-parser/*	报告解析配置
/api/admin/supply-*	供应链相关
/api/admin/system/*	系统配置
/api/admin/unlock-gates/*	通关配置
/api/migration/run	数据迁移

4.14 统计与通知（/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.15 其他接口

路径	说明
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/*	保险规划

---

五、新增接口流程

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 验证

---

六、待清理的废弃接口

Controller	废弃接口	替代方案	清理条件
FamilyController	/invite-code, /invite-code/generate	/api/family/invite/generate	确认前端无调用
FamilyUserController	/switch-mode, /switch-to-child, /switch-back-to-parent, /switch-back-verify	/api/family/member/switch	确认前端无调用
ButlerController	/service-records, /commissions	—	无替代，可删除
TeacherController	全部 /api/teacher/* 方法	/api/guide/families/*	确认规划师端无调用
DanAssessmentController	/current（获取当前测评）	—	无前端调用方
NoticeController	GET /list（违反 POST 规范）	—	重构为 POST

---

文档最后更新：2026-08-18