# 学习数据准备规范

每个场景准备一份 UTF-8 编码的 `.json` 文件。从 `examples/template.json` 复制后修改，上传网站会自动检查格式；检查通过即可点击“生成学习页面”。不需要编程或 OpenAI API。

## 最小示例

```json
{
  "schema_version": 1,
  "title_zh": "酒店入住英语",
  "description_zh": "先看中文，再展开英文，点击朗读练习。",
  "notices_zh": ["房型和退房时间请以酒店实际规定为准。"],
  "sections": [{
    "id": "check-in",
    "title_zh": "前台入住",
    "items": [{
      "id": "booking",
      "source_number": "1",
      "zh": "我有预订，可以办理入住吗？",
      "answer_zh": "当然，可以看一下您的护照吗？",
      "english": [
        {"role": "question", "text": "I have a reservation. Could I check in, please?"},
        {"role": "answer", "text": "Of course. May I see your passport, please?"}
      ]
    }]
  }]
}
```

## 字段规则

| 位置 | 字段 | 如何填写 |
| --- | --- | --- |
| 整份文件 | `schema_version` | 固定填数字 `1` |
| 整份文件 | `title_zh`、`description_zh` | 中文标题、可选的中文介绍 |
| 整份文件 | `notices_zh` | 可选，中文注意事项数组，始终显示 |
| 整份文件 | `sections` | 按显示顺序排列的章节数组 |
| 章节 | `id` | 英文字母、数字、短横线或下划线组成，章节间不能重复 |
| 章节 | `title_zh`、`items` | 中文章节名、练习数组；纯说明章节可填空数组 |
| 章节 | `notes_zh`、`checklist_zh` | 可选的中文说明、准备清单，始终显示 |
| 练习 | `id` | 章节内唯一，格式与章节 `id` 相同 |
| 练习 | `source_number` | 可选的原文编号，使用字符串，例如 `"190"` |
| 练习 | `zh` | 中文句子或中文问题，始终显示 |
| 练习 | `answer_zh`、`notes_zh` | 可选的中文答复、中文注意事项，始终显示 |
| 练习 | `english` | 英文段落数组，至少一段，每段单独提供朗读按钮 |
| 英文段落 | `text` | 完整英文原句，展开该条后显示 |
| 英文段落 | `role` | 可选：`sentence` 短句、`question` 问题、`answer` 答复 |

`notes_zh`、`notices_zh`、`checklist_zh` 均为字符串数组。表格使用章节内可选 `tables`，完整示例见模板；中文列名 `columns_zh` 必须与每行 `zh` 的单元格数一致。每行可含 `english`，没有英文的行作为中文说明显示。

填写时保留原始中英文措辞，不删掉“视情况而定”“仅限特定材料”等技术限定条件。中文字段填写希望默认显示的内容，英文全部放入 `english`；系统不会自动翻译或猜测缺失内容。数字参数、单位和品牌名照原文填写。

单个文件不超过2 MB、100个章节、1000条练习与表格行合计。文字按纯文本显示，不使用 HTML。生成的页面统一重新编号，`source_number` 另外保留原文编号。下载的单文件离线版包含全部音频，不依赖网站登录或外部服务。

机器可读的完整约束为 `schema.json`。如用其他工具整理原始资料，可把本规范、模板和 `schema.json` 一起提供，要求其仅整理结构并原样保留全部内容。