# 中世对照历史时间轴 — 项目方案

> 把割裂的「中国史」和「世界史」两本书放一起看，会发现很多意想不到的对照。

## 一句话定位

学习历史时，把同一年代发生的中外大事左右对照着读。

## 核心决策（2026-09-28 锁定）

| 维度 | 决策 |
| --- | --- |
| 时间范围 | 上古（约公元前 3000） — 1949 年新中国成立 |
| 技术路线 | 静态 + Web 管理后台（数据 / 管理 / 展示三层） |
| 种子数据 | ~500+ 条/边（共 1000+ 条），分批交付 |
| 分类体系 | 5 大类 + 子分类 |
| 视觉风格 | 极简现代风（Tailwind + 卡片） |
| 时间轴布局 | 双栏对照（中国左 / 世界右） |

## 架构

```
项目根目录/
├── data/
│   ├── events.json          # 主数据（管理后台写入）
│   ├── events.schema.json   # JSON Schema 定义
│   └── events.seed.json     # 种子数据（初始 10 条示例）
├── public/                  # 前端 + 静态资源
│   ├── index.html           # 时间轴展示页
│   ├── admin/index.html     # 管理后台（Phase 4）
│   ├── css/style.css        # 自定义样式
│   └── js/{timeline,admin}.js
├── functions/api/           # Cloudflare Functions（Phase 4）
├── PROPOSAL.md              # 本文档
├── README.md                # 使用说明
└── wrangler.toml            # Cloudflare Pages 配置（Phase 5）
```

- **数据层**：`data/events.json`，Git 仓库版本化
- **管理层**：`/admin` 页 → Cloudflare Functions → GitHub API → commit → 触发自动部署
- **展示层**：`index.html`，读 `events.json`，渲染双栏对照时间轴
- **部署**：Cloudflare Pages（GitHub 推送即自动部署，永久免费）

## 数据 Schema

### 顶层结构

```json
{
  "version": "1.0",
  "generated_at": "2026-09-28T11:30:00+08:00",
  "categories": { ... },     // 5 大类 + 子分类定义
  "dynasties": [ ... ],      // 中国朝代映射（渲染时按 year 自动归类）
  "events": {
    "china": [ ... ],        // 中国事件数组
    "world": [ ... ]         // 世界事件数组
  }
}
```

### 单条事件结构

```json
{
  "id": "china-001",
  "year": -2070,             // 公元前年用负数
  "year_end": -1600,         // 可选，持续事件
  "year_approximate": true,  // 可选，年份大致时标注
  "title": "夏朝建立",
  "category": "political",
  "subcategory": "dynasty_founding",
  "description": "**禹** 之子启建立...（支持 Markdown）",
  "people": ["禹", "启"],
  "sources": [
    { "type": "wiki_zh", "url": "https://zh.wikipedia.org/wiki/夏朝", "title": "夏朝 - 维基百科" }
  ]
}
```

完整 Schema 见 `data/events.schema.json`。

## 5 大分类 + 子分类

| 类别（color） | 子分类 |
| --- | --- |
| 政治/战争（红） | 改朝换代、战争、起义/革命、政治制度、外交/条约、殖民与解放 |
| 经济/民生（金） | 经济政策、贸易、人口、灾荒 |
| 文化/文学艺术（蓝） | 哲学、宗教、文学、艺术、建筑、学术 |
| 科技（绿） | 天文、数学、医学、工程、四大发明、农业 |
| 名人（紫） | 思想家、政治家、军事家、科学家、艺术家 |

> 子分类用 `category.subcategory` 复合字段，例如 `"political.dynasty_founding"` 表示政治大类下的「改朝换代」。

## UI 设计

### 主页（index.html）

```
┌─────────────────────────────────────────────────┐
│ 标题: 中世对照历史时间轴                          │
│ 筛选: [分类▼] [年份范围: ▬▬▬●───●▬▬▬] [重置] │
├─────────────────┬─────┬─────────────────┤
│                 │     │                 │
│  中国           │ 年代│  世界           │
│  [朝代分组]     │ 尺  │                 │
│  [事件卡片]     │     │  [事件卡片]     │
│  [事件卡片]     │     │  [事件卡片]     │
│                 │     │                 │
└─────────────────┴─────┴─────────────────┘
```

- 时间轴按 100 年一档（高密度时段如春秋战国可缩到 50 年）
- 事件卡片左侧色条按分类着色
- 点击卡片展开描述 + 来源链接
- 顶部筛选器：分类（多选切换）、年份范围 slider

### 管理后台（admin/index.html，Phase 4）

- 顶部：登录（密码）
- 中部：事件列表（表格）+ 增删改按钮
- 表单：分类、年份、标题、描述、人物、来源
- 提交后通过 Cloudflare Functions → GitHub API → commit → 自动部署

## 执行计划

| Phase | 内容 | 状态 |
| --- | --- | --- |
| 1 | 项目骨架（PROPOSAL + Schema + demo + 种子 10 条） | ✅ 2026-09-28 |
| 2 | 种子范例（50 条中国 + 50 条世界） | ⏳ 待大山审 Phase 1 后 |
| 3 | 批量数据（450+ 条/边，按朝代/文明分组） | ⏳ |
| 4 | 管理后台（admin 页 + Functions + GitHub API） | ⏳ |
| 5 | GitHub repo + Cloudflare Pages 自动部署 | ✅ 2026-09-28（4 次 Actions run 才通，详见 `memory/lessons/github-actions-cloudflare-deploy-token-newline.md`）|

## 线上 URL

- **演示站**：https://china-world-timeline.pages.dev/
- **GitHub 仓库**：https://github.com/kumabarloc/china-world-timeline (private)
- **部署方式**：GitHub Actions 自动（push main → 自动 deploy，~2 分钟）

## 数据来源策略

- **主体**：维基百科中文 + 英文双语（每条事件附 URL，可点击验证）
- **重要事件**：补充《剑桥中国史》《全球通史》等权威学术资料
- **争议事件**：标注「存疑」，列出多方观点
- **审核机制**：你审 Phase 2 时发现来源不准/存疑的，我立即替换

## 待定事项

- [x] Cloudflare 账号（用现有 Barrett.wei@gmail.com）
- [x] GitHub 仓库（kumabarloc/china-world-timeline）
- [x] Cloudflare API Token（从 `/home/barloc/.openclaw/keys.sh` 写入 GitHub Secrets）
- [x] GitHub Actions workflow（wrangler@^3.90 + env vars 传 token，绕开 wrangler-action v3 redactor bug）
- [ ] 自定义域名（可选，Phase 6 再做）
- [ ] admin 鉴权方案（Phase 4 才需要）

## 后续展望（v2+）

- 时间轴缩放（按朝代/世纪切分）
- 跨事件关联（如：马可波罗来华 ↔ 元朝 ↔ 蒙古西征）
- 人物专题页（点击人物名聚合相关事件）
- 多语言（英文版时间轴）
- 协作模式（多人编辑 + PR 审核）