package cn.nianxx.thhotel.integrations.ai.superagent.repository;

import cn.nianxx.thhotel.integrations.ai.superagent.common.dto.SuperAgentDispatchRunDraft;
import cn.nianxx.thhotel.integrations.ai.superagent.common.dto.SuperAgentDispatchRunFailureUpdate;
import cn.nianxx.thhotel.integrations.ai.superagent.common.dto.SuperAgentDispatchRunSnapshot;
import cn.nianxx.thhotel.integrations.ai.superagent.common.dto.SuperAgentDispatchRunSuccessUpdate;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

/**
 * SuperAgent 自动分发运行持久化端口。Service 依赖该端口，不直接访问 Mapper 或 Entity。
 */
public interface SuperAgentDispatchRunRepository {

    /**
     * 幂等插入一条自动分发运行记录；同一 SourceMessage 和分发来源已存在时返回已有记录 ID。
     */
    Long insertIfAbsent(SuperAgentDispatchRunDraft draft);

    /**
     * 抢占到期可处理的分发记录，并将其标记为 RUNNING，供 worker 安全执行。
     */
    List<SuperAgentDispatchRunSnapshot> claimDue(
            String workerId,
            List<String> statuses,
            LocalDateTime now,
            LocalDateTime lockedUntil,
            int limit);

    /**
     * 按 ID 查询分发运行快照。
     */
    Optional<SuperAgentDispatchRunSnapshot> findById(Long id);

    /**
     * 标记分发成功并保存 SuperAgent 返回的安全结果。
     */
    void markSucceeded(SuperAgentDispatchRunSuccessUpdate update);

    /**
     * 标记分发失败；可重试失败会写入下一次处理时间。
     */
    void markFailed(SuperAgentDispatchRunFailureUpdate update);
}
