task_auto_plan_execute_project/include/app.hpp

#ifndef C2SYS_APP_HPP
#define C2SYS_APP_HPP

/**
 * @file app.hpp
 * @brief C2SYS 任务自主规划软件 — 核心业务逻辑层。
 *
 * 本文件声明了 C2SYS 应用程序的主控类，封装了方案管理、事件处理、
 * 任务生成、模板匹配、分发监控与状态上报等核心业务功能。
 * 采用事件驱动架构，内部通过消息队列机制实现模块间解耦。
 */

#include "config.hpp"
#include <vector>
#include <string>
#include <memory>
#include <functional>
#include <map>

namespace c2sys {

/**
 * @brief 系统运行状态枚举
 */
enum class SystemState : uint8_t {
    /// 初始化中
    Initializing  = 0,
    /// 已就绪
    Ready         = 1,
    /// 运行中
    Running       = 2,
    /// 异常态
    Error         = 3,
    /// 已停止
    Stopped       = 4
};

/**
 * @class App
 * @brief C2SYS 任务自主规划软件主控类。
 *
 * 提供完整的方案管理、事件处理、任务生成、模板匹配、分发与监控流程。
 * 支持 "人在回路" 与 "自主执行" 双模式切换，并保证上下文一致性。
 *
 * 使用示例：
 * @code
 *   c2sys::App app;
 *   app.initialize("config.txt");
 *   app.setRunMode(c2sys::RunMode::Autonomous);
 *   app.start();
 *   // ... 运行期间自动处理事件与任务 ...
 *   app.stop();
 * @endcode
 */
class App {
public:
    /// @brief 默认构造函数
    App();

    /// @brief 析构函数
    ~App();

    // ======================== 生命周期管理 ========================

    /**
     * @brief 初始化系统，加载配置。
     * @param configFile 配置文件路径，为空则使用默认配置
     * @return 初始化成功返回 true
     *
     * 初始化流程：
     *   1. 加载配置文件（如存在）
     *   2. 初始化事件队列与模板库
     *   3. 设置运行模式为默认模式（人在回路）
     */
    bool initialize(const std::string& configFile = "");

    /**
     * @brief 启动系统主循环。
     * @return 启动成功返回 true
     *
     * 启动后系统进入 Running 状态，开始处理事件循环和状态刷新。
     */
    bool start();

    /**
     * @brief 停止系统主循环。
     */
    void stop();

    /**
     * @brief 获取当前系统状态。
     * @return 系统状态枚举值
     */
    SystemState getState() const;

    // ======================== 模式管理 ========================

    /**
     * @brief 设置运行模式。
     * @param mode 目标运行模式（人在回路 / 自主执行）
     * @return 切换成功返回 true
     *
     * 模式切换时自动保存当前上下文快照到 ModeStateCache，
     * 保证状态不丢失、不冲突。
     */
    bool setRunMode(RunMode mode);

    /**
     * @brief 获取当前运行模式。
     * @return 当前运行模式
     */
    RunMode getRunMode() const;

    // ======================== 方案管理 (F-001, F-002, F-003) ========================

    /**
     * @brief 添加一个作战方案到系统。
     * @param plan 方案数据实体
     * @return 添加成功返回 true
     */
    bool addPlan(const PlanData& plan);

    /**
     * @brief 获取所有方案列表。
     * @return 方案列表（常量引用）
     */
    const std::vector<PlanData>& getAllPlans() const;

    /**
     * @brief 根据 ID 查询方案详情。
     * @param planId 方案 ID
     * @return 指向方案的指针，未找到返回 nullptr
     */
    const PlanData* findPlanById(const std::string& planId) const;

    /**
     * @brief 对比多个方案的关键指标。
     * @param planIds 待对比的方案 ID 列表
     * @return 包含各指标对比结果的描述字符串
     */
    std::string comparePlans(const std::vector<std::string>& planIds) const;

    // ======================== 事件管理 (F-006, F-007) ========================

    /**
     * @brief 接收并处理原始事件（模拟外部情报输入）。
     * @param raw 原始事件数据
     * @return 转换后的标准化事件 ID，失败返回空字符串
     *
     * 执行流程：
     *   1. 校验原始报文哈希
     *   2. 过滤无效/重复事件
     *   3. 转化为 StandardEvent 并加入待办队列
     *   4. 返回标准化事件 ID
     */
    std::string ingestRawEvent(const EventRaw& raw);

    /**
     * @brief 获取待办事件列表。
     * @return 待办事件列表
     */
    std::vector<StandardEvent> getPendingEvents() const;

    /**
     * @brief 处理指定事件（用户操作或自动处理）。
     * @param eventId 标准化事件 ID
     * @param accept  true 表示接受并处理，false 表示拒绝/忽略
     * @return 操作成功返回 true
     */
    bool processEvent(const std::string& eventId, bool accept);

    // ======================== 任务生成 (F-008) ========================

    /**
     * @brief 根据事件生成关联任务。
     * @param eventId 标准化事件 ID
     * @return 生成的任务 ID，失败返回空字符串
     *
     * 在 "自主执行" 模式下自动匹配最优模板并生成任务；
     * 在 "人在回路" 模式下触发确认流程。
     */
    std::string generateTaskFromEvent(const std::string& eventId);

    // ======================== 模板管理 (F-009, F-010) ========================

    /**
     * @brief 添加任务模板到知识库。
     * @param tmpl 任务模板实体
     * @return 添加成功返回 true
     */
    bool addTemplate(const TaskTemplate& tmpl);

    /**
     * @brief 根据场景自动匹配最优模板。
     * @param scenario 场景描述
     * @return 匹配度最高的模板，未找到则返回空 optional
     */
    const TaskTemplate* matchBestTemplate(const std::string& scenario) const;

    /**
     * @brief 保存当前模板库快照。
     * @return 快照版本号
     */
    std::string saveSnapshot();

    /**
     * @brief 回滚到指定快照版本。
     * @param version 快照版本号
     * @return 回滚成功返回 true
     */
    bool rollbackToSnapshot(const std::string& version);

    // ======================== 分发监控 (F-004, F-005) ========================

    /**
     * @brief 将选定方案分发至执行节点。
     * @param planId 方案 ID
     * @param nodeIds 目标节点 ID 列表
     * @return 成功分发的节点数量
     *
     * 包含重试机制：超时或拒绝的节点会重试（不超过 maxRetryCount 次）。
     */
    int dispatchPlan(const std::string& planId, const std::vector<std::string>& nodeIds);

    /**
     * @brief 获取所有分发回执。
     * @return 分发回执列表
     */
    std::vector<DistributionAck> getDistributionAcks() const;

    /**
     * @brief 上报任务执行状态（由执行单元或模拟器调用）。
     * @param status 执行状态实体
     */
    void reportExecutionStatus(const ExecutionStatus& status);

    /**
     * @brief 获取指定任务的执行状态。
     * @param taskId 任务 ID
     * @return 指向执行状态的指针，未找到返回 nullptr
     */
    const ExecutionStatus* getExecutionStatus(const std::string& taskId) const;

    // ======================== 配置与日志 ========================

    /**
     * @brief 记录一条操作日志。
     * @param log 操作日志结构体
     */
    void logOperation(const OperationLog& log);

    /**
     * @brief 获取所有操作日志。
     * @return 操作日志列表
     */
    std::vector<OperationLog> getOperationLogs() const;

    /**
     * @brief 获取当前系统配置。
     * @return 系统配置常量引用
     */
    const SystemConfig& getConfig() const;

private:
    /// @brief 内部实现类，隐藏具体实现细节
    class Impl;
    /// @brief PIMPL 模式实现指针
    std::unique_ptr<Impl> pImpl_;
};

} // namespace c2sys

#endif // C2SYS_APP_HPP