# 需求分析报告：成长规划师功能

## 一、原始需求（从对话中提取）

### 需求1：首次登录角色选择
**描述**：用户第一次登录时，要显示一个页面让用户先选择是成长规划师、家长还是孩子，再进入详情页更新信息。

**关键要素**：
- 首次登录时显示角色选择页面
- 可选角色：成长规划师、家长、孩子
- 选择角色后进入信息完善页面

### 需求2：成长规划师信息录入
**描述**：成长规划师录入身份证、性别、照片和成长规划师证书号。

**关键要素**：
- 必填字段：身份证号、性别、照片、证书号
- 这些字段仅成长规划师需要填写

### 需求3：成长规划师查看家庭任务
**描述**：成长规划师可查看关联家庭的任务执行情况。

**关键要素**：
- 成长规划师可以查看所关联家庭的任务
- 需要有"关联家庭"的绑定机制

### 需求4：成长规划师审核任务
**描述**：成长规划师可审核家长及孩子的任务完成。

**关键要素**：
- 成长规划师可以审核任务（通过/拒绝）
- 支持单个任务审核和批量审核

### 需求5：分享码绑定家庭
**描述**：通过分享码给家长，家长注册或登录确认绑定。

**关键要素**：
- 成长规划师有分享码（邀请码）
- 家长使用分享码绑定成长规划师
- 家长注册或登录时可以使用邀请码

### 需求6：接受家长咨询
**描述**：接受家长咨询。

**关键要素**：
- 家长可以联系成长规划师
- 需要有沟通渠道

### 需求7：调整任务
**描述**：调整任务（成长规划师可以修改家庭成员的任务）。

**关键要素**：
- 成长规划师可以修改/删除家长或孩子创建的任务
- 需要有任务调整的权限

---

## 二、需求与实现对照

### ✅ 需求1：首次登录角色选择

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 首次登录显示角色选择 | ✅ 已实现 - `user-edit.vue` 中通过 `needsRoleSelect` 参数控制 | ✅ |
| 可选角色：成长规划师、家长、孩子 | ✅ 已实现 - 三种角色卡片 | ✅ |
| 选择后进入详情页 | ✅ 已实现 - `confirmRole()` 方法切换到详情表单 | ✅ |

**实现位置**：
- `zxyj-frontend/pages/user-edit/user-edit.vue`
- 首次登录判断：`options.needsRoleSelect === 'true'`

---

### ✅ 需求2：成长规划师信息录入

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 身份证号（成长规划师必填） | ✅ 已实现 | ✅ |
| 性别（成长规划师必填） | ✅ 已实现 | ✅ |
| 成长规划师照片（成长规划师必填） | ✅ 已实现 - `teacherPhoto` | ✅ |
| 成长规划师证书号（成长规划师必填） | ✅ 已实现 - `teacherNo` | ✅ |
| 成长规划师证书照片 | ✅ 已实现 - `certificateImage` | ✅ |

**实现位置**：
- 前端：`user-edit.vue` 第99-130行（成长规划师额外字段）
- 后端：`User.java` 实体类包含对应字段
- DTO：`UpdateUserDTO` 应包含这些字段（需验证）

---

### ⚠️ 需求3：成长规划师查看家庭任务

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 查看关联家庭列表 | ✅ 已实现 - `GuideFamilyTaskController.getBoundFamilies()` | ✅ |
| 获取家庭任务概览 | ✅ 已实现 - `getFamilyTaskOverview()` | ✅ |
| 获取孩子任务列表 | ✅ 已实现 - `getChildTasks()` | ✅ |
| **关联家庭的绑定机制** | ⚠️ **存在潜在问题** - 见下文"需求偏差分析" | ⚠️ |

---

### ✅ 需求4：成长规划师审核任务

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 单任务审核 | ✅ 已实现 - `GuideFamilyTaskController.reviewTask()` | ✅ |
| 批量审核 | ✅ 已实现 - `batchReviewTasks()` | ✅ |
| 审核通过/拒绝 | ✅ 已实现 | ✅ |

---

### ✅ 需求5：分享码绑定家庭

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 家庭邀请码机制 | ✅ 已实现 - `Family.inviteCode` | ✅ |
| 家长使用邀请码绑定 | ✅ 已实现 - `UserController.joinFamily()` | ✅ |
| 成长规划师分享码给家长 | ✅ 已实现 - `GuideController.getFamilyInviteCode()` | ✅ |
| 绑定后成长规划师能看到家庭 | ✅ 已实现 - `UserService.joinFamily()` 更新 `teacherFamilyIds` | ✅ |

**实现位置**：
- `GuideController.getFamilyInviteCode()` - 第148-179行
- `UserService.joinFamily()` - 第751-764行自动关联成长规划师

---

### ✅ 需求6：接受家长咨询

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 家长联系成长规划师 | ✅ 已实现 - `TeacherMessageController.sendMessage()` | ✅ |
| 成长规划师回复咨询 | ✅ 已实现 - `TeacherMessageController.replyMessage()` | ✅ |
| 成长规划师查看咨询列表 | ✅ 已实现 - `TeacherMessageController.getMessages()` | ✅ |
| 家长查看咨询记录 | ✅ 已实现 - `TeacherMessageController.getMyMessages()` | ✅ |

**实现位置**：
- `TeacherMessage.java` - 实体类
- `TeacherMessageMapper.java` - Mapper
- `TeacherMessageService.java` - Service
- `TeacherMessageController.java` - REST API

---

### ✅ 需求7：调整任务

| 需求点 | 实现情况 | 状态 |
|--------|----------|------|
| 成长规划师修改任务 | ✅ 已实现 - `GuideFamilyTaskController.updateTask()` | ✅ |
| 成长规划师删除任务 | ✅ 已实现 - `GuideFamilyTaskController.deleteTask()`（不限创建者） | ✅ |
| 调整任务（修改/删除）权限 | ✅ 已实现 - role=teacher 可调整家庭内所有任务 | ✅ |

**实现位置**：
- `GuideFamilyTaskController.updateTask()` - 第271-317行
- `GuideFamilyTaskController.deleteTask()` - 第319-349行

---

## 三、需求偏差分析

> **更新说明**：以下偏差已全部修复

### ✅ 偏差1：家庭关联机制不完整 - 已修复

**问题描述**：
- 家庭邀请码机制已实现（`Family.inviteCode`）
- 家长可以通过邀请码绑定家庭
- ~~**但**：家长绑定家庭时，未自动将家庭ID添加到成长规划师的 `teacherFamilyIds` 字段~~ ✅ **已修复**

**解决方案**：
- 在 `UserService.joinFamily()` 中，检查家庭是否有绑定的成长规划师，如有则更新成长规划师的 `teacherFamilyIds`（第751-764行）

---

### ✅ 偏差2：接受家长咨询功能缺失 - 已修复

**问题描述**：
- 需求提到"接受家长咨询"
- ~~但当前没有实现任何家长与成长规划师之间的沟通渠道~~ ✅ **已实现**

**已实现功能**：
- 家长可以发送咨询消息给成长规划师
- 成长规划师可以查看和回复咨询
- 数据库表：`teacher_messages`

---

### ✅ 偏差3：成长规划师调整任务功能缺失 - 已修复

**问题描述**：
- 需求提到"调整任务"
- ~~当前只有创建者可以删除任务（`TaskService.deleteTask()`）~~
- ~~**无任务修改 API**~~ ✅ **已实现**

**已实现功能**：
- 成长规划师可以修改家庭成员创建的任务 - `GuideFamilyTaskController.updateTask()`
- 成长规划师可以删除家庭内任何任务（不限于创建者）- `GuideFamilyTaskController.deleteTask()`

---

## 四、待确认问题清单（已全部确认）

### ✅ 问题1：成长规划师家庭绑定流程 - 已确认
- ✅ 成长规划师通过 `GuideController.getFamilyInviteCode()` 获取邀请码
- ✅ `teacherFamilyIds` 和家庭表数据通过 `UserService.joinFamily()` 自动同步

### ✅ 问题2：成长规划师审核流程 - 已确认
- ✅ 成长规划师提交信息后可直接使用（无需审核）

### ✅ 问题3：角色字段统一性 - 已确认
- ✅ role 是当前角色，roles 是所有角色，格式没问题
- ✅ 登录返回 role 字段

### ✅ 问题4：小程序成长规划师功能 - 已确认
- ✅ 成长规划师主要通过 Web 端管理家庭任务
- ✅ `/pages/teacher/index` 页面存在

### ✅ 问题5：权限控制完整性 - 已确认
- ✅ Web 端路由守卫正确获取 role

---

## 五、待实现功能清单

> **更新说明**：以下功能已全部实现

### ✅ 1. 家庭绑定时自动关联成长规划师 - 已实现
- ✅ 家长使用邀请码绑定家庭时
- ✅ 自动将家庭ID添加到成长规划师的 `teacherFamilyIds`
- ✅ `UserService.joinFamily()` 第751-764行

### ✅ 2. 接受家长咨询功能 - 已实现
- ✅ 家长可以联系成长规划师 - `TeacherMessageController`
- ✅ 成长规划师可以查看和回复咨询 - API 完整
- ✅ 数据库表：`teacher_messages`

### ✅ 3. 成长规划师调整任务功能 - 已实现
- ✅ 成长规划师可以修改家庭成员创建的任务 - `GuideFamilyTaskController.updateTask()`
- ✅ 成长规划师可以删除家庭内任何任务 - `GuideFamilyTaskController.deleteTask()`

---

## 六、测试建议

1. 首次登录 → 角色选择 → 信息完善流程
2. 成长规划师提交信息后状态检查
3. 家长使用邀请码绑定家庭 → 验证成长规划师 `teacherFamilyIds` 是否更新
4. 成长规划师查看关联家庭和任务
5. 成长规划师审核任务（单个和批量）
6. 成长规划师调整/修改/删除任务
7. 家长发送咨询 → 成长规划师回复
8. 权限控制测试（用非 teacher 角色访问）

---

## 七、个人中心（我的）页面功能

### 7.1 菜单项

| 菜单项 | 可见角色 | 说明 |
|--------|---------|------|
| 📝 修改个人资料 | 全部 | 跳转 user-edit 页面 |
| 👶 我的孩子 | 仅家长 | 跳转孩子管理页面 |
| 📊 积分记录 | 全部 | 跳转积分明细页面 |
| 🔐 设置/重置密码 | 仅家长和成长规划师 | 孩子不可见 |
| 🚪 退出登录 | 全部 | 退出登录 |

### 7.2 密码功能

**设置密码**：
- 家长和成长规划师可设置6位数字密码
- 孩子模式不显示此菜单

**重置密码**：
- 需要先验证旧密码
- 再设置新密码

**切换模式验证**：
- 孩子切换回家长模式时需要验证密码
- 成长规划师切换到家长模式时需要验证密码（通过 Web 端）

### 7.3 修改个人资料

- 跳转到 `/pages/user-edit/user-edit` 页面
- 用户可修改昵称、头像、性别、生日等信息
- 成长规划师可修改成长规划师证书号、证书照片等信息

---

## 八、任务创建功能

### 8.1 必填项

| 字段 | 类型 | 说明 |
|------|------|------|
| 标题 | String | 任务名称 |
| 内容 | String | 任务描述 |
| 类型 | String | 学习类/生活类/运动类/其他 |
| 完成方式 | List | 打卡/文本/语音/图片/视频，可多选 |
| 积分 | Integer | 1-10分 |
| 时长 | Integer | 分钟 |
| 完成孩子 | List | 多个孩子可多选 |
| 频率 | String | daily/weekly/monthly |
| 周期次数 | Integer | 周期内最多完成次数，超过不计积分 |
| 任务性质 | String | 一次性onetime/循环recurring |
| 是否需要审核 | Integer | 0否/1是 |
| 审核方式 | String | creator/parent/teacher/ai |

### 8.2 非必填项

| 字段 | 类型 | 说明 |
|------|------|------|
| 最早开始时间 | DateTime | 不设置表示不限时 |
| 最晚结束时间 | DateTime | 不设置表示不限时 |

### 8.3 任务创建入口

**小程序端**：
- 家长首页 → "+ 添加任务"按钮
- 任务列表页面 → "+ 添加任务"按钮

**Web端**：
- 任务管理 → 创建任务

### 8.4 任务模板

**模板来源**：
1. 历史任务 - 用户曾经创建的任务
2. 公开模板 - 系统预设的任务模板

**模板内容**：
- 标题、内容、类型
- 完成方式、积分、时长
- 默认审核设置

### 8.5 任务表结构

```sql
tasks 表新增字段：
- executor_type VARCHAR(20) COMMENT '执行者类型: child/parent'
- executor_id BIGINT COMMENT '执行者ID'
- task_type VARCHAR(20) COMMENT '任务性质: onetime/recurring'
- complete_types JSON COMMENT '完成方式: ["checkin","text","image"...]'
- review_type VARCHAR(20) COMMENT '审核人类型: creator/parent/teacher/ai'
- earliest_start DATETIME COMMENT '最早开始时间'
- latest_end DATETIME COMMENT '最晚结束时间'
- max_frequency INT COMMENT '周期内最多完成次数'
```

### 8.6 审核流程

| 审核人类型 | 说明 |
|------------|------|
| creator | 任务创建人审核 |
| parent | 家长审核 |
| teacher | 成长规划师审核 |
| ai | AI自动审核 |

### 8.7 实现状态

| 功能 | 状态 | 说明 |
|------|------|------|
| 后端DTO | ✅ 完成 | CreateTaskDTO 已添加所有字段 |
| 后端实体 | ✅ 完成 | Task 实体已添加所有字段 |
| 后端Service | ✅ 完成 | TaskService.createTask 已更新 |
| 小程序端 | ✅ 完成 | tasks.vue 已实现完整表单 |
| Web端 | ⏳ 待开发 | 需要单独实现 |