package com.example.finance.service;

import com.example.finance.dto.StatisticsQuery;
import com.example.finance.dto.StatisticsRangeQuery;
import com.example.finance.enums.StatisticsDimension;
import com.example.finance.vo.CategoryStatisticsVO;
import com.example.finance.vo.MonthlyStatisticsVO;
import com.example.finance.vo.StatisticsGroupVO;
import com.example.finance.vo.StatisticsSummaryVO;
import com.example.finance.vo.TrendStatisticsVO;

import java.util.List;

/**
 * 统计服务接口，提供月度收支统计、分类统计和趋势分析功能。
 */
public interface StatisticsService {

    /**
     * 获取月度收支统计（总收入、总支出、结余、交易笔数）
     *
     * @param userId 用户ID
     * @param query 统计查询条件（年份、月份）
     * @return 月度统计结果
     */
    MonthlyStatisticsVO getMonthlyStatistics(Long userId, StatisticsQuery query);

    /**
     * 获取分类维度的统计数据（各分类的金额、笔数、占比）
     *
     * @param userId 用户ID
     * @param query 统计查询条件（年份、月份）
     * @return 分类统计列表
     */
    List<CategoryStatisticsVO> getCategoryStatistics(Long userId, StatisticsQuery query);

    /**
     * 获取每日收支趋势统计数据
     *
     * @param userId 用户ID
     * @param query 统计查询条件（年份、月份）
     * @return 按日排列的趋势统计列表
     */
    List<TrendStatisticsVO> getTrendStatistics(Long userId, StatisticsQuery query);

    /**
     * 获取指定时间范围内的统计概览（收支汇总、日均、最大单笔、平均每笔）
     *
     * @param userId 用户ID
     * @param query 时间范围查询条件
     * @return 统计概览
     */
    StatisticsSummaryVO getSummary(Long userId, StatisticsRangeQuery query);

    /**
     * 按指定维度对时间范围内的交易进行分组统计
     *
     * @param userId    用户ID
     * @param query     时间范围查询条件
     * @param dimension 统计维度
     * @return 分组统计列表
     */
    List<StatisticsGroupVO> getGroup(Long userId, StatisticsRangeQuery query, StatisticsDimension dimension);
}