先在 crates/lol_champions/src/{champion}/tests.rs 写测试
- 使用 ChampionTestHarness::build::<Champion>(name, HarnessMode::Headless, &config)
- 至少覆盖：施法成功、冷却生效、消耗扣除、目标筛选、多段/重施窗口
运行测试确保失败（红）
再实现技能逻辑，让测试通过（绿）
重构（如有必要）

测试写完后才允许实现或修改技能代码。

单元测试 Debug 流程

首先要通过日志定位问题，不要一上来就盲目添加修复代码

在代码执行路径上添加详细的 info! 的中文日志
如果还是找不到问题就继续添加更多日志输出
问题解决后日志可以留下，只需要将 info! 改为 debug!

验收标准

cargo check -p lol_champions cargo test -p lol_champions

英雄技能系统

架构设计

架构类型：基于 ECS 与 Observer 的解耦技能架构。
核心设计原则：回归代码主导逻辑，施法校验由统一管线处理，技能的具体动作与状态变迁完全由代码观察者系统控制。
行为与状态：技能的运行逻辑以系统形式写在代码中，运行时状态挂载在 ECS 实体上。

英雄技能开发流程与核心组件

统一管线

管线定位：通用施法前置校验与扣减资源，校验通过后派发事件。详见 skill-pipe.md。

观察者与联动

英雄观察者：通过监听施法事件分发技能逻辑。
联动观察者：监听伤害造成与普攻结束等衍生事件。

原子动作与状态

原子动作：播放动画、冲刺位移、范围伤害场、发射飞弹等。详见 skill-action.md。
状态系统：提供护盾、眩晕、减速等通用效果。

英雄标准目录结构

路径规则：英雄目录位于 crates/lol_champions/src/<hero>/。
mod.rs：注册插件与核心施法监听器。
技能文件：q.rs、w.rs、e.rs、r.rs 存放对应主动技能逻辑。
passive.rs：存放被动技能逻辑。
buffs.rs：声明英雄特有的状态组件。
tests.rs：集成测试与测试配置。

数值读取机制

计算公式值：通过 get_skill_value 动态解析属性加成公式。详见 skill-value.md。
配置原始值：通过 get_skill_data_value 读取特定等级原始数组。

典型技能参考文档

单段技能：skill-single-stage.md
分段重施技能：skill-multi-stage.md
被动联动技能：skill-passive.md
飞弹与投射物：skill-missile.md
延迟范围伤害（地面警示器）：skill-delayed-aoe.md
位移系统：skill-dash.md
控制系统（CC）：skill-cc.md
动画系统：skill-animation.md
冷却控制机制：skill-cooldown.md
测试与调试实践：skill-test.md
搜索研究英雄技能的详细介绍：skill-research.md

开发经验积累

数据驱动倾向：一切可配置的数值优先从 RON 读取

团队犯过最多的错误就是写硬编码常量替代 RON 数据。每次新技能必须遵循以下优先级：

calculations（公式值） → get_skill_value(spell_obj, name, level, |stat| ...)
- 适合：基础伤害、加成系数等需要与攻击力/法强联动的数值
- 例如：锐雯风斩 min_damage 公式 = MinBase + total_AD * 0.6
dataValues（数据值） → get_skill_data_value(spell_obj, name, level)
- 适合：持续时间、百分比、固定数值等按等级查表的值
- 例如：菲奥娜 R 的 MarkDuration、PercentMS、VitalPercent、HealPerSecond、锐雯 R 的 Duration、PercentBonusAD、TooltipAttackRange
effectAmounts（效果值） → 通过 get_skill_value 传 1.0 作为 stat 提取倍率
- 适合：需要从 RON 公式中提取纯倍率的场景
- 技巧：对 stat(total_AD) * effectValue(N) 这样的公式，传 |stat| if stat == 2 { 1.0 } else { 0.0 } 即得到 effectValue[N] 原始值
- 例如：德莱厄斯 W 的总伤害倍率 = get_skill_value(..., "empowered_attack_damage", ..., |stat| if stat == 2 { 1.0 } else { 0.0 })，然后 ratio = total_mult - 1.0（减去基础普攻 100% AD）
cooldownTime（冷却时间） → 直接从 spell_obj.spell_data.cooldown_time 读取
- get_skill_data_value 不能读 cooldownTime，因为它是 spell 顶层字段而非 dataValues
- cooldownTime 数组索引 0 往往是 nil 占位，真正的值从索引 1 开始
- 读取方式：spell_obj.spell_data.as_ref().and_then(|d| d.cooldown_time.as_ref()).and_then(|v| v.get(skill.level).copied()).unwrap_or(default)
- 注意索引用 skill.level 而非 skill.level - 1
保留为硬编码常量的情况（仅限以下两类）：
- 手感常数：前摇延迟、缓冲区时间、触发阈值等游戏手感调优值。它们不来自 Riot 的数据导出，而是开发者的手感调优。例如：FIORA_R_ACTIVE_DURATION = 0.5（R 生效前延迟）、VITAL_R_TIMEOUT = 1.5（要害过期红色闪烁预警）
- 命中框常数：圆形 AoE 半径、Sweet Spot 起始距离等空间碰撞参数。它们决定的是技能"打不打得中"而非"打多少伤害"。例如：AATROX_Q_RADIUS = 300.0、AATROX_Q_SWEET_SPOT_MIN = 200.0
- 判断标准：如果 RON 中能找到对应字段 → 读 RON；如果 RON 中没有且是游戏设计/调优参数 → 硬编码；如果 RON 中有但值明显不对 → 以 RON 为准并检查配置

Buff 属性修改的逆操作模式

技能开启时直接修改属性（伤害/攻击距离/速度），到期后必须准确恢复原始值。

错误做法：在恢复代码中硬编码回退值

// ❌ 硬编码 0.25 和 75.0，一旦 RON 修改就不同步
damage.0 = damage.0 * (1.0 - 0.25 / 1.25);
attack.range -= 75.0;

正确做法：在 Buff 组件中存储应用时的实际值，到期后按存储值恢复

// ✅ Buff 组件中记录原始加成
pub struct BuffRivenR {
    pub timer: Timer,
    pub bonus_ad_ratio: f32,  // 从 RON PercentBonusAD 读取的实际值
    pub bonus_range: f32,     // 从 RON TooltipAttackRange 读取的实际值
}
// ✅ 恢复时用存储值
damage.0 /= 1.0 + buff_r.bonus_ad_ratio;
attack.range -= buff_r.bonus_range;

RON 数值索引规则

字段	索引方式	说明
`dataValues.values`	`level - 1`	`get_skill_data_value` 内部处理
`effectAmounts.values`	`level - 1`	通过 formula 的 effectIndex 间接访问
`cooldownTime`	`level`（⚠️ 不是 level-1）	索引 0 通常是 nil 占位，真正的各级数值从索引 1 开始
`castRange` / `castRadius`	`level - 1`	`get_skill_cast_radius` 内部处理

测试必须检验的维度

施法成功：技能管线应当通过（SkillCastResult::Started）
效果生效：伤害/Debuff/Buff 已正确挂载
冷却扣除：can_cast(slot_index) 变为 false
消耗扣除：蓝量/能量正确减少
目标筛选：友军不受伤害，敌军受到伤害
多段重施：重施窗口正确，第二次施法走不同分支
Buff 过期：属性恢复回初始值
数据驱动正确性：所有从 RON 读取的数值应与硬编码时代的测试期望一致