package jnpf.attendance.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.github.pagehelper.PageInfo;
import jnpf.entity.attendance.AttendanceBookRecordEntity;
import jnpf.model.attendance.dto.AttendanceBookRecordDto;
import jnpf.model.attendance.dto.BatchAttendanceBookRecordDto;
import jnpf.model.attendance.dto.BookRecordDayListDto;
import jnpf.model.attendance.dto.BookRecordMonthListDto;
import jnpf.model.attendance.dto.BookRecordMonthStatisticsDto;
import jnpf.model.attendance.dto.LeaveRemarkSummaryDto;
import jnpf.model.attendance.dto.SchedulesImportDto;
import jnpf.model.attendance.vo.BatchOperationResultVo;
import jnpf.model.attendance.vo.BookRecordDayListVo;
import jnpf.model.attendance.vo.BookRecordMonthListVo;
import jnpf.model.attendance.vo.BookRecordMonthStatisticsVo;
import jnpf.model.attendance.vo.LeaveRemarkSummaryVo;

import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.List;

/**
 * 考勤本记录表Service
 * 
 * @author Generated
 * @create 2026-04-15
 */
public interface AttendanceBookRecordService extends IService<AttendanceBookRecordEntity> {
    
    /**
     * 新增或修改考勤记录（Upsert）
     * 根据考勤本ID、员工ID、考勤日期、时段类型唯一确定一条记录
     * 如果记录存在则更新，不存在则新增
     *
     * @param dto 考勤记录DTO
     * @return 记录ID
     */
    String saveOrUpdateRecord(AttendanceBookRecordDto dto);

    /**
     * 获取考勤本月统计数据
     *
     * @param req 统计请求参数
     * @return 本月统计结果（按员工维度，支持分页）
     */
    PageInfo<BookRecordMonthStatisticsVo> getMonthStatistics(BookRecordMonthStatisticsDto req);

    /**
     * 考勤本导入
     *
     * @param importDto 导入参数
     * @throws IOException IO异常
     */
    void bookRecordImport(SchedulesImportDto importDto) throws IOException;

    /**
     * 考勤本导出
     *
     * @param bookId 考勤本ID
     * @param month  月份（格式：yyyy-MM）
     */
    void bookRecordExport(String bookId, String month);

    /**
     * 导出考勤本模板（只有表头，无数据）
     *
     * @param bookId 考勤本ID
     * @param month  月份（格式：yyyy-MM）
     */
    void exportTemplate(String bookId, String month, HttpServletResponse response);

    /**
     * 获取日考勤本列表
     * <p>根据考勤本的使用范围获取人员列表，展示指定日期的考勤记录</p>
     *
     * @param req 查询参数
     * @return 日考勤本列表（按员工分组）
     */
    List<BookRecordDayListVo> getDayList(BookRecordDayListDto req);

    /**
     * 获取月考勤本列表
     * <p>根据考勤本的使用范围获取人员列表，展示该月所有日期的考勤记录</p>
     *
     * @param req 查询参数
     * @return 月考勤本列表（按员工分组）
     */
    List<BookRecordMonthListVo> getMonthList(BookRecordMonthListDto req);

    /**
     * 需求10：批量新增或修改考勤记录
     *
     * @param dto 批量考勤记录DTO
     * @return 批量操作结果
     */
    BatchOperationResultVo batchSaveOrUpdateRecord(BatchAttendanceBookRecordDto dto);

    /**
     * 需求6：获取假勤汇总信息（包含请假备注和考勤统计）
     *
     * @param dto 统计请求参数
     * @return 假勤汇总信息
     */
    LeaveRemarkSummaryVo getLeaveAttendanceSummary(LeaveRemarkSummaryDto dto);
}
