package com.zsElectric.boot.system.service;

import com.zsElectric.boot.system.model.dto.ChurnUserExportDTO;
import com.zsElectric.boot.system.model.query.HistoryBusinessQuery;
import com.zsElectric.boot.system.model.query.StationRankQuery;
import com.zsElectric.boot.system.model.vo.*;

import java.util.List;

/**
 * 数据看板服务接口
 *
 * @author zsElectric
 * @since 2026-03-09
 */
public interface DataBoardService {

    /**
     * 获取实时数据（累计总数据）
     *
     * @return 实时数据VO
     */
    DataBoardRealTimeVO getRealTimeData();

    /**
     * 获取今日实时数据
     *
     * @return 今日实时数据VO
     */
    DataBoardTodayVO getTodayData();

    /**
     * 获取充电度数时段对比趋势
     *
     * @param compareDate 对比日期（格式：yyyy-MM-dd）
     * @return 充电度数趋势VO
     */
    ChargePowerTrendVO getChargePowerTrend(String compareDate);

    /**
     * 获取历史营业数据
     * <p>
     * 日趋势：yearMonth 格式为 yyyy-MM，查询该月每日数据；
     * 月趋势：yearMonth 格式为 yyyy，查询该年每月汇总数据
     * </p>
     *
     * @param query 查询参数（yearMonth 必传）
     * @return 历史营业数据VO
     */
    HistoryBusinessDataVO getHistoryBusinessData(HistoryBusinessQuery query);

    /**
     * 获取站点排名数据
     *
     * @param query 查询参数
     * @return 站点排名列表VO
     */
    StationRankListVO getStationRankData(StationRankQuery query);

    /**
     * 获取用户流失率
     *
     * @return 用户流失率VO
     */
    UserChurnRateVO getUserChurnRate();

    /**
     * 获取流失用户列表（用于导出）
     * <p>
     * 包含用户个人信息和最后一次充电信息
     * </p>
     *
     * @param periodType 时段类型：7d-近7天，1m-近1个月，3m-近3个月
     * @return 流失用户列表
     */
    List<ChurnUserExportDTO> getChurnUserExportList(String periodType);
}
