# 浠艾福（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 新增接口检查清单

```bash
# 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}/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.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*