xiaozhang/xinli

Fork 0

xiao12feng 6473c94e1c 量表导入功能实现

2025-11-07 12:07:24 +08:00

19 KiB

Raw Blame History

量表导入JSON标准格式说明

📋 概述

本文档详细说明如何使用JSON格式导入量表数据到系统中。JSON格式适用于批量导入完整的量表数据，包括量表基本信息、题目、选项、因子、计分规则等。

🎯 导入方式

系统支持三种导入方式：

JSON文本导入：在导入界面直接粘贴JSON文本
JSON文件导入：上传.json格式的文件
PDF/DOCX文档导入：系统自动解析文档并转换为JSON格式（自动识别）

📝 JSON数据结构

完整JSON结构

{
  "scale": {
    // 量表基本信息
  },
  "items": [
    // 题目列表（包含选项）
  ],
  "factors": [
    // 因子列表（包含计分规则）
  ],
  "interpretations": [
    // 结果解释配置（可选）
  ],
  "warningRules": [
    // 预警规则配置（可选）
  ]
}

🔍 详细字段说明

1. 量表基本信息 (scale)

{
  "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)

{
  "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)

每个题目包含一个选项数组：

{
  "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)

{
  "factors": [
    {
      "factor": {
        "factorCode": "F1",                 // 因子编码（必填）
        "factorName": "躯体化",             // 因子名称（必填）
        "factorEnName": "Somatization",     // 因子英文名称（可选）
        "factorDescription": "躯体化因子描述", // 因子描述（可选）
        "factorOrder": 1                    // 因子排序（可选）
      },
      "rules": [
        // 计分规则列表
      ]
    }
  ]
}

字段说明：

factorCode：因子编码，建议使用 F1、F2、F3 等格式
factorName：因子的中文名称
factorOrder：因子的排序顺序

5. 计分规则 (rules)

每个因子包含一个计分规则数组：

{
  "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) - 可选

{
  "interpretations": [
    {
      "scaleId": null,                      // 量表ID（导入时自动设置，无需填写）
      "factorId": null,                     // 因子ID（导入时自动设置，可选）
      "scoreMin": 0,                        // 分数下限（必填）
      "scoreMax": 10,                       // 分数上限（必填）
      "level": "低",                        // 等级（可选）
      "levelName": "正常范围",              // 等级名称（可选）
      "interpretationTitle": "正常范围",    // 解释标题（必填）
      "interpretationContent": "您的得分在正常范围内", // 解释内容（可选）
      "suggestions": "继续保持良好的心理状态", // 建议指导（可选）
      "sortOrder": 1                       // 排序顺序（可选）
    }
  ]
}

字段说明：

scoreMin 和 scoreMax：定义分数范围，系统会根据实际得分匹配对应的解释
factorId：如果留空（null），表示针对量表总体；如果填写，表示针对特定因子

7. 预警规则 (warningRules) - 可选

{
  "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题量表（无因子）

{
  "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量表（含因子和计分规则）

{
  "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文本导入

进入 心理测评管理 → 量表管理
点击 "导入" 按钮
在弹出对话框中，切换到 "JSON文本" 标签页
将JSON文本粘贴到文本框中
点击 "确定" 按钮导入

方式2：JSON文件导入

将JSON数据保存为 .json 文件
进入 心理测评管理 → 量表管理
点击 "导入" 按钮
在弹出对话框中，切换到 "文件上传" 标签页
选择JSON文件并上传
点击 "确定" 按钮导入

方式3：PDF/DOCX文档导入（自动解析）

准备PDF或DOCX格式的量表文档
进入 心理测评管理 → 量表管理
点击 "导入" 按钮
在弹出对话框中，切换到 "文件上传" 标签页
选择PDF/DOCX文件并上传
点击 "预览解析结果" 查看系统自动识别的结果
根据需要调整JSON数据
点击 "确定" 按钮导入

⚠️ 注意事项

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不能为空 解决方法：

检查必填字段是否都已填写
参考本文档的字段说明，补充缺失的字段

📚 相关文档

新量表导入完整操作指南 - 手动操作步骤
ScaleImportVO.java - 数据结构定义

✅ 验证清单

导入前请检查：

JSON格式正确（可以使用JSON验证工具验证）
scaleCode 唯一且符合命名规范
scaleName 已填写
所有题目都有 itemNumber 和 itemContent
所有题目都至少包含1个选项
所有选项都有 optionCode、optionContent 和 optionScore
如果有因子，所有因子都有 factorCode 和 factorName
如果有因子，所有计分规则的 itemNumber 都能在题目列表中找到
status 字段设置为 "0"（正常）或 "1"（停用）

最后更新：2025-01-XX

19 KiB Raw Blame History Unescape Escape

量表导入JSON标准格式说明

📋 概述

🎯 导入方式

📝 JSON数据结构

完整JSON结构

🔍 详细字段说明

1. 量表基本信息 (scale)

2. 题目列表 (items)

3. 选项列表 (options)

4. 因子列表 (factors)

5. 计分规则 (rules)

6. 结果解释 (interpretations) - 可选

7. 预警规则 (warningRules) - 可选

📄 完整JSON示例

示例1：简单的5题量表（无因子）

示例2：SCL-90量表（含因子和计分规则）

🚀 使用步骤

方式1：JSON文本导入

方式2：JSON文件导入

方式3：PDF/DOCX文档导入（自动解析）

⚠️ 注意事项

1. 数据完整性

2. 数据唯一性

3. 数据映射

4. 字段类型

5. 可选字段

🔍 常见错误

错误1：JSON格式错误

错误2：量表编码已存在

错误3：题目序号映射失败

错误4：必填字段缺失

📚 相关文档

✅ 验证清单

19 KiB

Raw Blame History