Update AGENTS.md

This commit is contained in:
Pjandro
2026-10-14 20:49:51 +00:00
parent dfdcb5124d
commit a5acf82312
+74 -81
View File
@@ -2,92 +2,76 @@
## Project Overview ## Project Overview
Конвертер `.docx` → `.pdf` на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot REST API); плюс `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint в репозитории нет; SPA гейтуется `npm run build`). Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI/lint нет; SPA гейтуется `npm run build`). Вход стека — контейнер `gateway` (nginx), НЕ 8080; Docker-секция README устарела — авторитет этот файл.
## Architecture & Data Flow ## Architecture & Data Flow
Пайплайн `WordPdfConverter.convertToStream` — порядок шагов фиксирован, менять местами нельзя: ### Пайплайн `WordPdfConverter.convertToStream` (порядок фиксирован, менять местами нельзя)
1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз заново добавляет системные шрифты в реестр `PhysicalFonts`; бандл регистрируется поверх; чистка реестра — **до** `load()`. Ключ реестра — имя шрифта, `addPhysicalFont(URI)` НЕ перезаписывает занятый ключ → `BundledFonts.init()` вызывает `dropNonBundled()` (иначе системный `DejaVuSerif.ttf` блокирует наш `DejaVuSerif-Regular.ttf`). 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя шрифта, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()`.
2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): 2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица `SymbolMapper` сгенерирована) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах один закэшированный номер) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»).
`DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`; docx4j 17.x теряет on/off при разборе) 3. `WordprocessingMLPackage.load` → `WordPdfValidator.checkPageCount(pkg, maxPages)` — **до** рендера.
→ `SymbolFontNormalizer` (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица `SymbolMapper` сгенерирована, руками не менять) 4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg, options)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет — свой Java2D-движок `internal/chart/*` рендерит в PNG 300 dpi и подменяет на `pic:pic`; объект, выключенный в `ConvertOptions`, пропускается до рендера и остаётся в docx).
→ `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`) 5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
→ `GlyphCoverageNormalizer` (шаг 2.4: режет ран по покрытию глифов и пишет семейство в `w:rFonts`; трогает только раны с одним `w:t` и явным `w:rFonts`; покрытие — `java.awt.Font.canDisplay` через `BundledFonts.awtFont`, не `GlyphCheck` — тот логирует на каждый глиф). 6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
3. `WordprocessingMLPackage.load(байты)` → `WordPdfValidator.checkPageCount(pkg)` — **до** рендера.
4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg, options)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок `internal/chart/*` рендерит их в PNG 300 dpi и подменяет на `pic:pic`; после `setFontMapper`, до `FOSettings`; рисунок, выключенный в `ConvertOptions`, пропускается ранним `continue` до рендера и остаётся в docx — в PDF на его месте пусто, как без движка)
→ `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует в FOP-конфиге **все** бандл-семейства — FOP встраивает только задекларированные)
→ `FORendererApacheFOP` / `FOUserAgent` (заголовок PDF = параметр `title`, если непустой)
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
### REST API (`wordpdf-app`) ### REST API (`wordpdf-app`, все классы package-private)
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (очередь 16, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера. - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`.
- Разделение ошибок: валидация байтов до очереди (`WordPdfValidator.checkInput(byte[])` + проверка zip-подписи + `checkPageCountLightweight(byte[])`) → `ValidationException` → 400; ошибки ядра/рендера → `ConversionFailedException` → 500; очередь занята → 503; таймаут (`wordpdf.convert-timeout`, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500. - Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`.
- Фронт ходит на `${import.meta.env.BASE_URL}api/...` (vite `base` из env `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). - Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; неизвестный путь → 404; catch-all → 500 (подробности только в лог). Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCountLightweight` (порядок значим).
- Факультативные параметры `renderCharts`/`renderSmartArt` (query или multipart-form — Spring биндит и то и другое) контроллер превращает в `ConvertOptions`; дефолты — константы ядра `WordPdfSettings.RENDER_CHARTS`/`RENDER_SMARTART`. Лимиты входа задаёт **только конфигурация сервера**: свойства `wordpdf.max-bytes` (байты) / `wordpdf.max-pages` (страниц), env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES` (relaxed binding, прецедент `WORDPDF_CONVERT_TIMEOUT`); `@Value` в конструкторе `ConvertController` с дефолтом-SpEL из констант ядра (`MAX_INPUT_BYTES`=20 MiB / `MAX_PAGES`=1000), значение ≤ 0 — падение на старте. Параметрами запроса лимиты не переопределяются (регрессии `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `ConvertLimitsTest`). SPA шлёт только чекбоксы. Потолок загрузки — 100 МБ (`client_max_body_size 100m` в nginx + Spring multipart `100MB`); больше отсекается до валидатора. - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). `/actuator/**` открыт (HEALTHCHECK). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404.
- **Ключ доступа**: `ApiKeyFilter` (сервлет-фильтр, единственная граница доступа) сверяет заголовок `X-API-Key` со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`; сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты `ConvertControllerTest` — пустой ключ). `/actuator/**` открыт — им дышит Docker HEALTHCHECK (actuator публикует только `health`). 401 отдаёт сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит), тело в той же форме `{"error": …}`. Прод: compose выключает springdoc env'ами `SPRINGDOC_API_DOCS_ENABLED`/`SPRINGDOC_SWAGGER_UI_ENABLED` — документация с валидным ключом даёт 404 (`ApiExceptionHandler.notFound` даёт 404 всем неизвестным путям, а не 500 от catch-all). SPA: экран `ApiKeyGate`, ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается и форма открывается пустой; заголовок подставляет только `api.ts`. Регрессии — `ApiKeyFilterTest`, `ConvertControllerTest#unknownPath_notFound`. - Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (20 MiB / 1000); значение ≤ 0 → падение на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт.
- SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate`; запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`).
### Критические инварианты (нарушение = битый вывод)
- **`docx4j.convert.out.fo.gsubFeatures=false`** — ставится в статическом блоке `WordPdfConverter`. Иначе docx4j навешивает `fox:gsub-features` без объявления префикса → FO невалиден → `WordLayoutFixups` молча отказывается от всех фиксов → FOP падает на `docx4j-baseline`. Без фиксов нет колонок и колонок таблиц.
- **`slf4j-simple` обязателен** в ядре: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия `noLoggingWarningInPdf`). Приложение (`wordpdf-app`) исключает `slf4j-simple` из зависимости ядра — логи ведёт logback из Boot; предупреждение в PDF возникает только при полном отсутствии SLF4J-провайдера, `slf4j-simple.properties` из core остаётся инертным ресурсом.
- **JAXB-обход обязан раскрывать `JAXBElement`** (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через `ContentAccessor` из `org.docx4j.wml` (НЕ `org.docx4j.contentcontrol` — в 17.x его нет). Тип секции — `SectPr$Type.getVal()`; маркер — `R.LastRenderedPageBreak` (`CTLastRenderedPageBreak` в 17.x отсутствует).
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`), умеет хинты `docx4j:baseline`/`docx4j:line-box`. `Fop.Renderers.getRenderer()` возвращает **список** — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
- `docx2fo.xslt` в репозитория нет — он в jar `docx4j-export-fo`. `WordLayoutFixups` (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки `w:cols/@w:num` и колонки таблиц; побочный эффект — авто-ширины колонок без `tblGrid`/`tcW` стали уже (слово может перенестись в ячейке).
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- **nginx `client_max_body_size 100m`** (`gateway/nginx.conf`, шлюз; столько же в прод-`nginx.conf` и Spring multipart) — потолок загрузки стека: без директивы upload режется HTML-413 от шлюза до бэкенда вместо JSON-ошибки API. Авторитетный лимит — свойство `wordpdf.max-bytes` (env `WORDPDF_MAX_BYTES`, дефолт 20 MiB), значения выше 100 МБ держит шлюз/multipart.
### Шрифты (30 TTF в `wordpdf-core/src/main/resources/fonts/`, SIL OFL)
Алиасы MS→open-source (`BundledFontMapper`): Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). Noto Naskh Arabic / Noto Sans Armenian (только regular, ради глифов U+07B1–08FF и U+058D/E) в `BundledFontMapper` не регистрируются — `FontFallback.selectCovering` перебирает весь реестр `PhysicalFonts` сам. У них только regular-начертание: `BundledFonts.families()` это учитывает, `BundledFontsTest.allFamiliesHaveAllVariants` их не проверяет. Символы U+2000–U+2EFF: `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если глиф есть, иначе виртуальный «Segoe UI Symbol» → fallback (как в Word; регрессия `ruPlain_emDashEmbeddedNotHelvetica`).
### Валидация входа (`WordPdfValidator`)
Константы `MAX_INPUT_BYTES = 20 MiB`, `MAX_PAGES = 1000` лежат в `WordPdfSettings` — едином файле-дефолтах ядра. Оба лимита переопределяются на вызов `ConvertOptions` (у `WordPdfValidator` перегрузки `checkInput(byte[], long)`, `checkPageCount(byte[]|pkg, int)`, `checkPageCountLightweight(byte[], int)`); REST API параметрами запроса их **не** пробрасывает — значения берутся из конфигурации сервера (свойства `wordpdf.max-bytes`/`wordpdf.max-pages`, env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`). В ядре рантайм-конфигурации нет. Вход валидатора и конвертера — только `byte[]`/`WordprocessingMLPackage`, файловых перегрузок в ядре нет (`.docx` по имени проверяет `ConvertController` — с байтов расширение не видно). Страницы = **максимум трёх нижних оценок**: (1) кэш `docProps/app.xml <Pages>` — недостоверен (реальный кейс: `<Pages>1</Pages>` при 110 маркерах); (2) явные разрывы `w:br type="page"` / `pageBreakBefore` / межсекционные `sectPr` (кроме `continuous`); (3) `w:lastRenderedPageBreak` + 1. Lightweight-путь (zip/StAX, без docx4j) согласован с JAXB: `sectPr` в body — «все минус 1»; `sectPr` в `pPr` не считается; колонтитулы — по содержимому zip. Расхождение допустимо только в завышение. `convert(byte[], String)` (и перегрузка с `ConvertOptions`) возвращает байты и файлового вывода не имеет — отказ структурно не оставляет артефакта (регрессия `staleCachePageCountRejectedBeforeRender`; Lightweight-путь на мусоре без zip-подписи молчит — оценку «1», подпись проверяет приложение).
### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`) ### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
Свой Java2D-рендер DrawingML. Калибровка surface3D зафиксирована тестами, эталон — стр. 3 `develop/word-export.pdf` (ручной экспорт Word, `pdftoppm -r 300`): `CAMERA_DISTANCE = 2.36` (`perspective` — НЕ угол FOV; fov≈49°), `DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`, поля `0.1485/0.116/0.146` от области построения, `rotY` берётся как `-Math.toRadians(...)` (знак обратный правому правилу), Lambert `0.92 + 0.88·dot` кламп `[0.80; 1.25]`, свет `(0.83, 0.48, 0.28)`. Цели: силуэт 314,9×65,3 pt центр (227,3; 82,3), уклон передней кромки 0.1282, аспект 0.207, шаги осей 0.0504/0.1176. Триангуляция ячейки — диагональ с большей суммой значений (седло; фиксированная диагональ даёт невидимую щепку); клиппинг полос — по треугольникам. `w01 = z[r+1][c]`, `w10 = z[r][c+1]` — перестановка закручивает квад в бабочку. `ChartRenderer.axisBounds` без явного `c:min` поднимает нижнюю границу до 0. Пустой `c:title` + `autoTitleDeleted val="0"` → автозаголовок `Chart Title` (для pie/pie3D/doughnut — имя ряда). Границы калибровки менять только вместе с тестами `Surface3dPainterTest`/`PiePainterTest`. Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`). `ChartSpec.parse` (`enum Type`: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой `c:title` + `autoTitleDeleted="0"` → автозаголовок `Chart Title`) → `ChartRenderer` (осевые «круглые» шаги 1/2/5·10ⁿ как Word) → пейнтеры `CartesianPainter`/`PiePainter`/`Surface3dPainter` (калибровка по стр. 3 `develop/word-export.pdf`: `CAMERA_DISTANCE=2.36`, `DEPTH_RATIO=0.705`, `HEIGHT_RATIO=0.664`, свет `(0.83,0.48,0.28)`); `SmartArtRenderer` рисует кэш разложенной схемы `word/diagrams/drawing1.xml`; палитра темы — `DrawMlColor`. Калибровочные константы менять только вместе с `Surface3dPainterTest`/`PiePainterTest`. Обход `pkg.getParts()` — только по **снимку** списка (`createImagePart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, не `getOwningRelationshipPart()`; обход XML обязан раскрывать `JAXBElement`; при падении рендера — `gd.getAny().clear()` + warn (деградация, не падение).
В `DrawingPreRenderer` rels части берутся через `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()` — у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр (живой обход → `ConcurrentModificationException`). ### Критические инварианты (нарушение = битый вывод)
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback.
- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`); `Fop.Renderers.getRenderer()` возвращает **список**. `docx2fo.xslt` в репозитория нет — он в jar `docx4j-export-fo`.
- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; lightweight-путь (StAX по zip, без docx4j) на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение.
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- Внимательно: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
### Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`)
Алиасы MS→open-source в `BundledFontMapper.ALIASES`: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans; виртуальный «Segoe UI Symbol» для U+2000–U+2EFF → fallback. Noto Naskh Arabic / Noto Sans Armenian — только regular, в маппер не регистрируются (покрытие подбирает `PhysicalFonts`-реестр). Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`).
## Key Directories ## Key Directories
| Путь | Назначение | |Путь|Назначение|
|---|---| |---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException`, `WordPdfSettings` (константы-дефолты), `ConvertOptions` (рисование на вызов) | |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException`, `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)|
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы MS→open-source) | |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы MS→open-source)|
| `…/wordpdf/internal/` | 4 байтовых нормализатора + `FopFallbackFonts` | |`…/wordpdf/internal/`|4 байтовых нормализатора + `FopFallbackFonts`|
| `…/wordpdf/internal/chart/` | Java2D-рендер диаграмм/SmartArt в PNG | |`…/wordpdf/internal/chart/`|Java2D-рендер диаграмм/SmartArt в PNG|
| `wordpdf-core/src/main/resources/fonts/` | 30 TTF + лицензии — бинарные фикстуры, часть jar | |`wordpdf-core/src/main/resources/fonts/`|30 TTF + лицензии — бинарные фикстуры, часть jar|
| `wordpdf-core/src/test/resources/samples/` | 11 закоммиченных `.docx`-фикстур (единственные фикстуры) | |`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)|
| `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API: `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler` | |`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API: `WordPdfApplication`, `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`|
| `wordpdf-web/src/` | SPA (React+TS+Vite+Tailwind): компоненты в `components/`, вся сеть в `api.ts` | |`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): компоненты в `components/`, вся сеть в `api.ts`|
| корневые `Dockerfile`, `docker-compose.yml`, `gateway/nginx.conf` | образ бэкенда (multi-stage, temurin-21); compose app+web+gateway; прод-запуск — из `PROD-DIR`, не отсюда | |корневые `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage, temurin-21); compose app+web+gateway|
| корневой `docker-compose.dev.yml` | dev-стенд без ключа: проект `wordpdf-dev`, вход http://127.0.0.1:9011, springdoc включён | |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — в `PROD-DIR/`|
| корневой `.env.example` | шаблон env деплоя: ключ (`WORDPDF_API_KEY`) и лимиты входа (`WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`); реальный прод `.env` живёт в `PROD-DIR/`, в репо его нет | |`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать|
| `wordpdf-web/Dockerfile`, `wordpdf-web/nginx.conf` | образ SPA (node→nginx); только статика (прокси — в шлюзе); base сборки — `ARG VITE_BASE` (prod `/pdf-converter/`, дефолт `/`) |
| `develop/` (вне git) | рабочие материалы и эталон Word 365 (`word.docx` + `word.pdf`), артефакты ручной калибровки — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
## Development Commands ## Development Commands
```bash ```bash
mvn clean verify # все модули + тесты — обязательный гейт перед push mvn clean verify # все модули + тесты — обязательный гейт перед push
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, POST /api/v1/convert java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
npm run dev # (wordpdf-web/) SPA :5173, proxy /api → :8080 curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: вход 127.0.0.1:9011, без ключа mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
cd PROD-DIR && docker compose up -d --build # прод: PROD-HOST:9010 (только LAN) mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core)
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест npm run dev # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080
npm run build # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint)
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: http://127.0.0.1:9011, без ключа, springdoc вкл
``` ```
Compose: `gateway` (nginx) — единственный вход: `/api`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app` (`/actuator` открыт фильтром), остальное → `web` (DNS-имена в сети compose). Два режима запуска. **Прод** — каталог `PROD-DIR` (вне репо; проект `wordpdf-prod`, build-context'ы указывают в репозиторий, образы `*:prod`): `gateway` опубликован только на `PROD-HOST:9010` (LAN), ключ — `.env` этого каталога (fail-closed `${WORDPDF_API_KEY:?…}`), springdoc выключен env'ами, SPA собрана с `VITE_BASE=/pdf-converter/`; свой `nginx.conf` (= репозиторный + `proxy_read_timeout 300s`, иначе длинные конвертации рвутся 504). Наружный вход — `https://pjandro.ru/pdf-converter/`: nginx на PROD-HOST (`/etc/nginx/conf.d/localhost.conf`) проксирует IP-литералом `PROD-HOST:9010` и срезает префикс завершающим слэшем `proxy_pass`; при недоступном стеке `error_page` отдаёт 503 (HTML/`{"error": …}`), nginx не падает; мониторинг без ключа — `/pdf-converter/health`. **Dev-стенд** — из репо `docker compose -f docker-compose.dev.yml up -d --build` (проект `wordpdf-dev`, вход http://127.0.0.1:9011, пустой ключ — фильтр прозрачен, springdoc включён). Отзыв ключа = правка прод `.env` + `docker compose up -d` в прод-каталоге. После пересоздания контейнеров `app`/`web` старому `gateway` нужен `restart` (nginx кэширует DNS бэкендов при старте — иначе 502). **Запуск по просьбе пользователя = прод-стек** (каталог прода, `up -d --build`); dev-стенд, `java -jar` / `npm run dev` — внутренняя отладка, запуском приложения не считать. **Обновление прода («эту версию в прод») = та же `docker compose up -d --build` в прод-каталоге**: прод пересобирается из **текущего рабочего дерева репозитория** (`build.context` — каталог, не git-ref: незакоммиченные правки поедут в прод), прод-`.env` с ключом и наружный шлюз 88.88 при этом не меняются; гейт успешности — `docker compose ps` (3× healthy) и `curl -s http://PROD-HOST:9010/actuator/health` → UP. `wordpdf.convert-timeout` переопределяется env `WORDPDF_CONVERT_TIMEOUT` (relaxed binding Boot). Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать):
Перезапуск прода — скрипт `./restart.sh` в прод-каталоге: без флага `restart app web` → гейт healthy `app` (до 120 с) → `restart gateway`; с `--build` — `up -d --build` (пересборка из рабочего дерева). Gateway всегда рестартует последним (nginx кэширует DNS бэкендов). Файл живёт только в прод-каталоге, в репозитории его нет.
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
```bash ```bash
mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
@@ -95,37 +79,46 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
``` ```
Деплой. **Прод** — каталог `PROD-DIR` (вне репо; проект `wordpdf-prod`, образы `*:prod`, build-context'ы указывают в репозиторий → пересборка берёт **рабочее дерево**, незакоммиченные правки поедут в прод): gateway только на `PROD-HOST:9010` (LAN), ключ — `.env` прод-каталога (fail-closed `${WORDPDF_API_KEY:?…}`), springdoc выключен env'ами, SPA собрана с `VITE_BASE=/pdf-converter/`, свой `nginx.conf` = репозиторный + `proxy_read_timeout 300s` (дефолтные 60 с рвут длинные конвертации). Наружный вход `https://pjandro.ru/pdf-converter/` (внешний nginx PROD-HOST). **Dev-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, :9011, пустой ключ). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `VITE_BASE` не передаётся). Перезапуск прода — `./restart.sh` в прод-каталоге: без флага `restart app web` → гейт healthy `app` (до 120 с) → `restart gateway`; `--build` — `up -d --build`. Gateway всегда последним (nginx кэширует DNS бэкендов — иначе 502). Гейт успешности: `docker compose ps` (3× healthy) + `curl http://PROD-HOST:9010/actuator/health` → UP. Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка.
## Code Conventions & Common Patterns ## Code Conventions & Common Patterns
- Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-классы `BundledFontMapper` (наследник `BestMatchingMapper`), `DrawMlColor` (палитра темы) и Spring-компоненты `wordpdf-app`. - Классы `final`, приватный конструктор, только `static` (stateless, DI нет; конфигурация — `Docx4jProperties` + classpath-ресурсы). Исключения — экземпляры по природе: docx4j-наследники `BundledFontMapper`, `DrawMlColor` и Spring-компоненты `wordpdf-app`.
- Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов. - Нормализаторы — единая сигнатура `public static byte[] normalize(byte[] docx) throws IOException` с флагом `changed`: нечего менять → вернуть **тот же массив** (`assertSame` в тестах); package-private хук `static String rewrite(String xml)` для юнит-тестов.
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние `IOException`/`IllegalStateException` оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог. - Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же. - Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
- Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`. - Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
- Внутренние API package-private; наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`. - Внутренние API package-private (наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`); в `wordpdf-app` всё package-private.
- В `wordpdf-app` всё package-private (контроллер, advice, service, исключения); в SPA вся сетевая логика только в `src/api.ts` — компоненты `fetch` не вызывают. - Тестовые методы: `объект_условие` через underscore — `ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`.
## Important Files ## Important Files
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён из зависимости ядра. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет.
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; форки FOP/jeuclid приходят транзитивно с `docx4j-export-fo`, пинить не надо. - `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`; `wordpdf.max-bytes`/`max-pages` здесь намеренно нет.
- `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core.
- `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; surefire с `-Djava.awt.headless=true`.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. - `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур (команда в javadoc). - `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API).
- `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур.
## Runtime & Tooling Preferences ## Runtime & Tooling Preferences
- Java 21 + Maven (обязательны; wrapper `mvnw` нет). UTF-8. Фронт: Node.js ≥ 20.19 (Vite 7+), вне Maven-депа. - Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant.
- Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой `dependencyManagement`. - Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable.
- CI, линтеров, форматтеров, checkstyle — нет; проверка одна: `mvn clean verify`. - Фронт: Node ≥ 20.19 (фактически vite `^8.3.0`, React `^19.2`, TS `~6.0`, Tailwind `^4.3`, oxlint; docker-сборка на `node:24-alpine`), npm с закоммиченным `package-lock.json` (`npm ci`).
- CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят). - Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят).
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, рабочие ветки `main`/`dev` защищены (правила глобального AGENTS.md).
## Testing & QA ## Testing & QA
- JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ, несмотря на test-классpath Boot), package-private тесты в mirror-пакетах. - JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ `@BeforeAll` где нужен warm-up шрифтов).
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%. - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах).
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word.
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → `byte[]` (`WordPdfConverterTest.sampleBytes`), PDF для PDFBox — временный файл (`convertPdf`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`). - Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`.
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`. - Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив (`assertSame`)» и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`).
- Тесты `wordpdf-app` (`ConvertControllerTest`, MockMvc) берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-app` без `-am` не соберётся. Гейт SPA — `npm run build` (tsc -b); UI-тестов нет. - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`).
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`. - Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой + javadoc-ссылка): `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_*`); `noLoggingWarningInPdf` — регрессия `slf4j-simple` (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`).
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint).