docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,64 @@
|
||||
# Как контрибьютить
|
||||
|
||||
## Ветка и PR
|
||||
|
||||
Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`,
|
||||
`master`, `dev`: прямо в них не коммитим.
|
||||
|
||||
1. Ветка от свежей `main` (`git switch -c <name>`).
|
||||
2. Коммиты логическими блоками.
|
||||
3. Перед push — полный гейт: `./mise.sh run verify`.
|
||||
4. `git push -u origin <name>` → pull request в дефолтную ветку.
|
||||
5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig +
|
||||
сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required.
|
||||
`macos-sim` — не required.
|
||||
|
||||
## Конвенции кода
|
||||
|
||||
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет);
|
||||
в `internal/**` — package-private, `public` только вызываемым извне пакета.
|
||||
- Ошибки публичного API — только `ConversionException` (и подтипы); в chart —
|
||||
деградация вместо падения.
|
||||
- Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24,
|
||||
[MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
|
||||
`Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке
|
||||
грепом восстанавливаются пары тестов).
|
||||
- Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа.
|
||||
- PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены.
|
||||
- Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J —
|
||||
`internal/chart` и `wordpdf-app`; остальное молчит.
|
||||
|
||||
## Регрессивная конвенция (фикс бага)
|
||||
|
||||
Каждый фикс расхождения с Word оформляется полным набором:
|
||||
|
||||
```
|
||||
нормализатор/рендерер → юнит на правило → тест во всём конвейере
|
||||
→ javadoc-ссылка «Регрессия — Тест#имя, фикстура …»
|
||||
```
|
||||
|
||||
Фикстуры для новых тестов не генерируются на лету и не перезаписываются:
|
||||
`charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются
|
||||
никогда**; все 12 `.doc` — эталоны заказчика.
|
||||
|
||||
## Критические инварианты (нарушение = битый вывод)
|
||||
|
||||
Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`,
|
||||
[repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)):
|
||||
|
||||
- static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение
|
||||
сканов PhysicalFonts) — не удалять;
|
||||
- `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы;
|
||||
- порядок нормализаторов правил 1–11 фиксирован;
|
||||
- вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт
|
||||
`vendoredXsltTracksJarCopy`;
|
||||
- `slf4j-simple` обязателен в ядре;
|
||||
- префикс `/word/media/chart-*` — контракт с `ChartImageHandler`;
|
||||
- финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу.
|
||||
|
||||
## Документация сайта
|
||||
|
||||
Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят
|
||||
в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе
|
||||
strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация —
|
||||
[`docs-deploy`](../operations/docs-site.md).
|
||||
@@ -0,0 +1,83 @@
|
||||
# Окружение разработчика
|
||||
|
||||
Требуется **Java 17**, **Maven 3.9.16**, **Node 24** (engines Vite: `^20.19.0 ||
|
||||
>=22.12.0`), **Python 3.15** (прод-автотесты, сайт документации). Всё это ставит
|
||||
project-local mise: сам бинарь — в `./.mise/bin` (gitignored), кеш инструментов —
|
||||
в user-директории mise, **в систему ничего не устанавливается**. Версии пиныны
|
||||
в `mise.toml`.
|
||||
|
||||
## Бутстрап (первая настройка)
|
||||
|
||||
```bash
|
||||
sh bootstrap.sh # Linux / macOS: качает mise, ставит инструменты, npm ci SPA
|
||||
```
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 # Windows
|
||||
```
|
||||
|
||||
Дальше команды — через обёртку `./mise.sh` (Windows: `.\mise.ps1`):
|
||||
|
||||
```bash
|
||||
./mise.sh run verify # полный гейт перед push
|
||||
./mise.sh exec -- mvn -v # любая команда с инструментами в PATH
|
||||
./mise.sh tasks # список задач
|
||||
```
|
||||
|
||||
Альтернатива — активировать mise в шелле и работать напрямую (`mvn`, `npm`, `python`):
|
||||
`eval "$(./.mise/bin/mise activate bash)"`.
|
||||
|
||||
## Задачи mise
|
||||
|
||||
|Задача|Содержание|
|
||||
|---|---|
|
||||
|`verify`|`mvn clean verify` — тесты + PMD + JaCoCo (гейт перед push)|
|
||||
|`verify-nofontconfig`|тот же verify в контейнере без fontconfig (как CI; требует podman/docker)|
|
||||
|`mem-bench`|замер памяти конвейера (TSV пиков + JFR)|
|
||||
|`app-package`|исполняемый jar бэкенда|
|
||||
|`app-run`|бэкенд на :8080, ключ выключен (после `app-package`)|
|
||||
|`web-install`|`npm ci` в `wordpdf-web`|
|
||||
|`web-build`|гейт SPA: `tsc -b && vite build`|
|
||||
|`web-lint`|oxlint|
|
||||
|`web-dev`|SPA на :5173, vite-proxy на :8080|
|
||||
|`prod-tests`|прод-автотесты; обязателен `WORDPDF_BASE_URL`, факультативно `WORDPDF_API_KEY`|
|
||||
|`docs-install`|venv `docs/.venv` + `mkdocs-material`|
|
||||
|`docs-serve`|локальный предпросмотр сайта на :8000 (live-reload)|
|
||||
|`docs-build`|strict-сборка сайта в `site/` (битые ссылки/навигация = ошибка)|
|
||||
|`docs-javadoc`|javadoc публичного API core в `wordpdf-core/target/site/apidocs`|
|
||||
|`docs-deploy`|публикация сайта на rpi (:9012): javadoc + strict-build + rsync|
|
||||
|
||||
## Прямые команды (без задач)
|
||||
|
||||
```bash
|
||||
mvn clean verify # все модули + тесты
|
||||
mvn test -Djacoco.skip=true # тесты без агента покрытия
|
||||
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached
|
||||
mvn -pl wordpdf-app -am test # -am обязателен: app берёт фикстуры из test-jar core
|
||||
mvn -pl wordpdf-app -am package # исполняемый jar → wordpdf-app/target/
|
||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен
|
||||
|
||||
npm ci && npm run build # в wordpdf-web/ (или задачи web-*)
|
||||
npm run dev # SPA :5173, проксирует /api на :8080
|
||||
```
|
||||
|
||||
## Стенды на контейнерах (podman)
|
||||
|
||||
```bash
|
||||
# dev (:9011), без ключа, springdoc включён
|
||||
podman-compose -f compose.dev.yml up -d --build --force-recreate
|
||||
|
||||
# prod-like (:9010), fail-closed: нужен .env с WORDPDF_API_KEY (шаблон .env.example)
|
||||
cp .env.example .env # ключ: openssl rand -hex 32
|
||||
podman-compose up -d --build
|
||||
```
|
||||
|
||||
`--force-recreate` для dev обязателен: без него podman-compose пересоберёт образ,
|
||||
но контейнеры оставит на старом jar. Наружу публикуется только nginx-gateway
|
||||
(9010/9011), 8080 наружу не выставляется. Подробности —
|
||||
[Стенды](../operations/stack.md).
|
||||
|
||||
!!! info "«Запусти тестовый сервер»"
|
||||
Так в проекте называют dev-стенд (`compose.dev.yml`, `http://<LAN-IP>:9011`),
|
||||
а не `java -jar`. Готовность — контейнеры healthy (`podman-compose -f
|
||||
compose.dev.yml ps`) + корень SPA отвечает 200.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Тесты
|
||||
|
||||
## Гейты
|
||||
|
||||
Полный гейт перед push — `./mise.sh run verify` (= `mvn clean verify`); на `verify`
|
||||
висят и валят сборку:
|
||||
|
||||
|Гейт|Порог|
|
||||
|---|---|
|
||||
|surefire (тесты)|все зелёные, `-Djava.awt.headless=true`|
|
||||
|PMD (`pmd-ruleset.xml`)|любой приоритет нарушения валит; `includeTests=true`; **подавления запрещены** — чинить кодом|
|
||||
|JaCoCo LINE|≥ 0.90 (оба модуля)|
|
||||
|JaCoCo BRANCH|≥ 0.85 (только `wordpdf-core`)|
|
||||
|
||||
Провал — HTML/XML-отчёт уже в `target/site/jacoco/`. CI-эквивалент без fontconfig —
|
||||
`./mise.sh run verify-nofontconfig`. `mvn test` PMD/JaCoCo-гейты не запускает.
|
||||
|
||||
## Стек и конвенции
|
||||
|
||||
- **JUnit 6** (`org.junit.jupiter`), **только `Assertions`** — Mockito/AssertJ
|
||||
запрещены, их нет в pom (в app-тестах допустим inline-Hamcrest
|
||||
`org.hamcrest.Matchers.containsString` в `andExpect`).
|
||||
- Только `@Test` (исключения: два `@BeforeAll` прогрева шрифтов, `@AfterEach
|
||||
drainWorker` в `ConversionTimeoutTest`); ни `@Nested`, ни `@ParameterizedTest`,
|
||||
ни `@Disabled`, ни `assertAll`.
|
||||
- Тестовые классы package-private, зеркалят main-пакеты.
|
||||
- Именование: регрессионные — `объект_условие` (`pageNumbers_recomputedNotCached`),
|
||||
юниты — camelCase (`pageFieldBecomesFldSimple`).
|
||||
- Сообщения ассертов — по-русски, с наблюдаемым значением; литерал слева.
|
||||
- Тестовых утилит нет — хелперы намеренно дублируются в классах.
|
||||
|
||||
## Фикстуры
|
||||
|
||||
Только закоммиченные `wordpdf-core/src/test/resources/samples/`: **13 `.docx` +
|
||||
12 `.doc`** (`.doc` — эталоны заказчика). В тестах фикстуры **не генерировать**;
|
||||
XSD-невалидную `.docx`-фикстуру правят, а не код
|
||||
(`python3 docs/standards/docx/validate-fixtures.py …`). Синтетика в памяти разрешена:
|
||||
docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`.
|
||||
|
||||
Ловушка загрузки: **core** грузит classloader-ресурсом без ведущего слэша
|
||||
(`getResourceAsStream("samples/…")`), **app** — class-relative со слэшем
|
||||
(`/samples/…`, ресурсы из test-jar core; отсюда обязательный `-am`).
|
||||
|
||||
## Как проверяется PDF
|
||||
|
||||
**Текстом, не растеризацией**: PDFBox 3 `PDFTextStripper` (нормализация пробелов);
|
||||
негативные маркеры — `#` (.notdef) и `Helvetica` (фолбэк-шрифт FOP); имя шрифта
|
||||
символа — приём `fontNameOf`; встроенные подмножества — обход ресурсов страниц
|
||||
(`EAAAAA+Carlito-Bold`). Пиксели (BufferedImage, отношения к эталонам Word 300 dpi
|
||||
с допусками) — только юниты chart-пейнтеров.
|
||||
|
||||
## App-тесты
|
||||
|
||||
4 набора свойств = 4 Spring-контекста: `ConvertControllerTest` (пин пустого
|
||||
`wordpdf.api-key=`), `ApiKeyFilterTest`, `ConvertLimitsTest`, `ConversionTimeoutTest`;
|
||||
`ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring. Проверяют HTTP-код,
|
||||
заголовки, текст ошибки. Ловушка: mise инжектирует корневой `.env` в окружение задач
|
||||
— ambient `WORDPDF_API_KEY` дал бы 401 во всех MockMvc-тестах, поэтому ключ пинится
|
||||
свойствами контекста.
|
||||
|
||||
## Прод-автотесты
|
||||
|
||||
`prod-autotests/` (pytest + requests): 31 проверка против **живого** стенда —
|
||||
4 открытые + 27 `needs_key` (SKIP без ключа). Конфигурация только env:
|
||||
`WORDPDF_BASE_URL` (обязателен), `WORDPDF_API_KEY`, `WORDPDF_MAX_MB`/`MAX_PAGES`,
|
||||
`WORDPDF_SAMPLES_DIR`. Таймауты `(10, 180)` — больше серверных 2m. Запуск:
|
||||
`WORDPDF_BASE_URL=… ./mise.sh run prod-tests` (в CI гоняются job'ом `autotests`
|
||||
после deploy).
|
||||
|
||||
Глубина (счётчики, пары «нормализатор ↔ тест», пиксельные допуски) —
|
||||
[testing.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md).
|
||||
Reference in New Issue
Block a user