template/docs/dev/enemy/enemy-combat-flow.md

需求综述

战斗上下文系统已经完成，下一步需要在 packages-user/data-system/src/combat 中补齐真正的战斗流程，使其可以驱动“与某只怪物实际交战”这一行为，而不再只是做战前预估。

本次设计将战斗拆为三个阶段：

1. 战前准备
2. 战斗过程
3. 战后处理

其中：

• 战前准备与战后处理都属于流程阶段，需要支持两类扩展点：
  • 外部注入钩子：面向系统层或外部模块的扩展，适合做动画、日志、兼容桥接等观察型逻辑
  • 自定义脚本：面向战斗流程对象本身的注册式扩展，通过 addCombatScript 注入
• 战斗过程本身只保留一个实际结算方法，输出 IEnemyDamageInfo；这个方法是纯计算、无副作用的方法，直接写在流程对象内部，不额外设计成可注入接口
• 创建战斗流程对象时，必须一次性绑定勇士与怪物上下文，后续不可更改；流程对象本身始终绑定一个上下文，但在真正执行战斗时，传入战斗专用 handler 的 context 与 locator 允许为 null，以支持与不在地图上的怪物战斗
• 流程对象对外暴露统一的 battle(...) 异步方法，由它串起三个阶段；battle 接收的是计算后的怪物对象，而不是 IEnemyView

本次设计的重点不是把所有战后行为硬编码进一个类里，而是先把“可编排、可扩展、与现有 combat 风格一致”的骨架搭起来。删怪、发奖励、旧系统桥接等默认行为，全部由外部脚本或钩子注入，这个系统本身只提供流程壳。

接口设计与预期

IEnemyDamageInfo

本次不新增 IDamageInfo 结构，直接复用现有的 IEnemyDamageInfo 作为战斗过程的返回值。当前阶段只需要真实伤害值与回合数，现有结构已经足够。

• IEnemyDamageInfo.damage：预期频率高频。对于真正消费战斗结果的代码来说，最常读取的一定是伤害值；无论是战后脚本、展示层还是日志统计，都会优先关心这一项。典型使用场景：战后脚本根据本次伤害值决定是否触发濒死保护、成就统计或额外效果。
• IEnemyDamageInfo.turn：预期频率低频。回合数虽然重要，但大多数战斗逻辑只关心能否战斗和最终伤害，真正直接读取回合数的场景相对少得多，因此归为低频。

若后续确实出现额外结算字段需求，再单独讨论；本次设计不预留额外成员。

IEnemyHandlerBase 与 IReadonlyEnemyHandlerBase

本次保留四种 handler 语义，但不再把它们平铺写成四份完整定义，而是先抽出两个 base：

• IEnemyHandlerBase<TEnemy, THero>：可写怪物版本，只保留 enemy、hero、data
• IReadonlyEnemyHandlerBase<TEnemy, THero>：只读怪物版本，只保留 enemy、hero、data

然后再由四个具体接口各自补上 context 与 locator：

• IRequiredEHandler<TEnemy, THero>
• IReadonlyRequiredEHandler<TEnemy, THero>
• INullableEHandler<TEnemy, THero>
• IReadonlyNullableEHandler<TEnemy, THero>

这样拆分后，真正共享的只有三项公共成员，context / locator 是否可空则留给具体接口自己表达，不再把“可空”硬塞进 base 的泛型参数里。

建议定义如下：

interface IEnemyHandlerBase<TEnemy, THero> {
    readonly enemy: IEnemy<TEnemy>;
    readonly hero: IReadonlyHeroAttribute<THero>;
    readonly data: IStateBase;
}

interface IReadonlyEnemyHandlerBase<TEnemy, THero> {
    readonly enemy: IReadonlyEnemy<TEnemy>;
    readonly hero: IReadonlyHeroAttribute<THero>;
    readonly data: IStateBase;
}

interface IRequiredEHandler<TEnemy, THero> extends IEnemyHandlerBase<
    TEnemy,
    THero
> {
    readonly context: IEnemyContext<TEnemy, THero>;
    readonly locator: ITileLocator;
}

interface IReadonlyRequiredEHandler<
    TEnemy,
    THero
> extends IReadonlyEnemyHandlerBase<TEnemy, THero> {
    readonly context: IReadonlyEnemyContext<TEnemy, THero>;
    readonly locator: ITileLocator;
}

interface INullableEHandler<TEnemy, THero> extends IEnemyHandlerBase<
    TEnemy,
    THero
> {
    readonly context: IEnemyContext<TEnemy, THero> | null;
    readonly locator: ITileLocator | null;
}

interface IReadonlyNullableEHandler<
    TEnemy,
    THero
> extends IReadonlyEnemyHandlerBase<TEnemy, THero> {
    readonly context: IReadonlyEnemyContext<TEnemy, THero> | null;
    readonly locator: ITileLocator | null;
}

这里有三个关键点：

• 旧的 required 语义和 nullable 语义都保留，但命名改为 RequiredEHandler / NullableEHandler
• Base 只承载真正共享的三项成员，不再把 context / locator 抽象过度
• 内部纯计算阶段继续使用 required 版本；战斗流程钩子与脚本使用 nullable 版本

风险说明

如果直接把 required 版本放宽成可空，至少会带来下面这些风险：

• 现有 damage calculator、aura converter、上下文构建逻辑会被迫接收可空 context / locator，需要成片补判断或非空断言
• 一些本来应当被视为错误调用的场景，会因为接口被放宽而静默溜过去，后续更难排查
• 战斗流程只是一个新需求，却会把可空语义扩散成 combat 旧模块的公共契约变化，影响面明显过大

IEnemyHandlerBase 与 IReadonlyEnemyHandlerBase 的成员频率可以一并分析，因为二者仅在 enemy 的只读性上不同：

• enemy：预期频率中频。无论是实际结算、战前判定还是战后奖励脚本，核心输入始终是当前这只怪物本身，但真正手写这类读取的位置并不会太多，因此定为中频。典型使用场景：内部结算方法读取怪物攻击、防御、特殊属性并计算战斗结果。
• hero：预期频率中频。战斗过程一定会读它，但对外部脚本来说，不是每一个脚本都会直接碰勇士属性，因此不宜定为高频。典型使用场景：战前脚本读取勇士当前生命值或某个关键属性，决定是否允许本次战斗继续执行。
• data：预期频率低频。虽然它能访问全局状态，但真正直接走到这一级的脚本相对少，通常只有做跨系统联动时才会用到。

四个具体接口额外补上的成员频率如下：

• context：预期频率低频。只有需要反查地图对象、刷新上下文或处理周边状态时才会用到，不属于大多数战斗脚本的常规输入。
• locator：预期频率低频。只有与地图强绑定的脚本才会真正关心坐标；很多离图战斗或纯数值逻辑根本不会访问它。

其中：

• 钩子接收 IReadonlyNullableEHandler
• 脚本接收 INullableEHandler
• 内部纯计算方法额外组装 IReadonlyRequiredEHandler

这样既能隔离战斗场景的可空语义，也不会再把 IEnemyView 这种可写入口直接暴露给战斗阶段。

ICombatFlowHooks

战斗流程对象应支持实例级钩子注入，风格上与仓库中现有的 IHookable/IHookController 体系保持一致。这里的钩子只负责观察与通知，不参与流程控制，因此返回值统一为 Promise<void>。

建议形态如下：

interface ICombatFlowHooks<TEnemy, THero> extends IHookBase {
    onBeforeCombat?(
        handler: IReadonlyNullableEHandler<TEnemy, THero>,
        info: IEnemyDamageInfo
    ): Promise<void>;

    onAfterCombat?(
        handler: IReadonlyNullableEHandler<TEnemy, THero>,
        info: IEnemyDamageInfo
    ): Promise<void>;
}

• ICombatFlowHooks.onBeforeCombat()：预期频率低频。只有少数系统级扩展会专门监听战前阶段，例如动画准备、录像标记或调试日志，因此它属于明确存在但并不常写的扩展点。典型使用场景：渲染层在战前收到 info 后决定是否播放某段过渡动画。
• ICombatFlowHooks.onAfterCombat()：预期频率低频。它主要服务于系统层通知与收尾，常见业务逻辑更适合写在脚本里，而不是写成钩子。典型使用场景：录像或日志系统在战后统一记录本次战斗结果。

因此战斗流程对象本身建议实现为：

interface ICombatFlow<TEnemy, THero> extends IHookable<
    ICombatFlowHooks<TEnemy, THero>
> {}

这里钩子与脚本的分工很明确：

• 钩子偏系统扩展与观察
• 脚本偏流程配置与流程控制

ICombatScript

战前与战后脚本统一收敛为一个注册入口，不再拆成 addBeforeCombatScript / addAfterCombatScript 两套 API。脚本本身就是一个对象，同时提供战前与战后两个方法。

建议形态如下：

interface ICombatScript<TEnemy, THero> {
    readonly priority: number;

    before(
        handler: INullableEHandler<TEnemy, THero>,
        info: IEnemyDamageInfo
    ): Promise<boolean>;

    after(
        handler: INullableEHandler<TEnemy, THero>,
        info: IEnemyDamageInfo
    ): Promise<void>;
}

ICombatScript 的成员频率如下：

• ICombatScript.priority：预期频率中频。每个脚本对象都必须声明优先级，但它只在定义脚本与注册冲突判断时出现，不属于到处都会写到的成员。典型使用场景：删怪脚本需要排在奖励脚本之前或之后时，通过 priority 控制顺序。
• ICombatScript.before()：预期频率中频。战前脚本有明确使用场景，例如读取预先算出的伤害信息、拦截非法战斗或执行战前演出，但并不是每一个脚本都会真正写战前逻辑。典型使用场景：某个脚本在战前根据 info.damage 判断本次战斗是否允许继续执行。
• ICombatScript.after()：预期频率中频。大多数默认行为更偏向战后，但它同样只会出现在定义脚本的代码里，不应误判成高频。典型使用场景：战后脚本删除怪物、发放奖励、扣除勇士生命或触发额外状态修改。

如果某个脚本只关心战前或战后，则另一侧直接返回默认值即可：

• 不关心战前时，before 返回 Promise.resolve(true)
• 不关心战后时，after 返回 Promise.resolve()

对应流程对象提供：

• addCombatScript(script)：注册一个脚本对象
• deleteCombatScript(script)：删除一个脚本对象

优先级规则建议与现有系统保持一致：

• 数值越大越先执行
• 若已有脚本占用同一优先级，则在注册时使用 logger.warn(...) 抛出警告，并直接放弃这次新增，不保留重复项

只有 before 允许通过返回 false 取消战斗；钩子和 after 都不参与流程控制。

战斗过程

战斗过程不额外抽成公开接口、类型别名或可注入配置，而是直接实现为 CombatFlow 内部的一个同步方法。它只负责一件事：

• 根据传入的怪物与勇士状态结算 IEnemyDamageInfo

这个同步方法必须是纯计算、无副作用的方法：

• 不修改勇士状态
• 不删除怪物
• 不发放奖励
• 不做任何桥接逻辑

异步需求全部放在战前与战后阶段处理；真正的勇士状态修改也放在战后脚本中执行，而不是放在这个内部结算方法里。

ICombatFlow

ICombatFlow 是对外的战斗流程对象。它在构造时绑定勇士与上下文，后续不可更改，负责串起“战前 → 战斗 → 战后”三段流程，并统一返回 Promise。

建议成员如下：

• readonly hero: IReadonlyHeroAttribute<THero>：当前绑定的勇士属性对象
• readonly context: IEnemyContext<TEnemy, THero>：当前绑定的怪物上下文
• addCombatScript(script)：注册脚本对象
• deleteCombatScript(script)：删除脚本对象
• battle(enemy, locator?)：执行一次完整战斗流程

这些成员与方法的频率分析如下：

• ICombatFlow.hero：预期频率低频。它主要用于初始化后的少量检查、调试或对外只读暴露，不会成为常规调用点。
• ICombatFlow.context：预期频率低频。和 hero 类似，它更多是一个绑定关系的公开暴露，而不是经常被外部消费的核心接口。
• ICombatFlow.addCombatScript()：预期频率中频。虽然运行时通常只在初始化阶段调用，但从“用户会不会写这个调用”的角度看，所有默认行为和扩展模块都要通过它注册脚本，因此它会出现在若干模块初始化代码中。典型使用场景：在战斗系统初始化时注册删怪、奖励、战前拦截等脚本。
• ICombatFlow.deleteCombatScript()：预期频率低频。只有模块卸载、临时逻辑失效或测试场景才会显式移除脚本，常规游戏流程很少写到它。
• ICombatFlow.battle()：预期频率低频。这里的频率是指“会有多少地方真的去写这个调用”，而不是运行时调用次数；通常只有触发器入口、强制战斗指令和少量特殊逻辑会直接调用它，因此归为低频。

建议形态如下：

interface ICombatFlow<TEnemy, THero> extends IHookable<
    ICombatFlowHooks<TEnemy, THero>
> {
    readonly hero: IReadonlyHeroAttribute<THero>;
    readonly context: IEnemyContext<TEnemy, THero>;

    addCombatScript(script: ICombatScript<TEnemy, THero>): void;

    deleteCombatScript(script: ICombatScript<TEnemy, THero>): void;

    battle(
        enemy: IReadonlyEnemy<TEnemy>,
        locator?: ITileLocator | null
    ): Promise<IEnemyDamageInfo | null>;
}

这里不再接收 IEnemyView。调用方只要能提供计算后的怪物对象，就可以发起战斗；若该怪物本来就在地图中，再额外提供 locator 即可。

流程顺序

建议的执行顺序如下：

1. 调用 battle(enemy, locator?)，传入计算后的怪物对象，以及可选的地图定位符
2. 组装 INullableEHandler 与 IReadonlyNullableEHandler：data 统一来自绑定上下文上的 dataState；context 与 locator 是否为 null 取决于这只怪物是否真的属于当前地图上下文
3. 先额外组装一个内部使用的 IReadonlyRequiredEHandler，调用流程对象内部的纯计算方法，得到 IEnemyDamageInfo
4. 执行 onBeforeCombat(handler, info) 钩子；钩子只做观察与准备，不影响流程
5. 按优先级执行全部战前脚本；战前脚本同样接收 info，若任一脚本明确返回 false，则直接取消战斗并返回 null
6. 按优先级执行全部战后脚本；真正的勇士扣血等副作用在这里完成
7. 执行 onAfterCombat(handler, info) 钩子
8. 兑现 battle(...) 返回的 Promise

这样安排后，流程既能处理地图内怪物，也能处理离图怪物，同时不会把观察逻辑和真正参与控制的逻辑混在一起。

预期体量

预期代码体量为 120-180 行。分析如下：

• combat/types.ts 的改动主要是补齐 IEnemyHandlerBase、IReadonlyEnemyHandlerBase、IRequiredEHandler、IReadonlyRequiredEHandler、INullableEHandler、IReadonlyNullableEHandler，以及战斗流程相关接口
• combat/combat.ts 中的 CombatFlow 类主要包含脚本存储、优先级校验、handler 组装、纯伤害计算与统一的 battle(...) 编排逻辑
• combat/index.ts 的导出改动体量很小，基本只是一两行

由于本次不接入全局 legacy hook，也不硬编码任何默认行为，因此整体体量会比先前方案更小。

实现思路

1. 在 combat/types.ts 中补齐战斗流程接口

新增战斗流程所需的类型，包括：

• 复用现有 IEnemyDamageInfo 作为战斗结果类型
• 新增 IEnemyHandlerBase 与 IReadonlyEnemyHandlerBase
• 新增 IRequiredEHandler 与 IReadonlyRequiredEHandler
• 新增 INullableEHandler 与 IReadonlyNullableEHandler
• ICombatFlowHooks
• ICombatScript
• ICombatFlow

这里不新增 IDamageInfo，但会新增战斗专用 handler；旧 handler 保持原状，不再直接改公共契约。

2. 在 combat/combat.ts 中实现 CombatFlow

实现一个真正的流程编排类：

• 构造器中绑定 hero 与 context
• 通过私有成员保存脚本列表
• 提供 addCombatScript / deleteCombatScript
• 提供统一的 battle(enemy, locator?)
• 在类内部写一个同步的纯伤害计算方法

此类本身不做具体战斗结算，只负责把三阶段按顺序跑通。

3. 抽出统一的脚本注册逻辑

全部脚本共用同一套行为：

• 注册
• 注销
• 按优先级从高到低排序
• 同优先级警告并直接放弃新增项

因此 combat.ts 中应优先抽出一个局部的脚本登记结构或辅助方法，避免重复写优先级判断与删除逻辑。

4. 将伤害计算与状态修改拆开

流程类内部的结算方法只负责计算 IEnemyDamageInfo，不产生任何副作用。真正的勇士扣血、删怪、发奖励等行为全部放在战后脚本中处理。是否复用现有 IDamageSystem 的预估结果，可以在实现时再决定，但这部分仍然不设计成一个可替换的公开配置点。

5. 所有默认行为都通过外部脚本定义

默认的战后行为，如：

• 删除怪物
• 发放金币与经验
• 战后额外状态修改
• 旧系统桥接

都统一通过外部 ICombatScript 或实例级钩子完成。CombatFlow 本身只提供壳，不内置任何默认战前或战后逻辑。

6. 在 combat/index.ts 中导出新模块

当前 combat/index.ts 只导出了 context、damage、enemy、mapDamage、types，实现后需要补上对 combat.ts 的导出，保证 @user/data-system 的上层调用点可以直接使用战斗流程对象。

涉及文件

需要引用的文件

• @motajs/common：需要 IHookBase、IHookable、IHookController、Hookable、HookController、logger，分别用于实例级钩子能力与重复优先级警告
• @user/data-base：需要 IStateBase、IReadonlyHeroAttribute、IReadonlyEnemy
• combat/types.ts：已有 IEnemyContext、IReadonlyEnemyContext、IEnemyDamageInfo 等接口，是本次接口扩展的核心落点
• combat/damage.ts：虽然本次不直接修改，但内部的纯伤害计算方法大概率会参考或复用这里的预估逻辑
• trigger/collector.ts：可参考其优先级冲突时的警告写法，但本次脚本注册的冲突处理规则与它不同

需要修改的文件

packages-user/data-system/src/combat/types.ts

• 新增 IEnemyHandlerBase<TEnemy, THero> 接口：抽出 enemy、hero、data 三个共享成员
• 新增 IReadonlyEnemyHandlerBase<TEnemy, THero> 接口：抽出只读 handler 的共享成员
• 新增 IRequiredEHandler<TEnemy, THero> 接口：承接 required 语义的 context 与 locator
• 新增 IReadonlyRequiredEHandler<TEnemy, THero> 接口：承接只读 required 语义
• 新增 INullableEHandler<TEnemy, THero> 接口：承接 nullable 语义的 context 与 locator
• 新增 IReadonlyNullableEHandler<TEnemy, THero> 接口：承接只读 nullable 语义
• 新增 ICombatFlowHooks<TEnemy, THero> 接口：实例级战斗钩子定义
• 新增 ICombatScript<TEnemy, THero> 接口：定义统一的脚本对象模型
• 新增 ICombatFlow<TEnemy, THero> 接口：定义流程对象的公开 API

packages-user/data-system/src/combat/combat.ts

• 新增 CombatFlow<TEnemy, THero> 类：实现战斗流程编排
• 新增脚本存储成员：保存脚本列表
• 新增优先级注册/注销辅助逻辑：统一处理重复优先级警告与放弃注册
• 实现 addCombatScript / deleteCombatScript
• 实现内部同步结算方法：纯计算 IEnemyDamageInfo
• 实现 battle(enemy, locator?)：按“战前 → 战斗 → 战后”的顺序执行

packages-user/data-system/src/combat/index.ts

• 新增 export * from './combat'：将战斗流程对象导出给上层使用

已确认事项

1. 直接复用 IEnemyDamageInfo，本次不新增新的结算结果结构
2. 全局 hook 属于 legacy 内容，不纳入本次设计
3. 这个系统只是流程壳，默认行为全部由外部脚本或钩子定义，不做任何硬编码
4. 战斗阶段不上传 IEnemyView，统一处理 computed enemy；真正执行战斗时，战斗专用 handler 上的 context 与 locator 允许为 null
5. 新增战斗专用 handler，但不修改旧 handler，也不新增可注入的战斗过程接口；脚本统一为单对象模型
6. 内部伤害计算方法是纯计算、无副作用的方法；真正的勇士状态修改放在战后脚本中执行