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,75 @@
|
||||
# API библиотеки
|
||||
|
||||
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
|
||||
Javadoc каждого члена — [apidocs](/apidocs/index.html).
|
||||
|
||||
## `WordPdfConverter`
|
||||
|
||||
```java
|
||||
public final class WordPdfConverter {
|
||||
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
|
||||
throws ConversionException;
|
||||
public static synchronized void warmup();
|
||||
}
|
||||
```
|
||||
|
||||
- `convert` — единственный путь конвертации (двухаргументной перегрузки **нет**).
|
||||
Принимает байты `.docx` или `.doc` (маршрутизация по сигнатуре), возвращает байты PDF.
|
||||
`title` — заголовок PDF. `options == null` → `ValidationException`.
|
||||
- `warmup()` — идемпотентный прогрев конвейера; не бросает.
|
||||
|
||||
## `WordPdfValidator`
|
||||
|
||||
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
|
||||
|
||||
```java
|
||||
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
|
||||
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
|
||||
```
|
||||
|
||||
Проверяются: непустота, размер (`maxMb`), сигнатура (zip/CFB), для docx — контейнер
|
||||
(`[Content_Types].xml` с типом документа), производные пороги (распаковка, XML,
|
||||
растры, записи zip), число страниц (lightweight-скан, без docx4j; для `.doc` —
|
||||
по сырым байтам мостом).
|
||||
|
||||
## `ConvertOptions`
|
||||
|
||||
```java
|
||||
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
|
||||
boolean errorOnOle, long maxMb, int maxPages) {}
|
||||
```
|
||||
|
||||
**Порядок полей фиксирован.** `maxMb`/`maxPages` должны быть больше 0. Дефолтов
|
||||
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
|
||||
флаги только отменяют конвертацию находкой.
|
||||
|
||||
## Ошибки
|
||||
|
||||
```
|
||||
ConversionException (RuntimeException)
|
||||
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
|
||||
├── ChartsFoundException — errorOnCharts и найдены диаграммы
|
||||
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
|
||||
└── OleFoundException — errorOnOle и найдены OLE-объекты
|
||||
```
|
||||
|
||||
Ловите `ConversionException` — он покрывает всё; `ValidationException` — отдельно,
|
||||
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
|
||||
|
||||
## Инвариант параллельности
|
||||
|
||||
`convert` **потокобезопасен, но сериализован**: все конвертации идут под монитором
|
||||
класса `WordPdfConverter.class` — ядро мутирует глобальный реестр шрифтов docx4j
|
||||
(`PhysicalFonts`). Параллельные вызовы корректны, но исполняются последовательно;
|
||||
собственный пул/очередь с отказом при переполнении — забота вызывающего
|
||||
(так делает `wordpdf-app`: один воркер, очередь 16).
|
||||
|
||||
## Шрифты и окружение
|
||||
|
||||
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации
|
||||
возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие
|
||||
конвертации.
|
||||
- `java.awt.Font` не используется (глифы — fontbox напрямую): **fontconfig хосту не нужен**,
|
||||
контейнер без `/etc/fonts` работает.
|
||||
- Нужен SLF4J-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
|
||||
предупреждений попадает в PDF.
|
||||
Reference in New Issue
Block a user