package cn.iocoder.yudao.module.qcreport.service.aiimport.document;

/**
 * 一种输入格式的抽取器。
 * <p>
 * 之所以做适配器而不是在一个大类里 {@code switch (extension)}：三类输入的抽法毫无共同点
 * （图片什么都不用做、PDF 要先判断有没有文本层、Office 要按格式解析表格），
 * 塞进一个类会得到一个既读不了也改不动的分支塔。
 * <p>
 * 实现按 {@code @Order} 固定顺序排列，门面取<b>第一个</b> {@link #supports} 为真的——
 * 顺序固定是为了消除歧义（PDF 可能同时被 PDF 适配器和 Office 适配器「认领」），
 * 而不是为了择优。
 */
public interface QcReportImportAdapter {

    /**
     * 是否能处理这个文件。
     *
     * @param extension 小写、去点的扩展名，如 {@code pdf}；没有扩展名时为空串
     * @param contentType 浏览器上报的 MIME 类型，可能为 null（本地文件常见）
     */
    boolean supports(String extension, String contentType);

    /**
     * 抽取。
     * <p>
     * 不做「返回 null 表示失败」这种约定：读不出内容、格式不支持、页数超限都是**确定的失败原因**，
     * 各自对应一个错误码，让用户知道下一步该做什么（换个格式 / 拆页 / 重新扫描）。
     *
     * @param content          文件字节
     * @param originalFilename 原始文件名，用于错误与提示文案
     * @return 抽取结果
     */
    QcReportDocumentExtract extract(byte[] content, String originalFilename);

}