Ревью-фиксы: DoS chart-XML, корректность вывода, auth-обход, стандарты OOXML в docs/ #36
@@ -28,6 +28,8 @@
|
||||
|
||||
### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
|
||||
|
||||
Нормативный источник любых правок/решений по диаграммам и SmartArt — ECMA-376 (`docs/standards/`: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + `schema/*.xsd`; поведение Word — `ms-oi29500.md`, `ms-odrawxml.md`), а не догадки по исходникам LibreOffice/Word-эмпирике; эмпирические калибровки (камера, `PIE_DEPTH`) менять только вместе с пиксельными тестами. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.).
|
||||
|
||||
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 = "Название диаграммы"` (русская замена англ. плейсхолдеру Word); палитра `accent1..6` темы, легенда по умолчанию снизу, позиция `t` поддержана, `overlay` → место не резервируется) → `ChartRenderer` (осевые «круглые» шаги `niceUnit` 1/2/5·10ⁿ как Word) → пейнтеры `CartesianPainter`/`PiePainter` (`PIE_DEPTH=0.22`, `PIE_FIT=0.865`)/`Surface3dPainter` (калибровка по эталону Word 300 dpi, камера — регрессия `cameraMatchesWordReference`: `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` рисует кэш разложенной схемы (relationship `…/office/2007/relationships/diagramDrawing`, фактически `word/diagrams/drawing1.xml`; fit-scale ×0.80), формы строит `PresetGeometry` — ECMA-пресет-геометрия `a:prstGeom`: avLst/gdLst/pathLst семи пресетов (rect, roundRect, ellipse, gear6, gear9, circularArrow, leftCircularArrow) дословно из `presetShapeDefinitions.xml`, вычислитель префиксных формул; оператор `?:` = «if x > 0 then y else z» (ISO/IEC 29500-1, НЕ x != 0), углы в Arc2D передавать со знаком минус (математическая конвенция y вверх), неизвестный пресет → прямоугольник ячейки (синхрон таблицы со стандартом пинит `PresetGeometryTest#tableMatchesEcmaXml`); палитра темы — `DrawMlColor` (instance; без ThemePart — дефолтная Office-палитра `accent1=4472C4`…); текст — `DrawMlText`; утилиты `RgbHsl`. Калибровочные константы менять только вместе с `Surface3dPainterTest`/`PiePainterTest`. Обход `pkg.getParts()` — только по **снимку** списка (`createImagePart` мутирует реестр → CME); rels частей — `part.getRelationshipsPart()`, НЕ `getOwningRelationshipPart()` (это rels ссылающегося); обход XML обязан раскрывать `JAXBElement`.
|
||||
|
||||
### Критические инварианты (нарушение = битый вывод)
|
||||
@@ -61,6 +63,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|
||||
|`.gitea/workflows/`|Gitea Actions: `pr.yml` (PR checks), `main.yml` (тесты + coverage-сводка и комментарий в PR → `images-app`/`images-web` (build+push в Nexus) → deploy (рендер прод-конфигов + pull) → autotests → rollback)|
|
||||
|корневой `GITEA-vars.md`|инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений|
|
||||
|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 21 проверка): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh`|
|
||||
|`docs/standards/`|нормативная документация OOXML: PDF+md ECMA-376 Part 1 (5-е изд.), md [MS-OI29500]/[MS-ODRAWXML], XSD `schema/` — источник истины для chart-движка (правило — в секции «Chart-движок»); регенерация — `docs/standards/README.md`|
|
||||
|`develop/` (вне git, gitignored)|рабочие материалы и эталоны Word для ручного сравнения — **не фикстуры**, в тесты/jar не подключать; на 2026-10 директория пуста (эталоны вынесены, пиксельные замеры зашиты числами в chart-тестах)|
|
||||
|
||||
## Development Commands
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,48 @@
|
||||
# Нормативная документация OOXML
|
||||
|
||||
Источник истины для chart-движка (`wordpdf-core/.../internal/chart/`) и нормализаторов: любые правки диаграмм/SmartArt/представления docx — по документам ниже, а не по догадкам. Правило закреплено в `AGENTS.md` (секция «Chart-движок»).
|
||||
|
||||
## Источники
|
||||
|
||||
|Файл|Документ|Редакция/дата|URL|SHA-256|
|
||||
|---|---|---|---|---|
|
||||
|`ECMA-376-1_5th_edition_december_2016.pdf`|ECMA-376 Part 1 «Fundamentals and Markup Language Reference»|5-е изд., декабрь 2016|https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.pdf|`7cccfd0ad0e2ef89316acece15e44a8a088d0603ce4bba4e7b0361b50d13a37d`|
|
||||
|`ecma376-part1-5th.md`|Тот же текст, извлечённый из PDF (поиск по номерам секций)|5-е изд.|производный (см. регенерацию)|`86af445c080d9a481eaa426fc1721d50a1c4eff875535f9d03fe93d2b95b21b6`|
|
||||
|`ms-oi29500.md`|[MS-OI29500] «Office Implementation Information for ISO/IEC-29500 Standards» — как Word реально пишет docx (§2.1 — комментарий к Part 1, §3.1 — к Part 4)|260818 (август 2026)|https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-OI29500/%5bMS-OI29500%5d-260818.docx|`3e3eabb060a3772d096f001e7fee682fc4be12a2dd55ea360430fff14dd5845d`|
|
||||
|`ms-odrawxml.md`|[MS-ODRAWXML] «Office Drawing Extensions to Office Open XML» — расширения Word/Excel для чартов (ChartEx, стили/цвета)|261006 (октябрь 2026)|https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-ODRAWXML/%5bMS-ODRAWXML%5d-261006.docx|`f5a2517c4984b2ba2f0ade504bd0c9660c74f619290910a9b491c0f2ca9db64a`|
|
||||
|`schema/dml-chart.xsd`|XSD DrawingML Charts (`c:`-пространство имён)|5-е изд.|вложенный `OfficeOpenXML-XMLSchema-Strict.zip` в ECMA-архиве выше|`189b9631129a7d6c9f971b42b94c8942d260f11f81615f427db059bbf442cdc3`|
|
||||
|`schema/dml-diagram.xsd`|XSD DrawingML Diagrams (`dgm:`)|5-е изд.|там же|`179cd2fa4b981e1e2faa9ce99bb18c5d4d896dc1edb144af50f5cc8c52eb8569`|
|
||||
|`schema/dml-main.xsd`|XSD DrawingML Main (`a:`, пресет-геометрия — типы)|5-е изд.|там же|`078871240cff323ddd22a395281421b737fa61508fd39ffaa2947ba2bc01175e`|
|
||||
|
||||
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (poppler/pandoc), при регенерации другим инструментом могут измениться; первичен PDF/docx выше.
|
||||
|
||||
## Что где искать
|
||||
|
||||
- **Диаграммы (`c:chart`)** — ECMA-376 §21.2 (`grep -n "^21.2" ecma376-part1-5th.md`; каждый элемент — секция вида `21.2.2.132 overlay (Overlay)`) + `schema/dml-chart.xsd`; расширения Word — `ms-odrawxml.md`.
|
||||
- **Диаграммы-схемы SmartArt (`dgm:`)** — ECMA-376 §21.4 + `schema/dml-diagram.xsd`. Кэш разложенной схемы (`word/diagrams/drawing1.xml`, relationship `…/office/2007/relationships/diagramDrawing`) — проприетарный MS-формат, нормативного XSD нет; authoritative источник фактической геометрии — сам `dsp:drawing`.
|
||||
- **Пресет-геометрия (`a:prstGeom`)** — ECMA-376 Annex D; машинная копия таблицы пресетов — `wordpdf-core/src/test/resources/geom/presetShapeDefinitions.xml` (синхрон пинит `PresetGeometryTest#tableMatchesEcmaXml`).
|
||||
- **Chart Drawings (`c:drawing`)** — ECMA-376 §21.3.
|
||||
- **Поведение Word (что он реально пишет в `w:r`/`w:t`/`lastRenderedPageBreak`, текстбоксы, чарты)** — `ms-oi29500.md` (указатели на секции Part 1, напр. §2.17.3.3.13 → Part 1 §17.3.3.13).
|
||||
|
||||
## Регенерация
|
||||
|
||||
```bash
|
||||
# ecma376-part1-5th.md — из PDF в репозитории (постобработка: выбросить строки
|
||||
# `^\s*\d{1,4}\s*$` (номера страниц), `^ECMA-376 Part 1\s*$` (колонтитул),
|
||||
# строки с `.....` (точки оглавления); остальной текст — как есть)
|
||||
pdftotext -layout docs/standards/ECMA-376-1_5th_edition_december_2016.pdf /tmp/p1.txt
|
||||
|
||||
# ms-oi29500.md / ms-odrawxml.md — свежие dated-.docx с learn.microsoft.com
|
||||
# (при 404 — самый свежий .docx со страниц лендингов:
|
||||
# https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/1fd4a662-8623-49c0-82f0-18fa91b413b8
|
||||
# https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/06cff208-c6e1-4db7-bb68-665135e5f0de)
|
||||
curl -sSL -o /tmp/oi29500.docx "https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-OI29500/%5bMS-OI29500%5d-260818.docx"
|
||||
curl -sSL -o /tmp/odrawxml.docx "https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-ODRAWXML/%5bMS-ODRAWXML%5d-261006.docx"
|
||||
pandoc /tmp/oi29500.docx -t gfm-raw_html --wrap=none -o docs/standards/ms-oi29500.md
|
||||
pandoc /tmp/odrawxml.docx -t gfm-raw_html --wrap=none -o docs/standards/ms-odrawxml.md
|
||||
|
||||
# schema/*.xsd — из официального ECMA-архива
|
||||
curl -sSL -o /tmp/p1.zip "https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.zip"
|
||||
unzip -o /tmp/p1.zip "OfficeOpenXML-XMLSchema-Strict.zip" -d /tmp/
|
||||
unzip -o /tmp/OfficeOpenXML-XMLSchema-Strict.zip dml-chart.xsd dml-diagram.xsd dml-main.xsd -d docs/standards/schema/
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user