# 量表导入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