|
@@ -226,4 +226,73 @@ cd cfc-langgraph && pip install -r requirements.txt && uvicorn src.app:app --por
|
|
|
|
|
|
|
|
## 后端接口规范
|
|
## 后端接口规范
|
|
|
|
|
|
|
|
-- 后台/api的接口规范都用post方式
|
|
|
|
|
|
|
+- 后台/api的接口规范都用post方式
|
|
|
|
|
+
|
|
|
|
|
+## 家庭成员列表接口规范
|
|
|
|
|
+
|
|
|
|
|
+### 统一接口：`POST /api/family/member/list`
|
|
|
|
|
+
|
|
|
|
|
+**唯一入口**，所有获取家庭成员信息的需求必须调用此接口。
|
|
|
|
|
+
|
|
|
|
|
+**替代（已废弃，请勿新增调用）：**
|
|
|
|
|
+- `POST /api/family/user/family-members` — 返回 Map 格式，信息分散在 parents + children 两块
|
|
|
|
|
+- `POST /api/family/user/members/visible` — 只返回 `show_to_family=1` 的部分
|
|
|
|
|
+- `POST /api/family/user/children/list` — 只返回孩子，不包含家长
|
|
|
|
|
+- `POST /api/user/children/list` — 同上，重复路由
|
|
|
|
|
+
|
|
|
|
|
+**请求：**
|
|
|
|
|
+```json
|
|
|
|
|
+// 可选的过滤参数
|
|
|
|
|
+{
|
|
|
|
|
+ "visibleOnly": true, // 仅返回 show_to_family=1 的成员（默认false）
|
|
|
|
|
+ "includeFamily": true // 是否包含家庭信息（familyId/name/inviteCode，默认false）
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**返回：** `Result<List<FamilyMemberVO>>`
|
|
|
|
|
+
|
|
|
|
|
+**`FamilyMemberVO` 字段说明：**
|
|
|
|
|
+
|
|
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
|
|
+|------|------|------|
|
|
|
|
|
+| `id` | Long | family_members.id |
|
|
|
|
|
+| `source` | String | `family_member` 或 `parent` |
|
|
|
|
|
+| `userId` | Long | 关联的用户ID |
|
|
|
|
|
+| `nickname` | String | 昵称 |
|
|
|
|
|
+| `phone` | String | 手机号 |
|
|
|
|
|
+| `avatar` | String | 头像 |
|
|
|
|
|
+| `gender` | String | male/female |
|
|
|
|
|
+| `age` | Integer | 年龄（由 birthday 实时计算） |
|
|
|
|
|
+| `effectiveRole` | String | parent/child/teacher |
|
|
|
|
|
+| `roleLabel` | String | 关系标签（如"爸爸""妈妈""爷爷""奶奶"） |
|
|
|
|
|
+| `generation` | Integer | 辈分值 |
|
|
|
|
|
+| `isSpouse` | Boolean | 是否配偶 |
|
|
|
|
|
+| `isAdmin` | Boolean | 是否家庭管理员 |
|
|
|
|
|
+| `isSelf` | Boolean | 是否当前用户自己 |
|
|
|
|
|
+| `totalPoints` | Integer | 总积分 |
|
|
|
|
|
+| `showToFamily` | Integer | 对家庭成员可见性（1=可见, 0=不可见） |
|
|
|
|
|
+| `trustScore` | BigDecimal | 信任度 0-100 |
|
|
|
|
|
+| `intimacyScore` | BigDecimal | 亲密度 0-100 |
|
|
|
|
|
+| `communicationScore` | BigDecimal | 沟通质量 0-100 |
|
|
|
|
|
+| `memberType` | String | 成员类型（parent/child） |
|
|
|
|
|
+
|
|
|
|
|
+**后端实现：**
|
|
|
|
|
+- Controller: `FamilyMembersController.listMembers()` → `FamilyMemberService.listMembers()`
|
|
|
|
|
+- 传入 `visibleOnly=true` 时，调用 `FamilyMemberService.listMembers()` 后按 `show_to_family` 过滤
|
|
|
|
|
+- 不传 `familyMemberId` 参数，根据 JWT 的 userId 自动获取用户的 `familyId`
|
|
|
|
|
+
|
|
|
|
|
+**前端调用：**
|
|
|
|
|
+```js
|
|
|
|
|
+import { getFamilyMemberList } from '@/utils/api.js'
|
|
|
|
|
+// 已封装为：request('/api/family/member/list', 'POST', { visibleOnly: true })
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**新增成员相关接口：**
|
|
|
|
|
+| 功能 | 路径 | 说明 |
|
|
|
|
|
+|------|------|------|
|
|
|
|
|
+| 添加成员 | `POST /api/family/member/add` | 创建新家庭成员 |
|
|
|
|
|
+| 更新成员 | `POST /api/family/member/update` | 修改成员信息 |
|
|
|
|
|
+| 踢出成员 | `POST /api/family/member/kick` | 删除成员 |
|
|
|
|
|
+| 切换视角 | `POST /api/family/member/switch` | 切换到指定成员视图 |
|
|
|
|
|
+| 检查编辑 | `POST /api/family/member/editable` | 检查成员是否可编辑 |
|
|
|
|
|
+| 变更日志 | `POST /api/family/member/logs` | 成员变更历史 |
|
