# 需求分析报告：指导师功能

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

### 需求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 角色访问）