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

---

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

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 任务表结构

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端	⏳ 待开发	需要单独实现