package com.ruoyi.web.modules.industryservice.service;

import java.util.List;
import org.springframework.web.multipart.MultipartFile;
import com.ruoyi.common.core.domain.TreeSelect;
import com.ruoyi.web.modules.industryservice.domain.BizLargeLivestockFarmer;
import com.ruoyi.web.modules.industryservice.domain.vo.LargeLivestockFarmerImportResultVo;

/**
 * 养殖大户数据填报服务。
 * <p>
 * 覆盖：分页查询、增删改、Excel 导入（按唯一键 upsert）、按年月导出、
 * 年份/月份/乡镇/村树选项，以及草畜失衡预警同步。
 * </p>
 */
public interface IBizLargeLivestockFarmerService
{
    /** 按主键查询详情（含派生字段落库值） */
    BizLargeLivestockFarmer selectBizLargeLivestockFarmerById(Long id);

    /**
     * 分页列表查询。
     * 常用筛选：{@code statYear}、{@code statMonth}、{@code townDeptId}、{@code enterpriseName}（模糊）。
     */
    List<BizLargeLivestockFarmer> selectBizLargeLivestockFarmerList(BizLargeLivestockFarmer query);

    /**
     * 新增一条填报。
     * 校验通过后计算派生字段、校验唯一键，写入后同步草畜失衡预警。
     *
     * @return 影响行数
     */
    int insertBizLargeLivestockFarmer(BizLargeLivestockFarmer row);

    /**
     * 修改一条填报（物理更新全字段）。
     * 恢复草畜平衡时会清除对应预警记录。
     *
     * @return 影响行数
     */
    int updateBizLargeLivestockFarmer(BizLargeLivestockFarmer row);

    /**
     * 物理删除；同时按 {@code LLF-{id}} 清除关联草畜失衡预警。
     *
     * @param updateBy 操作人（当前实现未写审计字段，保留参数与同类模块一致）
     */
    int deleteBizLargeLivestockFarmerByIds(Long[] ids, String updateBy);

    /**
     * Excel 导入。
     * <ul>
     *   <li>年月由接口参数传入，不读 Excel 标题年</li>
     *   <li>唯一键 (年,月,村,企业名称)：库中已有则更新，否则插入</li>
     *   <li>任一行校验失败则整批不写库（事务回滚）</li>
     * </ul>
     */
    LargeLivestockFarmerImportResultVo importData(MultipartFile file, Integer statYear, Integer statMonth,
            String username);

    /** 可选年份（与存栏等模块共用年份策略） */
    List<Integer> listYearOptions();

    /** 可选月份 1～12 */
    List<Integer> listMonthOptions();

    /** 乡镇下拉（报表用乡镇列表） */
    List<java.util.Map<String, Object>> listTownOptions();

    /** 县→乡镇→村树，供新增/编辑选村 */
    List<TreeSelect> listVillageTree();

    /** 按年月导出；{@code townDeptId} 为空表示该月全部乡镇 */
    byte[] exportByYearMonth(Integer statYear, Integer statMonth, Long townDeptId);

    /**
     * 按年月导出；填表人写入模板第二行。
     *
     * @param fillerName 一般为当前登录用户名
     */
    byte[] exportByYearMonth(Integer statYear, Integer statMonth, Long townDeptId, String fillerName);
}
