package cn.iocoder.yudao.module.mes.service.trace.crossregion;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceAntiConfigRespVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionHandleReqVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionStatisticsReqVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionStatisticsRespVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionSummaryRespVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionWarningPageReqVO;
import cn.iocoder.yudao.module.mes.controller.admin.trace.crossregion.vo.MesTraceCrossRegionWarningRespVO;
import cn.iocoder.yudao.module.mes.dal.dataobject.trace.consumer.MesTraceConsumerScanEventDO;

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

/**
 * 窜货预警 Service 接口
 * <p>
 * 消费者扫码地区与袋码出库经销商所在地区不一致时自动生成预警，并提供管理端稽查、处理与统计能力。
 *
 * @author 超级管理员
 */
public interface MesTraceCrossRegionService {

    /**
     * 消费者扫码成功后进行窜货判定，异常流向自动生成预警
     * <p>
     * 判定失败不影响溯源主流程，实现层需保证不抛异常。
     *
     * @param event 消费者扫码事件（含解析后的追溯码、入口类型、扫码地区）
     */
    void checkAndCreateWarning(MesTraceConsumerScanEventDO event);

    /**
     * 获得窜货预警分页
     *
     * @param reqVO 查询条件
     * @return 窜货预警分页
     */
    PageResult<MesTraceCrossRegionWarningRespVO> getWarningPage(MesTraceCrossRegionWarningPageReqVO reqVO);

    /**
     * 处理窜货预警（已处理 / 误报），仅待处理状态可处理
     *
     * @param reqVO 处理信息
     */
    void handleWarning(MesTraceCrossRegionHandleReqVO reqVO);

    /**
     * 获得窜货预警汇总
     *
     * @param startTime 开始时间，可空
     * @param endTime   结束时间，可空
     * @return 汇总信息
     */
    MesTraceCrossRegionSummaryRespVO getWarningSummary(LocalDateTime startTime, LocalDateTime endTime);

    /**
     * 获得窜货预警分布统计（按省份/城市/经销商/物料/批次分组）
     *
     * @param reqVO 分组条件
     * @return 分布统计列表
     */
    List<MesTraceCrossRegionStatisticsRespVO> getWarningStatistics(MesTraceCrossRegionStatisticsReqVO reqVO);

    /**
     * 获得防窜货规则配置
     *
     * @return 规则配置
     */
    MesTraceAntiConfigRespVO getConfig();

    /**
     * 更新防窜货规则配置（判定粒度切换：PROVINCE 跨省 / CITY 跨市）
     *
     * @param warningLevel 判定粒度
     */
    void updateConfig(String warningLevel);

}