0. 先和大家打个招呼
一名独立开发者，对中国历史和可视化技术有浓厚兴趣。
说实话，这个项目的规模远超我最初的预期。最开始我只是想做一个简单的长平之战地图展示，但和 TRAE 沟通后，它一步步帮我把这个想法扩展成了一个完整的战役可视化平台。
最让我印象深刻的是 TRAE 对历史数据的严谨态度。当我提出"校验所有战役的伤亡数据"时，它主动联网搜索了《史记》《三国志》《明史》等正史原文，逐场核实了 10 场战役的数字，还发现了萨尔浒之战的伤亡阵营搞反了这样一个我完全没注意到的问题。
另一个让我觉得"原来这么简单"的时刻是士兵建模。我只说了一句"当前的士兵太丑了，参考网页游戏的风格"，TRAE 就直接重写了整个渲染系统，用 roundRect、fillEllipse 等精细绘制函数替代了原来的方块堆叠，四种兵种各有独立造型。整个过程我只给了一句话的需求描述。
最大的坎是构建打包。为了让产物能直接双击打开（不依赖服务器），我们经历了多次迭代——从 type=“module” 跨域问题、到脚本执行顺序、再到地图图片被误删，每一步都是 TRAE 帮我定位和解决的。这种"你说问题，我来解决"的配合方式，确实跨过了我原本以为搞不定纯前端 Canvas 开发的门槛。
1. Demo 简介
是什么
墨战图是一款纯前端单页应用，用 Canvas 2D 精细像素风格可视化再现中国古代 10 场经典战役。零后端依赖，打包后单个 HTML 文件即可直接在浏览器中打开运行。
面向谁
核心用户包括：历史爱好者、中小学历史教师、对古代军事感兴趣的大众用户、以及需要在课堂上展示战役进程的教育工作者。
主要功能
- 10 场战役可视化：长平之战、赤壁之战、淝水之战、巨鹿之战、垓下之战、官渡之战、夷陵之战、牧野之战、汉水之战、萨尔浒之战
- 精细像素士兵建模：步兵、骑兵、弓兵、将领四种独立造型，含铠甲纹路、武器挥舞、死亡动画
- 演示模式：一键自动播放，Web Speech API 中文语音解说 + 底部字幕同步 + 阶段倒计时
- 交互探索：点击部队/建筑/地形查看史实详情，底部阶段标签跳转，滚轮缩放，拖拽平移
- 结局面板：展示双方伤亡统计、史籍原文引用、历史影响
2. Demo 创作思路
灵感来源
看了很多历史纪录片，发现古代战役的讲解通常是"一张静态地图 + 旁白描述"。我想：能不能做成一个可以交互的动态地图，让用户自己探索每场战役的进程、查看部队信息、感受战场氛围？
想解决的问题
- 历史教学中，学生难以直观理解战役的地理布局和部队调动
- 现有的古代战争可视化产品通常需要安装、付费或依赖后端服务
- 战役数据散落在各处，没有一个统一的、可交互的查看方式
为什么做这个方向
选择纯前端 Canvas 方案有两个核心考量：第一，零门槛——用户不需要安装任何东西，打开 HTML 就能用；第二，性能可控——像素风格渲染在 Canvas 2D 上性能优秀，即使几百个士兵同时在场也能保持流畅。同时，数据驱动的架构让 10 场战役共享同一套代码，只需维护数据即可扩展。
3. Demo 体验地址
解压后直接运行 index.html 文件即可：
墨战图.zip (3.5 MB)
4. TRAE 实践过程
以下是使用 TRAE 完成墨战图开发的完整流程：
- 项目初始化与架构搭建
使用 Vite + TypeScript 创建项目，定义数据模型（BattleData、UnitData、RouteData 等），建立核心渲染循环。
TypeScriptViteCanvas 2D - 多战役数据体系建设
从"只支持长平之战"扩展到 10 场战役。创建campaigns.ts（战役目录）和campaignBattles.ts（动态数据生成），实现动态阵营系统（颜色、名称随战役切换）。
数据驱动10 场战役正史校验 - 历史数据校验
要求 TRAE 联网核实所有战役的伤亡数据。成功发现萨尔浒之战的伤亡阵营搞反（后金 500 vs 明军 45870 被错误互换），并修正了赤壁、淝水、牧野等战役中"兵力"与"伤亡"混淆的问题。
数据校验正史引用萨尔浒修正 - 士兵精细像素建模重写
从简单的方块堆叠升级为精细像素画风格。四种兵种各有完整建模：步兵（兜鍪、札甲、长戟）、骑兵（完整战马+骑手+披风）、弓兵（束发冠、交叉绑带轻甲、弓箭拉弦动画）、将领（武冠、鱼鳞甲、飘动大旗）。
像素画4 种兵种动画系统 - UI 组件整合与优化
将右下角 BattleStats 面板的功能合并到顶部 OverviewBar（兵力条+伤亡+态势+进度一体化），移除左下角时间轴中的冗余播放按钮，保留底部阶段标签栏作为主要阶段导航。
UI 整合OverviewBar阶段标签 - 演示模式与语音解说
实现 Web Speech API 中文语音解说、底部字幕同步显示、阶段间隔根据解说时长动态调整、前置倒计时 5 秒快速进入、播完不循环。
Web Speech API语音解说字幕 - 单文件打包方案
解决file://协议下的跨域问题：构建后脚本将 JS/CSS 内联到 HTML，<script>移到</body>前（确保 DOM 解析后执行），地图图片保留在 assets 目录，路径改为相对路径。
单文件零服务器file:// 兼容
关键任务对话
2505136201538788:500abea7129aa2731af6346d1d567d95_6a42597588e133bae9bdc126.6a45c489b146925261bb2347.6a45c489b146925261bb2345:TRAE Work CN.0.1.34.no_sid.no_ppe.T(2026/7/2 09:53:13)
2505136201538788:10aa72c7dc00b7c94e8bc5afdb0c0e54_6a42597588e133bae9bdc126.6a462657b146925261bb2714.6a462657b146925261bb2712:TRAE Work CN.0.1.34.no_sid.no_ppe.T(2026/7/2 16:50:31)
2505136201538788:dc2aecfe8ca362152b2328ad5a169f10_6a42597588e133bae9bdc126.6a4e3a17c0452fb193fa77d8.6a4e3a17c0452fb193fa77d6:TRAE Work CN.0.1.34.no_sid.no_ppe.T(2026/7/8 19:52:55)
2505136201538788:c62486cd125ca1475b544dbbea5cc36a_6a42597588e133bae9bdc126.6a4e3e30c0452fb193fa785f.6a4e3e30c0452fb193fa785d:TRAE Work CN.0.1.34.no_sid.no_ppe.T(2026/7/8 20:10:24)
