package com.gzzm.lobster.parse;

import java.io.InputStream;

/**
 * DocumentParser —— 文档解析器接口 / Document parser contract.
 *
 * <p>实现约定：
 * <ul>
 *   <li>不抛 checked 异常以外的错误；内部无法抽取的子元素用 {@code <!-- [parse error: ...] -->}
 *       占位，不中断整体流程。</li>
 *   <li>页眉、页脚、水印等统一丢弃，不作特例还原。</li>
 *   <li>嵌入图片第一期统一占位 {@code [图片]}（或带描述），不抽取二进制。</li>
 *   <li>markdown 正文首部必须含 YAML 元信息块（kind / source / totalChars 等）。</li>
 * </ul>
 */
public interface DocumentParser {

    /** 支持的 kind 标签（docx / xlsx / pptx / pdf / text），用于 outline 和 workspace 索引段. */
    String kind();

    /** 解析入口. {@code in} 由调用方负责关闭（通常是 try-with-resources 包住的原件流）. */
    ParseResult parse(InputStream in, String originalName, String mimeType) throws Exception;
}