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,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