cfc/docs/requirements-analysis.md

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

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

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