# 域聊测试问卷 JSON 格式规范 v1.0

本文档定义了域聊平台测试问卷文件的 JSON 格式规范。开发者需按照此规范编写问卷文件，上传后经审核通过即可在 Android 客户端使用。

## 一、文件基本信息

| 项目 | 说明 |
|------|------|
| 文件格式 | `.json` |
| 文件编码 | UTF-8（无 BOM） |
| 最大文件大小 | 512 KB |
| 最大题目数量 | 200 道 |

## 二、顶层结构

```json
{
  "title": "问卷标题",
  "description": "问卷描述（可选）",
  "version": "1.0.0",
  "category": "personality",
  "language": "zh-CN",
  "author": "作者名称（可选）",
  "estimated_minutes": 5,
  "questions": [],
  "result_rules": [],
  "scoring": {}
}
```

### 顶层字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | string | 是 | 问卷标题，最多 100 字符 |
| `description` | string | 否 | 问卷描述，介绍问卷内容、适用人群等 |
| `version` | string | 否 | 问卷版本号，默认 `1.0.0` |
| `category` | string | 否 | 分类：`personality`/`knowledge`/`interest`/`relationship`/`career`/`health`/`general` |
| `language` | string | 否 | 语言代码，默认 `zh-CN` |
| `author` | string | 否 | 作者名称 |
| `estimated_minutes` | number | 否 | 预计完成时间（分钟） |
| `questions` | array | 是 | 题目数组，至少 1 道，最多 200 道 |
| `result_rules` | array | 否 | 结果判定规则数组 |
| `scoring` | object | 否 | 计分配置 |

## 三、题目结构

### 3.1 单选题（single）

```json
{
  "id": "q1",
  "type": "single",
  "question": "你更喜欢哪种休闲方式？",
  "description": "题目补充说明（可选）",
  "required": true,
  "options": [
    { "value": "A", "label": "阅读书籍", "score": 1 },
    { "value": "B", "label": "户外运动", "score": 2 },
    { "value": "C", "label": "社交聚会", "score": 3 },
    { "value": "D", "label": "观看影视", "score": 1 }
  ]
}
```

### 3.2 多选题（multiple）

```json
{
  "id": "q2",
  "type": "multiple",
  "question": "以下哪些是你擅长的？（可多选）",
  "required": true,
  "min_select": 1,
  "max_select": 3,
  "options": [
    { "value": "A", "label": "编程开发", "score": 2 },
    { "value": "B", "label": "设计创作", "score": 2 },
    { "value": "C", "label": "沟通表达", "score": 1 },
    { "value": "D", "label": "数据分析", "score": 2 }
  ]
}
```

### 3.3 判断题（boolean）

```json
{
  "id": "q3",
  "type": "boolean",
  "question": "你认为自己是一个外向的人。",
  "required": true,
  "true_label": "是",
  "false_label": "否",
  "true_score": 2,
  "false_score": 0
}
```

### 3.4 评分题（rating）

```json
{
  "id": "q4",
  "type": "rating",
  "question": "请为你当前的压力水平打分",
  "required": true,
  "min": 1,
  "max": 10,
  "min_label": "完全没有压力",
  "max_label": "压力极大",
  "step": 1
}
```

### 3.5 填空题（text）

```json
{
  "id": "q5",
  "type": "text",
  "question": "请用一句话描述你自己",
  "required": false,
  "placeholder": "例如：我是一个热爱生活的人",
  "max_length": 200
}
```

### 3.6 量表题（scale）— 李克特量表

```json
{
  "id": "q6",
  "type": "scale",
  "question": "我在社交场合感到自在",
  "required": true,
  "scale_points": 5,
  "labels": ["非常不同意", "不同意", "中立", "同意", "非常同意"],
  "scores": [1, 2, 3, 4, 5]
}
```

### 题目通用字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | 是 | 题目唯一标识，如 `q1`、`q2` |
| `type` | string | 是 | 题目类型：`single`/`multiple`/`boolean`/`rating`/`text`/`scale` |
| `question` | string | 是 | 题干内容 |
| `description` | string | 否 | 题目补充说明 |
| `required` | boolean | 否 | 是否必答，默认 `true` |

## 四、计分与结果判定

### 4.1 计分配置（scoring）

```json
"scoring": {
  "mode": "sum",
  "dimensions": {
    "extraversion": { "name": "外向性", "question_ids": ["q1", "q3", "q6"] },
    "neuroticism": { "name": "神经质", "question_ids": ["q2", "q4"] }
  }
}
```

| 字段 | 说明 |
|------|------|
| `mode` | 计分模式：`sum`（总分）/`dimension`（维度分）/`none`（不计分） |
| `dimensions` | 维度配置，每个维度包含名称和关联题目 ID |

### 4.2 结果规则（result_rules）

```json
"result_rules": [
  {
    "id": "result_a",
    "title": "外向型人格",
    "description": "你是一个外向、热情、善于社交的人...",
    "condition": {
      "type": "score_range",
      "dimension": "extraversion",
      "min": 10,
      "max": 20
    },
    "advice": "建议你多参与社交活动，发挥你的沟通优势...",
    "icon": "🌟"
  },
  {
    "id": "result_b",
    "title": "内向型人格",
    "description": "你是一个内敛、深思、专注的人...",
    "condition": {
      "type": "score_range",
      "dimension": "extraversion",
      "min": 0,
      "max": 9
    },
    "advice": "建议你在独处中恢复能量，同时适度拓展社交圈...",
    "icon": "🌙"
  }
]
```

### 条件类型

| 类型 | 说明 | 字段 |
|------|------|------|
| `score_range` | 总分/维度分区间 | `dimension`(可选), `min`, `max` |
| `answer_match` | 答案匹配 | `question_id`, `values`(数组) |
| `and` | 多条件同时满足 | `conditions`(数组) |
| `or` | 任一条件满足 | `conditions`(数组) |

## 五、完整示例

以下是一个完整的简单性格测试问卷示例：

```json
{
  "title": "简易性格测试",
  "description": "通过几个简单问题，快速了解你的性格倾向",
  "version": "1.0.0",
  "category": "personality",
  "estimated_minutes": 2,
  "scoring": {
    "mode": "sum"
  },
  "questions": [
    {
      "id": "q1",
      "type": "single",
      "question": "周末你更愿意？",
      "options": [
        { "value": "A", "label": "在家看书追剧", "score": 0 },
        { "value": "B", "label": "和朋友出去玩", "score": 2 }
      ]
    },
    {
      "id": "q2",
      "type": "boolean",
      "question": "在聚会上你会主动和陌生人交谈",
      "true_score": 1,
      "false_score": 0
    },
    {
      "id": "q3",
      "type": "scale",
      "question": "我喜欢成为众人关注的焦点",
      "scale_points": 5,
      "labels": ["非常不同意", "不同意", "中立", "同意", "非常同意"],
      "scores": [0, 0, 1, 2, 2]
    }
  ],
  "result_rules": [
    {
      "id": "introvert",
      "title": "内向型",
      "description": "你更享受独处时光，内心世界丰富，做事专注认真。",
      "condition": { "type": "score_range", "min": 0, "max": 2 },
      "icon": "🌙"
    },
    {
      "id": "ambivert",
      "title": "中间型",
      "description": "你在内外向之间取得平衡，既能享受独处也能融入社交。",
      "condition": { "type": "score_range", "min": 3, "max": 4 },
      "icon": "⚖️"
    },
    {
      "id": "extrovert",
      "title": "外向型",
      "description": "你充满活力，善于社交，喜欢与人互动，是人群中的焦点。",
      "condition": { "type": "score_range", "min": 5, "max": 6 },
      "icon": "☀️"
    }
  ]
}
```

## 六、注意事项

1. **JSON 合法性**：确保文件是合法的 JSON，不包含注释（`//` 或 `/* */`）
2. **ID 唯一性**：所有题目 ID 和结果规则 ID 必须唯一
3. **分数一致性**：确保每个可计分选项都有 `score` 字段
4. **条件覆盖**：确保结果规则的条件能覆盖所有可能的分数范围，避免无结果匹配
5. **文本长度**：题干和选项标签建议简洁明了，避免过长
6. **编码格式**：必须使用 UTF-8 编码，确保中文正常显示

## 七、API 获取问卷

Android 客户端可通过以下接口获取问卷：

```
GET /api/developer.php?action=list_questionnaires&status=approved
GET /api/developer.php?action=get_questionnaire&id=xxx&raw=1
```

`raw=1` 时直接返回本格式的原始 JSON，客户端可直接解析渲染测试界面。