|
|
@@ -77,6 +77,9 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
|
|
|
| `OctopusController` | `/api/octopus` | 章鱼图（帮助记录/触手聚合） | — |
|
|
|
| `PearlController` | `/api/pearl` | 珍珠图（25 类社会连接聚合 + 互动/提醒/优先级） | — |
|
|
|
| `AbilityController` | `/api/ability` | 能力图（SKILL 帮助记录聚合为能力节点） | — |
|
|
|
+| `ServiceRoleApplicationController` | `/api/service-role` | 统一服务角色申请（多角色合一 + 管理端审批） | — |
|
|
|
+| `GuideTeamController` | `/api/guide/team` | 规划师团队/邀请码/上下级 | — |
|
|
|
+| `GuideFamilyTaskController` | `/api/guide/families` | 规划师侧家庭任务管理 + 家庭解绑 | — |
|
|
|
|
|
|
---
|
|
|
|
|
|
@@ -1397,4 +1400,67 @@ interactionType 取值：`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
|
|
|
|
|
|
---
|
|
|
|
|
|
-*文档最后更新：2026-09-29*
|
|
|
+### 4.44 统一服务角色申请（`/api/service-role/*`）
|
|
|
+
|
|
|
+多角色（规划师/营养师/管家/供应商/内容管理员/活动策划）统一申请入口，一次提交可含多个角色，管理端审批通过后回写 `users.roles` 并按角色初始化附属记录。
|
|
|
+
|
|
|
+| 路径 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `POST /api/service-role/apply` | 提交服务角色申请（`roles` 必填） |
|
|
|
+| `POST /api/service-role/my-apply` | 查询我的最新申请记录 |
|
|
|
+| `POST /api/service-role/upload-image` | 上传身份证/资质证书图片（multipart，字段名 `file`） |
|
|
|
+| `POST /api/service-role/admin/list` | 管理端：申请列表（`status` 查询参数，默认 `0`） |
|
|
|
+| `POST /api/service-role/admin/approve` | 管理端：批准（`{ id }`） |
|
|
|
+| `POST /api/service-role/admin/reject` | 管理端：驳回（`{ id, reason }`） |
|
|
|
+
|
|
|
+**状态语义**（`service_role_applications.status`）
|
|
|
+
|
|
|
+| 值 | 含义 |
|
|
|
+|----|------|
|
|
|
+| `0` | 待审核（同一 userId 仅允许一条待审，重复提交返回「您已提交过申请，请等待审核」） |
|
|
|
+| `1` | 已通过 |
|
|
|
+| `2` | 已驳回（原因存 `reject_reason`） |
|
|
|
+
|
|
|
+**POST `/api/service-role/apply`** 请求体（`ServiceRoleApplyDTO`）
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| `roles` | List\<String\> | 申请角色，`@NotEmpty` 至少一个 |
|
|
|
+| `idCard` | String | 身份证号 |
|
|
|
+| `idCardImages` | List\<String\> | 身份证图片 URL 数组（落库转 JSON 字符串） |
|
|
|
+| `certificateImages` | List\<String\> | 资质证书图片 URL 数组 |
|
|
|
+| `province` / `city` / `district` / `street` | String | 四级地址 |
|
|
|
+| `addressDetail` | String | 详细地址 |
|
|
|
+
|
|
|
+**审批通过后的角色落地规则**（`ServiceRoleApplicationServiceImpl.approve`）
|
|
|
+
|
|
|
+| 申请角色 | 副作用 |
|
|
|
+|----------|--------|
|
|
|
+| `planner` | `guides` 新增一行（`status=active`）+ `users.roles` 追加 `teacher` |
|
|
|
+| `nutritionist` | `users.nutritionist_status=approved` + `roles` 追加 `nutritionist` |
|
|
|
+| `butler` | `users.butler_status=approved` + `butler_profiles` 新增一行 + `roles` 追加 `butler` |
|
|
|
+| `vendor` | `users.vendor_status=approved` + `roles` 追加 `supplier` |
|
|
|
+| `article_admin` | `users.article_admin_status=approved` + `roles` 追加 `knowledge_admin` |
|
|
|
+| `activity_provider` | `users.activity_provider_status=approved` + `roles` 追加 `activity_manager` |
|
|
|
+
|
|
|
+> **注意**：approve/reject 仅对 `status=0` 的记录生效，已处理返回「该申请已处理」。
|
|
|
+> `upload-image` 对图片类型文件先走 `wechatService.checkImage()` 内容安全检测，未通过直接拒绝。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 4.45 规划师解除家庭绑定（`POST /api/guide/families/unbind`）
|
|
|
+
|
|
|
+| 路径 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `POST /api/guide/families/unbind` | 规划师解除自己名下的家庭绑定（请求体 `{ id }`，即 `guide_families.id`） |
|
|
|
+
|
|
|
+- 角色校验：仅 `role=teacher` 可调用，否则返回 `Access denied`。
|
|
|
+- 归属校验：`GuideFamilyService.unbindByGuide()` 按 `id + guide_id + status='binding'` 定位，只能解除属于自己的绑定。
|
|
|
+- 副作用：将 `guide_families.status` 置为 `cancelled`。
|
|
|
+- 家长侧解绑为独立接口 `POST /api/bind/unbind`（按 familyId 定位，并通知规划师）。
|
|
|
+
|
|
|
+> **注意**：前端 `unbindFamily(id)` 需传 `guide_families.id`（绑定记录 ID），不是 `familyId`。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+*文档最后更新：2026-10-04*
|
iwt