H100PowerManger/src/pCCU/core/CoordFsm.hpp

#ifndef PCCU_COORD_FSM_HPP
#define PCCU_COORD_FSM_HPP

#include "../fsm/tinyfsm.hpp"
#include "../protocol/FcProtocol.h"
#include "../protocol/PmProtocol.h"
#include "../protocol/CanBms.h"
#include "PowerCoordinator.h"

namespace ccu {

class SystemData;

//============================================================================
// CoordFsm：pCCU 电源协调状态机骨架（TinyFSM，事件驱动）。
//
// 【当前状态：框架已参与编译，未接入运行流程（惰性）】
//   - 无任何代码调用 CoordFsm::start() / CoordFsm::dispatch()，
//     运行行为与接入前完全一致；
//   - 各状态 react() 均为 TODO 空实现，由开发者填写协调策略。
//
// 【设计约定】
//   - 边沿事件走 dispatch：指令到达(PmControlEvent)、操作步骤完成(StepDoneEvent)、
//     周期节拍(TickEvent)；
//   - 电平状态不进事件：最新 FC/BMS 状态由状态机在 TickEvent 中直接读取
//     SystemData 快照，避免周期状态报文淹没事件队列；
//   - TinyFSM 非线程安全：dispatch 必须收敛到单线程（MOOS 主循环线程），
//     接收线程产生的事件一律先排队，由 tick() 在主线程统一 drain 后
//     逐个 dispatch。
//
// 【接线指南：将来启用时按以下步骤操作】
//
//  1) 事件桥（可在 PowerCoordinator 或独立 EventBus 中实现）：
//     a. 线程安全事件队列：pushEvent(std::function<void()>)
//     b. tick() 末尾 drain 队列并逐个执行（单线程 dispatch）
//
//  2) CCU::OnStartUp：
//          CoordFsm::init(m_coord, m_sysData);
//          CoordFsm::start();
//
//  3) CCU::handlePmMessage 的 0x0001 分支（decode 成功后）：
//          CoordFsm::dispatch(PmControlEvent(c));
//        （c 为已解析的 PmControlValue，按值捕获）
//
//  4) 验证：编译运行后日志出现 "[CoordFsm] 进入状态: CoordNormalState" 即接线成功。
//
// 【状态说明】
//   CoordNormalState     正常运行（初始状态）：周期功率分配/阈值判断、响应主机指令
//   CoordBusyState       协调操作进行中：等待 StepDoneEvent 推进，完成后返回 Normal
//   CoordFaultState      故障处理：告警抑制/降级运行/恢复判断
//============================================================================

//---- 事件定义（边沿触发） ------------------------------------------------

// 周期节拍：由 coordinationTick 转发（AppTick 频率，默认 4Hz）
struct TickEvent : tinyfsm::Event {
    double now;                // MOOSTime
    TickEvent() : now(0) {}
    explicit TickEvent(double t) : now(t) {}
};

// 主机操控指令到达：PM 0x0001 每次成功解析触发一次
struct PmControlEvent : tinyfsm::Event {
    PmControlValue cmd;
    PmControlEvent() {}
    explicit PmControlEvent(const PmControlValue& c) : cmd(c) {}
};

// 协调操作步骤完成/超时：由协调动作引擎产生（预留）。
// status 携带完成时刻的 BCU 节点状态快照（SOC/电压/电流/告警，可判故障）
struct StepDoneEvent : tinyfsm::Event {
    bool           confirmed;   // true=确认完成；false=超时未确认
    BcuNodeStatus  status;      // 完成时刻 BCU 节点状态快照
    StepDoneEvent() : confirmed(false) {}
    StepDoneEvent(bool ok, const BcuNodeStatus& s) : confirmed(ok), status(s) {}
};

//---- 状态机 ---------------------------------------------------------------

class CoordFsm : public tinyfsm::Fsm<CoordFsm> {
public:
    // 启用时注入上下文（见接线指南）
    static void init(PowerCoordinator* coord, SystemData* sys) {
        m_coord = coord;
        m_sys   = sys;
    }
    static PowerCoordinator* coord() { return m_coord; }
    static SystemData*       sys()   { return m_sys; }

    // 事件处理默认实现：状态类按需覆盖；未覆盖的事件静默忽略
    virtual void react(tinyfsm::Event const &) {}
    virtual void react(TickEvent const &) {}
    virtual void react(PmControlEvent const &) {}
    virtual void react(StepDoneEvent const &) {}

    // 状态进入/退出钩子（状态类覆盖以打日志/做进出动作）
    virtual void entry() {}
    virtual void exit() {}

private:
    static PowerCoordinator* m_coord;
    static SystemData*       m_sys;
};

//---- 状态类 ---------------------------------------------------------------

// 正常运行（初始状态）
class CoordNormalState : public CoordFsm {
public:
    void entry() override;
    void exit() override;
    void react(TickEvent const &e) override;
    void react(PmControlEvent const &e) override;
    void react(StepDoneEvent const &e) override;
};

// 协调操作进行中（提交多步协调动作后进入）
class CoordBusyState : public CoordFsm {
public:
    void entry() override;
    void exit() override;
    void react(TickEvent const &e) override;
    void react(StepDoneEvent const &e) override;
};

// 故障处理
class CoordFaultState : public CoordFsm {
public:
    void entry() override;
    void exit() override;
    void react(TickEvent const &e) override;
    void react(StepDoneEvent const &e) override;
};

} // namespace ccu

#endif // PCCU_COORD_FSM_HPP