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
+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).