Files
java-word-pdf/docs/architecture/doc-bridge.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

4.7 KiB
Raw Blame History

Мост .doc → .docx

Бинарный формат Word 97–2003 читается собственным мостом без внешних зависимостей (POI остаётся test-scope): байты .doc парсятся по спецификациям [MS-DOC] (сам документ) и [MS-CFB] (OLE2-контейнер), собираются in-memory .docx — и дальше идут тем же конвейером, что и обычные docx.

Точка входа

DocToDocx.convert(byte[] docBytes, long maxMb)  // → байты .docx (вызывает WordPdfConverter)
DocToDocx.countPages(byte[] docBytes)           // → страницы по сырым байтам (вызывает валидатор)

Страницы .doc считаются по сырым байтам до конвертации (PageCount из SummaryInformation, разрывы 0x0C, межсекционные разрывы, pageBreakBefore) — тот же скан используется валидатором лимита страниц. Любой брак (не-CFB, шифрованный документ, Word 6–95) → ConversionException (в REST — 400).

Классы пакета internal/doc (18 top-level)

Класс Спецификация Что делает
CfbReader [MS-CFB] §2.2–2.6 FAT/DIFAT/miniFAT, directory; бюджеты против враждебного FAT, любой брак → ConversionException
FibHeader [MS-DOC] §2.5.1 заголовок FIB: потоки 1Table/0Table, пары fc/lcb нужных индексов, сверка раскладок по nFib
PieceTable §2.9.135 текст: куски CP1252/UTF-16LE, клампинг к cbMac, проверка aCP
Grpprl §2.6.2 свойства форматирования (sprm'ы): bold/italic/шрифт/цвет/подсветка/заливка/отступы/табуляции
ChpxIndex / PapxIndex §2.4.6 FKP-страницы символьных/абзацных свойств
Styles §2.9.271 STSH: стилевые цепочки абзацев и символов (stk=1/2)
Tables §2.6.3 TAP TTP-абзаца → сетка, границы, выравнивание таблицы
Lists §2.9.200/.201 PlfLst/PlfLfo → word/numbering.xml
Sections §2.8.26 PlcfSed → геометрия секций, ориентация, нумерация страниц, titlePg
FontTable §2.9.286 SttbfFfn: индекс ftc → имя семейства
SummaryInfo [MS-OLEPS] \x01SummaryInformation: в т.ч. PageCount
Headers §2.4.1 Plcfhdd: 6 колонтитуков на секцию → headerN.xml/footerN.xml
OfficeArt [MS-ODRAW] картинки: BLIP-хранилище (JPEG/PNG/TIFF/DIB/EMF/WMF/PICT)
PrcData §2.9.210 разворачивание «огромных» grpprl, вынесенных за FKP-страницу
DocToDocx — оркестратор + вложенный DocxBody (сборка document.xml)
DocxWriter — мульти-частный zip: content-types, rels, numbering, headers, media

17 из 18 классов package-private; наружу — только DocToDocx.

Модель деградации (не падение)

Объект в .doc Поведение
OLE-внедрения (U+0001 в тексте) плейсхолдер заменяется его же BLIP-картинкой
картинки JPEG/PNG/TIFF/DIB переносятся дословно / через ImageIO в PNG
EMF/WMF/PICT пропуск с warn (векторные растеризаторы не в контуре)
битые/неподдерживаемые конструкции снисходительный разбор, объект исчезает или упрощается — текст не теряется

Поэтому error-флаги (errorOnCharts/errorOnSmartArt/errorOnOle) на .doc не срабатывают: OLE-вложения бинарного формата — это U+0001 с BLIP-плейсхолдером, мост деградирует их в картинки, «OLE-объектов» в смысле docx-пути в результате нет.

Сознательный остаток

Семантика рестартов списков (fNoRestart/ilvlRestartLim), fLegal, AUTONUM-поля (трактуются как обычные списки), часть тонкостей объединённых ячеек — осознанные упрощения вне контура; полный перечень — doc-bridge.md (репозиторий).