pdfwright 0.2.2__tar.gz → 0.4.0__tar.gz

{pdfwright-0.2.2 → pdfwright-0.4.0}/.gitignore

@@ -31,3 +31,5 @@ pdfwright/examples/output/
 
 # 本地发布凭据（scripts/publish.sh --config 默认读它）
 .publish.env
+
+runtime/

{pdfwright-0.2.2 → pdfwright-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pdfwright
-Version: 0.2.2
+Version: 0.4.0
 Summary: 配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。
 License: Proprietary
 Requires-Python: >=3.12
@@ -11,6 +11,7 @@ Requires-Dist: jsonschema>=4.23
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: pikepdf>=8.0
 Requires-Dist: pillow>=10.0
+Requires-Dist: pypdf>=4.0
 Requires-Dist: python-barcode>=0.16.1
 Requires-Dist: python-docx>=1.1
 Requires-Dist: reportlab<6,>=5.0

{pdfwright-0.2.2 → pdfwright-0.4.0}/examples/cooperation_contract.json

@@ -791,12 +791,12 @@
   "data": {
     "party_a": {
       "name": "xxx公司",
-      "address": "北京市海淀区中关村大街1号",
+      "address": "北京市海淀区某某大街 1 号",
       "representative": "xxx"
     },
     "party_b": {
       "name": "yyy公司",
-      "address": "上海市浦东新区张江高科技园区",
+      "address": "上海市浦东新区某某高科技园区",
       "representative": "yyy"
     }
   }

{pdfwright-0.2.2 → pdfwright-0.4.0}/examples/daily_report.json

@@ -827,7 +827,7 @@
     "keywords": "工程日报, 施工, 人员, 设备, 材料"
   },
   "data": {
-    "project_name": "城东污水处理厂扩建工程",
+    "project_name": "某某污水处理厂扩建工程",
     "date": "2026-09-19",
     "person": [
       {

{pdfwright-0.2.2 → pdfwright-0.4.0}/examples/generate_all.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 
 from pdfwright import DocumentConfig
+from pdfwright.fonts.registry import has_embeddable_cjk_font
 from pdfwright.render.html import render_html
 from pdfwright.render.pdf import render_pdf
 from pdfwright.validate import validate_document
@@ -26,6 +27,12 @@ def main() -> int:
     if not check_only:
         OUTPUT_DIR.mkdir(exist_ok=True)
 
+    # 渲染中文需要可嵌入的中文字体；缺字体时只跳过渲染，校验照跑 ——
+    # validate_document 不碰字体，整个脚本提前 return 会让这道关卡空转。
+    can_render = has_embeddable_cjk_font()
+    if not can_render:
+        print("⚠️  本机没有可嵌入的中文字体（ReportLab 只支持 TrueType/glyf）：只校验、不渲染")
+
     files = sorted(EXAMPLES_DIR.glob("*.json"))
     files = [f for f in files if f.parent == EXAMPLES_DIR]
     if not files:
@@ -45,6 +52,10 @@ def main() -> int:
                 print(f"    [{issue.path}] {issue.message}")
             continue
 
+        if not can_render:
+            print(f"{path.stem:<22}{'✓':<8}{'—':<6}{'（无字体，未渲染）':<20}")
+            continue
+
         document = DocumentConfig.from_dict(config)
         data = config.get("data")
         try:
@@ -67,7 +78,8 @@ def main() -> int:
     if failures:
         print(f"❌ {failures} 个示例未通过")
         return 1
-    print(f"✅ {len(files)} 个示例全部通过" + ("" if check_only else f"；产物在 {OUTPUT_DIR}"))
+    suffix = "" if can_render else "（无字体，仅校验）"
+    print(f"✅ {len(files)} 个示例全部通过{suffix}" + ("" if check_only else f"；产物在 {OUTPUT_DIR}"))
     return 0
 
 
@@ -78,4 +90,4 @@ def _page_count(pdf_bytes: bytes) -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

{pdfwright-0.2.2 → pdfwright-0.4.0}/examples/service_contract.json

@@ -532,12 +532,12 @@
     },
     "party_a": {
       "name": "xxx公司",
-      "address": "北京市海淀区中关村大街1号",
+      "address": "北京市海淀区某某大街 1 号",
       "representative": "xxx"
     },
     "party_b": {
       "name": "yyy公司",
-      "address": "上海市浦东新区张江高科技园区",
+      "address": "上海市浦东新区某某高科技园区",
       "representative": "yyy"
     },
     "clauses": [

{pdfwright-0.2.2 → pdfwright-0.4.0}/examples/staff_form.json

@@ -25,7 +25,7 @@
         { "label": "Vue", "value": "Vue" }, { "label": "Kubernetes", "value": "Kubernetes" }
       ]}},
     { "name": "emergency", "type": "string", "label": "紧急联系人", "default": "xxx（父亲）138-1111-2222" },
-    { "name": "address", "type": "textarea", "label": "现居住地址", "default": "浙江省杭州市余杭区文一西路 969 号" },
+    { "name": "address", "type": "textarea", "label": "现居住地址", "default": "浙江省杭州市余杭区某某路 1 号" },
     { "name": "photo", "type": "image", "label": "证件照" },
     { "name": "signature", "type": "image", "label": "本人签名", "empty": "blank" }
   ],

{pdfwright-0.2.2 → pdfwright-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdfwright"
-version = "0.2.2"
+version = "0.4.0"
 description = "配置驱动的 PDF 生成基础库：JSON 配置 → 模板求值（变量/循环/条件）→ 高保真 PDF。纯 Python 引擎（ReportLab + fontTools + Jinja2 + pikepdf），无外部软件依赖。"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -17,6 +17,8 @@ dependencies = [
     "pillow>=10.0",
     "segno>=1.6.6",
     "python-barcode>=0.16.1",
+    # BSD-3，纯 Python：读回产物做「一致性指纹」（跨平台比对版式与字体，见 postprocess/fingerprint.py）
+    "pypdf>=4.0",
 ]
 
 [build-system]
@@ -35,6 +37,10 @@ exclude = ["examples/output"]
 addopts = "-ra --strict-markers"
 testpaths = ["tests"]
 pythonpath = ["src"]
+markers = [
+    # 需要本机装**可嵌入中文字体**的用例（无字体的容器里自动跳过，见 tests/conftest.py）
+    "needs_cjk: 用例前提是本机存在可嵌入的中文字面（ReportLab 只支持 TrueType/glyf）",
+]
 
 [tool.ruff]
 line-length = 100
@@ -81,12 +87,23 @@ check_untyped_defs = true
 [tool.basedpyright]
 typeCheckingMode = "basic"
 include = ["src"]
+# 显式指向 **工作区根** 的 venv：basedpyright 默认会优先用同目录下的 ``.venv``，
+# 而子项目里可能存在空壳/过期的 ``.venv``（本地遗留），于是纯 Python 依赖
+# （pypdf / segno / openpyxl…）解析不到 → 检查结果取决于本机残留目录，不可复现。
+venvPath = ".."
+venv = ".venv"
 # basedpyright 的 ``ignore`` 只接受「文件/目录 glob」，不支持「每模块忽略哪些规则」
 # （旧写法 [{module, codes}] 会让 basedpyright 报配置错并以退出码 3 结束，等于从未生效）。
-# 这三个解析器大量使用第三方库动态属性，规则级豁免无法表达，故整体不纳入 basedpyright；
-# 它们仍由 mypy 检查。
+# 下列模块大量使用第三方库动态属性（python-docx / reportlab / fontTools 的属性在
+# 类型存根里查不到），规则级豁免无法表达，故整体不纳入 basedpyright；仍由 mypy 检查。
+# 逐个列「真实报错」的模块，不是「docx 目录全列」—— docx_helpers / docx_state 目前
+# 干净，未列；新增模块请先单独跑一次 basedpyright 再决定要不要加进来。
 ignore = [
   "src/pdfwright/converters/docx.py",
+  "src/pdfwright/converters/docx_block.py",
+  "src/pdfwright/converters/docx_common.py",
+  "src/pdfwright/converters/docx_run.py",
+  "src/pdfwright/converters/docx_table.py",
   "src/pdfwright/converters/xlsx.py",
   "src/pdfwright/fonts/scanner.py",
 ]

{pdfwright-0.2.2 → pdfwright-0.4.0}/src/pdfwright/__init__.py

@@ -26,7 +26,7 @@ from pdfwright.postprocess import verify_pdfa
 from pdfwright.render.html import render_html
 from pdfwright.render.pdf import PdfRenderer, render_pdf, render_pdf_to_file
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "BatchItem",

pdfwright-0.4.0/src/pdfwright/commands.py

@@ -0,0 +1,197 @@
+"""文本命令标签：在 Word 正文里用 ``{{ ... }}`` 描述**非文本元素**。
+
+作者不必用开发工具/内容控件/书签，直接打字即可（导入时转成对应元素）：
+
+.. list-table::
+   :header-rows: 1
+
+   * - 标签
+     - 转成
+   * - ``{{__TOC__}}`` / ``{{__TOC__:3}}``
+     - ``toc``（可选层级数）
+   * - ``{{__pageBreak__}}``
+     - ``pageBreak``
+   * - ``{{hiddenText:SEAL_PARTY_A}}``
+     - ``hiddenText``（不可见、可抽取，供签章系统定位）
+   * - ``{{img:photo}}`` / ``{{img:logo.png,mxw_120,mxh_80,dx_3mm,dy_1mm}}``
+     - ``image``（``photo`` 视为数据键；带 ``/``/``.``/``:`` 的视为路径或 URL）
+   * - ``{{sign:签字人[,数据键][,mxw_…][,mxh_…][,dx_…][,dy_…]}}``
+     - ``sign``（第一个位置参数是签章人 = 隐藏文本锚点 + 字段名；第二个当本地签字图的数据键）
+   * - ``{{anchor:sec1}}``
+     - ``anchor``（命名跳转目标）
+
+**与数据表达式的区分**（`{{ }}` 同时是 Jinja 插值语法）：
+
+- 无参数的单名命令必须写成 ``__名字__``（如 ``__TOC__``），避免与同名数据变量冲突；
+- 带参数的命令用冒号分隔（``img:`` / ``sign:`` / ``hiddenText:`` / ``anchor:``），
+  ``{{ img:… }}`` 本身不是合法 Jinja 表达式，所以 ``__`` 可省（写成 ``__img:…__`` 也收）；
+- 都匹配不上时**按普通数据表达式处理**，本文档的解析完全不改变既有行为。
+
+渲染端还有一层兜底：万一有命令标签没被导入阶段消费（手写的 JSON、写错的名字），
+按「空 + 告警」处理，绝不让一个笔误把整篇渲染炸掉（``strip_commands``）。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+#: ``{{ ... }}`` 片段（非贪婪，跨行安全）
+TAG_RE = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
+#: 无参数命令（必须写 ``__名字__``）
+NO_ARG_COMMANDS = frozenset({"toc", "pagebreak"})
+#: 带参数命令（``名字:参数,参数``）
+ARG_COMMANDS = frozenset({"hiddentext", "img", "sign", "anchor"})
+ALL_COMMANDS = NO_ARG_COMMANDS | ARG_COMMANDS
+
+#: 尺寸参数名 → schema 的 style 键（``mxw_120`` / ``mxw=120`` / ``w_120`` 都收）。
+#: ``mxw/mxh`` 是作者常用的「最大宽/高」写法；当前实现里等价于 image 的
+#: ``style.width``/``style.height``（绘制尺寸，超版心时再等比缩）。
+SIZE_ARGS: dict[str, str] = {
+    "mxw": "width",
+    "w": "width",
+    "mxh": "height",
+    "h": "height",
+}
+
+#: 相对偏移参数名 → 元素字段（``dx_6mm`` / ``dy_2mm``，也收 ``dx=6mm``）。
+#: **右为正 / 上为正**，与第三方签章服务的 ``leftOrRight`` / ``upOrDown`` 同符号；
+#: 只挪绘制位置、不改变占位尺寸（注意与 ``position:"absolute"`` 的 ``y`` 方向相反）。
+OFFSET_ARGS: dict[str, str] = {
+    "dx": "offsetX",
+    "dy": "offsetY",
+}
+
+_SIZE_RE = re.compile(r"(?i)^(mxw|mxh|w|h)[_=](.+)$")
+_OFFSET_RE = re.compile(r"(?i)^(dx|dy)[_=](.+)$")
+
+
+@dataclass(frozen=True)
+class Command:
+    """解析出的命令标签（不依赖 schema；由调用方转成元素）。"""
+
+    name: str
+    args: tuple[str, ...]
+    body: str
+
+    def arg(self, index: int) -> str | None:
+        """第 ``index`` 个位置参数（无则 None）。"""
+        return self.args[index] if index < len(self.args) else None
+
+    def sizes(self) -> dict[str, str]:
+        """``mxw_120,mxh_80`` → ``{"width": "120", "height": "80"}``。"""
+        out: dict[str, str] = {}
+        for part in self.args:
+            match = _SIZE_RE.match(part)
+            if match:
+                out[SIZE_ARGS[match.group(1).casefold()]] = match.group(2).strip()
+        return out
+
+    def offsets(self) -> dict[str, str]:
+        """``dx_6mm,dy_2mm`` → ``{"offsetX": "6mm", "offsetY": "2mm"}``。"""
+        out: dict[str, str] = {}
+        for part in self.args:
+            match = _OFFSET_RE.match(part)
+            if match:
+                out[OFFSET_ARGS[match.group(1).casefold()]] = match.group(2).strip()
+        return out
+
+    def rest_args(self) -> tuple[str, ...]:
+        """既不是尺寸、也不是偏移的位置参数（``img:photo,mxw_120`` → ``("photo",)``）。"""
+        return tuple(
+            part for part in self.args if not _SIZE_RE.match(part) and not _OFFSET_RE.match(part)
+        )
+
+
+def parse_command(body: str) -> Command | None:
+    """``{{ ... }}`` 内部文本 → 命令；不是命令时返回 ``None``（按数据表达式处理）。"""
+    text = body.strip()
+    if not text:
+        return None
+    name, _separator, rest = text.partition(":")
+    stripped = name.strip()
+    key = stripped.strip("_").casefold()
+    if key not in ALL_COMMANDS:
+        return None
+    dunder = stripped.startswith("_") and stripped.endswith("_")
+    args = tuple(part.strip() for part in rest.split(",") if part.strip())
+    if key in NO_ARG_COMMANDS:
+        # 单名命令要求 ``__名字__``：否则 ``{{ toc }}`` 这种数据变量会被误认
+        return Command(key, args, text) if dunder else None
+    return Command(key, args, text) if args else None
+
+
+def iter_tags(text: str) -> list[tuple[int, int, str]]:
+    """扫出 ``{{ … }}`` 片段 ``(start, end, body)``，**支持嵌套**。
+
+    用花括号配对而不是正则：``{{img:{{ item.image }}}}`` 里的内层 ``{{ }}``
+    必须一起算进来，否则非贪婪正则会在内层 ``}}`` 提前截断（实测把模板切成
+    ``{{ item.image`` + 一个孤零零的 ``}}``）。
+    """
+    found: list[tuple[int, int, str]] = []
+    index = 0
+    length = len(text)
+    while True:
+        start = text.find("{{", index)
+        if start < 0:
+            return found
+        depth = 1
+        cursor = start + 2
+        while cursor < length and depth:
+            if text.startswith("{{", cursor):
+                depth += 1
+                cursor += 2
+            elif text.startswith("}}", cursor):
+                depth -= 1
+                cursor += 2
+            else:
+                cursor += 1
+        if depth:
+            return found  # 未闭合：后面不再是标签
+        found.append((start, cursor, text[start + 2 : cursor - 2]))
+        index = cursor
+
+
+def looks_like_command(body: str) -> bool:
+    """``{{ … }}`` 内部是否**看起来**是命令标签（首段是已知命令名）。
+
+    渲染端兜底用：即使参数写错（如 ``{{img:}}``、``{{__TOC__:x}}``）也当命令处理
+    （空 + 告警），而不是丢给 Jinja 报 ``chunk after expression`` 把整篇炸掉。
+    """
+    name = body.strip().partition(":")[0].strip().strip("_").casefold()
+    return name in ALL_COMMANDS
+
+
+def iter_commands(text: str) -> list[tuple[int, int, Command]]:
+    """文本里所有**合法**命令标签的 ``(start, end, command)``（按出现顺序）。"""
+    if "{{" not in text:
+        return []
+    found: list[tuple[int, int, Command]] = []
+    for start, end, body in iter_tags(text):
+        command = parse_command(body)
+        if command is not None:
+            found.append((start, end, command))
+    return found
+
+
+def strip_commands(text: str) -> tuple[str, list[str]]:
+    """去掉命令标签（渲染端兜底）：返回 ``(剩余文本, 遇到的命令标签原文)``。
+
+    导入阶段会把命令标签转成元素；万一还有残留（手写 JSON、参数写错的命令），
+    这里把它们当空处理并回报，让渲染端告警而不是抛 Jinja 语法错误。
+    """
+    if "{{" not in text:
+        return text, []
+    out: list[str] = []
+    names: list[str] = []
+    position = 0
+    for start, end, body in iter_tags(text):
+        if not looks_like_command(body):
+            continue
+        out.append(text[position:start])
+        names.append(body.strip())
+        position = end
+    if not names:
+        return text, []
+    out.append(text[position:])
+    return "".join(out), names

{pdfwright-0.2.2 → pdfwright-0.4.0}/src/pdfwright/converters/__init__.py

@@ -5,6 +5,7 @@ from pdfwright.converters.docx import (
     DocxField,
     DocxParseResult,
     docx_to_schema,
+    semantic_family,
 )
 from pdfwright.converters.html import (
     HtmlField,
@@ -23,6 +24,7 @@ __all__ = [
     "XlsxConverter",
     "docx_to_schema",
     "html_to_schema",
+    "semantic_family",
     "strip_html_tags",
     "xlsx_to_schema",
 ]

pdfwright-0.4.0/src/pdfwright/converters/docx.py

@@ -0,0 +1,123 @@
+"""DOCX 转换器：python-docx 解析 Word 文档 → pdfwright schema（高保真 + 模板标签 + 自动字段 key）。
+
+保真原则：**只翻译 docx 里真实存在的信息，不发明样式**。
+
+- 段落 = **一个元素**，`text` 是**富文本标记**（``<b>`` / ``<i>`` / ``<u>`` /
+  ``<font color= size= face=>``），``{{ 变量 }}`` **保持内联**——不再把
+  「``{{project_name}}日报``」拆成 input + 段落两个区域；
+- **逐 run** 取字体/字号/颜色/粗斜体（Word 的混排段落不会丢格式），但**样式已经表达过的
+  格式不重复写进 `text`**：整段同格式 → `text` 是纯文本（字体/字号/粗细在元素 `style`
+  上）；混排段落也只有与样式不同的片段才带标记。样式没有的位（下划线/高亮/上下标/字符间距）
+  留在内联标记里 —— 见 ``_baseline_fmt`` / ``_trim_fmt``；
+- 字体名**原样保留**（文档写 ``宋体`` 就存 ``宋体``、写 ``SimSun`` 就存 ``SimSun``、
+  写 ``华文中宋`` 就存 ``华文中宋``）——导入不替用户挑语义族，跨平台解析交给
+  fonts.registry（本机有该字面就精确命中真身，没有才按名字里的风格回退）；
+- 表格边框读 ``w:tblBorders`` / ``w:tcBorders``，底纹读 ``w:shd`` ——
+  **docx 没有底纹就不画底纹**（早前版本硬编码灰色表头，属于发明）；
+- 列宽读 ``w:gridCol`` / ``w:tcW``，垂直对齐读 ``w:vAlign``；
+- 图片提取为 image 元素（base64 data URL）；分页符 → pageBreak；
+- 字段识别：Word 内容控件（w:sdt）与**循环外**的 ``{{ 变量 }}`` → 可填字段；
+  **循环内**的 ``{{ 变量 }}`` → 保留为模板插值（渲染时按数据求值）；
+- 模板标签：``{% for x in y %}`` / ``{% endfor %}`` 可出现在段落或表格单元格中，
+  按出现顺序配对，循环体可跨多行（如「人员明细行 + 合计行」共享一个外层循环）。
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+from docx import Document
+
+from pdfwright.converters.docx_block import _DocxBlockMixin
+
+# ``DocxField`` 只在这里再导出（公开 API：``converters/__init__.py`` 从本模块取），
+# 本模块自己不用它 —— 故显式标注 F401。（noqa 只能跟规则码，说明写在独立注释行。）
+from pdfwright.converters.docx_common import (
+    DocxField,  # noqa: F401
+    DocxParseResult,
+)
+
+# 拆模块后本文件只剩「组合 + 入口」。`font_name` / `scan_jinja_tags` /
+# `strip_jinja_tags` 曾在这里带 F401 抑制注释再导出，但兄弟模块一律**直接**从
+# ``docx_common`` 导入，全仓（含测试与 pdfwright-web）无人从 ``converters.docx``
+# 取这三个名字 —— 那是纯死代码，还会让人误以为这里是它们的公开入口，故移除。
+# ``_format_number`` / ``semantic_family`` 相反：确实有人从这里导入，作为**向后兼容的
+# 公开入口**保留（本模块自己不用），并显式标注 F401。
+# （noqa 指令只能跟规则码，中文说明必须写在独立注释行。）
+from pdfwright.converters.docx_helpers import (  # noqa: F401
+    _format_number,  # 既有测试从这里导入
+    semantic_family,  # deprecated shim，见 docx_helpers.semantic_family
+)
+from pdfwright.converters.docx_run import _DocxRunMixin
+from pdfwright.converters.docx_table import _DocxTableMixin
+from pdfwright.errors import ConversionError
+from pdfwright.models import (
+    Element,
+)
+
+
+# 方法按职责拆到这些 mixin（共享状态在 ``docx_state.DocxConverterState`` 声明）：
+# 段落与 run → ``docx_run``，表格 → ``docx_table``，块结构与文档级信息 → ``docx_block``。
+class DocxConverter(_DocxRunMixin, _DocxTableMixin, _DocxBlockMixin):
+    """DOCX → DocumentConfig 转换器。"""
+
+    def __init__(self, auto_field: bool = True, inline_commands: bool = False) -> None:
+        self.auto_field = auto_field
+        #: 同一段落里的「文字 + 内联命令标签」是否**排在同一行**（见
+        #: ``_append_paragraph_content``）。默认 ``False`` = **块级**：文字与图片/签章位
+        #: 各自独立成块（导入结果与旧版逐字节一致，可自由拖拽、重排）；
+        #: 置 ``True`` 才包一层按内容的 ``row`` 保留 Word 的同行排版。
+        self.inline_commands = inline_commands
+        self._used_keys: set[str] = set()
+        self._part: Any = None
+        self._doc_defaults: Any = None
+        self._doc_sections: list[Any] = []
+        self._section_index = 0
+        self._table_margins: Any = None
+        # 列表编号：numId → {ilvl: (numFmt, start, lvlText)}；计数器随文档顺序累加
+        self._numbering: dict[str, dict[int, tuple[str, int, str]]] = {}
+        self._number_counters: dict[tuple[str, int], int] = {}
+        # 块栈：栈顶是当前打开的容器（``for`` / ``if``），其 children（if 在 else 时为
+        # else_children）收后续元素。元素为 ``(kind, node, in_else, chain_start)``；
+        # ``chain_start`` 标记 if 链起点（``{% elif %}`` 会在 else 分支里再开一个嵌套 if，
+        # 因此 ``{% endif %}`` 要把整条链一起关掉）。
+        self._block_stack: list[tuple[str, Element, bool, bool]] = []
+        # 内容插入目标覆盖：表格单元格必须写入自己的 td，而不是当前循环体
+        self._target_override: list[Element] | None = None
+        # 文档水印（浮动图片，``wp:anchor/@behindDoc=1``）
+        self._watermark: dict[str, Any] | None = None
+        # 文档默认字体（→ page.fontFamily；仅当文档自己声明了才下发，不按语言猜）
+        self._document_font_family: str | None = None
+
+    # ------------------------------------------------------------------ 入口
+    def convert(self, source: str | bytes | io.BytesIO) -> DocxParseResult:
+        try:
+            if isinstance(source, bytes):
+                document = Document(io.BytesIO(source))  # pyright: ignore[reportCallIssue]
+            elif isinstance(source, io.BytesIO):
+                document = Document(source)  # pyright: ignore[reportCallIssue]
+            else:
+                document = Document(source)  # pyright: ignore[reportCallIssue]
+        except Exception as exc:
+            # python-docx 只认 OOXML（.docx/.docm）；旧版二进制 .doc 会报
+            # PackageNotFoundError → 这里统一转成 ConversionError（HTTP 400 + 可读提示），
+            # 否则会以未处理异常冒到 500。
+            raise ConversionError(
+                message="不是有效的 .docx 文件（旧版二进制 .doc 需先转换为 .docx）",
+                detail={"reason": type(exc).__name__},
+                cause=exc,
+            ) from exc
+        self._part = document.part
+        return self._convert_doc(document)
+
+
+def docx_to_schema(
+    source: str | bytes | io.BytesIO, auto_field: bool = True, inline_commands: bool = False
+) -> DocxParseResult:
+    """一行调用：DOCX → DocumentConfig + 字段列表。
+
+    ``inline_commands``：同一段落里的「文字 + 内联命令标签」（``记录人：{{sign:…}}``）
+    是否排在**同一行**（默认 ``False`` = 块级，各自独立成块）。
+    """
+    return DocxConverter(auto_field=auto_field, inline_commands=inline_commands).convert(source)