package com.easyagents.document.core;

import com.easyagents.document.core.entity.ParseRequest;
import com.easyagents.document.core.entity.ParseResponse;
import com.easyagents.document.core.entity.ParseTaskInfo;
import com.easyagents.document.core.entity.ParseTaskStatus;

/**
 * 统一文档解析服务抽象。
 *
 * @author Codex
 * @since 2026-04-14
 */
public interface DocumentParseService<R extends ParseRequest> {

    /**
     * 同步解析文档并直接返回结果。
     *
     * @param request 解析请求
     * @return 解析结果
     */
    ParseResponse parse(ParseRequest request);

    /**
     * 异步提交文档解析任务。
     *
     * @param request 解析请求
     * @return 任务状态
     */
    ParseTaskStatus submit(ParseRequest request);

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

    /**
     * 获取异步任务最终结果。
     *
     * <p>该方法面向“结果读取”语义，provider 可以在内部等待任务完成后再返回最终结果，
     * 因此不适合用于高频轻量轮询；如果调用方希望统一查看“当前状态 + 已完成结果”，
     * 应优先使用 {@link #queryTaskInfo(String)}。</p>
     *
     * @param taskId 任务 ID
     * @return 解析结果
     */
    ParseResponse queryResult(String taskId);

    /**
     * 聚合查询异步任务信息。
     *
     * <p>该方法会先查询任务状态；如果任务仍在处理中，则仅返回当前状态。
     * 如果任务已经完成，则会继续查询并附带最终解析结果。</p>
     *
     * <p>注意：该方法在不同 provider 下可能触发结果下载或阻塞等待，
     * 因此更适合用于“状态+结果”一体化查询，而不是高频轻量轮询。</p>
     *
     * @param taskId 任务 ID
     * @return 聚合查询结果
     */
    default ParseTaskInfo queryTaskInfo(String taskId) {
        ParseTaskStatus taskStatus = queryTask(taskId);
        ParseTaskInfo taskInfo = ParseTaskInfo.fromStatus(taskStatus);
        if (taskStatus != null && "completed".equalsIgnoreCase(taskStatus.getStatus())) {
            taskInfo.setResult(queryResult(taskId));
        }
        return taskInfo;
    }
}
