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

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. 结论
+
+这份模板的目的是把动画从“视觉稿”变成“工程规格”。  
+只有规格明确，程序才能稳定接入。
+