docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+62
View File
@@ -0,0 +1,62 @@
# Диаграммы, SmartArt, формулы
XSLT-экспорт docx4j диаграммы не умеет, поэтому `DrawingPreRenderer` (шаг 3.5
конвейера) **до** генерации XSL-FO заменяет `c:chart` / `dgm:relIds` / `m:oMath`
на PNG-картинки (`pic:pic`). Рендер — собственный Java2D-движок (`internal/chart`,
21 класс), без Word/LibreOffice/JEuclid; текст рисуется глифами fontbox (`GlyphFont`),
поэтому fontconfig серверу не нужен.
## Диаграммы
- Выход: PNG **300 dpi** (`ChartRenderer.DPI = 300`), размеры из `wp:extent` (EMU→pt).
- Поддерживаемые типы (`ChartSpec.Type`): `PIE`, `PIE3D`, `DOUGHNUT`, `BAR`,
`BAR_HORIZONTAL`, `LINE`, `AREA`, `SURFACE3D`, `AREA3D`, `BAR3D`, `LINE3D`,
`RADAR`, `SCATTER`, `BUBBLE`, `STOCK`, `OF_PIE`, `SURFACE` (+ `UNSUPPORTED`).
- **Combo** («Комбинированная», §21.2.2.145): несколько групп в одном plotArea
(bar+line/area), привязка по `c:axId`, вторичная ось значений справа; серии
масштабируются по своей оси.
- Стекинг `stacked`/`percentStacked` — ряды накопленной суммой.
- Геометрия/камера 3-D и пропорции откалиброваны по эталонным экспортам Word
(пиксельные тесты с допусками).
## Умные границы (враждебный XML)
|Бюджет|Значение|Поведение при превышении|
|---|---|---|
|`ChartRenderer.MAX_PIXELS`|16 777 216 (4096², 64 МБ ARGB)|`fitDpi` понижает эффективный dpi (24″-график: 300→≈171 dpi), геометрия не меняется|
|`ChartSpec.MAX_POINTS`|100 000|отказ **до** предвыделения списка|
|`ChartRenderer.MAX_TICKS`|1000|безумный шаг оси заменяется «красивым» 1/2/5·10ⁿ|
|`DrawingPreRenderer.MAX_EXTENT_EMU`|22 000 000 (≈24″)|объект **остаётся как есть** + warn (не удаляется)|
|бюджет chart/math-PNG на документ|128 MiB|объект удаляется + warn|
## Модель деградации
Битая/неподдерживаемая часть роняет не конвертацию, а объект:
|Ситуация|Исход|
|---|---|
|битая chart-часть / превышение бюджета PNG|объект удалён + warn|
|неподдерживаемая/битая OMML-формула|**текст** (конкатенация `m:t`) + warn — текст терять хуже|
|`wp:extent` вне диапазона/ноль|объект остаётся + warn (FOP молча потеряет)|
|`OutOfMemoryError`|не деградация — `ConversionException` (REST 500)|
## SmartArt
`SmartArtRenderer` рисует диаграмму по разметке [MS-ODRAWXML]/§21.4: узлы, макет,
связи; тот же DPI/`fitDpi`.
## Формулы OMML
Собственный растер: `MathModel` разбирает OMML (§22.1) в дерево боксов,
`MathRenderer` рисует его только бандл-шрифтами. Конструкции вне списка `SUPPORTED`
деградируют в текст ещё на шаге нормализации (правило 6). Inline-формула опускается
на нижний запас рана — FOP ставит инлайн-графику нижним краем на базу строки.
## Контрафт media-частей
PNG-части получают имена `/word/media/chart-N.png` (константа
`CHART_MEDIA_URI_PREFIX`); по этому префиксу `ChartImageHandler` отключает
пересжатие картинок в FOP — переименование молча вернёт «мыльный» ресемпл.
Глубина (пейнтеры, калибровки, спецификационные секции) —
[chart.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md).
+61
View File
@@ -0,0 +1,61 @@
# Мост .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).
+63
View File
@@ -0,0 +1,63 @@
# Шрифты
Конвертация не зависит от шрифтов системы: **30 TTF упакованы в jar**
`wordpdf-core/src/main/resources/fonts/`, выгружаются во временный каталог и
регистрируются в docx4j/FOP. Реестр шрифтов после каждой конвертации возвращается
к бандлу — шрифты, встроенные в чужие docx, не влияют на последующие документы.
`java.awt.Font` не используется (метрики и глифы — fontbox напрямую), поэтому
**fontconfig серверу не нужен**.
## Бандл
7 текстовых семейств по 4 начертания + 2 покрывающих (только regular):
|Семейство|Аналог MS-шрифта|Назначение|
|---|---|---|
|Carlito|Calibri|метрически совместимая замена|
|Caladea|Cambria|метрически совместимая замена|
|Arimo|Arial|метрически совместимая замена|
|Tinos|Times New Roman|метрически совместимая замена|
|Cousine|Courier New|метрически совместимая замена|
|DejaVu Sans / DejaVu Serif|—|fallback с гарантированной кириллицей|
|Noto Naskh Arabic|—|арабские дополнения U+07B1–U+08FF|
|Noto Sans Armenian|—|армянские знаки Unicode 16|
## Алиасы (`BundledFontAliases`)
Имена шрифтов из документа подменяются аналогами при конвертации:
|Имя в docx|Физический шрифт|
|---|---|
|Calibri|Carlito|
|Cambria|Caladea|
|Arial|Arimo|
|Times New Roman|Tinos|
|Courier New|Cousine|
## Fallback-цепочка
1. **Ран** идёт своим шрифтом (по `w:rFonts` + алиасам).
2. Знака нет в шрифте рана (тире «—», кавычки, U+2000–U+2EFF) — ран падает в
**DejaVu Sans** (FOP-фолбэк-семейства задекларированы всецело, шаг 4 конвейера).
3. Serif-раны ищут покрытие сначала в serif-семействах (DejaVu Serif, Tinos, Caladea).
4. Знака нет и там — `GlyphCoverageNormalizer` (правило 7) режет ран и каждой части
назначает покрывающее семейство: serif → DejaVu Serif, sans → DejaVu Sans,
экзотика → Noto.
5. Знака нет ни в одном шрифте бандла — остаётся `.notdef` (пустой бокс).
Все шрифты встраиваются в PDF как **подмножества** (кириллица и латиница
воспроизводятся на любом просмотрщике).
## Лицензии
|Шрифты|Лицензия|
|---|---|
|Arimo, Cousine, Tinos, Carlito, Caladea|SIL OFL 1.1 (`fonts/FONT-LICENSE.txt`)|
|DejaVu Sans / DejaVu Serif|SIL OFL 1.1 / Bitstream Vera (`fonts/DejaVu-LICENSE.txt`)|
|Noto Naskh Arabic, Noto Sans Armenian|SIL OFL 1.1 (`fonts/Noto-LICENSE.txt`)|
GPL-шрифты в бандл не добавляем намеренно (из-за этого два символа эталона —
U+2188/U+218A — остаются `.notdef`; см. [Ограничения](limitations.md)).
Новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES`
(синхронность проверяет `BundledFontsTest`).
+40
View File
@@ -0,0 +1,40 @@
# Ограничения рендера
Конвертер **не является pixel-perfect рендером Word**: часть расхождений —
неустранимые невозможности связки docx4j + Apache FOP, а не упущения проекта.
## Что конвертируется приближённо
- Раскладка, поля и некоторые эффекты могут отличаться от Word (ограничения
FOP/docx4j по построению).
- Символы U+2000–U+2EFF (тире, кавычки): из шрифта рана, если в нём есть глиф,
иначе — из fallback-семейства DejaVu.
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
остаётся `.notdef` (пустой бокс). В эталонном наборе таких два: U+2188 (ↈ) и
U+218A (↊) — глифы есть только в GNU FreeSerif под GPL, а бандл держится целиком
на SIL OFL.
- Поддержка таблиц/изображений — базовая (уровень docx4j/FOP).
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
бинарного формата — уже растры (вставляются картинками), EMF/WMF/PICT пропускаются
с warn — [Мост .doc](doc-bridge.md).
## Стоп-лист «не чинить»
До любой попытки «починить» расхождение с Word — сверьтесь со списком: это
невозможности движка, попытка фикса хуже самого расхождения.
|Конструкция|Что происходит|Почему не чинится|
|---|---|---|
|`w:jc="distribute"`|рендерится как left|межсимвольного распределения в FOP нет; `text-align-last` в форке отсутствует|
|`w:suff="tab"`|игнорируется (label через hanging-tab)|нужна per-item ширина; совпадает с поведением docx4j|
|`w:lvlJc`|игнорируется|—|
|кернинг|не применяется|—|
|`framePr` (обтекание)|не поддерживается|—|
|кэш полей `REF`/`SEQ`/`TOC`|печатается кэш из docx|живой пересчёт вне контура (`PAGE`/`NUMPAGES`/`PAGEREF`/`DATE` — пересчитываются)|
|руби (надстрочница)|надстрочная часть вырезается, база печатается|ruby-разметки в FOP нет; потеря текста хуже потери аннотации|
|`ptab`|не поддерживается|—|
|U+2188/U+218A|`.notdef`|GPL-шрифты не добавляем намеренно|
|`lineRule="auto"`|—|не «чинить»: метрический шаг пинен тестом|
Полный перечень с доказательствами по ECMA-376 —
[render-limitations.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md).
+68
View File
@@ -0,0 +1,68 @@
# Архитектура
## Конвейер конвертации (шаги 0–7)
Единственный вход ядра — `WordPdfConverter.convert(byte[], String, ConvertOptions)`;
порядок шагов фиксирован и каждый обоснован:
|#|Шаг|Зачем|
|---|---|---|
|0|`DependencyGuard.check()`|API-проба commons-compress ≥ 1.25.0 — понятная ошибка вместо `NoSuchMethodError` внутри docx4j|
|1|`new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()`|реестр шрифтов = только бандл (+ встроенные в docx); системные сканы отключены гейт-свойствами; порядок строго такой, до `load()`|
|2|нормализаторы → `WordprocessingMLPackage.load`|12 правил переписывания байтов одним zip-проходом + OLE-вычистка (см. ниже)|
|3|`setFontMapper`|привязка имён шрифтов документа к физическим TTF|
|3.5|`DrawingPreRenderer.run`|диаграммы/SmartArt/OMML-формулы → PNG 300 dpi; **обязателен до `FOSettings`**, иначе FOP молча теряет диаграммы|
|4|`FOSettings` + `ChartImageHandler` + `FopFallbackFonts.declare`|FOP встраивает только задекларированные семейства; декларуются все бандл-семейства|
|4.25/4.5|`LayoutPostRenderer.register`, `setCustomXsltTemplates`|padding-компенсация таблиц; вендорный XSLT с AUDIT-FIX-патчами|
|5–6|общая `FopFactory` (DCL) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`|XSL-FO → PDF|
|7|`finally`|сброс temp-шрифтов, сброс общих кешей картинок (иначе ~1,5 ГБ за 30 конвертаций), возврат реестра к бандлу|
Нормализаторы правил 1–11 (один zip-проход, порядок значим): strict→transitional,
`on/off`→`true/false`, Symbol/Wingdings→Unicode, поля `PAGE`/`NUMPAGES` →
`w:fldSimple` (пересчёт вместо кэша), невидимые символы, OMML-фолбэк, резка ранов
по покрытию глифов, отступ таблиц, `suff="space"`, скрытый текст, руби. Правило 12 —
`OleObjectNormalizer` (отдельным байтовым проходом).
Полное «что делает каждый шаг и почему именно так» —
[pipeline.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md).
## Слои ядра (`wordpdf-core`)
|Слой|Содержимое|
|---|---|
|публичный API (`ru.pjandro.wordpdf`)|`WordPdfConverter`, `WordPdfValidator`, `ConvertOptions`, иерархия ошибок — см. [API библиотеки](../library/api.md)|
|`internal/`|нормализаторы (контракт `byte[] normalize(byte[])`), `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`|
|`internal/doc/`|мост бинарного `.doc` → in-memory `.docx` — [Мост .doc](doc-bridge.md)|
|`internal/chart/`|Java2D-рендер диаграмм/SmartArt/формул → PNG — [Диаграммы](charts.md)|
|`fonts/`|бандл из 30 TTF, маппинг алиасов, `GlyphFont` (метрики/глифы через fontbox, без AWT) — [Шрифты](fonts.md)|
Всё, кроме публичного API, — package-private; контракт наружу не расширяется.
## Параллельность
`PhysicalFonts` docx4j — глобальный мутируемый реестр → **все конвертации
сериализованы монитором класса `WordPdfConverter.class`**. Приложение (`wordpdf-app`)
дополнительно держит однопоточный `ThreadPoolExecutor` с очередью 16 мест (переполнение
→ 503, timeout 2m → 504), головой очереди стоит `warmup()`.
## REST-конвейер приложения (`wordpdf-app`)
`POST /api/v1/convert` → `ApiKeyFilter` (401) → `ConvertController` (проверка
расширения/размера, параметры) → `ConversionService` (очередь, Future с таймаутом,
перевод исключений ядра в HTTP) → ядро. Обработчик исключений пишет JSON
`{"error": …}` — карта кодов в [REST API](../api/errors.md). В модуле 11 классов,
все package-private кроме `WordPdfApplication`.
## Веб-интерфейс (`wordpdf-web`)
React SPA; вся сеть — ровно две функции в `api.ts` (`convertDocx`, `probeApiKey`),
состояние — `useState` в `App.tsx`, store-библиотек нет. Запросы идут на тот же
путь `/api/...` относительно базы раздачи — CORS не нужен.
## Внешние поверхности
- `gateway/nginx.conf` — единственная наружная точка стендов (:9010/:9011):
`/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → app:8080, остальное → web;
[Эксплуатация: стенды](../operations/stack.md).
- Прод (`https://pjandro.ru/pdf-converter/`) рендерится job'ом `deploy` из
Gitea Variables — [Деплой](../operations/deployment.md).