From f5e6838cbeed0cb584595b0a016d04edbec23d83 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Wed, 14 Oct 2026 22:17:04 +0000 Subject: [PATCH] =?UTF-8?q?Docs:=20AGENTS.md=20=D0=BF=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D0=B3=D0=B5=D0=BD=D0=B5=D1=80=D0=B8=D1=80=D0=BE=D0=B2=D0=B0?= =?UTF-8?q?=D0=BD=20=D0=B0=D1=83=D0=B4=D0=B8=D1=82=D0=BE=D0=BC=20=D0=BA?= =?UTF-8?q?=D0=BE=D0=B4=D0=B0=20=E2=80=94=20=D0=B8=D1=81=D0=BF=D1=80=D0=B0?= =?UTF-8?q?=D0=B2=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=BE=D0=BF=D1=80=D0=BE=D0=B2?= =?UTF-8?q?=D0=B5=D1=80=D0=B3=D0=BD=D1=83=D1=82=D1=8B=D0=B5=20=D1=83=D1=82?= =?UTF-8?q?=D0=B2=D0=B5=D1=80=D0=B6=D0=B4=D0=B5=D0=BD=D0=B8=D1=8F=20(self-?= =?UTF-8?q?map=20Noto,=20Calibri=20Light,=20public=20WordPdfApplication,?= =?UTF-8?q?=20=D0=B0=D0=B2=D1=82=D0=BE=D0=B7=D0=B0=D0=B3=D0=BE=D0=BB=D0=BE?= =?UTF-8?q?=D0=B2=D0=BE=D0=BA=20=D0=BA=D1=80=D1=83=D0=B3=D0=BE=D0=B2=D1=8B?= =?UTF-8?q?=D1=85,=20=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D1=83=D0=BF=D0=B0=D0=B2=D1=88=D0=B5=D0=B3=D0=BE=20=D1=80=D0=B5?= =?UTF-8?q?=D0=BD=D0=B4=D0=B5=D1=80=D0=B0),=20=D0=B4=D0=BE=D0=B1=D0=B0?= =?UTF-8?q?=D0=B2=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=BD=D0=B5=D1=83=D1=87=D1=82?= =?UTF-8?q?=D1=91=D0=BD=D0=BD=D1=8B=D0=B5=20=D0=B4=D0=B5=D1=82=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=20(=D0=BA=D0=BE=D0=BD=D1=81=D1=82=D0=B0=D0=BD=D1=82?= =?UTF-8?q?=D1=8B=20=D0=BF=D0=B5=D0=B9=D0=BD=D1=82=D0=B5=D1=80=D0=BE=D0=B2?= =?UTF-8?q?,=20=D0=BC=D0=B0=D0=BF=D0=BF=D0=B8=D0=BD=D0=B3=20400=20=D0=B4?= =?UTF-8?q?=D0=BB=D1=8F=20MissingServletRequest*,=20plugin-=D0=B2=D0=B5?= =?UTF-8?q?=D1=80=D1=81=D0=B8=D0=B8,=20README=20=D1=83=D1=81=D1=82=D0=B0?= =?UTF-8?q?=D1=80=D0=B5=D0=BB=20=D1=88=D0=B8=D1=80=D0=B5=20Docker-=D1=81?= =?UTF-8?q?=D0=B5=D0=BA=D1=86=D0=B8=D0=B8,=20proxy=5Fread=5Ftimeout=20?= =?UTF-8?q?=D1=82=D0=BE=D0=BB=D1=8C=D0=BA=D0=BE=20=D0=B2=20=D0=BF=D1=80?= =?UTF-8?q?=D0=BE=D0=B4=D0=B5,=20=D0=B0=D1=80=D1=85=D0=B8=D0=B2=20=D1=81?= =?UTF-8?q?=D1=82=D0=B5=D0=BA=D0=B0=2088.14,=20vite.local.config.ts,=20?= =?UTF-8?q?=D1=87=D0=B8=D1=81=D0=BB=D0=B0=20=D1=82=D0=B5=D1=81=D1=82=D0=BE?= =?UTF-8?q?=D0=B2=2013/109)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 87 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 45 insertions(+), 42 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6cab704..3de00fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,60 +2,62 @@ ## Project Overview -Конвертер `.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 устарела — авторитет этот файл. +Конвертер `.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 нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут — авторитет этот файл. ## Architecture & Data Flow -### Пайплайн `WordPdfConverter.convertToStream` (порядок фиксирован, менять местами нельзя) +### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` (порядок фиксирован, менять местами нельзя) -1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя шрифта, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()`. -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 рисует «#»). -3. `WordprocessingMLPackage.load` → `WordPdfValidator.checkPageCount(pkg, maxPages)` — **до** рендера. -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). +Наружу `checkInput(bytes, maxBytes)` вызывается **до** приватного `convertToStream`; внутри `convertToStream`: + +1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). +2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»; покрытие — `java.awt.Font.canDisplay` + BitSet-кэш, НЕ docx4j `GlyphCheck` — тот плодит INFO-лог) → `WordprocessingMLPackage.load`. +3. `WordPdfValidator.checkPageCount(pkg, maxPages)` — **до** рендера. +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; упавший рендер — объект **удаляется** из docx (`gd.getAny().clear()`) + warn, деградация не падение). 5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`. 6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет). -### REST API (`wordpdf-app`, все классы package-private) +### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`) -- Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. -- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. -- Ошибки (`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` (порядок значим). -- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). `/actuator/**` открыт (HEALTHCHECK). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404. -- Лимиты входа задаёт **только конфигурация сервера**: `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/`). +- Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). +- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. +- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). Четыре app-исключения (`ValidationException`, `ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 400/500/503/504. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCountLightweight` (порядок значим). +- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). `/actuator/**` открыт (HEALTHCHECK). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404. +- Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (20 MiB / 1000); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. +- SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). ### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`) -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 (деградация, не падение). +Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр × `DPI/72`, размеры — в пунктах, EMU→pt `cx/12700.0`). `ChartSpec.parse` (`enum Type`: PIE/PIE3D/DOUGHNUT/BAR/BAR_HORIZONTAL/LINE/AREA/SURFACE3D/UNSUPPORTED; пустой `c:title` + `autoTitleDeleted="0"` → у **круговых** имя первого ряда, у прочих — `AUTO_TITLE = "Chart Title"`; палитра `accent1..6` темы, легенда по умолчанию снизу) → `ChartRenderer` (осевые «круглые» шаги `niceUnit` 1/2/5·10ⁿ как Word; маркеры легенды 0.32/0.55 кегля, отрезок 2.4 кегля) → пейнтеры `CartesianPainter`/`PiePainter` (`DEPTH_RATIO=0.22`, `TILT_CORRECTION=0.95`, `FIT_MARGIN=0.865`)/`Surface3dPainter` (калибровка по стр. 3 `develop/word-export.pdf`: `CAMERA_DISTANCE=2.36`, `DEPTH_RATIO=0.705`, `HEIGHT_RATIO=0.664`, `GUTTER_LEFT/RIGHT=0.1485`, `GUTTER_TOP=0.116`, `GUTTER_BOTTOM=0.146`, свет `LIGHT_X/Y/Z=0.83/0.48/0.28`); `SmartArtRenderer` рисует кэш разложенной схемы `word/diagrams/drawing1.xml`; палитра темы — `DrawMlColor` (instance); текст — `DrawMlText`; утилиты `RgbHsl`, `PrstGeomShapes`. Калибровочные константы менять только вместе с `Surface3dPainterTest`/`PiePainterTest`. Обход `pkg.getParts()` — только по **снимку** списка (`createImagePart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, НЕ `getOwningRelationshipPart()` (это rels ссылющегося); обход XML обязан раскрывать `JAXBElement`. ### Критические инварианты (нарушение = битый вывод) - `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 допустимо только в завышение. +- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`); `Fop.Renderers.getRenderer()` возвращает **список** (рендер выбирается по mime `application/pdf`). `docx2fo.xslt` в репозитории нет — он в jar `docx4j-export-fo`. +- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `sectPr` в body + `w:br type="page"` + `pageBreakBefore` (рекурсивно, включая таблицы и `w:sdt`). Lightweight-путь (StAX по zip, secure-ридер без DTD/external entities): `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитулах — только `w:br type="page"`; на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение. `pageCountOf` package-private намеренно (тесты). - Известный остаток эталона: 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`). +7 семейств × 4 начертания (Carlito/Caladea/Arimo/Tinos/Cousine/DejaVu Sans/DejaVu Serif) + Noto Naskh Arabic / Noto Sans Armenian (только regular). Алиасы в `BundledFontMapper.ALIASES` (ключи lowercase): MS→аналоги — Calibri→Carlito, **Calibri Light→Carlito**, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; **self-map** всех бандл-семейств, включая Noto (иначе unmatched уходит в DejaVu-фолбэк); fallback — DejaVu Sans; виртуальный `SYMBOL_FONT` «Segoe UI Symbol» (U+2000–U+2EFF) → fallback до основного цикла. `DISPLAY_NAMES` — обратное маппинг lowercase→отображаемое имя для `documentFontName` (пишет `GlyphCoverageNormalizer` в `w:rFonts`). `BundledFonts.awtFont` возвращает `Font` размера 1 — всегда `deriveFont(size)`. Новый шрифт = файл + запись в `BundledFonts.ENTRIES` (синхрон проверяет `BundledFontsTest`). ## Key Directories |Путь|Назначение| |---|---| |`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, self-map, DISPLAY_NAMES)| |`…/wordpdf/internal/`|4 байтовых нормализатора + `FopFallbackFonts`| -|`…/wordpdf/internal/chart/`|Java2D-рендер диаграмм/SmartArt в PNG| -|`wordpdf-core/src/main/resources/fonts/`|30 TTF + лицензии — бинарные фикстуры, часть jar| +|`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| +|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)| -|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API: `WordPdfApplication`, `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`| -|`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): компоненты в `components/`, вся сеть в `api.ts`| -|корневые `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage, temurin-21); compose app+web+gateway| +|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (9 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter` + 4 класса исключений| +|`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)| +|корневые `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, HEALTHCHECK actuator); compose app+web+gateway| |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)| -|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| +|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| ## Development Commands @@ -79,46 +81,47 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples ``` -Деплой. **Прод** — на пользовательском LAN-сервере; координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Наружный вход `https://pjandro.ru/pdf-converter/`. **Dev-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, :9011, пустой ключ). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `VITE_BASE` не передаётся). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. +Деплой. **Прод** — на пользовательском LAN-сервере; координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит `proxy_read_timeout 300s` — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). **Dev-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, `127.0.0.1:9011:80`, без env → ключ пуст, springdoc вкл). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` не передаётся). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. ## Code Conventions & Common Patterns - Классы `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)` для юнит-тестов (возвращает `null` при отсутствии изменений); правятся только части `word/*.xml`. - Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. -- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же. +- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться). - Константы UPPER_SNAKE с числовыми эталонными значениями (`CAMERA_DISTANCE`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`. -- Внутренние API package-private (наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`); в `wordpdf-app` всё package-private. -- Тестовые методы: `объект_условие` через underscore — `ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`. +- Внутренние API package-private (наружу из `internal` торчат только `normalize`/`declare`/`DrawingPreRenderer.run`); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. +- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`). ## Important Files - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. -- `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-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=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-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен Docker HEALTHCHECK `/actuator/health`); тест-зависимости: `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`. +- Корневой `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`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`. - `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. -- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). +- `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-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует. - `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур. +- `wordpdf-web/vite.local.config.ts` — легаси-одноразовщик (прокси `/api` → :8091), коммит против воли автора (`*.local` в gitignore не накрывает `.ts`-суффикс), в `tsconfig.node.json` не включён; кандидат на удаление, не тиражировать паттерн. ## Runtime & Tooling Preferences - Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant. - Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable. -- Фронт: 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`). +- Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/oxlint из lockfile), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3.0`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; docker-сборка web на `node:24-alpine`. - CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`. -- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят). -- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, рабочие ветки `main`/`dev` защищены (правила глобального AGENTS.md). +- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar). +- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; ветки `dev` в репо пока нет — только `main`). ## Testing & QA -- 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 шрифтов). +- 13 тестовых классов / 109 `@Test` (core 10/89, app 3/20). 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 шрифтов в `GlyphCoverageNormalizerTest`). - **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 таблицах). -- Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word. -- Фикстуры — закоммиченные `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`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив (`assertSame`)» и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). +- Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585 допуск 0.06; `Surface3dPainterTest` `assertRange` в pt, shading допуск 0.10). +- Фикстуры — закоммиченные `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[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). +- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив (`assertSame`)» и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `pageCountOf`, `ChartSpec.readTitle`). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/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). +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCountLightweight_agreesWithJaxbPath` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`. +- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error). -- 2.56.1