cfc/docs/dan-requirements.md

DAN测评模块需求分析

版本: V1.4 更新时间: 2026-04-16

---

一、需求背景与现状

1.1 业务背景

DAN测评是一个针对儿童注意力、专注力、记忆力、逻辑思维等多维能力的综合评估系统。测评结果用于：

• 评估孩子当前的能力水平
• 生成针对性的成长建议
• 追踪能力发展趋势
• 为家长提供教育参考
• 支持任务模板智能推荐

1.2 核心业务变化（V1.3 → V1.4）

变化项	V1.3（旧）	V1.4（新）
等级概念	DAN等级 A/B/C/D	取消，改为测评包
能力维度	固定五维（注意力/专注力/记忆力/逻辑/综合）	指标体系，可配置
任务推荐	无	自动推荐+手动确认
收费方式	无	P2阶段与外部系统集成

1.3 测评包定义

测评包	适用年龄	类型	说明
A1	7-9岁	儿童认知能力发展	儿童认知能力综合评估
A2	10岁以上	青少年核心素养	青少年核心素养综合评估
B1	7-9岁	儿童家庭环境	家庭环境评估
B2	10岁以上	青少年家庭环境	家庭环境评估
B3	7-9岁	儿童学习习惯	学习习惯评估
B4	10岁以上	青少年学习习惯	学习习惯评估
B5	7-9岁	儿童心理状态	心理状态评估
B6	10岁以上	职业发展	职业发展评估

1.4 现有实现状态

组件	状态	说明
DanAssessmentResult 实体	⚠️ 已定义	存在于 entity/DanAssessmentResult.java
AssessmentAppointment 实体	⚠️ 已定义	存在于 entity/AssessmentAppointment.java
DAN测评 API	❌ 不存在	无对应 Controller
预约 API	⚠️ 部分实现	依赖 Appointment 实体
前端页面	❌ 不存在	无对应页面

---

二、指标体系设计

2.1 指标定义

指标是测评的最小评估单元，每个指标有唯一的指标编码、所属能力维度、等级阈值。

指标属性

属性	类型	说明
indicatorCode	String	指标编码，如 COG001（认知能力）、EMI001（情绪心理）
indicatorName	String	指标名称
dimension	String	能力维度（COG/EMI/SOC/PHY）
description	String	指标说明
levelThresholds	JSON	等级阈值，如 {"高":80,"中":60,"低":0}
sortOrder	Integer	排序

指标维度

维度编码	维度名称
COG	认知能力
EMI	情绪心理
SOC	社会关系
PHY	身体健康

2.2 测评包-指标映射（dan_package_indicator）

每个测评包包含一组指标，定义见下表：

测评包	包含指标
A1（儿童认知能力发展-7-9岁）	COG001, COG002, COG003, COG004, COG005
A2（青少年核心素养-10岁以上）	COG001, COG002, COG003, COG004, COG005, COG006
B1（儿童家庭环境-7-9岁）	EMI001, EMI002, SOC001
B2（青少年家庭环境-10岁以上）	EMI001, EMI002, EMI003, SOC001, SOC002
B3（儿童学习习惯-7-9岁）	SOC001, SOC002, PHY001
B4（青少年学习习惯-10岁以上）	SOC001, SOC002, SOC003, PHY001, PHY002
B5（儿童心理状态-7-9岁）	EMI001, EMI002, PHY001
B6（职业发展-10岁以上）	EMI001, EMI002, EMI003, PHY001, PHY002

2.3 指标-任务模板映射（dan_indicator_template）

每个指标可关联多个任务模板，用于测评后的任务推荐。

指标	推荐任务模板类型
COG001（认知灵活）	认知灵活性训练、多任务切换
COG002（工作记忆）	工作记忆训练、数字记忆
COG003（注意力广度）	舒尔特方格、视觉搜索
COG004（注意力稳定性）	专注力训练、静态任务
COG005（逻辑推理）	逻辑思维训练、 puzzles
COG006（问题解决）	策略游戏、方案规划
EMI001（情绪识别）	情绪日记、情绪识别训练
EMI002（情绪调节）	情绪调节练习、放松训练
EMI003（抗压能力）	压力应对训练、心理韧性
SOC001（社交技能）	社交互动练习、沟通训练
SOC002（合作能力）	团队合作任务、小组活动
PHY001（运动协调）	运动游戏、协调性训练
PHY002（身体耐力）	体能训练、耐力运动

---

三、需求清单

3.1 需求列表

需求ID	描述	优先级	状态
DAN-001	测评预约创建与管理	P0	⚠️ 部分实现
DAN-002	测评结果录入与存储（按指标）	P0	⚠️ 已定义实体
DAN-003	测评结果列表查询	P0	❌ 未实现
DAN-004	测评结果详情查看	P0	❌ 未实现
DAN-005	指标得分展示	P0	⚠️ 已定义字段
DAN-006	指标等级计算	P0	❌ 未实现
DAN-007	历史趋势对比	P1	❌ 未实现
DAN-008	成长建议生成（按指标）	P1	❌ 未实现
DAN-009	下次复测提醒	P1	❌ 未实现
DAN-010	测评报告导出	P1	❌ 未实现
DAN-011	测评统计报表	P1	❌ 未实现
DAN-012	测评包管理	P1	❌ 未实现
DAN-013	指标库管理	P1	❌ 未实现
DAN-014	指标-模板映射管理	P1	❌ 未实现
DAN-015	任务自动推荐	P1	❌ 未实现
DAN-016	收费集成预留	P2	❌ 未实现
DAN-017	成长规划师录入权限	P0	⚠️ 已定义
DAN-018	家长查看权限	P0	⚠️ 已定义
DAN-019	测评数据脱敏	P2	❌ 未实现

---

四、需求详细说明

4.1 测评包管理（DAN-012）

功能描述

管理测评包的定义，包括测评包编码、名称、适用年龄范围、包含的指标列表。

字段定义

字段	类型	必填	说明
id	Long	是	主键
packageCode	String	是	测评包编码（A1/A2/B1-B6）
packageName	String	是	测评包名称
ageRangeMin	Integer	是	适用最小年龄
ageRangeMax	Integer	是	适用最大年龄
category	String	是	分类（认知能力/核心能力/家庭环境/行为表现/心理状态）
indicators	JSON	是	指标编码数组，如 ["ATT001","MEM001"]
description	String	否	说明
isActive	Integer	是	是否启用（1启用/0禁用）
createdAt	Date	是	创建时间
updatedAt	Date	是	更新时间

---

4.2 指标库管理（DAN-013）

功能描述

管理指标的定义，支持指标的增删改查。

字段定义

字段	类型	必填	说明
id	Long	是	主键
indicatorCode	String	是	指标编码（如 ATT001）
indicatorName	String	是	指标名称
dimension	String	是	能力维度
description	String	否	指标说明
levelThresholds	JSON	是	等级阈值（如 {"高":80,"中":60,"低":0}）
sortOrder	Integer	否	排序
isActive	Integer	是	是否启用
createdAt	Date	是	创建时间
updatedAt	Date	是	更新时间

---

4.3 指标-任务模板映射管理（DAN-014）

功能描述

管理指标与任务模板的关联关系，支持自动推荐逻辑。

字段定义

字段	类型	必填	说明
id	Long	是	主键
indicatorCode	String	是	指标编码
templateId	Long	是	任务模板ID
weight	Integer	否	推荐权重（1-10）
isActive	Integer	是	是否启用
createdAt	Date	是	创建时间
updatedAt	Date	是	更新时间

---

4.4 预约管理（DAN-001）

功能描述

家长或成长规划师为孩子预约DAN测评，选择测评时间、成长规划师和测评包。

业务流程

家长/成长规划师 → 选择测评包 → 选择时间 → 预约记录生成 → 成长规划师确认 → 测评执行 → 标记完成

字段定义

字段	类型	必填	说明
childId	Long	是	预约的孩子
teacherId	Long	是	成长规划师
packageCode	String	是	测评包编码
appointmentDate	Date	是	预约日期
appointmentTime	String	是	预约时间（HH:mm）
notes	String	否	备注
status	String	是	pending/completed/cancelled

---

4.5 测评结果录入与存储（DAN-002）

功能描述

成长规划师完成测评后，录入测评结果并存储。测评结果按指标存储得分。

字段定义

字段	类型	必填	说明
id	Long	是	主键
childId	Long	是	测评的孩子
teacherId	Long	是	成长规划师ID
appointmentId	Long	否	关联的预约ID
packageCode	String	是	测评包编码
indicatorScores	JSON	是	指标得分数组

// indicatorScores 示例
[
  {"code": "ATT001", "name": "注意力广度", "score": 85, "level": "高"},
  {"code": "MEM001", "name": "短时记忆", "score": 72, "level": "中"},
  {"code": "LOG001", "name": "逻辑推理", "score": 90, "level": "高"}
]

其他字段

字段	类型	必填	说明
assessmentDate	Date	是	测评日期
durationMinutes	Integer	否	测评时长
gameRecords	String	否	游戏记录（JSON）
analysisReport	String	否	分析报告
growthSuggestions	String	否	成长建议（按指标生成）
nextReviewDate	Date	否	下次复测日期
status	String	是	draft/completed/archived
createdAt	Date	是	创建时间
updatedAt	Date	是	更新时间

状态流转

• draft：草稿（成长规划师录入中）
• completed：已完成（正式结果）
• archived：已归档（历史记录）

---

4.6 测评结果列表查询（DAN-003）

功能描述

根据孩子ID查询测评记录列表，支持筛选和分页。

筛选条件

条件	类型	说明
childId	Long	孩子ID（必填）
timeRange	String	时间范围（recent_month/recent_quarter/all）
packageCode	String	测评包筛选
status	String	状态筛选

返回字段

• 列表展示：不包含详细分析报告和成长建议
• 包含字段：id、assessmentDate、packageCode、indicatorScores 摘要、status

---

4.7 测评结果详情查看（DAN-004）

功能描述

查看单次测评的完整结果。

展示内容

模块	内容
基本信息	测评日期、成长规划师、测评包、测评时长
指标得分	indicatorScores 完整展示，按维度分组
指标等级	每个指标的等级（高/中/低）
分析报告	analysisReport 全文
成长建议	growthSuggestions 全文（按指标维度）
下次复测	nextReviewDate

---

4.8 指标等级计算（DAN-006）

功能描述

根据指标得分和等级阈值计算指标等级。

计算规则

1. 查询指标定义的 levelThresholds
2. 根据得分判断等级：
   • score >= 高阈值 → "高"
   • score >= 中阈值 → "中"
   • score < 中阈值 → "低"

示例

// 指标定义
{"indicatorCode": "ATT001", "levelThresholds": {"高":80,"中":60,"低":0}}

// 得分85 → 等级"高"
// 得分65 → 等级"中"  
// 得分55 → 等级"低"

---

4.9 历史趋势对比（DAN-007）

功能描述

展示孩子历次测评各指标的趋势变化。

展示内容

• 折线图：各指标得分趋势
• 表格：历史测评记录对比
• 维度汇总：按能力维度的平均得分

时间范围

• 最近三月
• 最近半年
• 全部历史

---

4.10 成长建议生成（DAN-008）

功能描述

根据测评结果（按指标）生成针对性的成长建议。

生成规则

1. 遍历所有指标，筛选出等级为"低"或"中"的指标
2. 根据指标维度生成对应建议：
   • ATT（注意力）：专注力训练游戏、日常注意力培养建议
   • MEM（记忆力）：记忆方法教学、记忆训练游戏
   • LOG（逻辑思维）：逻辑思维训练、问题解决技巧
   • EMI（情绪调节）：情绪管理方法、情绪调节练习
   • BEH（行为习惯）：行为养成计划、自控力培养
   • FAM（家庭环境）：家庭支持建议、亲子互动改善

建议类型

• 日常生活建议
• 游戏训练建议
• 专业干预建议（如需）

---

4.11 任务自动推荐（DAN-015）

功能描述

测评完成后，根据指标得分自动推荐相关任务模板，家长可手动选择确认。

业务流程

测评完成 → 系统分析指标得分 → 筛选得分低的指标 
→ 查找对应任务模板 → 按权重排序 → 展示推荐列表 
→ 家长选择确认 → 创建任务

推荐算法

1. 筛选低分指标：score < 中阈值的指标
2. 查找关联模板：从 dan_indicator_template 查询关联的任务模板
3. 权重排序：按 weight 降序排列
4. 去重：同一模板只推荐一次

展示内容

• 推荐任务列表：templateName、推荐理由（关联的指标）
• 家长操作：选择确认 / 忽略 / 自定义选择

---

4.12 下次复测提醒（DAN-009）

功能描述

根据 nextReviewDate 发送复测提醒。

提醒机制

• 提前7天/3天/1天提醒
• 提醒方式：系统消息推送
• 触发：定时任务每日扫描

---

4.13 测评报告导出（DAN-010）

功能描述

将测评结果导出为PDF格式。

导出内容

• 封面：孩子信息、测评日期、测评包
• 总体评价：各维度得分汇总
• 指标雷达图
• 各指标详细分析（得分+等级）
• 历史趋势对比
• 成长建议（按维度）
• 下次复测计划

---

4.14 测评统计报表（DAN-011）

功能描述

提供测评统计功能。

统计维度

• 测评总次数
• 各测评包分布
• 各指标平均分
• 各等级分布（高/中/低）
• 测评完成率

---

4.15 收费集成预留（DAN-016）

功能描述

P2阶段与外部收费系统集成，目前预留接口。

预留内容

1. 测评包定价字段（dan_package.price）
2. 支付状态字段（dan_appointment.paymentStatus）
3. 回调通知接口（/api/dan/payment/callback）
4. 订单创建接口（预留）

---

4.16 成长规划师录入权限（DAN-017）

权限范围

• 创建测评结果
• 编辑自己录入的测评结果
• 查看自己负责家庭的测评记录
• 管理测评包、指标、模板映射

---

4.17 家长查看权限（DAN-018）

权限范围

• 查看自己孩子的所有测评记录
• 查看测评详情
• 查看历史趋势
• 确认任务推荐

---

4.18 测评数据脱敏（DAN-019）

脱敏规则

• 街道级汇总展示
• 匿名化处理
• 仅展示统计趋势

---

五、API接口设计

5.1 测评包管理

方法	路径	功能	权限
GET	/api/dan/packages	测评包列表	公开
GET	/api/dan/packages/{code}	测评包详情	公开
POST	/api/dan/packages	创建测评包	管理员
PUT	/api/dan/packages/{id}	更新测评包	管理员
DELETE	/api/dan/packages/{id}	删除测评包	管理员

5.2 指标管理

方法	路径	功能	权限
GET	/api/dan/indicators	指标列表	公开
GET	/api/dan/indicators/{code}	指标详情	公开
POST	/api/dan/indicators	创建指标	管理员
PUT	/api/dan/indicators/{id}	更新指标	管理员
DELETE	/api/dan/indicators/{id}	删除指标	管理员

5.3 指标-模板映射

方法	路径	功能	权限
GET	/api/dan/indicator-template	映射列表	成长规划师
POST	/api/dan/indicator-template	创建映射	管理员
PUT	/api/dan/indicator-template/{id}	更新映射	管理员
DELETE	/api/dan/indicator-template/{id}	删除映射	管理员

5.4 预约管理

方法	路径	功能	权限
POST	/api/dan/appointments	创建预约	家长/成长规划师
GET	/api/dan/appointments	预约列表	家长/成长规划师
GET	/api/dan/appointments/{id}	预约详情	家长/成长规划师
PUT	/api/dan/appointments/{id}	修改预约	家长/成长规划师
DELETE	/api/dan/appointments/{id}	取消预约	家长/成长规划师

5.5 测评结果

方法	路径	功能	权限
POST	/api/dan/results	创建测评记录	成长规划师
GET	/api/dan/results/child/{childId}	测评列表	家长/成长规划师
GET	/api/dan/results/{id}	测评详情	家长/成长规划师
PUT	/api/dan/results/{id}	更新测评记录	成长规划师
DELETE	/api/dan/results/{id}	删除测评记录	成长规划师

5.6 任务推荐

方法	路径	功能	权限
GET	/api/dan/results/{id}/recommend-tasks	获取推荐任务	家长
POST	/api/dan/results/{id}/confirm-tasks	确认推荐任务	家长

5.7 分析与统计

方法	路径	功能	权限
GET	/api/dan/analysis/{id}	能力分析	家长/成长规划师
GET	/api/dan/trend/{childId}	历史趋势	家长/成长规划师
GET	/api/dan/statistics/child/{childId}	测评统计	家长/成长规划师
GET	/api/dan/statistics/family/{familyId}	家庭统计	家长

5.8 导出

方法	路径	功能	权限
GET	/api/dan/export/{id}	导出PDF报告	家长/成长规划师

5.9 收费集成（P2）

方法	路径	功能	权限
POST	/api/dan/payment/create	创建支付订单	家长
POST	/api/dan/payment/callback	支付回调	外部系统

---

六、前端页面

页面	路径	功能
测评包选择	/pages/dan/packages	选择测评包
预约页面	/pages/dan/appointment	预约创建与管理
测评列表	/pages/dan/list	测评历史记录
测评详情	/pages/dan/detail	测评结果详情
指标雷达图	/pages/dan/radar	能力维度雷达图
趋势对比	/pages/dan/trend	历史趋势图表
任务推荐	/pages/dan/recommend	任务推荐确认
统计报表	/pages/dan/statistics	测评统计
管理后台	/pages/admin/dan	测评包/指标/映射管理

---

七、数据库设计

7.1 测评包表（dan_package）

CREATE TABLE dan_package (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    package_code VARCHAR(10) NOT NULL UNIQUE,
    package_name VARCHAR(50) NOT NULL,
    age_range_min INT NOT NULL,
    age_range_max INT NOT NULL,
    category VARCHAR(20) NOT NULL,
    indicators JSON NOT NULL,
    description TEXT,
    price DECIMAL(10,2) DEFAULT 0,
    is_active TINYINT DEFAULT 1,
    created_at DATETIME,
    updated_at DATETIME,
    INDEX idx_code (package_code),
    INDEX idx_category (category)
);

7.2 指标表（dan_indicator）

CREATE TABLE dan_indicator (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    indicator_code VARCHAR(20) NOT NULL UNIQUE,
    indicator_name VARCHAR(50) NOT NULL,
    dimension VARCHAR(20) NOT NULL,
    description TEXT,
    level_thresholds JSON NOT NULL,
    sort_order INT DEFAULT 0,
    is_active TINYINT DEFAULT 1,
    created_at DATETIME,
    updated_at DATETIME,
    INDEX idx_code (indicator_code),
    INDEX idx_dimension (dimension)
);

7.3 指标-任务模板映射表（dan_indicator_template）

CREATE TABLE dan_indicator_template (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    indicator_code VARCHAR(20) NOT NULL,
    template_id BIGINT NOT NULL,
    weight INT DEFAULT 5,
    is_active TINYINT DEFAULT 1,
    created_at DATETIME,
    updated_at DATETIME,
    INDEX idx_indicator (indicator_code),
    INDEX idx_template (template_id)
);

7.4 测评预约表（dan_appointment）

CREATE TABLE dan_appointment (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    child_id BIGINT NOT NULL,
    teacher_id BIGINT,
    package_code VARCHAR(10) NOT NULL,
    appointment_date DATE NOT NULL,
    appointment_time VARCHAR(10) NOT NULL,
    notes TEXT,
    payment_status VARCHAR(20) DEFAULT 'unpaid',
    status VARCHAR(20) DEFAULT 'pending',
    created_at DATETIME,
    updated_at DATETIME,
    INDEX idx_child (child_id),
    INDEX idx_teacher (teacher_id),
    INDEX idx_date (appointment_date)
);

7.5 测评结果表（dan_assessment_result）

CREATE TABLE dan_assessment_result (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    child_id BIGINT NOT NULL,
    teacher_id BIGINT NOT NULL,
    appointment_id BIGINT,
    package_code VARCHAR(10) NOT NULL,
    indicator_scores JSON NOT NULL,
    assessment_date DATE NOT NULL,
    duration_minutes INT,
    game_records JSON,
    analysis_report TEXT,
    growth_suggestions TEXT,
    next_review_date DATE,
    status VARCHAR(20) DEFAULT 'draft',
    created_at DATETIME,
    updated_at DATETIME,
    INDEX idx_child (child_id),
    INDEX idx_teacher (teacher_id),
    INDEX idx_date (assessment_date),
    INDEX idx_package (package_code)
);

---

八、开发优先级

P0（紧急）

1. DAN-012 测评包管理

   • 后端 CRUD API
   • 管理后台页面

2. DAN-013 指标库管理

   • 后端 CRUD API
   • 管理后台页面

3. DAN-014 指标-模板映射

   • 后端 CRUD API
   • 管理后台页面

4. DAN-001 预约管理

   • 后端 CRUD API
   • 前端预约页面

5. DAN-002 测评结果录入

   • 后端结果录入 API
   • 指标等级自动计算

6. DAN-003 测评列表查询

   • 后端列表 API
   • 前端列表页面

7. DAN-004 测评详情

   • 后端详情 API
   • 前端详情页面（按指标展示）

P1（重要）

1. DAN-006 指标等级计算

   • 自动计算逻辑
   • 等级展示

2. DAN-007 历史趋势

   • 趋势 API
   • 趋势图表前端

3. DAN-008 成长建议

   • 建议生成规则引擎
   • 建议展示

4. DAN-015 任务自动推荐

   • 推荐算法实现
   • 家长确认流程

5. DAN-009 复测提醒

   • 定时任务

P2（扩展）

1. DAN-010 报告导出
2. DAN-011 统计报表
3. DAN-016 收费集成
4. DAN-019 数据脱敏

---

九、现有代码参考

9.1 实体类（需更新）

• zxyj-backend/src/main/java/com/zxyj/entity/DanAssessmentResult.java - 需增加 packageCode 和 indicatorScores
• zxyj-backend/src/main/java/com/zxyj/entity/AssessmentAppointment.java - 需增加 packageCode

9.2 需创建

• zxyj-backend/src/main/java/com/zxyj/entity/DanPackage.java
• zxyj-backend/src/main/java/com/zxyj/entity/DanIndicator.java
• zxyj-backend/src/main/java/com/zxyj/entity/DanIndicatorTemplate.java
• zxyj-backend/src/main/java/com/zxyj/controller/dan/DanPackageController.java
• zxyj-backend/src/main/java/com/zxyj/controller/dan/DanIndicatorController.java
• zxyj-backend/src/main/java/com/zxyj/controller/dan/DanAssessmentController.java
• zxyj-backend/src/main/java/com/zxyj/controller/dan/DanRecommendController.java
• zxyj-frontend/pages/dan/ 目录及页面

---

十、待完善事项

功能	优先级	说明
测评包CRUD	P0	后端API + 管理后台
指标库CRUD	P0	后端API + 管理后台
映射管理	P0	后端API + 管理后台
预约CRUD	P0	后端API
结果录入	P0	后端API + 指标等级计算
列表查询	P0	后端API + 前端
详情展示	P0	前端页面（按指标）
等级计算	P1	自动计算逻辑
趋势分析	P1	后端API + 前端图表
成长建议	P1	规则引擎
任务推荐	P1	推荐算法 + 家长确认
复测提醒	P1	定时任务
报告导出	P2	PDF生成
统计报表	P2	统计API
收费集成	P2	P2阶段讨论