# 浠艾福（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 对话 | — |
| `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） | — |
| `ContactController` | `/api/contact` | 联系人 CRUD/互动/邀请入家庭 | — |
| `ContactMatchController` | `/api/contact/match` | 联系人对接（send/accept/reject/列表） | — |
| `OctopusController` | `/api/octopus` | 章鱼图（帮助记录/触手聚合） | — |
| `PearlController` | `/api/pearl` | 珍珠图（25 类社会连接聚合 + 互动/提醒/优先级） | — |
| `AbilityController` | `/api/ability` | 能力图（SKILL 帮助记录聚合为能力节点） | — |

---

## 三、已废弃接口清单

> 标记 `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 或 `{}`）

**响应**：
```json
{
  "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` 回收
- **无关联用户的手动成员**：直接删除记录

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

**请求体**：
```json
{
  "memberId": 12345
}
```

**响应**：
```json
{
  "code": 200,
  "message": "踢出成功",
  "data": null
}
```

---

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

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

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

**请求体**：
```json
{
  "memberId": 12345,
  "targetFamilyId": 67890
}
```

**响应**：
```json
{
  "code": 200,
  "message": "回收成功",
  "data": null
}
```

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

---

### 4.2 Family Invite 接口详细

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

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

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

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

---

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

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

**请求体**：
```json
{
  "familyInviteCode": "fam_abc123"
}
```

**响应**：
```json
{
  "code": 200,
  "message": "绑定成功",
  "data": null
}
```

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

---

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

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

**请求体**：
```json
{
  "token": "abc123def456"
}
```

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

---

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

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

**响应**：
```json
{
  "code": 200,
  "data": {
    "inFamily": true,
    "familyId": 100,
    "familyName": "张三的家庭",
    "isAdmin": true
  }
}
```

---

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

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

**请求体**：无额外参数

**响应**：
```json
{
  "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` — 批准加入申请

**请求体**：
```json
{
  "requestId": 1001,
  "comment": ""
}
```

**响应**：
```json
{
  "code": 200,
  "message": "已同意"
}
```

---

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

**请求体**：
```json
{
  "requestId": 1001,
  "comment": "不符合条件"
}
```

**响应**：
```json
{
  "code": 200,
  "message": "已拒绝"
}
```

---

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

**请求体**：无额外参数

**响应**：
```json
{
  "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/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/exercise/list` | 运动打卡列表 |
| `POST /api/health/exercise/create` | 创建运动打卡（支持 stepCount 微信步数） |
| `POST /api/health/exercise/sync-wechat-steps` | 同步微信运动步数（传 encryptedData+iv，返回当日步数与近30天数据） |

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

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

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

| 路径前缀 | 说明 |
|----------|------|
| `/api/admin/articles/*` | 文章管理 |
| `POST /api/admin/articles/move` | 调整精选文章的推荐顺序（`{ id, direction: 'up'|'down' }`，已边界时返回 400） |
| `/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）：
```json
{ "memberId": 123, "memberType": "child", "familyId": 1 }
```

**numsoul 请求参数**：
```json
{ "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 结构：**
```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` | 删除商品 |

### 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`。

---

### 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` 请求体：**
```json
{
  "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` 响应结构：**
```json
{
  "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 端点 — 禁止重复注册。**

## 六、待清理的废弃接口

| 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）

返回：
```json
{
  "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`**

请求体：
```json
{ "image_url": "https://cdn.example.com/photo.jpg" }
```

返回：同上。

---

*文档最后更新：2026-09-13*