package com.cmvr.edge.client.service;

import cmvr.msgs.Agv;
import cmvr.msgs.Agv.AgvRuntimeState;

import com.cmvr.edge.client.model.EdgeCommonVO;

import java.util.List;

/**
 * 边缘系统AGV服务
 *
 * @author cmvr-iot
 * @since 2026-07-02
 */
public interface EdgeAgvService {

    /**
     * 获取AGV运行时状态
     *
     * @param edgeCommonVO 边缘通用参数
     * @return AGV运行时状态
     */
    AgvRuntimeState getRuntimeState(EdgeCommonVO edgeCommonVO);

    /**
     * 获取导航状态
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 导航状态
     */
    Agv.AgvNavigationStatus getNavigationStatus(EdgeCommonVO edgeCommonVO);

    /**
     * 紧急停止
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void emergencyStop(EdgeCommonVO edgeCommonVO);

    /**
     * 清除故障
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void clearFault(EdgeCommonVO edgeCommonVO);

    /**
     * 导航到指定位置
     *
     * @param edgeCommonVO 边缘通用参数
     * @param pose 目标位姿
     */
    void navigateToPose(EdgeCommonVO edgeCommonVO, Agv.AgvPose2d pose);

    /**
     * 导航到站点
     *
     * @param edgeCommonVO 边缘通用参数
     * @param stationId 站点ID
     */
    void navigateToStation(EdgeCommonVO edgeCommonVO, String stationId);

    /**
     * 跟随路径
     *
     * @param edgeCommonVO 边缘通用参数
     * @param pathSegments 路径段列表
     */
    void followPath(EdgeCommonVO edgeCommonVO, List<Agv.AgvPathSegment> pathSegments);

    /**
     * 暂停导航
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void pauseNavigation(EdgeCommonVO edgeCommonVO);

    /**
     * 恢复导航
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void resumeNavigation(EdgeCommonVO edgeCommonVO);

    /**
     * 取消导航
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void cancelNavigation(EdgeCommonVO edgeCommonVO);

    /**
     * 设置速度
     *
     * @param edgeCommonVO 边缘通用参数
     * @param velocity 速度
     */
    void setVelocity(EdgeCommonVO edgeCommonVO, Agv.AgvVelocity velocity);

    /**
     * 停止速度控制
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void stopVelocityControl(EdgeCommonVO edgeCommonVO);

    /**
     * 列出所有地图
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 地图列表
     */
    List<String> listMaps(EdgeCommonVO edgeCommonVO);

    /**
     * 列出所有站点
     *
     * @param edgeCommonVO 边缘通用参数
     * @return 站点列表
     */
    List<Agv.AgvStation> listStations(EdgeCommonVO edgeCommonVO);

    /**
     * 切换地图
     *
     * @param edgeCommonVO 边缘通用参数
     * @param mapName 地图名称
     */
    void switchMap(EdgeCommonVO edgeCommonVO, String mapName);

    /**
     * 上传地图
     *
     * @param edgeCommonVO 边缘通用参数
     * @param mapName 地图名称
     * @param content 地图内容
     */
    void uploadMap(EdgeCommonVO edgeCommonVO, String mapName, String content);

    /**
     * 下载地图
     *
     * @param edgeCommonVO 边缘通用参数
     * @param mapName 地图名称
     * @return 地图内容
     */
    String downloadMap(EdgeCommonVO edgeCommonVO, String mapName);

    /**
     * 开始建图
     *
     * @param edgeCommonVO 边缘通用参数
     * @param dimension 建图维度（2D/3D/两者）
     * @param mapName 地图名称（可选）
     * @param realTime 是否实时建图
     * @return 会话ID
     */
    String startMapping(EdgeCommonVO edgeCommonVO, Agv.AgvMapDimension dimension, String mapName, boolean realTime);

    /**
     * 停止建图
     *
     * @param edgeCommonVO 边缘通用参数
     */
    void stopMapping(EdgeCommonVO edgeCommonVO);
}
