docvortex 0.4.24__tar.gz → 0.4.25__tar.gz

{docvortex-0.4.24/src/docvortex.egg-info → docvortex-0.4.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.24
+Version: 0.4.25
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

{docvortex-0.4.24 → docvortex-0.4.25}/src/docvortex/analyzers/native/office/docx/docx_converter.py

@@ -48,6 +48,8 @@ class DocxConverter(_DocxConstants, _DocxResources, _DocxStyles, _DocxNumbering,
 
     def _reset_document_state(self) -> None:
         """每次转换重新创建可变状态及解码器，避免失败或复用实例残留旧文档。"""
+        self._close_mammoth_fallback_context()
+        self._fallback_docx_bytes: Optional[bytes] = None  # 仅转换期间保留规范化后的原包
         self.docx_obj = None
         self.pages = []
         self.cur_page = []
@@ -149,19 +151,24 @@ class DocxConverter(_DocxConstants, _DocxResources, _DocxStyles, _DocxNumbering,
         self._reset_document_state()
         # 读取文件字节，以便 mammoth 和 python-docx 各自使用独立读取流
         file_bytes = self._sanitize_missing_internal_relationships(file_stream.read())
-        # 使用完整 DOCX 上下文预解析顶层表格，避免转换非表格正文带来的资源浪费
-        self._mammoth_tables_html = self._preparse_tables_with_mammoth(file_bytes)
-        self._mammoth_table_idx = 0
-        self.docx_obj = Document(BytesIO(file_bytes))
-        self.toc_anchor_set = self._collect_toc_anchor_set()
-        self.toc_anchor_aliases = self._collect_toc_anchor_aliases(
-            self.toc_anchor_set,
-        )
-        # 预扫描文档，识别用作章节标题的列表numId
-        self.heading_list_numids = self._detect_heading_list_numids()
-        self.pages.append(self.cur_page)
-        self._walk_linear(self.docx_obj.element.body)
-        self._add_header_footer(self.docx_obj)
+        self._fallback_docx_bytes = file_bytes
+        try:
+            # 使用完整 DOCX 上下文预解析顶层表格，避免转换非表格正文带来的资源浪费
+            self._mammoth_tables_html = self._preparse_tables_with_mammoth(file_bytes)
+            self._mammoth_table_idx = 0
+            self.docx_obj = Document(BytesIO(file_bytes))
+            self.toc_anchor_set = self._collect_toc_anchor_set()
+            self.toc_anchor_aliases = self._collect_toc_anchor_aliases(
+                self.toc_anchor_set,
+            )
+            # 预扫描文档，识别用作章节标题的列表numId
+            self.heading_list_numids = self._detect_heading_list_numids()
+            self.pages.append(self.cur_page)
+            self._walk_linear(self.docx_obj.element.body)
+            self._add_header_footer(self.docx_obj)
+        finally:
+            self._close_mammoth_fallback_context()
+            self._fallback_docx_bytes = None
 
     def _close_active_list(self) -> None:
         """关闭当前活跃列表块，但保留 Word numId 的连续编号计数。"""

{docvortex-0.4.24 → docvortex-0.4.25}/src/docvortex/analyzers/native/office/docx/tables.py

@@ -1,13 +1,17 @@
 """DOCX 表格处理；共享当前 Converter 的单文档状态。"""
 
 import re
+from contextlib import ExitStack
 from io import BytesIO
 from typing import Any, Optional
 from docx import Document
 from docx.oxml.xmlchemy import BaseOxmlElement
 from loguru import logger
+from mammoth import docx as mammoth_docx
+from mammoth import read_embedded_style_map
 from mammoth.conversion import convert_document_element_to_html
-from mammoth.docx import body_xml
+from mammoth.options import read_options
+from mammoth.zips import open_zip
 from .office_xml import read_str
 from .....schema import BlockType
 
@@ -43,7 +47,7 @@ class _DocxTables:
 
         Returns:
             list[str | None]: 与正文顶层表格对齐的 HTML 列表；None 表示该表格
-                未找到可靠 Mammoth 结果，后续走孤立 XML 回退解析
+                未找到可靠 Mammoth 结果，后续走完整文档上下文回退解析
         """
         try:
             import mammoth as _mammoth
@@ -206,10 +210,41 @@ class _DocxTables:
             if vmerge.get(f"{{{w_ns}}}val") in (None, "continue"):
                 continuation_nodes.update(cell.iter())
 
+        ignored_nodes = set(continuation_nodes)
+        mc_ns = "http://schemas.openxmlformats.org/markup-compatibility/2006"
+        for alternate in xml_table.iter(f"{{{mc_ns}}}AlternateContent"):
+            # Mammoth 的 Office XML 读取器仅展开 Fallback 分支。
+            for branch in alternate:
+                if branch.tag != f"{{{mc_ns}}}Fallback":
+                    ignored_nodes.update(branch.iter())
+        for simple_field in xml_table.iter(f"{{{w_ns}}}fldSimple"):
+            # Mammoth 不解析简单域，其内部的缓存文字也不参与匹配。
+            ignored_nodes.update(simple_field.iter())
+
+        wordml_ns = "http://schemas.microsoft.com/office/word/2010/wordml"
+        for content_control in xml_table.iter(f"{{{w_ns}}}sdt"):
+            properties = content_control.find(f"{{{w_ns}}}sdtPr")
+            if properties is None or properties.find(f"{{{wordml_ns}}}checkbox") is None:
+                continue
+            content = content_control.find(f"{{{w_ns}}}sdtContent")
+            if content is None:
+                continue
+            # Mammoth 以复选框替换内容控件里的首个非空 Text 节点。
+            first_text = next(
+                (
+                    node
+                    for node in content.iter()
+                    if node not in ignored_nodes and node.tag in char_tags and _DocxTables._xml_table_char_fragment(node)
+                ),
+                None,
+            )
+            if first_text is not None:
+                ignored_nodes.add(first_text)
+
         text = "".join(
             _DocxTables._xml_table_char_fragment(node)
             for node in xml_table.iter()
-            if node not in continuation_nodes and node.tag in char_tags
+            if node not in ignored_nodes and node.tag in char_tags
         )
         return {
             "row_count": len(xml_table.xpath('.//*[local-name()="tr"]')),
@@ -221,11 +256,20 @@ class _DocxTables:
     @staticmethod
     def _html_table_signature(html_table) -> dict:
         """提取 HTML 表格的轻量签名，用于过滤 Mammoth 额外生成的表格。"""
+        text_fragments = []
+        for fragment in html_table.strings:
+            anchor = fragment.find_parent("a")
+            if anchor is not None and anchor.parent.name == "sup":
+                marker = re.fullmatch(r"(footnote|endnote)-ref-(\d+)", anchor.get("id", ""))
+                if marker and anchor.get("href") == f"#{marker.group(1)}-{marker.group(2)}":
+                    # 只忽略 Mammoth 生成的脚注引用，保留正文中的普通 [1]。
+                    continue
+            text_fragments.append(fragment.strip())
         return {
             "row_count": len(html_table.find_all("tr")),
             "cell_count": len(html_table.find_all(["td", "th"])),
             "image_count": len(html_table.find_all("img")),
-            "text": _DocxTables._normalize_table_match_text(html_table.get_text("", strip=True)),
+            "text": _DocxTables._normalize_table_match_text("".join(text_fragments)),
         }
 
     @staticmethod
@@ -396,47 +440,64 @@ class _DocxTables:
             return None
         return f"<p>{''.join(items)}</p>"
 
-    def _handle_tables(self, element: BaseOxmlElement):
-        """
-        处理表格。
+    def _close_mammoth_fallback_context(self) -> None:
+        """关闭当前文档回退解析持有的 ZIP 资源，并清除其缓存。"""
+        context = getattr(self, "_mammoth_fallback_context", None)
+        self._mammoth_fallback_context = None
+        if context is not None:
+            context[0].close()
+
+    def _mammoth_fallback_html(self, element: BaseOxmlElement) -> str:
+        """在原 DOCX 的样式、编号、关系和图片上下文中转换当前表格。"""
+        context = self._mammoth_fallback_context
+        if context is None:
+            file_bytes = self._fallback_docx_bytes
+            if file_bytes is None:
+                raise ValueError("DOCX fallback source is unavailable")
+            resources = ExitStack()
+            try:
+                package = resources.enter_context(open_zip(BytesIO(file_bytes), "r"))
+                paths = mammoth_docx._find_part_paths(package)
+                read_part = mammoth_docx._part_with_body_reader(None, package, paths, False)
+                embedded_style_map = read_embedded_style_map(BytesIO(file_bytes))
+                conversion_options = read_options({"embedded_style_map": embedded_style_map}).value
+                context = (resources, read_part, paths.main_document, conversion_options)
+                self._mammoth_fallback_context = context
+            except Exception:
+                resources.close()
+                raise
+
+        _, read_part, main_part, conversion_options = context
+        table = read_str(element.xml)
 
-        优先使用完整文档 mammoth 转换的预解析结果（支持列表、图片、样式等
-        复杂单元格内容），若预解析结果耗尽则回退到孤立 XML 解析模式。
+        def read_selected_table(_root: Any, body_reader: Any) -> Any:
+            """每次获取独立 reader，只解析当前 XML 表格并沿用主文档关系。"""
+            return body_reader.read_all([table])
 
-        Args:
-            element: 元素对象
-        Returns:
-            list[RefItem]: 元素引用列表
-        """
-        # 优先使用预解析表格（完整文档上下文，能正确处理列表/图片等）
-        if self._mammoth_table_idx < len(self._mammoth_tables_html):
-            html = self._mammoth_tables_html[self._mammoth_table_idx]
-            self._mammoth_table_idx += 1
-            if html is not None:
-                html = self._normalize_table_colspans(html)
-                table_block = {
-                    "type": BlockType.TABLE,
-                    "content": html,
-                }
-                self.cur_page.append(table_block)
-                return
-
-        # 回退：孤立 XML 解析模式（原始方案，不含文档上下文）
-        table = read_str(element.xml)
-        body_reader = body_xml.reader()
-        t = body_reader.read_all([table])
-        res = convert_document_element_to_html(t.value[0])
-        html = self._normalize_table_colspans(res.value)
-        html = self._inject_equations_into_table_html(
-            html,
-            element,
-            self._require_document_part(),
-        )
-        table_block = {
-            "type": BlockType.TABLE,
-            "content": html,
-        }
-        self.cur_page.append(table_block)
+        result = read_part(main_part, read_selected_table)
+        return convert_document_element_to_html(result.value[0], **conversion_options).value
+
+    def _handle_tables(self, element: BaseOxmlElement) -> None:
+        """按正文顺序输出表格；预匹配失败时使用完整 DOCX 上下文回退。"""
+        table_index = self._mammoth_table_idx
+        self._mammoth_table_idx += 1
+        html = self._mammoth_tables_html[table_index] if table_index < len(self._mammoth_tables_html) else None
+        stage = "full-context fallback"
+        try:
+            if html is None:
+                html = self._mammoth_fallback_html(element)
+            stage = "colspan normalization"
+            html = self._normalize_table_colspans(html)
+            if table_index >= len(self._mammoth_tables_html) or self._mammoth_tables_html[table_index] is None:
+                stage = "equation injection"
+                html = self._inject_equations_into_table_html(
+                    html,
+                    element,
+                    self._require_document_part(),
+                )
+        except Exception as exc:
+            raise RuntimeError(f"table #{table_index + 1}, {stage}: {exc}") from exc
+        self.cur_page.append({"type": BlockType.TABLE, "content": html})
 
     def _normalize_table_colspans(self, html: str) -> str:
         """

{docvortex-0.4.24 → docvortex-0.4.25}/src/docvortex/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.4.24"
+__version__ = "0.4.25"
 
 __all__ = ["__version__"]

{docvortex-0.4.24 → docvortex-0.4.25/src/docvortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.24
+Version: 0.4.25
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

{docvortex-0.4.24 → docvortex-0.4.25}/src/docvortex.egg-info/SOURCES.txt

@@ -540,6 +540,7 @@ tests/unittest/test_docx_math.py
 tests/unittest/test_docx_render.py
 tests/unittest/test_docx_special_char_tables.py
 tests/unittest/test_docx_table.py
+tests/unittest/test_docx_table_context.py
 tests/unittest/test_emfplus_integration.py
 tests/unittest/test_epub_backlinks.py
 tests/unittest/test_epub_quoted_note_types.py

docvortex-0.4.25/tests/unittest/test_docx_table_context.py

@@ -0,0 +1,314 @@
+"""DOCX 表格匹配与完整文档上下文回退的回归测试。"""
+
+from __future__ import annotations
+
+import json
+from io import BytesIO
+from pathlib import Path
+
+import mammoth
+import pytest
+from bs4 import BeautifulSoup
+from docx import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.opc.packuri import PackURI
+from docx.opc.part import Part
+from docx.oxml import parse_xml
+from docx.oxml.ns import qn
+from lxml import etree
+from PIL import Image
+from loguru import logger
+
+from docvortex.analyzers.native.office.docx.docx_converter import DocxConverter
+from docvortex.api import parse
+
+NS = (
+    'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" '
+    'xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" '
+    'xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" '
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"'
+)
+ISSUE_CASES = ("control", "footnote", "endnote", "checkbox", "alternate", "field")
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _save(document: Document) -> bytes:
+    """把内存中的 DOCX 文档序列化为字节。"""
+    output = BytesIO()
+    document.save(output)
+    return output.getvalue()
+
+
+def _table_html(converter: DocxConverter) -> list[str]:
+    """按正文顺序提取转换器输出的表格 HTML。"""
+    return [block["content"] for page in converter.pages for block in page if block["type"] == "table"]
+
+
+def _attach_note(document: Document, *, note_type: str) -> None:
+    """为脚注或尾注引用添加真实的 OOXML 包成员。"""
+    relation_type = RT.FOOTNOTES if note_type == "footnote" else RT.ENDNOTES
+    part = Part(
+        PackURI(f"/word/{note_type}s.xml"),
+        f"application/vnd.openxmlformats-officedocument.wordprocessingml.{note_type}s+xml",
+        (
+            f'<w:{note_type}s {NS}><w:{note_type} w:id="1">'
+            "<w:p><w:r><w:t>注释正文</w:t></w:r></w:p>"
+            f"</w:{note_type}></w:{note_type}s>"
+        ).encode(),
+        document.part.package,
+    )
+    document.part.relate_to(part, relation_type)
+
+
+def _issue_trigger(name: str, *, checked: bool) -> str | None:
+    """生成 issue 中会造成 XML 与 Mammoth 文本签名不一致的元素。"""
+    if name in {"footnote", "endnote"}:
+        return f'<w:r {NS}><w:{name}Reference w:id="1"/></w:r>'
+    if name == "checkbox":
+        value = "1" if checked else "0"
+        return (
+            f'<w:sdt {NS}><w:sdtPr><w14:checkbox><w14:checked w14:val="{value}"/>'
+            "</w14:checkbox></w:sdtPr><w:sdtContent><w:r><w:t>☐</w:t></w:r>"
+            "</w:sdtContent></w:sdt>"
+        )
+    if name == "alternate":
+        return (
+            f'<mc:AlternateContent {NS}><mc:Choice Requires="w14"><w:r><w:t>Choice</w:t></w:r>'
+            "</mc:Choice><mc:Fallback><w:r><w:t>Fallback</w:t></w:r>"
+            "</mc:Fallback></mc:AlternateContent>"
+        )
+    if name == "field":
+        return f'<w:fldSimple {NS} w:instr=" FILENAME "><w:r><w:t>report.docx</w:t></w:r></w:fldSimple>'
+    return None
+
+
+def _build_issue_document(*, styled: bool, checked: bool) -> bytes:
+    """构造普通表、脚注、尾注、复选框、兼容分支和简单域混合文档。"""
+    document = Document()
+    _attach_note(document, note_type="footnote")
+    _attach_note(document, note_type="endnote")
+    for name in ISSUE_CASES:
+        table = document.add_table(rows=2, cols=2)
+        first = table.cell(0, 0).paragraphs[0]
+        if styled:
+            first.style = document.styles["List Paragraph"]
+        trigger = _issue_trigger(name, checked=checked)
+        if trigger:
+            first._p.append(parse_xml(trigger))
+        first.add_run(f"{name} A1")
+        for row, col in ((0, 1), (1, 0), (1, 1)):
+            table.cell(row, col).text = f"{name} {'AB'[col]}{row + 1}"
+    return _save(document)
+
+
+@pytest.mark.parametrize("styled", (True, False))
+@pytest.mark.parametrize("checked", (True, False))
+def test_issue_11_tables_match_and_survive(styled: bool, checked: bool) -> None:
+    """验证所有触发条件均能匹配原表，并保持六张表的内容与顺序。"""
+    file_bytes = _build_issue_document(styled=styled, checked=checked)
+    converter = DocxConverter()
+    preparsed = converter._preparse_tables_with_mammoth(file_bytes)
+
+    assert len(preparsed) == len(ISSUE_CASES)
+    assert all(html is not None for html in preparsed)
+    converter.convert(BytesIO(file_bytes))
+    html_tables = _table_html(converter)
+    assert len(html_tables) == len(ISSUE_CASES)
+    for name, html in zip(ISSUE_CASES, html_tables):
+        cells = BeautifulSoup(html, "html.parser").find_all("td")
+        assert len(cells) == 4
+        assert f"{name} A1" in cells[0].get_text()
+        assert cells[-1].get_text() == f"{name} B2"
+    checkbox = BeautifulSoup(html_tables[3], "html.parser").find("input")
+    assert checkbox is not None
+    assert checkbox.has_attr("checked") is checked
+
+
+def test_issue_11_public_parse_keeps_all_tables() -> None:
+    """从公开 parse 入口验证 issue 的各张表仍在结构化结果中。"""
+    result = parse(_build_issue_document(styled=True, checked=True), file_suffix="docx")
+    serialized = json.dumps(result.to_dict(), ensure_ascii=False)
+    assert all(f"{name} B2" in serialized for name in ISSUE_CASES)
+
+
+def test_note_marker_filter_keeps_literal_bracketed_number() -> None:
+    """只从签名排除 Mammoth 生成的注释引用，保留单元格正文中的 [1]。"""
+    html = BeautifulSoup(
+        '<table><tr><td>[1]<sup><a id="footnote-ref-1" href="#footnote-1">[1]</a></sup>'
+        '<sup><a id="endnote-ref-2" href="#endnote-2">[2]</a></sup></td></tr></table>',
+        "html.parser",
+    ).table
+    assert html is not None
+    assert DocxConverter._html_table_signature(html)["text"] == "[1]"
+
+
+def _build_fallback_document() -> bytes:
+    """构造带显式编号、样式、链接、图片、公式和纵向合并的回退表格。"""
+    document = Document()
+    for label in ("first", "second"):
+        table = document.add_table(rows=2, cols=3)
+        table.cell(0, 0).merge(table.cell(1, 0))
+        cell = table.cell(0, 0)
+        paragraph = cell.paragraphs[0]
+        paragraph.style = document.styles["List Number"]
+        paragraph.add_run(label)
+        if label == "first":
+            ppr = paragraph._p.get_or_add_pPr()
+            ppr.append(parse_xml(f'<w:numPr {NS}><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr>'))
+            rid = document.part.relate_to("https://example.com/docx-table", RT.HYPERLINK, is_external=True)
+            paragraph._p.append(parse_xml(f'<w:hyperlink {NS} r:id="{rid}"><w:r><w:t>linked</w:t></w:r></w:hyperlink>'))
+            png = BytesIO()
+            Image.new("RGB", (3, 3), "red").save(png, format="PNG")
+            png.seek(0)
+            paragraph.add_run().add_picture(png)
+            styled = cell.add_paragraph("styled")
+            styled.style = document.styles["List Paragraph"]
+            formula_paragraph = table.cell(0, 2).paragraphs[0]
+            math = etree.SubElement(formula_paragraph._p, qn("m:oMath"))
+            math_run = etree.SubElement(math, qn("m:r"))
+            etree.SubElement(math_run, qn("m:t")).text = "x+y"
+        table.cell(0, 1).text = f"{label} B1"
+        table.cell(1, 1).text = f"{label} B2"
+        table.cell(1, 2).text = f"{label} C2"
+    output = BytesIO(_save(document))
+    mammoth.embed_style_map(output, "p[style-name='List Paragraph'] => h6:fresh")
+    return output.getvalue()
+
+
+@pytest.mark.parametrize("preparsed", ([], [None, None]))
+def test_forced_fallback_keeps_full_document_context(monkeypatch: pytest.MonkeyPatch, preparsed: list) -> None:
+    """强制跳过预匹配，验证回退在两张表中保留全部受支持的上下文内容。"""
+    file_bytes = _build_fallback_document()
+    converter = DocxConverter()
+
+    def skip_preparse(_data: bytes) -> list:
+        """按参数强制表格走完整上下文回退。"""
+        return preparsed
+
+    monkeypatch.setattr(converter, "_preparse_tables_with_mammoth", skip_preparse)
+    converter.convert(BytesIO(file_bytes))
+    html_tables = _table_html(converter)
+    assert len(html_tables) == 2
+    first, second = [BeautifulSoup(html, "html.parser") for html in html_tables]
+    assert first.find("li") is not None
+    assert first.find("a", href="https://example.com/docx-table") is not None
+    image = first.find("img")
+    assert image is not None
+    assert image.get("src", "").startswith("data:image/")
+    assert first.find("eq") is not None
+    assert first.find("h6") is not None
+    assert first.find("td", rowspan="2") is not None
+    assert "first B2" in first.get_text()
+    assert "second B2" in second.get_text()
+    assert converter._mammoth_fallback_context is None
+    assert converter._fallback_docx_bytes is None
+
+
+def test_alignment_skips_extra_non_body_table() -> None:
+    """额外的文本框候选表不得抢占正文表格的匹配位置。"""
+    file_bytes = _build_issue_document(styled=True, checked=False)
+    document = Document(BytesIO(file_bytes))
+    body_tables = [child for child in document.element.body if child.tag == qn("w:tbl")]
+    converter = DocxConverter()
+    raw = mammoth.convert_to_html(BytesIO(file_bytes), transform_document=converter._mammoth_top_level_table_document).value
+    html_tables = BeautifulSoup(raw, "html.parser").find_all("table")
+    extra = BeautifulSoup("<table><tr><td>textbox only</td></tr></table>", "html.parser").table
+    aligned = converter._align_mammoth_tables_to_xml_tables([extra, *html_tables], body_tables, document.part)
+    assert len(aligned) == len(ISSUE_CASES)
+    assert all(html is not None for html in aligned)
+    assert "textbox only" not in "".join(aligned)
+
+
+def test_fallback_failure_does_not_skip_later_table(monkeypatch: pytest.MonkeyPatch) -> None:
+    """一张回退表解析失败时，警告定位表号且后续表仍输出。"""
+    converter = DocxConverter()
+
+    def skip_preparse(_data: bytes) -> list:
+        """强制后续两张表进入完整上下文回退。"""
+        return []
+
+    monkeypatch.setattr(converter, "_preparse_tables_with_mammoth", skip_preparse)
+    original = converter._mammoth_fallback_html
+    attempts = 0
+
+    def fail_first(element: object) -> str:
+        """仅模拟首张表发生上下文回退异常。"""
+        nonlocal attempts
+        attempts += 1
+        if attempts == 1:
+            raise ValueError("injected failure")
+        return original(element)
+
+    warnings = []
+    sink_id = logger.add(warnings.append, level="WARNING")
+    try:
+        monkeypatch.setattr(converter, "_mammoth_fallback_html", fail_first)
+        converter.convert(BytesIO(_build_fallback_document()))
+    finally:
+        logger.remove(sink_id)
+    assert len(_table_html(converter)) == 1
+    assert "second B2" in _table_html(converter)[0]
+    assert any("table #1, full-context fallback" in str(warning) for warning in warnings)
+    assert converter._mammoth_fallback_context is None
+
+
+def test_fallback_converter_reuse_and_error_release(monkeypatch: pytest.MonkeyPatch) -> None:
+    """同一转换器的连续调用和失败重试都释放旧包及回退状态。"""
+    converter = DocxConverter()
+
+    def skip_preparse(_data: bytes) -> list:
+        """强制各次转换均使用完整上下文回退。"""
+        return []
+
+    monkeypatch.setattr(converter, "_preparse_tables_with_mammoth", skip_preparse)
+    first = _build_fallback_document()
+    converter.convert(BytesIO(first))
+    first_tables = _table_html(converter)
+    assert converter._mammoth_fallback_context is None
+
+    original_add_header_footer = converter._add_header_footer
+
+    def fail_after_tables(_document: Document) -> None:
+        """模拟完成表格回退后发生的文档级异常。"""
+        raise RuntimeError("injected lifecycle failure")
+
+    monkeypatch.setattr(converter, "_add_header_footer", fail_after_tables)
+    with pytest.raises(RuntimeError, match="injected lifecycle failure"):
+        converter.convert(BytesIO(first))
+    assert converter._mammoth_fallback_context is None
+    assert converter._fallback_docx_bytes is None
+
+    monkeypatch.setattr(converter, "_add_header_footer", original_add_header_footer)
+    with pytest.raises(Exception):
+        converter.convert(BytesIO(b"invalid docx"))
+    assert converter._mammoth_fallback_context is None
+    assert converter._fallback_docx_bytes is None
+
+    converter.convert(BytesIO(_build_issue_document(styled=True, checked=True)))
+    assert len(_table_html(converter)) == len(ISSUE_CASES)
+    assert "first B2" not in "".join(_table_html(converter))
+    converter.convert(BytesIO(first))
+    assert _table_html(converter) == first_tables
+    assert converter._mammoth_fallback_context is None
+
+
+@pytest.mark.parametrize(
+    ("path", "expected_count", "expected_rows"),
+    [
+        ("tests/fixtures/docx/issue9-merged-cells.docx", 1, 37),
+        ("demo/ms_office_docs/docx_01.docx", 8, None),
+    ],
+)
+def test_existing_docx_samples_keep_tables(path: str, expected_count: int, expected_rows: int | None) -> None:
+    """回放真实 DOCX 样本，检查表格数量及 issue #9 的完整行数。"""
+    file_bytes = (PROJECT_ROOT / path).read_bytes()
+    converter = DocxConverter()
+    preparsed = converter._preparse_tables_with_mammoth(file_bytes)
+    assert len(preparsed) == expected_count
+    assert all(html is not None for html in preparsed)
+    converter.convert(BytesIO(file_bytes))
+    html_tables = _table_html(converter)
+    assert len(html_tables) == expected_count
+    assert html_tables == [converter._normalize_table_colspans(html) for html in preparsed]
+    if expected_rows is not None:
+        assert len(BeautifulSoup(html_tables[0], "html.parser").find_all("tr")) == expected_rows