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	生成邀请令牌（复用同家庭未过期未用尽的有效令牌；仅未过期记录计入 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	转让管理员	—

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	健康教练（请求体可选字段 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	今日推荐
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/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/knowledge-base/*	知识库管理
/api/admin/notices/*	公告管理
/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/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 报告模板管理（/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.16 其他接口

路径	说明
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.17 日常任务聚合（/api/daily-task/*）

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

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

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

4.19 家庭成员关系质量（/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.20 佣金管理（/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.21 管理端-能量配置（/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.22 管理端-公告（/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.23 管理端-成长规划师（/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.24 管理端-商品（/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.25 管理端-成长档案关联商品（/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.26 管理端-电商供应商（/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.27 管理端-测评材料（/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.28 管理端-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.29 管理端-报告解析（/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.30 家庭管家选择（/api/butler/*）

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

---

六、待清理的废弃接口

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-08-23