整理动画接入文档与调试面板分组

animation-dictionary.md

@@ -0,0 +1,357 @@
+# 动画字典 v1
+
+## 1. 目的
+
+这份文档用于统一说明：
+
+- 当前系统里**已经存在**的动画触发点
+- 哪些事件**适合继续补动画**
+- 每个动画应该归属到哪一层
+- `lite` 模式下哪些动画应该保留，哪些应该降级
+
+一句话：
+
+**动画字典 = 事件到动画效果的映射表。**
+
+它的价值是：
+
+- 防止动画实现越来越散
+- 方便做性能分级
+- 方便新玩法复用已有动画语言
+- 方便以后做动画 profile / theme
+
+---
+
+## 2. 分层约定
+
+当前动画建议分成 4 层：
+
+### 2.1 地图空间动画
+
+作用在地图对象本身。
+
+例如：
+
+- 当前目标点 pulse
+- 可打点外环
+- 已完成点 settle
+- 已跳过点灰化
+- 迷雾 reveal
+- 金币收集爆点
+
+归属：
+
+- `MapPresentation`
+- `MapScene`
+- `WebGL renderer`
+
+### 2.2 HUD 动画
+
+作用在底部 HUD、数字、状态块。
+
+例如：
+
+- 进度跃迁
+- 点距变化
+- 速度/里程/心率数字轻量过渡
+
+归属：
+
+- 页面层 `WXML / WXSS`
+- `MapEngine` 只负责下发状态类名
+
+### 2.3 UI / Feedback 动画
+
+作用在全局提示、局部闪光、反馈层。
+
+例如：
+
+- 顶部提示条出现
+- 局部 stage flash
+- 成功提示
+- 错误/警示提示
+
+归属：
+
+- `feedbackConfig`
+- `UiEffectDirector`
+- `FeedbackDirector`
+- 页面层消费
+
+### 2.4 微交互动画
+
+作用在按钮、弹层、设置面板等。
+
+当前优先级最低。
+
+---
+
+## 3. 已实现动画字典
+
+下面这一部分是当前已经落到代码里的内容。
+
+| 事件/状态 | 地图空间动画 | HUD 动画 | UI/Feedback 动画 | lite 保留 |
+|---|---|---|---|---|
+| `control_ready` | 当前目标点更亮、ready 强调 | 打点相关状态切换 | 无 | 是 |
+| `control_completed:start` | 开始点完成 settle 外环 | 进度/点距轻反馈 | 轻量成功反馈 | 是 |
+| `control_completed:control` | 普通检查点完成 settle 外环 | 进度跃迁、点距动效 | 轻量地图 flash / pulse | 是 |
+| `control_completed:finish` | 终点完成 settle 外环更明显 | 进度完成反馈 | finish 级反馈更强 | 是 |
+| `control_skipped` | 当前点灰化、斜杠标记 | 当前目标推进 | 轻提示（较轻） | 是 |
+| `target_changed` | 当前目标高亮切换 | 目标相关 HUD 状态切换 | 无 | 是 |
+| `heart_rate_updated` | 无 | 心率数字过渡 | 无 | 是 |
+| `timer_tick` | 无 | 计时器数字轻量过渡 | 无 | `lite` 可降级 |
+| `mileage_updated` | 无 | 里程数字过渡 | 无 | `lite` 可降级 |
+| `speed_updated` | 无 | 速度数字过渡 | 无 | `lite` 可降级 |
+| `panel_progress_changed` | 无 | 进度数字 / 状态切换 | 无 | 是 |
+| `map_pulse` | 地图局部 pulse | 无 | 可伴随轻 stage flash | `lite` 简化 |
+| `stage_flash` | 无 | 无 | 局部屏幕闪光 | `lite` 可关闭 |
+
+---
+
+## 4. 推荐新增动画字典
+
+下面这些是**非常适合继续补齐**的事件。
+
+### 4.1 高优先级
+
+#### `session_started`
+
+建议效果：
+
+- 地图：起点轻脉冲或开场吸附感
+- HUD：开始态切换
+- UI：顶部提示条轻弹入
+
+原因：
+
+- 这是对局开始的第一感受
+- 很适合统一“进入比赛状态”的语言
+
+#### `target_transition`
+
+指：
+
+- 一个点完成后
+- 下一个目标点接管当前目标状态
+
+建议效果：
+
+- 地图：旧点 settle，新点接管 pulse
+- HUD：目标进度轻切换
+- UI：可以不额外做
+
+原因：
+
+- 当前这条链已经有基础，但还不够“连续”
+- 这是顺序赛最值得打磨的高频体验
+
+#### `control_skipped`
+
+建议效果：
+
+- 地图：当前点灰化过渡更明显
+- HUD：提示“已跳过 x 号点”
+- UI：轻量 skip toast / 轻闪光
+
+原因：
+
+- 逻辑已经有
+- 状态已经有
+- 动画语言还不够完整
+
+---
+
+### 4.2 中优先级
+
+#### `gps_lock_changed:on`
+
+建议效果：
+
+- 地图：回中吸附感
+- HUD：无
+- UI：轻提示“已锁定定位点”
+
+#### `gps_lock_changed:off`
+
+建议效果：
+
+- 地图：无
+- HUD：无
+- UI：轻提示“已解除锁定”
+
+#### `center_scale_ruler_changed`
+
+建议效果：
+
+- UI：比例尺淡入/淡出
+
+原因：
+
+- 比例尺是工具型功能
+- 不需要强动画，但可以更自然
+
+#### `north_reference_changed`
+
+建议效果：
+
+- UI：小提示
+- 指北针顶部文案轻切换
+
+---
+
+### 4.3 下一阶段重点
+
+#### `heart_rate_zone_changed`
+
+建议效果：
+
+- HUD：颜色平滑切换
+- UI：边缘呼吸 / 警示
+- 地图：一般不建议直接做
+
+原因：
+
+- 未来心率玩法、危险状态会很依赖这条
+
+#### `danger_state_changed`
+
+适用于未来：
+
+- 幽灵追逐
+- 危险区
+- 高压状态
+
+建议效果：
+
+- UI：边缘呼吸
+- HUD：局部强调
+- 地图：危险区波纹
+
+#### `zone_entered / zone_cleared`
+
+适用于未来：
+
+- 区域玩法
+- 迷雾玩法
+- 领地玩法
+
+建议效果：
+
+- 地图：区域高亮 / reveal
+- HUD：区域状态变化
+- UI：轻量提示
+
+---
+
+## 5. 不建议过度动画化的节点
+
+下面这些不建议做太重：
+
+- 每次 GPS 更新
+- 每次地图缩放
+- 每次地图拖动
+- 每次 compass heading 变化
+- 每次 telemetry 微小变化
+
+原因：
+
+- 高频
+- 成本高
+- 极易拖垮低端机
+
+原则：
+
+**高频输入只做平滑，不做明显动画。**
+
+---
+
+## 6. 动画等级建议
+
+当前已有两级：
+
+- `standard`
+- `lite`
+
+建议动画字典里每项都标清楚在 `lite` 下如何处理。
+
+### `standard`
+
+- 完整 pulse
+- 完整 settle
+- HUD 数字过渡正常
+- 局部 flash 保留
+
+### `lite`
+
+- pulse 层数减少
+- settle 更轻
+- HUD 数字动画缩短或关闭
+- flash 关闭或极轻
+
+---
+
+## 7. 下一步推荐落地顺序
+
+建议按这个顺序继续推进：
+
+1. `session_started`
+2. `target_transition`
+3. `control_skipped`
+4. `gps_lock_changed`
+5. `heart_rate_zone_changed`
+6. `danger_state_changed`
+
+---
+
+## 8. 执行原则
+
+后面继续做动画时，遵循这几条：
+
+### 8.1 先看事件，再决定动画
+
+不要先想“做个好看的效果”，而是先问：
+
+- 哪个事件需要被用户感知？
+- 这个事件最适合地图 / HUD / UI 哪一层？
+
+### 8.2 只强化高价值反馈
+
+优先强化：
+
+- 开始
+- 打点成功
+- 目标切换
+- 跳点
+- 危险状态
+
+### 8.3 低端机优先
+
+任何新增动画都要先问：
+
+- `lite` 下要不要保留？
+- 不保留是否影响信息传达？
+
+### 8.4 动画不替代状态
+
+动画只做状态的表现，不能替代状态本身。
+
+也就是：
+
+- 先有状态
+- 再有动画
+
+---
+
+## 9. 阶段结论
+
+当前动画系统已经具备：
+
+- 主链
+- 分层
+- 高价值基础动画
+- 性能等级
+
+下一步的重点不是继续零散加动效，而是：
+
+**按动画字典逐项补齐高频体验链。**
+

animation-integration-spec.md

@@ -0,0 +1,163 @@
+# 动画接入规格模板
+
+## 1. 用途
+
+这份模板用于：
+
+- 设计公司交付动画时填写
+- 开发接入前确认规格
+- 作为动画实现与验收依据
+
+建议：一个动画一条记录。
+
+---
+
+## 2. 基础信息模板
+
+```md
+动画 ID：
+动画名称：
+所属页面/模块：
+所属层级：地图空间 / HUD / UI反馈 / 过场
+优先级：高 / 中 / 低
+
+触发事件：
+触发条件：
+是否高频：
+
+作用对象：
+起始状态：
+结束状态：
+
+动画形式：程序动画 / Lottie / 序列帧 / 视频 / 其他
+资源文件：
+
+时长：
+延迟：
+缓动：
+是否循环：
+是否可中断：
+重复触发策略：覆盖 / 忽略 / 重启 / 排队
+
+standard 表现：
+lite 表现：
+是否允许关闭：
+
+设计说明：
+开发备注：
+验收标准：
+```
+
+---
+
+## 3. 字段说明
+
+### 动画 ID
+
+要求：
+
+- 全局唯一
+- 使用英文或稳定标识
+
+例如：
+
+- `control_complete_flash`
+- `target_ready_pulse`
+- `session_intro_banner`
+
+### 所属层级
+
+建议四选一：
+
+- 地图空间
+- HUD
+- UI反馈
+- 过场
+
+### 触发事件
+
+必须明确写出触发它的事件。
+
+例如：
+
+- `control_completed:control`
+- `control_skipped`
+- `session_started`
+- `heart_rate_zone_changed:red`
+
+### 重复触发策略
+
+必须提前约定：
+
+- `覆盖`
+- `忽略`
+- `重启`
+- `排队`
+
+否则高频触发时容易行为不一致。
+
+### standard / lite
+
+每个动画都必须给出两档建议。
+
+例如：
+
+- `standard`：完整 pulse + 外环
+- `lite`：保留单层 pulse，去掉外环
+
+---
+
+## 4. 推荐填写示例
+
+```md
+动画 ID：control_complete_flash
+动画名称：打点成功轻闪光
+所属页面/模块：地图页
+所属层级：UI反馈
+优先级：高
+
+触发事件：control_completed:control
+触发条件：普通检查点打点成功
+是否高频：是
+
+作用对象：地图主舞台
+起始状态：正常地图状态
+结束状态：恢复正常地图状态
+
+动画形式：程序动画
+资源文件：无
+
+时长：320ms
+延迟：0ms
+缓动：ease-out
+是否循环：否
+是否可中断：是
+重复触发策略：重启
+
+standard 表现：淡白色局部 flash，透明度较明显
+lite 表现：透明度降低 50%，时长缩短到 220ms
+是否允许关闭：是
+
+设计说明：突出“完成打点”的即时成功感
+开发备注：通过 UiEffectDirector 下发 stageFx
+验收标准：普通打点时稳定触发，连续打点不拖尾
+```
+
+---
+
+## 5. 对设计公司的要求
+
+建议以后明确告诉设计公司：
+
+- 不只要演示稿
+- 必须提供参数规格
+- 必须提供资源清单
+- 必须说明低配降级方案
+
+---
+
+## 6. 结论
+
+这份模板的目的是把动画从“视觉稿”变成“工程规格”。  
+只有规格明确，程序才能稳定接入。
+

animation-integration-workflow.md

@@ -0,0 +1,268 @@
+# 动画接入工作流
+
+## 1. 目的
+
+这份文档用于说明：
+
+- 设计公司提供的动画稿，应该如何转成程序可执行的内容
+- 我方应该如何组织这类工作
+- 动画接入前、中、后的协作方式
+
+一句话：
+
+**不要把动画稿直接塞进程序，要先把它转成“工程规格”。**
+
+---
+
+## 2. 核心原则
+
+### 2.1 交付的是规格，不只是效果
+
+设计公司不能只给：
+
+- 视频
+- GIF
+- 一张效果图
+
+至少还需要给：
+
+- 动画名称
+- 触发时机
+- 作用对象
+- 起始状态
+- 结束状态
+- 时长
+- 延迟
+- 缓动
+- 是否循环
+- 是否可中断
+- 资源形式
+- 降级方案
+
+### 2.2 先分类，再决定技术实现
+
+不是所有动画都适合用同一种实现方式。
+
+必须先判断它属于：
+
+- 地图空间动画
+- HUD 动画
+- UI / Feedback 动画
+- 过场 / Cutscene 动画
+
+### 2.3 先看信息价值，再看视觉效果
+
+优先实现：
+
+- 帮助用户理解状态的动画
+- 引导视线的动画
+- 强化反馈的动画
+
+延后实现：
+
+- 纯装饰性动画
+- 对玩法理解没有帮助的长演出
+
+### 2.4 低端机优先
+
+任何动画都要先问：
+
+- `lite` 模式下怎么降级？
+- 不做时是否影响信息表达？
+
+---
+
+## 3. 推荐流程
+
+建议每个动画都按下面这条流程走：
+
+### 第一步：设计交付
+
+设计提供：
+
+- 动画视觉稿
+- 动画规格参数
+- 资源文件
+- 适配说明
+
+### 第二步：整理进动画字典
+
+先把动画纳入事件字典，而不是直接实现。
+
+例如：
+
+- 什么事件触发它
+- 作用在哪一层
+- `standard / lite` 如何处理
+
+### 第三步：技术归类
+
+判断该动画由哪一层承接：
+
+- `MapPresentation / Renderer`
+- 页面 `WXML / WXSS`
+- `UiEffectDirector`
+- 单独的 `Cutscene` 层
+
+### 第四步：选择实现方式
+
+例如：
+
+- 纯程序动画
+- 序列帧 / sprite
+- Lottie
+- 视频
+
+### 第五步：做性能分级
+
+明确：
+
+- `standard` 怎么做
+- `lite` 怎么做
+- 是否允许完全关闭
+
+### 第六步：联调与验收
+
+至少验证：
+
+- 触发正确
+- 状态切换正确
+- 多次连续触发是否正常
+- 可中断行为是否正确
+- 低端机是否流畅
+
+---
+
+## 4. 动画实现方式建议
+
+### 4.1 纯程序动画
+
+适合：
+
+- 地图 pulse
+- 数字过渡
+- HUD 状态变化
+- 按钮反馈
+
+优点：
+
+- 最轻
+- 最稳定
+- 最适合小程序
+
+### 4.2 Lottie / 骨骼类动画
+
+适合：
+
+- 局部高质量 UI 动效
+- 成功反馈
+- 勋章 / 特殊提示
+
+风险：
+
+- 小程序里复杂 Lottie 可能卡
+
+### 4.3 序列帧 / Sprite
+
+适合：
+
+- 爆点
+- 金币收集
+- 局部地图特效
+
+风险：
+
+- 占内存
+- 占包体
+
+### 4.4 视频 / 过场动画
+
+适合：
+
+- 章节开场
+- 比赛结果页
+- 特殊演出
+
+不适合：
+
+- 地图过程中的高频反馈
+
+---
+
+## 5. 当前项目里的推荐落点
+
+### 地图空间动画
+
+放在：
+
+- `MapPresentation`
+- `MapScene`
+- `WebGL Renderer`
+
+### HUD 动画
+
+放在：
+
+- 页面层 `WXML / WXSS`
+
+### Feedback 动画
+
+放在：
+
+- `feedbackConfig`
+- `UiEffectDirector`
+- `FeedbackDirector`
+
+### 过场动画
+
+建议未来独立一层：
+
+- `Transition`
+- `Cutscene`
+
+---
+
+## 6. 当前建议的协作方式
+
+以后和设计公司协作时，建议这样分工：
+
+### 设计公司负责
+
+- 视觉稿
+- 动画节奏
+- 参数规格
+- 资源文件
+- 降级建议
+
+### 我方负责
+
+- 事件归类
+- 技术选型
+- 动画字典维护
+- 分层接入
+- 性能分级
+
+---
+
+## 7. 推荐的工作顺序
+
+建议以后优先接这类动画：
+
+1. 打点成功
+2. 目标切换
+3. 跳点
+4. 高压 / 危险反馈
+5. 章节开场 / 过场动画
+
+---
+
+## 8. 结论
+
+动画接入的正确方式不是：
+
+**拿到设计稿 -> 直接写代码**
+
+而是：
+
+**拿到设计稿 -> 转成动画规格 -> 纳入动画字典 -> 选技术实现 -> 做性能分级 -> 再接程序**
+

animation-review-checklist.md

@@ -0,0 +1,162 @@
+# 动画接入评审清单
+
+## 1. 用途
+
+这份清单用于在接设计稿或准备开发前，快速判断：
+
+- 这个动画能不能接
+- 应该接到哪一层
+- 有没有性能风险
+- 有没有交付缺口
+
+---
+
+## 2. 设计稿评审
+
+### 2.1 动画目标是否明确
+
+- 这个动画是为了表达什么？
+- 它是状态反馈，还是纯装饰？
+- 用户不看它，会不会影响理解？
+
+### 2.2 触发条件是否明确
+
+- 由哪个事件触发？
+- 是否会高频触发？
+- 是否允许重复触发？
+
+### 2.3 交付是否完整
+
+- 是否有参数规格？
+- 是否有资源文件？
+- 是否有尺寸 / 比例说明？
+- 是否有 `lite` 降级说明？
+
+---
+
+## 3. 技术评审
+
+### 3.1 该动画属于哪一层
+
+- 地图空间
+- HUD
+- UI反馈
+- 过场
+
+### 3.2 最合适的实现方式是什么
+
+- 程序动画
+- Lottie
+- 序列帧
+- 视频
+
+### 3.3 是否真的需要资源文件
+
+很多动画其实可以纯程序实现，不需要额外资源。
+
+如果只是：
+
+- pulse
+- 渐隐
+- 平移
+- 数字过渡
+
+优先用程序动画。
+
+---
+
+## 4. 性能评审
+
+### 4.1 是否高频
+
+如果是高频事件，不适合做重动画：
+
+- GPS 更新
+- compass heading 更新
+- 拖动 / 缩放
+- telemetry 微小变化
+
+### 4.2 lite 模式怎么处理
+
+必须明确：
+
+- 保留
+- 简化
+- 关闭
+
+### 4.3 是否会增加页面层负担
+
+要判断：
+
+- 会不会引入高频 `setData`
+- 会不会创建大数组
+- 会不会增加持续循环动画
+- 会不会增加桥接成本
+
+---
+
+## 5. 交互评审
+
+### 5.1 是否可中断
+
+- 用户切页面怎么办？
+- 状态瞬间变化怎么办？
+- 连续触发怎么办？
+
+### 5.2 是否会和现有动画冲突
+
+- 同一事件是否已有动画？
+- 是否会重复表达同一个信息？
+- 是否和现有地图 pulse / HUD 动效叠加过重？
+
+---
+
+## 6. 当前项目特别注意项
+
+### 6.1 地图过程中的动画必须克制
+
+因为当前项目：
+
+- 地图是主舞台
+- 低端机性能敏感
+- 页面桥接成本高
+
+所以：
+
+- 地图上的高频动画必须轻量
+- 尽量减少页面层大范围动画
+
+### 6.2 优先动画化高价值节点
+
+优先做：
+
+- 打点成功
+- 目标切换
+- 跳点
+- 危险 / 高压反馈
+
+延后做：
+
+- 纯装饰性微动效
+- 复杂长演出
+
+---
+
+## 7. 验收清单
+
+动画接入完成后，至少确认：
+
+- 触发时机正确
+- 结束时机正确
+- 多次连续触发稳定
+- `standard / lite` 都可用
+- 低端机可接受
+- 不破坏现有状态链
+
+---
+
+## 8. 结论
+
+动画接入前，只要这份清单里有明显回答不出来的问题，就不应该直接开做。  
+先补规格，再接程序。
+

miniprogram/pages/map/map.wxml

@@ -566,6 +566,13 @@
             <text class="info-panel__label">Mock Speed</text>
             <text class="info-panel__value">{{mockSpeedText}}</text>
           </view>
+          <view class="control-row">
+            <view class="control-chip {{gpsTracking ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleToggleGpsTracking">{{gpsTracking ? '停止定位' : '开启定位'}}</view>
+          </view>
+          <view class="control-row">
+            <view class="control-chip {{locationSourceMode === 'real' ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleSetRealLocationMode">真实定位</view>
+            <view class="control-chip {{locationSourceMode === 'mock' ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleSetMockLocationMode">模拟定位</view>
+          </view>
           <view class="debug-group-title">心率</view>
           <view class="info-panel__row">
             <text class="info-panel__label">Heart Rate</text>
@@ -675,13 +682,6 @@
             <text class="info-panel__label">North Ref</text>
             <text class="info-panel__value">{{northReferenceText}}</text>
           </view>
-          <view class="control-row">
-            <view class="control-chip {{gpsTracking ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleToggleGpsTracking">{{gpsTracking ? '停止定位' : '开启定位'}}</view>
-          </view>
-          <view class="control-row">
-            <view class="control-chip {{locationSourceMode === 'real' ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleSetRealLocationMode">真实定位</view>
-            <view class="control-chip {{locationSourceMode === 'mock' ? 'control-chip--active' : 'control-chip--secondary'}}" bindtap="handleSetMockLocationMode">模拟定位</view>
-          </view>
           <view class="control-row">
             <view class="control-chip control-chip--secondary" bindtap="handleCycleNorthReferenceMode">{{northReferenceButtonText}}</view>
           </view>