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:
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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`).
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user