# 生产级交付检查清单

从"能跑的 Demo"到"能交付用户的生产级引擎"，需要补全以下内容。

---

## 一、性能与加载（玩家打开游戏的前 3 秒）

| # | 项目 | 说明 |
|---|------|------|
| 1.1 | 启动加载优化 | 骨架屏 + 进度条 + 首场景预加载优先级。替代当前串行 fetch JSON → 无 loading 进度 |
| 1.2 | 视频预加载策略 | LRU 缓存池（3-5 个已解码视频），降低内存占用，提升预加载命中率 |
| 1.3 | 大场景 JSON 懒加载 | 章节级按需加载（只加载当前章节的场景定义和视频），避免整个 demo.json 一次性加载 |
| 1.4 | 资源压缩 | 视频 WebM/MP4 双编码 + Gzip/Brotli JSON |
| 1.5 | 首屏时间目标 | <200ms（骨架屏 + 关键 CSS 内联） |

---

## 二、可靠性与错误处理

| # | 项目 | 说明 |
|---|------|------|
| 2.1 | 视频加载失败 | 超时检测 + 重试（指数退避 3 次）+ 错误画面 + 跳过按钮（ROADMAP P18） |
| 2.2 | JSON 解析失败 | 格式验证 + 错误提示 + 降级到默认剧情 |
| 2.3 | IndexedDB 不可用 | 检测 + 降级到 memory-only 模式 + 提示用户 |
| 2.4 | 内存溢出 | 视频缓存上限 + 自动释放最久未用的 buffer |
| 2.5 | 浏览器兼容检测 | 检测 Web Audio API / Fullscreen API / `<video>` 支持，不支持的显示提示 |

---

## 三、部署与分发

| # | 项目 | 说明 |
|---|------|------|
| 3.1 | 构建产物分析 | 代码分割 + tree-shaking 验证 |
| 3.2 | CDN 部署 | `public/videos/` 上传到 CDN，`videoUrl` 支持绝对路径 |
| 3.3 | PWA 离线支持 | Service Worker 缓存核心资源，离线也能玩 |
| 3.4 | 版本更新 | Service Worker 检测新版本 + 提示刷新 |
| 3.5 | 多环境配置 | 环境变量控制 JSON 路径、CDN 域名 |

---

## 四、内容管线与制作效率

| # | 项目 | 说明 |
|---|------|------|
| 4.1 | JSON Schema 验证 | 编辑器 + 引擎加载时验证 JSON 结构合法性 |
| 4.2 | 视频编码规范脚本 | 自动化 ffmpeg 批处理：统一编码参数、多场景生成 |
| 4.3 | 字幕工具链 | Aegisub 兼容 + 时间轴自动校准 |
| 4.4 | 分支冲突检测 | 死路检测（某些分支永不触发）+ 循环检测 |
| 4.5 | 版本管理 | 场景 JSON 版本号 + 存档兼容性检测 + 迁移逻辑 |

---

## 五、分析

| # | 项目 | 说明 |
|---|------|------|
| 5.1 | 玩家行为统计 | 匿名收集中途退出位置、热门分支、平均通关时长 |
| 5.2 | 错误上报 | `window.onerror` + Promise rejection 捕获 + 上报日志服务 |
| 5.3 | A/B 测试 | 同一场景多个视频变体，按用户分流 |

---

## 六、安全

| # | 项目 | 说明 |
|---|------|------|
| 6.1 | JSON 注入防护 | 禁止 eval，所有外部数据只做 JSON.parse |
| 6.2 | XSS 检查 | 确认没有 `v-html` 使用点 |
| 6.3 | 存档篡改防护 | 存档加 HMAC 签名校验，防止本地修改成就 |

---

## 七、测试

| # | 项目 | 说明 |
|---|------|------|
| 7.1 | 单元测试 | Engine / StateManager / VideoManager 核心逻辑测试 |
| 7.2 | 剧情路径遍历 | 自动遍历所有 choices 分支，验证无死路 |
| 7.3 | 跨浏览器测试 | Chrome / Firefox / Safari 兼容矩阵 |
| 7.4 | 性能回归 | Lighthouse + 自定义首屏/切换延迟基线 |

---

## 八、文档

| # | 项目 | 说明 |
|---|------|------|
| 8.1 | API 文档 | Engine 公开方法文档 |
| 8.2 | 场景 JSON 规范 | 完整字段参考手册 |
| 8.3 | 制作指南 | 如何从零制作一个交互式电影 |
| 8.4 | 部署指南 | 如何部署到服务器 / CDN / PWA |

---

## 优先级建议

| 优先级 | 内容 |
|:--:|------|
| **P0 立即可做** | JSON Schema 验证 (4.1)、场景分章节懒加载 (1.3)、错误处理 (2.1-2.5) |
| **P1 短期** | PWA 离线 (3.3)、视频编码规范脚本 (4.2)、单元测试 (7.1) |
| **P2 中期** | CDN 部署 (3.2)、分析 (5.1-5.2)、存档 HMAC (6.3) |
| **P3 长期** | A/B 测试 (5.3)、多环境配置 (3.5)、跨浏览器测试 (7.3) |