package jnpf.attendance.service;

import jnpf.base.service.SuperService;
import jnpf.entity.attendance.FtbScheduleGroupFixedParamEntity;
import jnpf.exception.HandleException;
import jnpf.exception.QueryException;
import jnpf.model.attendance.dto.scheduling.ScheduleGroupRuleConfigDto;
import jnpf.model.attendance.vo.scheduling.ScheduleGroupRuleConfigVo;

/**
 * 考勤组智能排班「排班规则配置」：固定排班核心参数与划线排班参数的查询与保存。
 *
 * <p>以「固定排班核心参数表」({@link FtbScheduleGroupFixedParamEntity}) 为主实体（每考勤组 1:1），
 * 划线参数由 {@code FtbScheduleGroupDrawingParamMapper} 协同维护。
 *
 * @author xiaofeng
 * @since 2026-05-13
 */
public interface ScheduleGroupRuleConfigService extends SuperService<FtbScheduleGroupFixedParamEntity> {

    /**
     * 获取排班规则配置。无表记录时子块返回与表 DEFAULT 一致的默认结构。
     *
     * @param groupId 考勤组 ID
     * @return 配置
     * @throws HandleException 参数非法
     * @throws QueryException  考勤组不存在或已删除
     */
    ScheduleGroupRuleConfigVo getRuleConfig(String groupId) throws HandleException, QueryException;

    /**
     * 保存排班规则配置。事务内对当前考勤组两块参数表按 {@code groupId} upsert。
     *
     * @param groupId 考勤组 ID（与请求体根 {@code groupId} 须一致）
     * @param dto     保存请求体（嵌套为 DTO）；与响应 VO 字段名与取值类型一致
     * @return 保存后的配置（等同再查一次）
     * @throws HandleException 参数非法 / 业务校验失败
     * @throws QueryException  考勤组不存在或已删除
     */
    ScheduleGroupRuleConfigVo saveRuleConfig(String groupId, ScheduleGroupRuleConfigDto dto)
            throws HandleException, QueryException;
}