package tech.easyflow.ai.document.service;

import tech.easyflow.ai.document.model.DocumentParseScenario;
import tech.easyflow.ai.document.model.DocumentSourceRef;
import tech.easyflow.ai.document.model.DocumentParseTaskInfo;
import tech.easyflow.ai.document.model.DocumentParseTaskStatus;
import tech.easyflow.ai.document.model.DocumentParsedResult;

/**
 * 统一文档解析桥接门面。
 *
 * <p>业务模块通过该门面使用文档解析能力，而不是直接依赖 easy-agents 的原始请求和结果模型。</p>
 *
 * @author Codex
 * @since 2026-04-14
 */
public interface DocumentParseBridgeService {

    /**
     * 同步解析单文档。
     *
     * @param source 文档源
     * @param scenario 解析场景
     * @return 标准化解析结果
     */
    DocumentParsedResult parse(DocumentSourceRef source, DocumentParseScenario scenario);

    /**
     * 异步提交单文档解析任务。
     *
     * @param source 文档源
     * @param scenario 解析场景
     * @return 异步任务状态
     */
    DocumentParseTaskStatus submit(DocumentSourceRef source, DocumentParseScenario scenario);

    /**
     * 查询异步任务状态。
     *
     * @param taskId 任务 ID
     * @return 异步任务状态
     */
    DocumentParseTaskStatus queryTask(String taskId);

    /**
     * 获取异步任务最终结果。
     *
     * <p>该方法面向“结果读取”语义，底层 provider 可能在内部等待任务完成后再返回最终结果，
     * 因此不适合直接作为轻量状态轮询接口；如果业务需要统一查看“当前状态 + 已完成结果”，
     * 应优先使用 {@link #queryTaskInfo(String)}。</p>
     *
     * @param taskId 任务 ID
     * @return 标准化解析结果
     */
    DocumentParsedResult queryResult(String taskId);

    /**
     * 聚合查询异步任务信息。
     *
     * <p>当任务仍在处理中时仅返回状态；当任务已完成时会附带标准化结果。
     * 该方法适合用于页面或业务侧统一读取“当前状态 + 可用结果”。</p>
     *
     * @param taskId 任务 ID
     * @return 聚合任务信息
     */
    DocumentParseTaskInfo queryTaskInfo(String taskId);
}
