package com.multictrl.modules.business.q20.service;

import cn.hutool.json.JSONObject;
import com.multictrl.common.page.PageData;
import com.multictrl.modules.business.dto.RouteDTO;
import com.multictrl.modules.business.q20.dto.*;

import java.util.Map;

/**
 * Q20航线任务服务接口
 * topic: thing/device/{device_sn}/services (下行)
 * 回复: thing/device/{device_sn}/services_reply (上行)
 *
 * @author 938693313@qq.com
 * @since 1.0.0 2026/5/20
 */
public interface Q20RouteService {

    /**
     * 分页查询本地已保存的Q20航线（bus_route，关联bus_route_waypoint航点）
     * 支持按航线名称(routeName)、航线ID(q20RouteId)模糊查询
     *
     * @param params 查询参数：page、limit、routeName(可选)、q20RouteId(可选)
     * @return 分页结果，每条含完整航点列表
     */
    PageData<RouteDTO> pageQ20Routes(Map<String, Object> params);

    /**
     * 获取下一个航线ID（根据库中最新Q20航线ID自动递增，无记录则返回默认ID）
     *
     * @param type 航线类型：route=上传航线(q20_route_)，auto=一键航线(q20_auto_)
     * @return 下一个可用的航线ID
     */
    String nextWayline(String type);

    /**
     * 上传航线（route_upload）
     *
     * @param deviceSn 设备序列号
     * @param dto      上传航线数据
     * @return 执行结果描述
     */
    String routeUpload(String deviceSn, Q20RouteUploadDTO dto);

    /**
     * 执行航线（route_execute）
     *
     * @param deviceSn 设备序列号
     * @param dto      执行航线数据
     * @return 执行结果描述
     */
    String routeExecute(String deviceSn, Q20RouteExecuteDTO dto);

    /**
     * 一键飞行，上传并执行航线（route_auto）
     *
     * @param deviceSn 设备序列号
     * @param dto      一键飞行数据
     * @return 执行结果描述
     */
    String routeAuto(String deviceSn, Q20RouteAutoDTO dto);

    /**
     * 取消悬停（break_loop_hover）
     *
     * @param deviceSn 设备序列号
     * @return 执行结果描述
     */
    String breakLoopHover(String deviceSn);

    /**
     * 获取航线信息（route_info）
     *
     * @param deviceSn 设备序列号
     * @param mode     模式（1=最近一次，2=指定route_id）
     * @param value    mode=2时为route_id，否则可传null
     * @return 设备返回的航线信息
     */
    JSONObject routeInfo(String deviceSn, int mode, String value);

    /**
     * 获取航线执行进度（route_progress）
     *
     * @param deviceSn 设备序列号
     * @return 设备返回的执行进度信息
     */
    JSONObject routeProgress(String deviceSn);

    /**
     * 暂停航线（route_pause）
     *
     * @param deviceSn 设备序列号
     * @return 执行结果描述
     */
    String routePause(String deviceSn);

    /**
     * 继续航线（route_resume）
     *
     * @param deviceSn 设备序列号
     * @return 执行结果描述
     */
    String routeResume(String deviceSn);

    /**
     * 退出航线（route_finish）
     *
     * @param deviceSn 设备序列号
     * @return 执行结果描述
     */
    String routeFinish(String deviceSn);

    /**
     * 获取围栏信息（geofence_info）
     *
     * @param deviceSn 设备序列号
     * @return 设备返回的围栏信息
     */
    JSONObject geofenceInfo(String deviceSn);

    /**
     * 上传围栏（geofence_upload）
     *
     * @param deviceSn 设备序列号
     * @param dto      围栏上传数据
     * @return 执行结果描述
     */
    String geofenceUpload(String deviceSn, Q20GeofenceUploadDTO dto);
}
