cmvr-es/cmvr-es/devices/agv/abstract_agv.h

//
// Created by xtkuang on 2025/5/8.
//

#ifndef CMVR_ES_ABSTRACT_AGV_H
#define CMVR_ES_ABSTRACT_AGV_H
#pragma once

#include <string>
#include <vector>

#include "common/types/agv/agv_types.h"
#include "devices/abstract_device.h"

namespace cmvr::device {

/**
 * @brief AGV/移动底盘设备抽象基类。
 *
 * 该接口只描述通用 AGV 能力。控制器特有的请求/响应字段应放在具体
 * 驱动类中；当公共 API 需要扩展点时，可通过 AgvAdapterParams 传递。
 */
class AbstractAGV : public AbstractDevice {
public:
    AbstractAGV() = default;
    ~AbstractAGV() override = default;

    DeviceKind kind() const noexcept override { return DeviceKind::AGV; }

    /**
     * @brief 获取 AGV 运行状态快照。
     */
    virtual AgvRuntimeState runtimeState() const { return {}; }

    /**
     * @brief 获取当前导航任务状态。
     */
    virtual AgvNavigationStatus navigationStatus() const { return {}; }

    /**
     * @brief 触发 AGV 急停行为。
     */
    virtual AgvResult emergencyStop()
    {
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "emergencyStop not implemented");
    }
    
    /**
     * @brief 清除可恢复的 AGV 故障或告警。
     */
    virtual AgvResult clearFault()
    {
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "clearFault not implemented");
    }

    /**
     * @brief 发起到世界/地图位姿的导航任务。
     */
    virtual AgvResult navigateToPose(
        const math::Pose2d& pose,
        const AgvMotionOptions& options = {},
        const AgvAdapterParams& adapter_params = AgvAdapterParams{})
    {
        (void)pose;
        (void)options;
        (void)adapter_params;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "navigateToPose not implemented");
    }
    
    /**
     * @brief 发起到指定地图站点的导航任务。
     */
    virtual AgvResult navigateToStation(
        const std::string& station_id,
        const AgvMotionOptions& options = {},
        const AgvAdapterParams& adapter_params = AgvAdapterParams{})
    {
        (void)station_id;
        (void)options;
        (void)adapter_params;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "navigateToStation not implemented");
    }
    
    /**
     * @brief 发起显式站点到站点路径导航任务。
     */
    virtual AgvResult followPath(const std::vector<AgvPathSegment>& path)
    {
        (void)path;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "followPath not implemented");
    }
    
    /**
     * @brief 暂停当前导航任务，如果设备支持。
     */
    virtual AgvResult pauseNavigation()
    {
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "pauseNavigation not implemented");
    }
    
    /**
     * @brief 恢复已暂停的导航任务，如果设备支持。
     */
    virtual AgvResult resumeNavigation()
    {
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "resumeNavigation not implemented");
    }
    
    /**
     * @brief 取消当前导航任务，如果设备支持。
     */
    virtual AgvResult cancelNavigation()
    {
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "cancelNavigation not implemented");
    }

    /**
     * @brief 向 AGV 下发低层速度控制指令。
     *
     * 该接口不同于导航命令。具体实现应明确速度控制在导航过程中是中断
     * 导航、与导航共存，还是被拒绝执行。
     */
    virtual AgvResult setVelocity(const AgvVelocity& velocity)
    {
        (void)velocity;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "setVelocity not implemented");
    }
    
    /**
     * @brief 通过下发零速度停止低层速度控制。
     *
     * 该接口不表示取消正在执行的导航任务；取消导航请使用
     * cancelNavigation()。
     */
    virtual AgvResult stopVelocityControl()
    {
        return setVelocity(AgvVelocity{});
    }

    /**
     * @brief 查询 AGV 可用地图名称列表。
     */
    virtual AgvResult listMaps(std::vector<std::string>& maps) const
    {
        (void)maps;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "listMaps not implemented");
    }
    
    /**
     * @brief 查询当前活动地图中的站点列表。
     */
    virtual AgvResult listStations(std::vector<AgvStation>& stations) const
    {
        (void)stations;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "listStations not implemented");
    }
    
    /**
     * @brief 切换当前活动地图。
     */
    virtual AgvResult switchMap(const std::string& map_name)
    {
        (void)map_name;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "switchMap not implemented");
    }
    
    /**
     * @brief 按名称上传或替换地图。
     */
    virtual AgvResult uploadMap(const std::string& map_name, const std::string& content)
    {
        (void)map_name;
        (void)content;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "uploadMap not implemented");
    }
    
    /**
     * @brief 按名称下载地图内容。
     */
    virtual AgvResult downloadMap(const std::string& map_name, std::string& content) const
    {
        (void)map_name;
        (void)content;
        return AgvResult::failure(AgvErrorCode::UnsupportedCommand, "downloadMap not implemented");
    }

};

} // namespace cmvr::device

#endif // CMVR_ES_ABSTRACT_AGV_H