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

62 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Мост .doc → .docx
Бинарный формат Word 97–2003 читается **собственным мостом** без внешних
зависимостей (POI остаётся test-scope): байты `.doc` парсятся по спецификациям
**[MS-DOC]** (сам документ) и **[MS-CFB]** (OLE2-контейнер), собираются in-memory
`.docx` — и дальше идут тем же конвейером, что и обычные docx.
## Точка входа
```java
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 (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md).