Files
java-word-pdf/AGENTS.md
T
2026-10-14 20:49:51 +00:00

125 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Repository Guidelines
## 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 устарела — авторитет этот файл.
## Architecture & Data Flow
### Пайплайн `WordPdfConverter.convertToStream` (порядок фиксирован, менять местами нельзя)
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).
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)
- Единственный эндпоинт `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/`).
### 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 (деградация, не падение).
### Критические инварианты (нарушение = битый вывод)
- `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
|Путь|Назначение|
|---|---|
|`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/internal/`|4 байтовых нормализатора + `FopFallbackFonts`|
|`…/wordpdf/internal/chart/`|Java2D-рендер диаграмм/SmartArt в PNG|
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + лицензии — бинарные фикстуры, часть 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|
|корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — в `PROD-DIR/`|
|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать|
## Development Commands
```bash
mvn clean verify # все модули + тесты — обязательный гейт перед push
mvn -pl wordpdf-app -am package # исполняемый jar бэкенда
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core)
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 вкл
```
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать):
```bash
mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
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
- Классы `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)` для юнит-тестов.
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же.
- Константы 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`.
## 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-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.
- `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
- 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`).
- CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`.
- Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят).
- Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, рабочие ветки `main`/`dev` защищены (правила глобального AGENTS.md).
## 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 шрифтов).
- **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`).
- 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).