xiaozhang/xinli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6473c94e1c
xinli/z_Project change/量表示例/16-量表导入JSON标准格式说明.md

693 lines
19 KiB
Markdown
Raw Normal View History

量表导入功能实现
2025-11-07 12:07:24 +08:00
# 量表导入JSON标准格式说明
## 📋 概述
本文档详细说明如何使用JSON格式导入量表数据到系统中。JSON格式适用于批量导入完整的量表数据，包括量表基本信息、题目、选项、因子、计分规则等。
## 🎯 导入方式
系统支持三种导入方式：
1. **JSON文本导入**：在导入界面直接粘贴JSON文本
2. **JSON文件导入**：上传.json格式的文件
3. **PDF/DOCX文档导入**：系统自动解析文档并转换为JSON格式（自动识别）
---
## 📝 JSON数据结构
### 完整JSON结构
```json
{
"scale": {
// 量表基本信息
},
"items": [
// 题目列表（包含选项）
],
"factors": [
// 因子列表（包含计分规则）
],
"interpretations": [
// 结果解释配置（可选）
],
"warningRules": [
// 预警规则配置（可选）
]
}
```
---
## 🔍 详细字段说明
### 1. 量表基本信息 (scale)
```json
{
"scaleCode": "SCL_90", // 量表编码（必填，唯一）
"scaleName": "症状自评量表SCL-90", // 量表名称（必填）
"scaleEnName": "Symptom Checklist 90", // 量表英文名称（可选）
"scaleType": "symptom", // 量表类型（可选）
"scaleVersion": "1.0", // 量表版本（可选）
"scaleIntro": "SCL-90量表简介", // 量表简介（可选）
"scaleDescription": "SCL-90详细描述", // 量表描述（可选）
"itemCount": 90, // 题目数量（可选，系统自动计算）
"estimatedTime": 30, // 预计完成时间（分钟）（可选）
"targetPopulation": "一般人群", // 适用人群（可选）
"author": "Derogatis", // 作者（可选）
"source": "心理卫生评定量表手册", // 来源（可选）
"reference": "参考文献", // 参考文献（可选）
"status": "0", // 状态：0-正常，1-停用（必填，默认"0"）
"sortOrder": 0 // 排序顺序（可选，默认0）
}
```
**字段说明**：
- `scaleCode`：必须唯一，建议使用英文大写字母和下划线，如 `SCL_90`、`EPQ_001`
- `scaleName`：量表的完整中文名称
- `scaleType`：量表类型，如 `symptom`（症状）、`personality`（人格）、`emotion`（情绪）等
- `status`：`"0"` 表示正常（启用），`"1"` 表示停用
---
### 2. 题目列表 (items)
```json
{
"items": [
{
"item": {
"itemNumber": 1, // 题目序号（必填）
"itemContent": "头痛", // 题目内容（必填）
"itemType": "single", // 题目类型：single-单选，multiple-多选（必填）
"required": "1", // 是否必答：0-否，1-是（必填，默认"1"）
"reverseScore": "0", // 是否反向计分：0-否，1-是（必填，默认"0"）
"sortOrder": 1 // 排序顺序（可选）
},
"options": [
// 选项列表
]
}
]
}
```
**字段说明**：
- `itemNumber`：题目序号，从1开始，建议连续
- `itemContent`：题目的完整文字内容
- `itemType`：`"single"` 表示单选题，`"multiple"` 表示多选题
- `required`：`"1"` 表示必答，`"0"` 表示可选
- `reverseScore`：`"1"` 表示反向计分（得分越高表示程度越低），`"0"` 表示正常计分
---
### 3. 选项列表 (options)
每个题目包含一个选项数组：
```json
{
"options": [
{
"optionCode": "A", // 选项编码（必填）
"optionContent": "没有", // 选项内容（必填）
"optionScore": 0, // 选项分数（必填）
"sortOrder": 1 // 排序顺序（可选）
},
{
"optionCode": "B",
"optionContent": "很轻",
"optionScore": 1,
"sortOrder": 2
},
{
"optionCode": "C",
"optionContent": "中等",
"optionScore": 2,
"sortOrder": 3
},
{
"optionCode": "D",
"optionContent": "偏重",
"optionScore": 3,
"sortOrder": 4
},
{
"optionCode": "E",
"optionContent": "严重",
"optionScore": 4,
"sortOrder": 5
}
]
}
```
**字段说明**：
- `optionCode`：选项编码，通常使用 A、B、C、D、E 或 1、2、3、4、5
- `optionContent`：选项的文字描述
- `optionScore`：该选项对应的分数（数字类型）
- `sortOrder`：选项的显示顺序，数字越小越靠前
---
### 4. 因子列表 (factors)
```json
{
"factors": [
{
"factor": {
"factorCode": "F1", // 因子编码（必填）
"factorName": "躯体化", // 因子名称（必填）
"factorEnName": "Somatization", // 因子英文名称（可选）
"factorDescription": "躯体化因子描述", // 因子描述（可选）
"factorOrder": 1 // 因子排序（可选）
},
"rules": [
// 计分规则列表
]
}
]
}
```
**字段说明**：
- `factorCode`：因子编码，建议使用 F1、F2、F3 等格式
- `factorName`：因子的中文名称
- `factorOrder`：因子的排序顺序
---
### 5. 计分规则 (rules)
每个因子包含一个计分规则数组：
```json
{
"rules": [
{
"itemNumber": 1, // 题目序号（必填，用于映射）
"rule": {
"optionIds": "1,2,3,4,5", // 选项ID列表，逗号分隔（可选，留空表示所有选项）
"weight": 1.0, // 权重（必填，默认1.0）
"calculationType": "sum" // 计算方式：sum-求和，avg-平均，max-最大，min-最小（必填）
}
},
{
"itemNumber": 4,
"rule": {
"optionIds": "",
"weight": 1.0,
"calculationType": "sum"
}
}
]
}
```
**字段说明**：
- `itemNumber`：题目序号，用于将规则映射到对应的题目
- `optionIds`：选项ID列表，逗号分隔。如果为空字符串，表示使用该题目的所有选项
- `weight`：权重，用于加权计算（默认1.0）
- `calculationType`：
- `"sum"`：求和（所有选中选项的分数之和 × 权重）
- `"avg"`：平均（所有选中选项的分数平均值 × 权重）
- `"max"`：最大（所有选中选项的分数最大值 × 权重）
- `"min"`：最小（所有选中选项的分数最小值 × 权重）
**注意**：`itemNumber` 必须与 `items` 数组中的题目序号对应。
---
### 6. 结果解释 (interpretations) - 可选
```json
{
"interpretations": [
{
"scaleId": null, // 量表ID（导入时自动设置，无需填写）
"factorId": null, // 因子ID（导入时自动设置，可选）
"scoreMin": 0, // 分数下限（必填）
"scoreMax": 10, // 分数上限（必填）
"level": "低", // 等级（可选）
"levelName": "正常范围", // 等级名称（可选）
"interpretationTitle": "正常范围", // 解释标题（必填）
"interpretationContent": "您的得分在正常范围内", // 解释内容（可选）
"suggestions": "继续保持良好的心理状态", // 建议指导（可选）
"sortOrder": 1 // 排序顺序（可选）
}
]
}
```
**字段说明**：
- `scoreMin` 和 `scoreMax`：定义分数范围，系统会根据实际得分匹配对应的解释
- `factorId`：如果留空（null），表示针对量表总体；如果填写，表示针对特定因子
---
### 7. 预警规则 (warningRules) - 可选
```json
{
"warningRules": [
{
"scaleId": null, // 量表ID（导入时自动设置，无需填写）
"factorId": null, // 因子ID（导入时自动设置，可选）
"ruleName": "重度抑郁预警", // 规则名称（必填）
"warningLevel": "高", // 预警等级：低、中、高、紧急（必填）
"scoreMin": 30, // 分数下限（可选）
"scoreMax": 40, // 分数上限（可选）
"percentileMin": 90, // 百分位下限（可选）
"percentileMax": 100, // 百分位上限（可选）
"autoResolve": "0", // 是否自动解除：0-否，1-是（可选）
"resolveCondition": "", // 解除条件（可选）
"status": "0" // 状态：0-正常，1-停用（必填）
}
]
}
```
---
## 📄 完整JSON示例
### 示例1：简单的5题量表（无因子）
```json
{
"scale": {
"scaleCode": "TEST_001",
"scaleName": "测试量表",
"scaleType": "general",
"status": "0",
"itemCount": 5
},
"items": [
{
"item": {
"itemNumber": 1,
"itemContent": "您是否经常感到焦虑？",
"itemType": "single",
"required": "1",
"reverseScore": "0",
"sortOrder": 1
},
"options": [
{
"optionCode": "A",
"optionContent": "从不",
"optionScore": 0,
"sortOrder": 1
},
{
"optionCode": "B",
"optionContent": "偶尔",
"optionScore": 1,
"sortOrder": 2
},
{
"optionCode": "C",
"optionContent": "经常",
"optionScore": 2,
"sortOrder": 3
},
{
"optionCode": "D",
"optionContent": "总是",
"optionScore": 3,
"sortOrder": 4
}
]
},
{
"item": {
"itemNumber": 2,
"itemContent": "您是否容易紧张？",
"itemType": "single",
"required": "1",
"reverseScore": "0",
"sortOrder": 2
},
"options": [
{
"optionCode": "A",
"optionContent": "从不",
"optionScore": 0,
"sortOrder": 1
},
{
"optionCode": "B",
"optionContent": "偶尔",
"optionScore": 1,
"sortOrder": 2
},
{
"optionCode": "C",
"optionContent": "经常",
"optionScore": 2,
"sortOrder": 3
},
{
"optionCode": "D",
"optionContent": "总是",
"optionScore": 3,
"sortOrder": 4
}
]
}
],
"factors": [],
"interpretations": [
{
"scoreMin": 0,
"scoreMax": 5,
"level": "低",
"levelName": "正常",
"interpretationTitle": "正常范围",
"interpretationContent": "您的焦虑水平在正常范围内"
},
{
"scoreMin": 6,
"scoreMax": 10,
"level": "中",
"levelName": "轻度",
"interpretationTitle": "轻度焦虑",
"interpretationContent": "您可能存在轻度焦虑，建议适当放松"
},
{
"scoreMin": 11,
"scoreMax": 15,
"level": "高",
"levelName": "中度",
"interpretationTitle": "中度焦虑",
"interpretationContent": "您可能存在中度焦虑，建议寻求专业帮助"
}
],
"warningRules": []
}
```
### 示例2：SCL-90量表（含因子和计分规则）
```json
{
"scale": {
"scaleCode": "SCL_90",
"scaleName": "症状自评量表SCL-90",
"scaleEnName": "Symptom Checklist 90",
"scaleType": "symptom",
"scaleVersion": "1.0",
"scaleIntro": "SCL-90是一个包含90个项目的症状自评量表",
"scaleDescription": "详细描述...",
"itemCount": 90,
"estimatedTime": 30,
"targetPopulation": "一般人群",
"author": "Derogatis",
"source": "心理卫生评定量表手册",
"status": "0"
},
"items": [
{
"item": {
"itemNumber": 1,
"itemContent": "头痛",
"itemType": "single",
"required": "1",
"reverseScore": "0",
"sortOrder": 1
},
"options": [
{
"optionCode": "A",
"optionContent": "没有",
"optionScore": 0,
"sortOrder": 1
},
{
"optionCode": "B",
"optionContent": "很轻",
"optionScore": 1,
"sortOrder": 2
},
{
"optionCode": "C",
"optionContent": "中等",
"optionScore": 2,
"sortOrder": 3
},
{
"optionCode": "D",
"optionContent": "偏重",
"optionScore": 3,
"sortOrder": 4
},
{
"optionCode": "E",
"optionContent": "严重",
"optionScore": 4,
"sortOrder": 5
}
]
},
{
"item": {
"itemNumber": 2,
"itemContent": "神经过敏，心中不踏实",
"itemType": "single",
"required": "1",
"reverseScore": "0",
"sortOrder": 2
},
"options": [
{
"optionCode": "A",
"optionContent": "没有",
"optionScore": 0,
"sortOrder": 1
},
{
"optionCode": "B",
"optionContent": "很轻",
"optionScore": 1,
"sortOrder": 2
},
{
"optionCode": "C",
"optionContent": "中等",
"optionScore": 2,
"sortOrder": 3
},
{
"optionCode": "D",
"optionContent": "偏重",
"optionScore": 3,
"sortOrder": 4
},
{
"optionCode": "E",
"optionContent": "严重",
"optionScore": 4,
"sortOrder": 5
}
]
}
],
"factors": [
{
"factor": {
"factorCode": "F1",
"factorName": "躯体化",
"factorDescription": "躯体化因子",
"factorOrder": 1
},
"rules": [
{
"itemNumber": 1,
"rule": {
"optionIds": "",
"weight": 1.0,
"calculationType": "sum"
}
},
{
"itemNumber": 4,
"rule": {
"optionIds": "",
"weight": 1.0,
"calculationType": "sum"
}
}
]
},
{
"factor": {
"factorCode": "F5",
"factorName": "焦虑",
"factorDescription": "焦虑因子",
"factorOrder": 5
},
"rules": [
{
"itemNumber": 2,
"rule": {
"optionIds": "",
"weight": 1.0,
"calculationType": "sum"
}
}
]
}
],
"interpretations": [
{
"factorId": null,
"scoreMin": 0,
"scoreMax": 160,
"level": "低",
"levelName": "正常",
"interpretationTitle": "正常范围",
"interpretationContent": "您的总体得分在正常范围内"
},
{
"factorId": null,
"scoreMin": 161,
"scoreMax": 250,
"level": "中",
"levelName": "轻度",
"interpretationTitle": "轻度症状",
"interpretationContent": "您可能存在轻度心理症状"
}
],
"warningRules": [
{
"factorId": null,
"ruleName": "重度症状预警",
"warningLevel": "高",
"scoreMin": 250,
"scoreMax": 360,
"status": "0"
}
]
}
```
---
## 🚀 使用步骤
### 方式1：JSON文本导入
1. 进入 `心理测评管理` → `量表管理`
2. 点击 **"导入"** 按钮
3. 在弹出对话框中，切换到 **"JSON文本"** 标签页
4. 将JSON文本粘贴到文本框中
5. 点击 **"确定"** 按钮导入
### 方式2：JSON文件导入
1. 将JSON数据保存为 `.json` 文件
2. 进入 `心理测评管理` → `量表管理`
3. 点击 **"导入"** 按钮
4. 在弹出对话框中，切换到 **"文件上传"** 标签页
5. 选择JSON文件并上传
6. 点击 **"确定"** 按钮导入
### 方式3：PDF/DOCX文档导入（自动解析）
1. 准备PDF或DOCX格式的量表文档
2. 进入 `心理测评管理` → `量表管理`
3. 点击 **"导入"** 按钮
4. 在弹出对话框中，切换到 **"文件上传"** 标签页
5. 选择PDF/DOCX文件并上传
6. 点击 **"预览解析结果"** 查看系统自动识别的结果
7. 根据需要调整JSON数据
8. 点击 **"确定"** 按钮导入
---
## ⚠️ 注意事项
### 1. 数据完整性
- `scale` 对象必须包含 `scaleCode` 和 `scaleName`
- 每个题目必须至少包含1个选项
- 如果配置了因子，必须为每个因子配置至少1条计分规则
### 2. 数据唯一性
- `scaleCode` 必须在系统中唯一
- 同一量表内的 `factorCode` 必须唯一
- 同一题目内的 `optionCode` 必须唯一
### 3. 数据映射
- 计分规则中的 `itemNumber` 必须与 `items` 数组中的题目序号对应
- 如果配置了 `interpretations` 或 `warningRules`，其中的 `factorId` 会在导入时自动映射
### 4. 字段类型
- 数字字段（`itemNumber`、`optionScore`、`weight`等）使用数字类型，不要加引号
- 字符串字段（`scaleCode`、`scaleName`等）使用双引号
- 布尔值字段（`status`、`required`等）使用字符串 `"0"` 或 `"1"`
### 5. 可选字段
- `interpretations` 和 `warningRules` 是可选的，可以省略或设置为空数组 `[]`
- 如果量表没有因子，`factors` 可以设置为空数组 `[]`
- 大部分字段都有默认值，可以省略
---
## 🔍 常见错误
### 错误1：JSON格式错误
**错误信息**：`JSON格式错误：...`
**解决方法**：
- 检查JSON语法，确保所有括号、引号匹配
- 使用JSON验证工具（如 jsonlint.com）验证JSON格式
- 确保没有多余的逗号
### 错误2：量表编码已存在
**错误信息**：`量表编码已存在：XXX`
**解决方法**：
- 修改 `scaleCode` 为唯一值
- 或先删除系统中已存在的量表
### 错误3：题目序号映射失败
**错误信息**：`找不到题目序号 X 对应的题目ID`
**解决方法**：
- 检查 `factors[].rules[].itemNumber` 是否与 `items[].item.itemNumber` 对应
- 确保题目序号从1开始，连续编号
### 错误4：必填字段缺失
**错误信息**：`XXX不能为空`
**解决方法**：
- 检查必填字段是否都已填写
- 参考本文档的字段说明，补充缺失的字段
---
## 📚 相关文档
- [新量表导入完整操作指南](./15-新量表导入完整操作指南.md) - 手动操作步骤
- [ScaleImportVO.java](../../ry-news-system/src/main/java/com/ddnai/system/domain/psychology/vo/ScaleImportVO.java) - 数据结构定义
---
## ✅ 验证清单
导入前请检查：
- [ ] JSON格式正确（可以使用JSON验证工具验证）
- [ ] `scaleCode` 唯一且符合命名规范
- [ ] `scaleName` 已填写
- [ ] 所有题目都有 `itemNumber` 和 `itemContent`
- [ ] 所有题目都至少包含1个选项
- [ ] 所有选项都有 `optionCode`、`optionContent` 和 `optionScore`
- [ ] 如果有因子，所有因子都有 `factorCode` 和 `factorName`
- [ ] 如果有因子，所有计分规则的 `itemNumber` 都能在题目列表中找到
- [ ] `status` 字段设置为 `"0"`（正常）或 `"1"`（停用）
---
**最后更新**：2025-01-XX
Reference in New Issue Copy Permalink