BattleLifecycle.kt

package io.github.lishangbu.avalon.game.battle.engine.core.model

/**
 * 战斗会话的全局生命周期。
 *
 * 设计意图：
 * - 用一个显式阶段描述整场 battle 目前处于“初始化、运行、已结束待结算、已结算”中的哪一段；
 * - 让上层不再通过 `started / ended / settled` 三个布尔字段自行拼装阶段语义；
 * - 为 session API 的调用边界提供统一判定依据。
 *
 * 这里刻意只表达“全局稳定阶段”，不把 `RESOLVING_TURN` 这类同步瞬时过程态持久化进 state，
 * 避免状态恢复时引入额外复杂度。
 */
enum class BattleLifecycle {
    /**
     * 会话已创建，但仍处于 side/unit 注册与业务配置阶段。
     */
    INITIALIZING,

    /**
     * 战斗已经正式开始，允许进入回合循环。
     */
    RUNNING,

    /**
     * 胜负或结束原因已经确定，但战后资源、副作用尚未统一结算。
     */
    ENDED_UNSETTLED,

    /**
     * 战后副作用已经全部完成，整场 battle 生命周期彻底结束。
     */
    SETTLED,
    ;

    /**
     * 当前 battle 是否仍处于建局阶段。
     */
    fun isInitializing(): Boolean = this == INITIALIZING

    /**
     * 当前 battle 是否正处于回合循环阶段。
     */
    fun isRunning(): Boolean = this == RUNNING

    /**
     * 当前 battle 是否已经结束。
     *
     * 说明：
     * - 只要进入 `ENDED_UNSETTLED` 或 `SETTLED`，都视为战斗结果已经确定；
     * - 结算完成与否只影响后置副作用，不影响“是否已终局”。
     */
    fun isEnded(): Boolean = this == ENDED_UNSETTLED || this == SETTLED

    /**
     * 当前 battle 是否已经完成最终结算。
     */
    fun isSettled(): Boolean = this == SETTLED
}