xtrip/CHANGELOG.md

变更记录（CHANGELOG）

本项目所有显著变更均记录于此。 版本号：vYYYY.MM.DD-XX；类型标签：[Add] / [Change] / [Fix] / [Remove] / [Doc] / [Chore]

v2026.10.17-03

22:45 · 抓取西安高德瓦片生成两张高清参考底图（仅供绘制参照，不参与游戏运行时加载）。

• [Add] public/assets/maps/xian-reference-full-z12.png（1536×1280）：全域概览，覆盖游戏 viewBox 对应范围（西至沣河、东至兵马俑/临潼）
• [Add] public/assets/maps/xian-reference-city-z14.png（2304×2304）：主城区高清图，覆盖城墙 / 回民街 / 大明宫 / 小雁塔 / 陕历博 / 大雁塔 / 曲江
• [Add] scripts/fetch-reference-maps.py：高德路网瓦片（webrd01~04）抓取 + PIL 拼接 + 版权署名条；Wikimedia Commons 与 OSM 瓦片服务在当前网络不可达，故改用高德源
• [Doc] 版权说明：参考图基于高德地图数据，已叠署名条，仅限项目内部参照（校准手账 SVG 坐标 / 走势），对外分发前应从 public/ 移出

v2026.10.17-02

21:06 · 包管理器由 npm 迁移至 pnpm 11（无依赖版本变化）。

• [Chore] 删除 node_modules/ 与 package-lock.json，改用 pnpm install 生成 pnpm-lock.yaml（入库）
• [Add] 新增 pnpm-workspace.yaml：allowBuilds: { esbuild: true } 批准 esbuild 安装期构建脚本（pnpm 11 安全策略默认忽略，未批准会拦截 pnpm run 的依赖状态检查）
• [Chore] .gitignore 日志段已含 pnpm-debug.log*，无额外调整

v2026.10.17-01

18:27 · 全量代码审查后的缺陷修复与性能优化（不改变玩法与视觉基调）。

• [Fix] 移动端摇杆正方向失效：rex 的 forceX/forceY 是像素级位移而非 [-1,1]，且正上/下/左/右必有一轴为 0；改用插件 noKey 判定推动状态
• [Fix] 纪念页显示期间地图输入未锁定可被穿透操作：输入互斥改为 uiLocks 计数模型，新增 ui:opened 事件由各 UI 组件自行加锁
• [Fix] 底图加载失败导致白屏：新增占位底图降级；MapScene 底图改用 setDisplaySize 铺满世界
• [Fix] hasSave() 误报有存档：改以解锁集合判定；unlock() 增加非法 id 校验（顺带把加载期 O(n) 过滤改为 O(1)）
• [Fix] 引导箭头首帧闪现（初始 alpha 归零）；HUD pointer-events: none 被 #ui > * 特异性覆盖而失效
• [Change] 性能：缓存解锁集合与景点索引，消除每帧 getSnapshot() 分配与 SPOTS.find 线性查找；UI 持锁期间直接跳过世界更新
• [Remove] 移除从未被消费的 Phaser 照片预加载与 buildPhotoPlaceholder（照片由 DOM <img> 按需加载，原实现白占约 65MB 纹理显存）
• [Change] 纪念页九宫格改用真实照片（缺失降级为景点图标）并支持点击复用拍立得弹窗放大重看
• [Doc] 同步 docs/spec.md 事件协议表与输入锁模型说明

v2026.10.16-01

首次完整实现（M1–M3）：可玩核心 + 完整体验 + 手账美化（全占位资源）。

• [Doc] 新增 docs/spec.md：经需求澄清与设计确认的细化技术规格（12 项决策记录、分层架构、数据模型、验收标准、M1–M6 交付路线、照片替换指南）
• [Add] 项目脚手架：Vite 5 + Phaser 3 + phaser3-rex-plugins；base: './' 相对路径，适配 GitHub Pages / Vercel 静态托管
• [Add] 混合架构落地：Phaser 地图层（PreloadScene / MapScene 双场景）+ DOM UI 层，经 event-bus 事件桥解耦通信
• [Add] 手账风西安地图：3000×2100 SVG 底图（明城墙 + 护城河、渭/灞/浐/沣水系、主干路网、罗盘、装饰边框），叠加 AI 纸张纹理（multiply 混合）
• [Add] 玩家角色：程序生成贴纸小人（4 方向 × 2 帧弹性行走动画），AI 精灵表就绪后可整体替换
• [Add] 玩法系统：WASD/方向键 + 移动端虚拟摇杆；景点触发冷却防连弹；localStorage 进度持久化（隐私模式内存降级）；屏幕边缘方向引导箭头（目标入视野自动淡出）
• [Add] DOM UI 组件：手账封面页（胶带/拍立得装饰、继续旅行与重新开始）、拍立得照片弹窗（叠沓翻看、手写文案、日期角标、照片缺失降级占位卡）、HUD 收集进度徽章、全解锁纪念页（照片九宫格 + 旅程统计）、竖屏旋转提示
• [Add] 数据驱动内容源：src/data/spots.js 十景点配置（坐标/照片/文案）；scripts/gen-placeholder-photos.mjs 占位照片生成脚本（本次生成 15 张 4:3 手账风占位 SVG）
• [Chore] 新增 .gitignore：依赖与构建产物、Capacitor/Android 打包产物、环境密钥、日志、编辑器与系统临时文件