docparser_office/

lib.rs

//! docparser Office 后端：DOCX / XLSX / PPTX 解析（`zip` + `quick-xml` 流式）。
//!
//! 与 Python `docparser/plugins/ooxml.py` 语义对齐：相同 IR/错误码/空白口径，
//! 但使用 `quick-xml` 流式解析（移除 `expat_serialized` 全局锁）。
//! 注意：解析是单线程流式的，未做 sheet/slide 级并行（原 `rayon` 依赖实际上未使用，已移除）。
//!
//! 架构（继承 PDF 后端的注册模式）：
//!   * `docx::DocxRawBackend` / `xlsx::XlsxRawBackend` / `pptx::PptxRawBackend` →
//!     `ParseCapability`（raw 模式快速文本提取）
//!   * `OfficePlugin` → `FormatPlugin`（RawDoc → IR Document 组装）
//!   * `register_defaults()` → 供 `core-python` 和 `cli` 调用

use std::sync::Arc;

// `DocError`/`Result` 只被 docx/xlsx 共用的 zip 读取辅助用到；只剩 pptx 时会成为未用导入。
#[cfg(any(feature = "docx", feature = "xlsx"))]
use docparser_core::error::{DocError, Result};
use docparser_core::plugin::{FormatPlugin, RawDoc};
use docparser_core::registry::Registry;

#[cfg(feature = "docx")]
pub mod docx;
#[cfg(feature = "pptx")]
pub mod pptx;
#[cfg(feature = "xlsx")]
pub mod xlsx;

/// 本 crate 实际编译进来的格式列表（随 feature 变化）。
pub const FORMATS: &[&str] = &[
    #[cfg(feature = "docx")]
    "docx",
    #[cfg(feature = "xlsx")]
    "xlsx",
    #[cfg(feature = "pptx")]
    "pptx",
];

/// OOXML 通用 namespace URI（quick-xml 0.42 起统一为 `&str`）。
pub mod ns {
    pub const W: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
    pub const A: &str = "http://schemas.openxmlformats.org/drawingml/2006/main";
    pub const P: &str = "http://schemas.openxmlformats.org/presentationml/2006/main";
    pub const C: &str = "http://schemas.openxmlformats.org/drawingml/2006/chart";
    pub const R: &str = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
    pub const SHEET: &str = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
    pub const REL: &str = "http://schemas.openxmlformats.org/package/2006/relationships";
    pub const VML: &str = "urn:schemas-microsoft-com:vml";
    pub const WP: &str = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
}

/// OOXML 元素**本地名**（去命名空间前缀）。
///
/// quick-xml 0.42 的 `Name::local_name()` 不返回 `w:`/`a:`/`p:` 前缀，因此这里只存本地名，
/// 比较一律用 `e.name().local_name().as_ref()`。副作用：`w:t` 与 `a:t` 都是 `"t"`，
/// 同名不同前缀的元素在本地名比较下不可区分——Office 的正文里不存在这种歧义元素。
pub mod tags {
    // docx
    pub const W_P: &str = "p";
    pub const W_TBL: &str = "tbl";
    pub const W_TR: &str = "tr";
    pub const W_TC: &str = "tc";
    pub const W_T: &str = "t";
    pub const W_R: &str = "r";
    pub const W_TAB: &str = "tab";
    pub const W_BR: &str = "br";
    pub const W_CR: &str = "cr";
    pub const W_SDT: &str = "sdt";
    pub const W_SDTC: &str = "sdtContent";
    pub const W_PPR: &str = "pPr";
    pub const W_BODY: &str = "body";
    pub const W_TXBX: &str = "txbxContent";
    // xlsx
    pub const SHEET_DATA: &str = "sheetData";
    pub const ROW: &str = "row";
    pub const C: &str = "c";
    pub const V: &str = "v";
    pub const IS: &str = "is";
    pub const T: &str = "t";
    pub const SI: &str = "si";
    pub const SST: &str = "sst";
    pub const NUM_FMT: &str = "numFmt";
    pub const CELL_XFS: &str = "cellXfs";
    pub const XF: &str = "xf";
    // pptx
    pub const P_SP: &str = "sp";
    pub const P_GRPSP: &str = "grpSp";
    pub const P_GFRAME: &str = "graphicFrame";
    pub const P_CXNSP: &str = "cxnSp";
    pub const P_SPTREE: &str = "spTree";
    pub const P_TXBODY: &str = "txBody";
    pub const P_PH: &str = "ph";
    pub const P_SLD: &str = "sld";
    pub const P_SLDID: &str = "sldId";
    pub const A_T: &str = "t";
    pub const A_BR: &str = "br";
    pub const A_TBL: &str = "tbl";
    pub const A_TR: &str = "tr";
    pub const A_TC: &str = "tc";
    pub const A_BLIP: &str = "blip";
    pub const A_OFF: &str = "off";
    pub const A_POS: &str = "pos";
    // chart
    pub const C_TX: &str = "tx";
    pub const C_V: &str = "v";
}

/// Office 插件：RawDoc → IR Document 组装（与 Python `plugins/ooxml.py` 的 FormatPlugin 语义对齐）。
pub struct OfficePlugin;

impl FormatPlugin for OfficePlugin {
    fn id(&self) -> &str {
        "office"
    }
    fn formats(&self) -> &[&str] {
        FORMATS
    }
    fn default_parse_chain(&self) -> Vec<&'static str> {
        vec!["office-raw"] // 当前只有 raw 后端；后续可增加 semantic 后端
    }
    fn default_process_chain(&self) -> Vec<&'static str> {
        vec![]
    }
    fn assemble(&self, raw: &RawDoc) -> docparser_core::model::Document {
        // 直接使用 raw 中的 pages，不做额外结构还原（raw 模式输出已在插件中组装好 text/tables）
        let pages: Vec<docparser_core::model::Page> = raw
            .pages
            .iter()
            .map(|rp| {
                let blocks: Vec<docparser_core::model::Block> = rp
                    .items
                    .iter()
                    .filter(|it| !it.text.trim().is_empty())
                    .map(|it| docparser_core::model::Block {
                        kind: docparser_core::model::BlockKind::Paragraph,
                        content: it.text.clone(),
                        ..Default::default()
                    })
                    .collect();
                let text = rp
                    .items
                    .iter()
                    .map(|it| it.text.as_str())
                    .collect::<Vec<_>>()
                    .join("\n");
                docparser_core::model::Page {
                    name: rp.name.clone(),
                    blocks,
                    text,
                    ..Default::default()
                }
            })
            .collect();
        docparser_core::model::Document {
            pages,
            ..Default::default()
        }
    }
}

/// 注册 Office 后端（docx/xlsx/pptx raw 文本提取）与插件。
///
/// 只注册编译进来的格式（见 [`FORMATS`]）；被 feature 裁掉的格式不会出现在注册表里，
/// `engine` 遇到该扩展名时按 `unsupported` 返回。
pub fn register_defaults(reg: &mut Registry) {
    // 注册后端的顺序：docx → xlsx → pptx，由 engine 解析链依次尝试
    #[cfg(feature = "docx")]
    reg.register_parse(Arc::new(docx::DocxRawBackend), None)
        .ok();
    #[cfg(feature = "xlsx")]
    reg.register_parse(Arc::new(xlsx::XlsxRawBackend), None)
        .ok();
    #[cfg(feature = "pptx")]
    reg.register_parse(Arc::new(pptx::PptxRawBackend), None)
        .ok();
    reg.register_plugin(Arc::new(OfficePlugin));
}

/// quick-xml 0.42 把 `&amp;` / `&#65;` 这类引用拆成独立的 `Event::GeneralRef`，
/// 不再是 Text 的一部分；这里按 0.37 的语义就地解码，未知实体丢弃（与 unescape 失败一致）。
#[cfg(any(feature = "docx", feature = "xlsx", feature = "pptx"))]
pub(crate) fn push_general_ref(buf: &mut String, e: &quick_xml::events::BytesRef<'_>) {
    match e.resolve_char_ref() {
        Ok(Some(ch)) => buf.push(ch),
        _ => {
            // 命名实体：借 unescape 解 `&name;`（预定义实体表在 quick-xml 内部）
            let entity = format!("&{};", e.xml10_content());
            if let Ok(t) = quick_xml::escape::unescape(&entity) {
                buf.push_str(&t);
            }
        }
    }
}

/// 从 ZIP 中读取字符串条目（找不到返回 None）。
#[cfg(any(feature = "docx", feature = "xlsx"))]
pub(crate) fn zip_read_str(
    zip: &mut zip::ZipArchive<std::fs::File>,
    name: &str,
) -> Result<Option<String>> {
    match zip.by_name(name) {
        Ok(mut f) => {
            let mut buf = Vec::new();
            std::io::Read::read_to_end(&mut f, &mut buf)
                .map_err(|e| DocError::corrupt(format!("读取 {name} 失败: {e}")))?;
            Ok(Some(String::from_utf8(buf).map_err(|e| {
                DocError::corrupt(format!("{name} 不是 UTF-8: {e}"))
            })?))
        }
        Err(zip::result::ZipError::FileNotFound) => Ok(None),
        Err(e) => Err(DocError::corrupt(format!("ZIP 读取 {name} 失败: {e}"))),
    }
}

/// 解析 rels 文件（如 `word/_rels/document.xml.rels`），返回 {id → target} 映射。
#[cfg(feature = "pptx")]
pub(crate) fn parse_rels(xml: &str) -> std::collections::HashMap<String, String> {
    use quick_xml::events::Event;
    use quick_xml::Reader;

    let mut map = std::collections::HashMap::new();
    let mut reader = Reader::from_str(xml);
    let mut buf = Vec::new();
    loop {
        match reader.read_event_into(&mut buf) {
            Ok(Event::Empty(ref e)) | Ok(Event::Start(ref e)) => {
                // 只读属性，文本裁剪与实体解析在此无关
                if e.name().local_name().as_ref() == "Relationship" {
                    let id = e
                        .attributes()
                        .filter_map(|a| a.ok())
                        .find(|a| a.key.as_ref() == "Id")
                        .map(|a| a.value.to_string());
                    let target = e
                        .attributes()
                        .filter_map(|a| a.ok())
                        .find(|a| a.key.as_ref() == "Target")
                        .map(|a| a.value.to_string());
                    if let (Some(id), Some(target)) = (id, target) {
                        map.insert(id, target);
                    }
                }
            }
            Ok(Event::Eof) => break,
            Err(e) => {
                // 损坏的 rels 不致命，记录并返回已有结果
                log::warn!("parse_rels 失败: {e}");
                break;
            }
            _ => {}
        }
        buf.clear();
    }
    map
}

#[cfg(test)]
mod tests {
    use super::FORMATS;

    /// `FORMATS` 必须与编译进来的 feature 严格一致（裁剪后不能"报"不存在的格式）。
    #[test]
    fn formats_follow_features() {
        let mut want: Vec<&str> = Vec::new();
        if cfg!(feature = "docx") {
            want.push("docx");
        }
        if cfg!(feature = "xlsx") {
            want.push("xlsx");
        }
        if cfg!(feature = "pptx") {
            want.push("pptx");
        }
        assert_eq!(FORMATS, want.as_slice());
    }
}