zsElectric-boot/src/main/java/com/zsElectric/boot/system/mapper/DataBoardMapper.java

package com.zsElectric.boot.system.mapper;

import com.zsElectric.boot.system.model.vo.DataBoardRealTimeVO;
import com.zsElectric.boot.system.model.vo.DataBoardTodayVO;
import com.zsElectric.boot.system.model.vo.StationRankVO;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

/**
 * 数据看板Mapper接口
 *
 * @author zsElectric
 * @since 2026-03-09
 */
@Mapper
public interface DataBoardMapper {

    /**
     * 获取累计实时数据
     *
     * @return 累计实时数据
     */
    DataBoardRealTimeVO selectRealTimeData();

    /**
     * 获取今日实时数据
     *
     * @param todayStart 今日开始时间
     * @param todayEnd 今日结束时间
     * @return 今日实时数据
     */
    DataBoardTodayVO selectTodayData(@Param("todayStart") String todayStart, @Param("todayEnd") String todayEnd);

    /**
     * 获取今日退款金额
     *
     * @param todayStart 今日开始时间
     * @param todayEnd 今日结束时间
     * @return 今日退款金额
     */
    BigDecimal selectTodayRefundAmount(@Param("todayStart") String todayStart, @Param("todayEnd") String todayEnd);

    /**
     * 获取累计退款金额
     *
     * @return 累计退款金额
     */
    BigDecimal selectTotalRefundAmount();

    /**
     * 按小时统计充电度数
     *
     * @param dateStart 开始日期时间
     * @param dateEnd 结束日期时间
     * @return 小时-充电度数映射
     */
    List<Map<String, Object>> selectHourlyChargePower(@Param("dateStart") String dateStart, @Param("dateEnd") String dateEnd);

    /**
     * 按日统计充电度数
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 日期-充电度数映射
     */
    List<Map<String, Object>> selectDailyChargePower(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 按日统计充电金额
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 日期-充电金额映射
     */
    List<Map<String, Object>> selectDailyChargeAmount(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 按日统计有效订单数
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 日期-订单数映射
     */
    List<Map<String, Object>> selectDailyValidOrders(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 按日统计注册用户数
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 日期-用户数映射
     */
    List<Map<String, Object>> selectDailyRegisterUsers(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 获取热门充电站排名
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @param limit 限制数量
     * @return 热门站点列表
     */
    List<StationRankVO> selectHotStations(@Param("startDate") String startDate, @Param("endDate") String endDate, @Param("limit") int limit);

    /**
     * 获取站点在时间段内的充电度数
     *
     * @param stationId 站点ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 充电度数
     */
    BigDecimal selectStationChargePower(@Param("stationId") String stationId, @Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 获取活跃用户数（在指定时间段内有充电记录的用户）
     *
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 活跃用户数
     */
    Long selectActiveUserCount(@Param("startDate") String startDate, @Param("endDate") String endDate);

    /**
     * 获取流失用户数（在早期有充电记录，但在最近时间段内没有充电记录的用户）
     *
     * @param earlyStart 早期开始日期
     * @param earlyEnd 早期结束日期
     * @param recentStart 最近开始日期
     * @param recentEnd 最近结束日期
     * @return 流失用户数
     */
    Long selectChurnUserCount(@Param("earlyStart") String earlyStart, @Param("earlyEnd") String earlyEnd,
                              @Param("recentStart") String recentStart, @Param("recentEnd") String recentEnd);

    /**
     * 获取今日首单金额（用户在今日的第一笔订单）
     *
     * @param todayStart 今日开始时间
     * @param todayEnd 今日结束时间
     * @return 首单金额
     */
    BigDecimal selectTodayFirstOrderAmount(@Param("todayStart") String todayStart, @Param("todayEnd") String todayEnd);

    /**
     * 获取累计首单金额
     *
     * @return 累计首单金额
     */
    BigDecimal selectTotalFirstOrderAmount();
}