# data.json 数据结构规范（Schema）

LockTrace·行迹·人生地图 的全部内容由一个 `js/data.json` 文件驱动。
本文档定义该文件的完整结构。照着改 JSON，不用碰任何代码。

- 示例成品：[`../js/data.json`](../js/data.json)（玄奘西行，18 事件）
- 空白模板：[`template.json`](template.json)
- 填写指南：[`guide.md`](guide.md)

---

## 一、顶层结构

```jsonc
{
  "person":   { ... },   // 必填，人物信息
  "coordinateSystem": "BD-09",        // 必填，固定值
  "coordinateProvider": "百度地图开放平台", // 必填，固定值
  "events": [ ... ]     // 必填，人生事件数组，按时间正序排列
}
```

## 二、person 人物对象

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | ✅ | 姓名，如 `"玄奘"` |
| `givenName` | string | ⬜ | 名（与姓分开时用），如 `"祎"` |
| `courtesyName` | string | ⬜ | 字 |
| `hao` | string | ⬜ | 号 |
| `years` | string | ✅ | 生卒年，如 `"602—664"`；在世人物可写 `"1980—"` |
| `title` | string | ✅ | 本地图主题，如 `"西天取经之路"` |
| `summary` | string | ✅ | 人物简介，2~4 句 |
| `portrait.alt` | string | ⬜ | 画像替代文本（无障碍），无画像也建议填 |

## 三、events[] 事件对象

事件**必须按时间先后排列**，顺序即播放顺序。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | ✅ | 全库唯一标识，建议 `英文关键词-年份`，如 `desert-627` |
| `year` | number\|string | ✅ | 发生年份，如 `627`；不确定可用 `"约627"` |
| `place` | string | ✅ | 当时地名，如 `"莫贺延碛"` |
| `modernPlace` | string | ✅ | 今地名，如 `"新疆哈密以西戈壁"` |
| `title` | string | ✅ | 事件标题，≤10 字 |
| `description` | string | ✅ | 事件叙述，60~160 字；**也是旁白朗读的文本** |
| `storyTag` | string | ⬜ | 故事标签，如 `"身陷绝境"` |
| `storyTagType` | string | ⬜ | 标签类型，如 `"艰难险阻"` |
| `storyImage` | boolean | ⬜ | 是否配故事插图，默认 `false` |
| `storyImageAlt` | string | ⬜ | 插图替代文本，`storyImage:true` 时建议填 |
| `phase` | string | ✅ | 人生阶段名，如 `"西行出发"`；同阶段必须**逐字一致**，筛选器据此生成 |
| `coordinates` | [number, number] | ✅ | `[经度, 纬度]`，BD-09 坐标 |
| `confidence` | string | ✅ | 史料可信度，见下表 |
| `sources` | array | ⬜ | 史料来源数组 |
| `intensity` | number | ✅ | 情感强度 **1~5 整数**，见下文 |

### confidence 取值（四选一）

| 值 | 页面显示 | 含义 |
| --- | --- | --- |
| `"confirmed"` | 史料·明确记载 | 有可靠史料明确记录 |
| `"inferred"` | 路线·合理推定 | 据史料推定，无直接记载 |
| `"disputed"` | 学界·存疑 | 学界有争议 |
| `"literary"` | 文学·演绎 | 文学作品中的情节（如西游记） |

### sources[] 来源

```json
{ "label": "《大唐西域记》卷一", "url": "https://..." }
```
- `label`：来源名称；`url`：可访问的链接。
- 没有在线来源时可省略整个 `sources` 字段。

### intensity 情感强度（1~5）

| 值 | 文案 | 适用情绪 | 地图上的表现 |
| --- | --- | --- | --- |
| 1 | 平静 | 日常、安定、收官 | 普通圆点，无发光 |
| 2 | 低 | 小波动、休整 | 微弱金光 |
| 3 | 中 | 一般事件 | 金色发光 |
| 4 | 高 | 重大抉择、重逢、突破 | 橙色发光，标记略放大 |
| 5 | 激荡 | 生死、绝境、巅峰、凯旋 | 红色脉动光环，强度条转红 |

赋值建议：全序列以 3 为基准，两端少用；一个人物的 5 分事件建议不超过 20%。

## 四、字段与页面的对应关系

| 页面位置 | 使用字段 |
| --- | --- |
| 左侧地图标记位置 | `coordinates` |
| 标记颜色/大小/脉冲 | `intensity` |
| 标记间连线 | 相邻两事件自动生成 |
| 侧边栏人物简介 | `person.*` |
| 阶段筛选按钮 | 所有事件的 `phase` 去重生成 |
| 人物画卷 | 第 1 张为主视觉；`storyImage:true` 的事件依次配 `images/xz_N.jpg` |
| 时间线卡片 | 事件全部字段 |
| 旁白朗读 | `year` + `place` + `title` + `description` 自动拼接 |

## 五、URL 参数（分享链接）

应用页 `map.html` 支持以下查询参数，自动生成、无需手写：

| 参数 | 说明 | 示例 |
| --- | --- | --- |
| `p` | 人物名（多人物数据源时用于校验） | `p=玄奘` |
| `e` | 定位到第几个事件（从 0 开始） | `e=3` |
| `t` | 主题：`dark` / `light` | `t=dark` |

示例：`map.html?p=玄奘&e=3&t=dark` 打开即定位在第 4 个事件。