Docs: AGENTS.md и README под байтовый API, ключ и два режима запуска
This commit is contained in:
@@ -15,9 +15,9 @@
|
|||||||
→ `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`)
|
→ `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`)
|
||||||
→ `GlyphCoverageNormalizer` (шаг 2.4: режет ран по покрытию глифов и пишет семейство в `w:rFonts`; трогает только раны с одним `w:t` и явным `w:rFonts`; покрытие — `java.awt.Font.canDisplay` через `BundledFonts.awtFont`, не `GlyphCheck` — тот логирует на каждый глиф).
|
→ `GlyphCoverageNormalizer` (шаг 2.4: режет ран по покрытию глифов и пишет семейство в `w:rFonts`; трогает только раны с одним `w:t` и явным `w:rFonts`; покрытие — `java.awt.Font.canDisplay` через `BundledFonts.awtFont`, не `GlyphCheck` — тот логирует на каждый глиф).
|
||||||
3. `WordprocessingMLPackage.load(байты)` → `WordPdfValidator.checkPageCount(pkg)` — **до** рендера.
|
3. `WordprocessingMLPackage.load(байты)` → `WordPdfValidator.checkPageCount(pkg)` — **до** рендера.
|
||||||
4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок `internal/chart/*` рендерит их в PNG 300 dpi и подменяет на `pic:pic`; после `setFontMapper`, до `FOSettings`)
|
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 встраивает только задекларированные)
|
→ `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует в FOP-конфиге **все** бандл-семейства — FOP встраивает только задекларированные)
|
||||||
→ `FORendererApacheFOP` / `FOUserAgent` (заголовок PDF = имя файла)
|
→ `FORendererApacheFOP` / `FOUserAgent` (заголовок PDF = параметр `title`, если непустой)
|
||||||
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
|
→ `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
|
||||||
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
|
5. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
|
||||||
|
|
||||||
@@ -25,7 +25,9 @@
|
|||||||
|
|
||||||
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (очередь 16, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера.
|
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (очередь 16, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` (шаг 1 пайплайна), параллельные конвертации вырывают его друг у друга из-под рендера.
|
||||||
- Разделение ошибок: валидация байтов до очереди (`WordPdfValidator.checkInput(byte[])` + проверка zip-подписи + `checkPageCountLightweight(byte[])`) → `ValidationException` → 400; ошибки ядра/рендера → `ConversionFailedException` → 500; очередь занята → 503; таймаут (`wordpdf.convert-timeout`, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500.
|
- Разделение ошибок: валидация байтов до очереди (`WordPdfValidator.checkInput(byte[])` + проверка zip-подписи + `checkPageCountLightweight(byte[])`) → `ValidationException` → 400; ошибки ядра/рендера → `ConversionFailedException` → 500; очередь занята → 503; таймаут (`wordpdf.convert-timeout`, 2m) → 504. Граница: сломанный контейнер → 400, валидный zip с мусором внутри → 500.
|
||||||
- Фронт ходит только на относительный `/api/...` — CORS не нужен (dev: vite-proxy → :8080; prod: nginx).
|
- Фронт ходит на `${import.meta.env.BASE_URL}api/...` (vite `base` из env `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`).
|
||||||
|
- Факультативные параметры `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`, тесты `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`.
|
||||||
|
|
||||||
### Критические инварианты (нарушение = битый вывод)
|
### Критические инварианты (нарушение = битый вывод)
|
||||||
|
|
||||||
@@ -35,7 +37,7 @@
|
|||||||
- 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`.
|
- 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` стали уже (слово может перенестись в ячейке).
|
- `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 — не добавляем намеренно).
|
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
|
||||||
- **nginx `client_max_body_size 6m`** (`wordpdf-web/nginx.conf`) обязателен: без него upload > 1 МБ режется HTML-413 от nginx до бэкенда вместо JSON-ошибки API.
|
- **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)
|
### Шрифты (30 TTF в `wordpdf-core/src/main/resources/fonts/`, SIL OFL)
|
||||||
|
|
||||||
@@ -43,7 +45,7 @@
|
|||||||
|
|
||||||
### Валидация входа (`WordPdfValidator`)
|
### Валидация входа (`WordPdfValidator`)
|
||||||
|
|
||||||
`MAX_INPUT_BYTES = 5 MiB`, `MAX_PAGES = 100`. Страницы = **максимум трёх нижних оценок**: (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(Path,Path)` **удаляет** уже открытый PDF (регрессия `staleCachePageCountRejectedBeforeRender` проверяет отсутствие артефакта).
|
Константы `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`)
|
||||||
|
|
||||||
@@ -55,7 +57,7 @@
|
|||||||
|
|
||||||
| Путь | Назначение |
|
| Путь | Назначение |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException` |
|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConversionException`, `WordPdfSettings` (константы-дефолты), `ConvertOptions` (рисование на вызов) |
|
||||||
| `…/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 |
|
||||||
@@ -63,8 +65,10 @@
|
|||||||
| `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: `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler` |
|
||||||
| `wordpdf-web/src/` | SPA (React+TS+Vite+Tailwind): компоненты в `components/`, вся сеть в `api.ts` |
|
| `wordpdf-web/src/` | SPA (React+TS+Vite+Tailwind): компоненты в `components/`, вся сеть в `api.ts` |
|
||||||
| корневые `Dockerfile`, `docker-compose.yml` | образ бэкенда (multi-stage, temurin-21); compose web+app |
|
| корневые `Dockerfile`, `docker-compose.yml`, `gateway/nginx.conf` | образ бэкенда (multi-stage, temurin-21); compose app+web+gateway; прод-запуск — из `PROD-DIR`, не отсюда |
|
||||||
| `wordpdf-web/Dockerfile`, `wordpdf-web/nginx.conf` | образ SPA (node→nginx); прокси `/api`, `/swagger-ui`, `/v3/api-docs` |
|
| корневой `docker-compose.dev.yml` | dev-стенд без ключа: проект `wordpdf-dev`, вход http://127.0.0.1:9011, springdoc включён |
|
||||||
|
| корневой `.env.example` | шаблон env деплоя: ключ (`WORDPDF_API_KEY`) и лимиты входа (`WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`); реальный прод `.env` живёт в `PROD-DIR/`, в репо его нет |
|
||||||
|
| `wordpdf-web/Dockerfile`, `wordpdf-web/nginx.conf` | образ SPA (node→nginx); только статика (прокси — в шлюзе); base сборки — `ARG VITE_BASE` (prod `/pdf-converter/`, дефолт `/`) |
|
||||||
| `references/` | эталон Word 365 (`word.docx` + `word.pdf`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
|
| `references/` | эталон Word 365 (`word.docx` + `word.pdf`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать |
|
||||||
| `diff/`, корневые `word-export.*` | gitignored артефакты ручной калибровки |
|
| `diff/`, корневые `word-export.*` | gitignored артефакты ручной калибровки |
|
||||||
|
|
||||||
@@ -75,11 +79,14 @@ mvn clean verify # все модули + тесты —
|
|||||||
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, POST /api/v1/convert
|
||||||
npm run dev # (wordpdf-web/) SPA :5173, proxy /api → :8080
|
npm run dev # (wordpdf-web/) SPA :5173, proxy /api → :8080
|
||||||
docker compose up -d --build # всё вместе: SPA+nginx публикует :8080, app не публикуется
|
docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: вход 127.0.0.1:9011, без ключа
|
||||||
|
cd PROD-DIR && docker compose up -d --build # прод: PROD-HOST:9010 (только LAN)
|
||||||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
|
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached # один тест
|
||||||
```
|
```
|
||||||
|
|
||||||
Compose: `web` проксирует `/api`, `/swagger-ui`, `/v3/api-docs` на `app` (DNS-имя в сети compose); бэкенд наружу не публикуется. `wordpdf.convert-timeout` переопределяется env `WORDPDF_CONVERT_TIMEOUT` (relaxed binding Boot).
|
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).
|
||||||
|
|
||||||
|
Перезапуск прода — скрипт `./restart.sh` в прод-каталоге: без флага `restart app web` → гейт healthy `app` (до 120 с) → `restart gateway`; с `--build` — `up -d --build` (пересборка из рабочего дерева). Gateway всегда рестартует последним (nginx кэширует DNS бэкендов). Файл живёт только в прод-каталоге, в репозитории его нет.
|
||||||
|
|
||||||
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
|
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — исключение):
|
||||||
|
|
||||||
@@ -119,7 +126,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
|
|||||||
- 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 c `-Djava.awt.headless=true`; только `Assertions` (без Mockito/AssertJ, несмотря на test-классpath Boot), package-private тесты в mirror-пакетах.
|
||||||
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
|
- **PDF сравнивается текстом, не растеризацией**: PDFBox `PDFTextStripper` для текста, override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страницы для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок. Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
|
||||||
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
|
- Текст нормализуется по пробелам (`tableImage_tableAndImage` — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
|
||||||
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → временный файл (`extractSample`/`extractToTemp`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`).
|
- Фикстуры — закоммиченные `samples/*.docx` (не генерировать в тестах); classpath → `byte[]` (`WordPdfConverterTest.sampleBytes`), PDF для PDFBox — временный файл (`convertPdf`). In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]` (`WordPdfValidatorTest`).
|
||||||
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`.
|
- Юниты нормализаторов работают строками (`rewrite`) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность `[Content_Types].xml`.
|
||||||
- Тесты `wordpdf-app` (`ConvertControllerTest`, MockMvc) берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-app` без `-am` не соберётся. Гейт SPA — `npm run build` (tsc -b); UI-тестов нет.
|
- Тесты `wordpdf-app` (`ConvertControllerTest`, MockMvc) берут фикстуры из test-jar core (classifier `tests`) → `-pl wordpdf-app` без `-am` не соберётся. Гейт SPA — `npm run build` (tsc -b); UI-тестов нет.
|
||||||
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`.
|
- Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: `DocxOnOffNormalizerTest`/`ruPlain_regularRunsUseRegularFont`, `FieldNormalizerTest`/`pageNumbers_recomputedNotCached`, `SymbolFontNormalizerTest`/`symbolFonts_bulletsAreNotHash`, `GlyphCoverageNormalizerTest`/`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`/`staleCachePageCountRejectedBeforeRender`, `BundledFontsTest`/`noLoggingWarningInPdf`, `Surface3dPainterTest`/`chartsSmartArt_drawingsBecomeImages`.
|
||||||
|
|||||||
@@ -27,7 +27,7 @@ java-word-pdf/
|
|||||||
|
|
||||||
| Класс | Назначение |
|
| Класс | Назначение |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(Path)` / `convert(Path, Path)` |
|
| `ru.pjandro.wordpdf.WordPdfConverter` | публичный API: `convert(byte[], String)` — байты на входе, байты PDF на выходе |
|
||||||
| `ru.pjandro.wordpdf.ConversionException` | исключение конвертации |
|
| `ru.pjandro.wordpdf.ConversionException` | исключение конвертации |
|
||||||
| `ru.pjandro.wordpdf.fonts.BundledFonts` | выгрузка TTF из jar и регистрация в docx4j |
|
| `ru.pjandro.wordpdf.fonts.BundledFonts` | выгрузка TTF из jar и регистрация в docx4j |
|
||||||
| `ru.pjandro.wordpdf.fonts.BundledFontMapper` | маппинг имён шрифтов документа → TTF |
|
| `ru.pjandro.wordpdf.fonts.BundledFontMapper` | маппинг имён шрифтов документа → TTF |
|
||||||
@@ -74,13 +74,17 @@ Swagger UI — `/swagger-ui.html`, OpenAPI — `/v3/api-docs`.
|
|||||||
|
|
||||||
```java
|
```java
|
||||||
import ru.pjandro.wordpdf.WordPdfConverter;
|
import ru.pjandro.wordpdf.WordPdfConverter;
|
||||||
|
import java.nio.file.Files;
|
||||||
import java.nio.file.Path;
|
import java.nio.file.Path;
|
||||||
|
|
||||||
Path pdf = WordPdfConverter.convert(Path.of("doc.docx")); // doc.pdf рядом
|
byte[] docx = Files.readAllBytes(Path.of("doc.docx"));
|
||||||
WordPdfConverter.convert(Path.of("doc.docx"), Path.of("out.pdf")); // явный выход
|
byte[] pdf = WordPdfConverter.convert(docx, "doc"); // заголовок PDF
|
||||||
|
Files.write(Path.of("out.pdf"), pdf);
|
||||||
```
|
```
|
||||||
|
|
||||||
Ошибки валидации (не `.docx`, файл не найден) бросают `ConversionException`.
|
Ошибки валидации (не `.docx` по содержимому, размер больше 5 МБ, страниц
|
||||||
|
больше ста) бросают `ConversionException`. Работа с файлами — забота
|
||||||
|
вызывающего: ядро пути не принимает.
|
||||||
|
|
||||||
### Веб-интерфейс и Docker
|
### Веб-интерфейс и Docker
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user