/**
 * 通用业务服务接口
 *
 * 在面向对象编程和分层架构中，接口定义了一组方法签名，
 * 用于声明特定业务功能的契约，而不包含具体的实现细节。
 * 这些接口起到了抽象业务逻辑的作用，使得上层代码（如控制器层）可以通过依赖注入的方式使用这些接口，
 * 而不需要关心具体的实现，从而提高了代码的可维护性、可扩展性和可测试性。
 */

/**
 * 用于定义通用的业务方法。
 * 这些方法可以被多个业务模块复用，提供统一的通用业务能力。
 */

package com.service;

import java.util.List;
import java.util.Map;

public interface CommonService {

    /**
     * 获取选项列表
     * 通常用于前端下拉框、单选按钮等表单组件的选项数据
     *
     * @param params 查询参数，包含：
     *               - table: 表名
     *               - field: 字段名
     *               - condition: 查询条件
     * @return 选项值的字符串列表
     */
    List<String> getOption(Map<String, Object> params);

    /**
     * 根据选项获取关联数据
     * 用于获取与某个选项值相关联的详细信息
     *
     * @param params 查询参数，包含：
     *               - table: 主表名
     *               - field: 选项字段名
     *               - value: 选项值
     *               - followTable: 关联表名
     *               - followField: 关联字段名
     * @return 关联数据的键值对映射
     */
    Map<String, Object> getFollowByOption(Map<String, Object> params);

    /**
     * 审核操作
     * 用于处理业务流程中的审核状态更新
     *
     * @param params 审核参数，包含：
     *               - id: 审核记录ID
     *               - status: 审核状态（通过/拒绝）
     *               - remark: 审核意见
     *               - auditor: 审核人
     */
    void sh(Map<String, Object> params);

    /**
     * 提醒统计
     * 用于统计需要提醒的记录数量，如待办事项、逾期任务等
     *
     * @param params 统计参数，包含：
     *               - table: 表名
     *               - column: 提醒字段名（如截止时间）
     *               - type: 提醒类型
     *               - remindstart: 提醒开始范围
     *               - remindend: 提醒结束范围
     * @return 符合提醒条件的记录数量
     */
    int remindCount(Map<String, Object> params);

    /**
     * 选择计算值
     * 用于执行聚合计算查询，如求和、平均值、最大值、最小值等
     *
     * @param params 计算参数，包含：
     *               - table: 表名
     *               - column: 计算字段名
     *               - type: 计算类型（sum、avg、max、min、count）
     *               - condition: 计算条件
     * @return 计算结果的键值对映射
     */
    Map<String, Object> selectCal(Map<String, Object> params);

    /**
     * 分组查询
     * 用于按某个字段分组统计数据
     *
     * @param params 分组参数，包含：
     *               - table: 表名
     *               - groupColumn: 分组字段名
     *               - calcColumn: 统计字段名
     *               - calcType: 统计类型
     *               - condition: 分组条件
     * @return 分组统计结果列表，每个元素是一个分组的统计信息
     */
    List<Map<String, Object>> selectGroup(Map<String, Object> params);

    /**
     * 选择值
     * 通用的数据查询方法，用于获取特定字段的值
     *
     * @param params 查询参数，包含：
     *               - table: 表名
     *               - column: 字段名
     *               - condition: 查询条件
     * @return 查询结果的键值对列表
     */
    List<Map<String, Object>> selectValue(Map<String, Object> params);

    /**
     * 时间统计值
     * 专门用于按时间维度进行统计，如按日、周、月、年统计
     *
     * @param params 时间统计参数，包含：
     *               - table: 表名
     *               - timeColumn: 时间字段名
     *               - statType: 统计类型（day、week、month、year）
     *               - calcColumn: 计算字段名
     *               - calcType: 计算类型
     *               - startTime: 开始时间
     *               - endTime: 结束时间
     * @return 时间统计结果列表
     */
    List<Map<String, Object>> selectTimeStatValue(Map<String, Object> params);
}