package com.yupi.project.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.yupi.project.model.entity.ChargingRobot;
import com.yupi.project.model.enums.RobotStatusEnum;

import java.util.Date;
import java.util.List;

/**
* @author Yupi
* @description 针对表【charging_robot(充电机器人表)】的数据库操作Service
* @createDate 2023-12-03 10:00:00
*/
public interface ChargingRobotService extends IService<ChargingRobot> {

    /**
     * 注册一个新的充电机器人
     *
     * @param robotUid 机器人唯一ID
     * @param initialStatus 初始状态
     * @return 创建的机器人实体，如果已存在则返回null或抛出异常
     */
    ChargingRobot registerRobot(String robotUid, RobotStatusEnum initialStatus);

    /**
     * 根据机器人UID查找机器人
     *
     * @param robotUid 机器人唯一ID
     * @return 机器人实体，未找到则返回null
     */
    ChargingRobot findByRobotUid(String robotUid);

    /**
     * 更新机器人电量
     *
     * @param robotId 机器人DB主键ID
     * @param batteryLevel 电量百分比
     * @return 是否更新成功
     */
    boolean updateBatteryLevel(Long robotId, Integer batteryLevel);

    /**
     * 更新机器人心跳时间
     *
     * @param robotId 机器人DB主键ID
     * @param heartbeatTime 心跳时间
     * @return 是否更新成功
     */
    boolean updateHeartbeatTime(Long robotId, Date heartbeatTime);

    /**
     * 查找指定状态的机器人列表
     *
     * @param status 机器人状态
     * @return 机器人列表
     */
    List<ChargingRobot> findRobotsByStatus(RobotStatusEnum status);

    /**
     * 分配一个空闲的机器人用于执行任务
     * (此方法需要考虑并发和选择策略)
     *
     * @return 分配到的机器人实体，若无空闲则返回null
     */
    ChargingRobot assignIdleRobot();

    /**
     * 释放机器人（例如任务完成或取消后）
     *
     * @param robotId 机器人ID
     * @return 操作是否成功
     */
    boolean releaseRobot(Long robotId);

    /**
     * 更新机器人的实时状态。
     * 此方法用于处理机器人通过MQTT等方式上报的常规状态信息（如心跳）。
     *
     * @param robotUID          机器人唯一标识符
     * @param status            机器人上报的当前状态 (枚举)
     * @param location          机器人上报的当前位置 (可选)
     * @param batteryLevel      机器人上报的电池电量 (可选, 0-100)
     * @param currentTaskId     机器人当前正在执行的任务ID (可选, 如果上报了)
     * @param lastHeartbeatTime 收到此状态消息的时间，可视为最后心跳时间
     * @return 更新是否成功
     */
    boolean updateRobotStatus(String robotUID, RobotStatusEnum status, String location, Integer batteryLevel, Long currentTaskId, Date lastHeartbeatTime);

    /**
     * 获取在线机器人数量 (状态不为 offline 或 error)
     *
     * @return 在线机器人数量
     */
    long countOnlineRobots();

    /**
     * 获取正在充电的机器人数量 (状态为 charging)
     *
     * @return 正在充电的机器人数量
     */
    long countChargingRobots();

    /**
     * 获取空闲机器人数量 (状态为 idle)
     *
     * @return 空闲机器人数量
     */
    long countIdleRobots();
} 