# 《三国志与乱世英雄史诗》沉浸式数字课程门户

高校通识课程的博物馆级数字门户：八章课程时间轴、三国疆域互动地图、四十件数字文物长廊、AI 讲解员、古琴战鼓程序化配乐，以及配套 Word 讲义与教学 PPT。全站以「玄墨 · 暗金 · 朱红」三色主视觉与衬线中文排版贯穿，强调留白与丝滑过渡动画。

---

## 一、系统架构

纯静态多页架构（零构建、零后端依赖，可直接部署到任意静态托管）：

```
sanguo-course/
├── index.html            首页：视差开场 + 旌旗战马 + 疆域轨迹画布 + 章节/文物预览
├── chapters.html         章节时间轴：8 章立体卡片（鼠标跟随 3D 倾斜）
├── chapter.html?id=N     章节详情：知识讲解 / TTS 朗读 / 动态画卷 / zoom-in 细赏
├── map.html              互动地图：Leaflet + 30 节点 + 疆域示意面 + 侧栏联动
├── relics.html           文物长廊：40 件瀑布流 + 360° 翻转卡（深链 #rXX）
├── archive.html          课程档案馆：讲义/课件下载 + 种子内容清单
├── css/main.css          全站设计系统（唯一视觉规范文件）
├── js/
│   ├── shared.js         导航/页脚注入、入场动效、声音按钮
│   ├── music.js          Web Audio 古琴×战鼓程序化配乐引擎
│   ├── home.js           首页：门帘、视差、余烬粒子、疆域轨迹画布
│   ├── zoom.js           通用 zoom-in 查看器（滚轮缩放/拖拽/热点聚焦）
│   ├── chapter-detail.js 详情页渲染、TTS 队列、动态画卷影院
│   ├── map.js            Leaflet 地图逻辑
│   ├── relics.js         文物渲染 + 博物馆线图 SVG 模板库 + 翻转卡
│   └── guide.js          AI 讲解员（知识库 + 流式打字 + 语音播报）
├── data/                 种子内容（全站数据唯一来源）
│   ├── chapters.js       八章课程数据
│   ├── places.js         30 地图节点 + 三国疆域多边形
│   └── relics.js         40 件文物档案
└── assets/
    ├── img/              22 张 AI 文生图（统一存放）
    └── downloads/        Word 讲义 + 教学 PPT
```

页面间关系：章节详情 ↔ 地图节点 ↔ 文物展品三者互相深链（`map.html#chibi`、`relics.html#r01`、`chapter.html?id=3`），构成课程知识网络。

## 二、视觉规范（Design Tokens）

三色主视觉，全部集中于 `css/main.css` 顶部 CSS 变量：

| 角色 | 色值 | 用途 |
|---|---|---|
| 玄墨 | `#0B0B0D` | 全站底色；`#121216 / #1A1A21` 为浮层与卡片阶 |
| 暗金 | `#C9A227` | 主强调：标题描金、分隔线、编号；高光 `#E8C86A`、沉金 `#8A6D1D` |
| 朱红 | `#C63C26` | 印章、蜀汉标识、战役标签；深朱 `#8E2A1C` |
| 缣帛白 | `#E9E3D5` | 正文；次级 `#A89F8D`、弱级 `#6F6859` |
| 功能色 | `#3E6B5E`（吴·黛青）/ `#5A6B8C`（魏·黛蓝） | 仅用于地图势力区分 |

字体体系（Google Fonts CDN）：

- **Noto Serif SC** 400/600/900 — 全站中文衬线，标题 900 加宽字距
- **Cinzel** — 拉丁展示体（章节编号、眉标、数据带）
- **Ma Shan Zheng** — 书法体点缀（引文、页脚词句）
- **JetBrains Mono** — 技术眉标与时间标签

描金标题实现：`linear-gradient` 多段金色 + `background-clip:text` + `drop-shadow` 金晕。全站噪点为 SVG `feTurbulence` data-URI 叠加，动效统一使用 `cubic-bezier(.22,.9,.28,1)` 缓动。

## 三、AI 生成资源清单（统一存放于 `assets/`）

文生图 22 张（`assets/img/`）：首屏三层（`hero-bg` 赤壁火光水墨长卷、`hero-horses` 战马旌旗、`hero-blade` 青龙偃月刀与羽扇剪影）、八章封面 `ch1~ch8`、讲解员立绘 `guide-zhuge`、十件核心文物图 `relic-*`。其余 30 件文物为程序绘制的博物馆线图风格 SVG（`js/relics.js` 模板库），保证展陈统一且体积可控。

文生语音（TTS）：章节详情页「AI 语音讲解」与 AI 讲解员语音播报均使用浏览器 `speechSynthesis`（zh-CN），逐句队列朗读，带 16 秒长句守护（规避 Chrome 长语音截断）。

文生音乐：`js/music.js` 以 Web Audio 程序化合成五声音阶古琴拨弦（含空谷延迟混响）、低频战鼓节奏与风声底噪，导航栏 ♪ 按钮与首页「入馆聆听」门帘控制开关。

文生视频（替代方案）：章节「动态画卷」以 AI 封面为底、Ken Burns 运镜 + 影院黑边 + 逐句画卷台词 + 余烬粒子构成 18 秒动态长卷，作为文生视频的轻量替代。

## 四、AI 接口预留（可升级点）

所有 AI 能力均留有替换钩子，无需改动页面结构：

1. **AI 讲解员 → 真实大模型**：设置 `window.SANGUO_GUIDE_API = async (question) => "回答文本"` 即可接管问答（默认走内置 29 组知识库匹配，支持流式打字与语音播报不变）。
2. **文生音乐 → 真实音频**：`window.MusicConfig = { url: 'xxx.mp3' }` 可扩展为 `<audio>` 播放（当前程序化引擎已实现同等体验）。
3. **动态画卷 → 文生视频**：将章节封面替换为 `<video>` 源即可，影院外框、进度条与台词系统可复用。
4. **地图底图**：当前使用 CARTO dark 在线瓦片；离线环境自动退化为纯墨底 + 疆域示意面，功能不受影响。

## 五、部署说明

纯静态站点，任何静态托管均可。本次通过 Cloudflare Pages 部署：

```bash
wrangler pages deploy . --project-name=sanguo-course
```

## 六、内容立场说明

- 课程坚持「文史互证」：演义虚构桥段（桃园结义、空城计、借东风、貂蝉等）在正文中均明确标注为文学意象，与《三国志》史实对照呈现。
- 标注「文学意象」「概念复原」的文物展品为《三国演义》文学形象或文献记载器物的风格化复原，非考古出土实物；历史文物线图（铜奔马、神兽镜、弩机等）依据通行考古形制绘制。
- 地图疆域多边形为风格化示意，非精确历史边界（页面图例已注明）。