package cn.iocoder.yudao.module.hrm.service.attendance;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRulePageReqVO;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRuleSaveReqVO;
import cn.iocoder.yudao.module.hrm.dal.dataobject.attendance.HrmAttendanceRuleDO;
import jakarta.validation.Valid;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 考勤规则配置 Service 接口
 *
 * @author 超级管理员
 */
public interface HrmAttendanceRuleService {

    /**
     * 新增考勤规则
     *
     * @param createReqVO 新增信息
     * @return 规则ID
     */
    Long createAttendanceRule(@Valid HrmAttendanceRuleSaveReqVO createReqVO);

    /**
     * 更新考勤规则
     *
     * @param updateReqVO 更新信息
     */
    void updateAttendanceRule(@Valid HrmAttendanceRuleSaveReqVO updateReqVO);

    /**
     * 删除考勤规则
     *
     * @param id 规则ID
     */
    void deleteAttendanceRule(Long id);

    /**
     * 获得考勤规则
     *
     * @param id 规则ID
     * @return 考勤规则
     */
    HrmAttendanceRuleDO getAttendanceRule(Long id);

    /**
     * 获得考勤规则分页
     *
     * @param pageReqVO 分页查询参数
     * @return 考勤规则分页
     */
    PageResult<HrmAttendanceRuleDO> getAttendanceRulePage(HrmAttendanceRulePageReqVO pageReqVO);

    /**
     * 获得启用的考勤规则列表
     *
     * @return 考勤规则列表
     */
    List<HrmAttendanceRuleDO> getAttendanceRuleList();

    /**
     * 根据部门ID获取考勤规则
     * 优先匹配部门规则，其次查找全局规则（deptId=null）
     *
     * @param deptId 部门ID
     * @return 考勤规则
     */
    HrmAttendanceRuleDO getAttendanceRuleByDeptId(Long deptId);

    /**
     * 根据部门ID + 打卡时间获取考勤规则
     *
     * 同一个部门允许配置多条考勤规则（多班次），此时按打卡时间匹配班次：
     * 优先取班次时间窗口包含该打卡时间的规则，都不包含时取时间窗口最接近的一条。
     *
     * @param deptId    部门ID
     * @param clockTime 打卡时间；为空时取该部门上班时间最早的一条规则
     * @return 考勤规则
     */
    HrmAttendanceRuleDO getAttendanceRuleByDeptId(Long deptId, LocalDateTime clockTime);

}