b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
69 lines
5.5 KiB
Markdown
69 lines
5.5 KiB
Markdown
# Архитектура
|
||
|
||
## Конвейер конвертации (шаги 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).
|