wiki: ingest round-2 outcome — openapi-generator gotchas + sched-admin-client-openapi updated (all F-1..F-5 closed, raw_ops deleted)

2026-08-18 22:49:08 +03:00
parent b019983906
commit 34e6e2c7ab
4 changed files with 77 additions and 19 deletions
--- a/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md
+++ b/.wiki/concepts/openapi-generator-3-1-spec-gotchas.md
@@ -8,12 +8,38 @@ updated: 2026-08-18

 # openapi-generator + OpenAPI 3.1 — gotchas

-Проверено вживую на F&F-раунде sched «клиент на любом ЯП одной командой»
-(2026-08-18): Python-клиент из `@sched/admin-api@0.1.2` спеки (3.1.0, 15 путей)
-через `openapi-generator` **7.24.0** (`-g python`, pydantic v2). Спеку НЕ чинили
-(их импл, TDD) — обходили. Находки F-1..F-5 полные — в
-`sched/.agents/inbox/2026-08-18T19-15-43Z-admin-fnf-openapi-client-report.md`;
-здесь — переиспользуемая суть.
+Проверено вживую на F&F-раундах sched «клиент на любом ЯП одной командой»
+(2026-08-18): Python-клиент из спеки `@sched/admin-api` через
+`openapi-generator` **7.24.0** (`-g python`, pydantic v2). Спеку НЕ чинили —
+обходили (round 1, 0.1.2). Round 2 (0.2.0): все гочи 1–4 **закрыты фиксами
+спеки/сервера**, raw-обход удалён — см. «Статус после round 2» ниже.
+
+## Статус после round 2 (0.2.0 / daemon 0.3.5)
+
+Все 5 находок round 1 подтверждены закрытыми (ретест 2026-08-18, отчёт
+`sched/.agents/inbox/2026-08-18T22-55-00Z-admin-openapi-fixes-round2-retest.md`):
+
+- **Гоча 1 (wrapped-ответы) — FIXED (спека).** Мутации теперь объявляют
+  `{task}/{run}/{schedule}` (response-компоненты TaskMutation/RunMutation/
+  ScheduleMutation), `GET /runs/{id}?logFromOffset` — RunLogChunk (allOf
+  RunRecord + logChunk/logTotalLength). Генератор выдаёт **InlineObjectN**-
+  модели (поля task/run/schedule/ok), десериализация нативная. `raw_ops.py`
+  из примера **удалён**.
+- **Гоча 2 (const:true) — FIXED.** `const` убран из спеки; `Health200Response.ok`
+  = обычный `StrictBool`.
+- **Гоча 3 (oneOf+discriminator) — FIXED.** `Schedule` стал плоской схемой
+  (`kind` + опциональные `cron/timezone/ms/at`); `rec.schedule.cron` читается
+  с типизированной модели. Normalization живьём: `once`→`{kind:once, at:ISO}`,
+  `interval`→`{kind:interval, ms}`.
+- **F-1 (health auth) — FIXED (сервер).** `/health` всегда открыт, auth —
+  после health-роута; прочие роуты с ключом 401.
+- **F-5 (dedupKey fail-fast) — FIXED (сервер).** POST/PATCH /schedules с
+  неизвестным top-level полем → 400 с именем поля.
+- Итог ретеста: **11/11 ранее-сырых операций идут через типизированный клиент,
+  сьют 24/24, smoke 19/19** (коммит sched `d658ff0`).
+
+Гочи 1–3 ниже — описание сломанного состояния round 1 (0.1.2) + паттерн обхода
+(потребительский escape-hatch, если спека где-то ещё сырая).

 ## Гоча 1 — ответы `{}` в спеке ломают десериализацию (главная)

@@ -47,20 +73,35 @@ updated: 2026-08-18
 модели приходит с `actual_instance=None` — правило (`cron`) недостижимо через
 модель, только через raw JSON: `raw["schedule"]["schedule"]["cron"]`.
 Касается любого oneOf+discriminator на этой версии генератора (3.1-ветка).
+Фикс (round 2): плоская output-схема вместо oneOf — `kind` + опциональные
+поля; per-kind валидация на сервере (parseScheduleEntry).

 ## Окружение (Windows)

 - `openapi-generator` 7.x требует **Java 11+**: системная Java 8 падает на
  class-load; ставь `JAVA_HOME` на новый JDK (Temurin 25 работает).
+  **Важно (round-2 уточнение):** CLI-обёртка (`@openapitools/openapi-generator-cli`)
+  спавнит `java` из **PATH**, не из `JAVA_HOME` — одного JAVA_HOME мало:
+  `$env:Path = "$env:JAVA_HOME\bin;" + $env:Path` до запуска, иначе
+  UnsupportedClassVersionError (class file 55.0 vs JRE 52.0 = Java 8 в PATH).
  Запуск: `npx --yes @openapitools/openapi-generator-cli generate -i spec.json -g python -o out --additional-properties=packageName=...`
+- Wrapped-ответы, объявленные **инлайн в `components.responses`**, дают имена
+  `InlineObject..InlineObjectN` и доступ `resp.schedule.schedule.cron` (двойной
+  `.schedule`). Работает; красивее — именованные схемы в `components.schemas`.
+- `info.version` спеки НЕ бьётся вместе с версией пакета (в 0.1.2 и 0.2.0 —
+  `0.1.0`); версия живёт только в package.json / dist-tags.
 - Windows excluded port ranges (Hyper-V/WinNAT) резервируют порты (напр. 8090/8091):
  `EACCES` на listen. Проверка: `netsh interface ipv4 show excludedportrange protocol=tcp`.
 - Консоль cp1251: не печатай `→`/`«»` в скриптах — `'charmap' codec can't encode`; ASCII-only.

-## Паттерн обхода (потребитель, клиент не трогаем)
+## Паттерн обхода (потребитель, клиент не трогаем) — исторический

-Тонкий raw-слой рядом с сгенерированным пакетом (в примере — `raw_ops.py`):
+Тонкий raw-слой рядом с сгенерированным пакетом (в примере был `raw_ops.py`):
 только операции, где спека `{}`, через `call_api`; остальное — через типизированный
 клиент. Сгенерированный пакет остаётся перегенерируемым.

-Пример целиком: `sched/examples/admin-client-python/` (24/24 сьют, 19/19 smoke).
+> **Статус:** после round 2 (0.2.0) обход не нужен — `raw_ops.py` удалён из
+> примера. Паттерн остаётся escape-hatch'ем для сырых спек в других проектах.
+
+Пример целиком: `sched/examples/admin-client-python/` (24/24 сьют, 19/19 smoke,
+typed-only).
--- a/.wiki/concepts/sched-admin-client-openapi.md
+++ b/.wiki/concepts/sched-admin-client-openapi.md
@@ -6,14 +6,28 @@ related: [[openapi-generator-3-1-spec-gotchas]], [[sched-fnf-r8-verification-sta
 updated: 2026-08-18
 ---

-# sched admin-client openapi — F&F раунд
+# sched admin-client openapi — F&F раунды

 Живая проверка claim'а sched openapi-spec: **«клиент на любом ЯП одной
-командой»**. Вердикт: **claim подтверждён с оговорками** — генерация одной
-командой работает, но 3.1-спека до «любого ЯП без правок» не дотягивает
-(8 операций требуют raw-обхода).
+командой»**. Вердикт round 1: **claim подтверждён с оговорками** (8 операций
+требуют raw-обхода). Вердикт round 2 (0.2.0/0.3.5): **claim подтверждён
+полностью** — все находки F-1..F-5 закрыты, raw-обход удалён, клиент
+типизированный end-to-end.

-## Что делал / ожидал / получил
+## Round 2 — ретест фиксов (0.2.0 / daemon 0.3.5), 2026-08-18
+
+| | |
+|---|---|
+| Что | `generate.ps1` заново против `@sched/admin-api@0.2.0` (tarball spec byte-identical pinned), сьют+smoke против `@sched/daemon@0.3.5` (:8127, no auth) |
+| Ожидал | все 5 находок закрыты, `raw_ops.py` не нужен |
+| Получил | **все 5 закрыты**; сьют **24/24** (3 прогона), smoke **19/19** — **полностью через типизированный клиент, 0 операций на обходе**; `raw_ops.py` **удалён**; F-1/F-5 подтверждены живьём на keyed-инстансе (:8128): health 200 open, /tasks 401 без ключа, 400 на неизвестные поля schedule body/patch |
+
+Deliverables round 2: коммит sched `d658ff0` (пример обновлён: openapi.json
+0.2.0, tests/smoke typed-only, raw_ops удалён, README+generate.ps1); репорт
+`sched/.agents/inbox/2026-08-18T22-55-00Z-admin-openapi-fixes-round2-retest.md`.
+Механика фиксов и генераторные грабли — [[openapi-generator-3-1-spec-gotchas]].
+
+## Round 1 — 2026-08-18 (0.1.2 / daemon 0.3.4)

 | | |
 |---|---|
@@ -45,12 +59,14 @@ updated: 2026-08-18
 ```powershell
 cd sched/examples/admin-client-python
 $env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-25.0.2.10-hotspot"
+$env:Path = "$env:JAVA_HOME\bin;" + $env:Path   # генератор спавнит java из PATH, не из JAVA_HOME
 .\generate.ps1
 pip install -r requirements.txt pytest
 SCHED_ADMIN_URL=http://127.0.0.1:8127/api python -m pytest tests/ -v
 python smoke.py --url http://127.0.0.1:8127/api
 ```

-Стенд раунда: published `@sched/daemon` 0.3.4, `--admin-port 8127`, NO AUTH,
-scratch sqlite (`/tmp/sched-acpy-stand/acpy.db`). Письменный `:8080` — под ключом
-(`SCHED_ADMIN_KEY=dev-key`), `:8123` — стейл-билд (health 0.1.8, нет POST /tasks).
+Стенд round 2: published `@sched/daemon` 0.3.5, `--admin-port 8127`, NO AUTH,
+scratch sqlite (`/tmp/sched-acpy-stand/acpy.db`). Round 1 стоял на 0.3.4.
+Письменный `:8080` — под ключом (`SCHED_ADMIN_KEY=dev-key`), `:8123` — стейл-билд
+(health 0.1.8, нет POST /tasks).
--- a/.wiki/index.md
+++ b/.wiki/index.md
@@ -21,8 +21,8 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever
 - [windows-recovery-host](entities/windows-recovery-host.md) — Windows Recovery Host (рабочий PC пользователя)

 ## Concepts
- [sched-admin-client-openapi](concepts/sched-admin-client-openapi.md) — F&F раунд 2026-08-18: Python-клиент одной командой из спеки (openapi-generator 7.24.0), 24/24 + smoke 19/19, вердикт «claim подтверждён с оговорками», находки F-1..F-5
- [openapi-generator-3-1-spec-gotchas](concepts/openapi-generator-3-1-spec-gotchas.md) — генерация клиентов из 3.1-спеки (openapi-generator 7.24.0, python): ответы `{}` + wrapped-тело → ValidationError (raw-обход + by_alias), `const:true` → строковый enum, oneOf+discriminator → actual_instance=None, Java 11+, Windows excluded-порты
+- [sched-admin-client-openapi](concepts/sched-admin-client-openapi.md) — F&F раунды 2026-08-18: Python-клиент одной командой из спеки (openapi-generator 7.24.0); r1 0.1.2 — 24/24+smoke 19/19, находки F-1..F-5 (8 операций на raw-обходе); r2 0.2.0/0.3.5 — все 5 закрыты, raw_ops удалён, 11/11 typed-only, вердикт «claim подтверждён полностью»
+- [openapi-generator-3-1-spec-gotchas](concepts/openapi-generator-3-1-spec-gotchas.md) — генерация клиентов из 3.1-спеки (openapi-generator 7.24.0, python): wrapped-ответы {} → ValidationError (raw-обход историчен: r2 спека фикснута), const:true → строковый enum, oneOf+discriminator → actual_instance=None (r2: плоская схема), java из PATH а не JAVA_HOME, InlineObjectN-имена, info.version не бьётся
 - [nvm-junction-ismain-gate-gotcha](concepts/nvm-junction-ismain-gate-gotcha.md) — ESM isMain-гейт молча не выполняется под junction'нутым npm-рутом (nvm/mise/volta); realpath-фикс; диагностика за 30 сек
 - [nvm-windows-node-switch](concepts/nvm-windows-node-switch.md) — смена версии Node на nvm-windows: junction, per-version глобалы, PATH-кэш, npm 11 allow-scripts; Node 22→24 evidence
 - [sched-fnf-r8-verification-stand](concepts/sched-fnf-r8-verification-stand.md) — стенд верификации F&F r8 (schedule-as-entity): путь, версии core 0.40.2/ui 0.2.0, карта репро-скриптов (миграции/движок/политики/API 52/UI 13), подтверждённый контракт (ceiling, retryCount, snapshot, pause AND, tz-hoist, PATCH-merge), находки №5 (U1 форма-tz, U2 вёрстка), как закрыть раунд
--- a/.wiki/log.md
+++ b/.wiki/log.md
@@ -137,3 +137,4 @@ Append-only log of wiki operations (ingests, promotions, lints, migrations).
 ## [2026-08-18] ingest | NEW concepts/nvm-junction-ismain-gate-gotcha.md — ESM isMain-гейт молча no-op под junction-префиксом npm-рута (C:\nvm4w\nodejs → realpath …\nvm\v22.22.0): import.meta.url резолвится в realpath, argv[1] держит литеральный → main() не выполняется, exit 0. Бьёт global-install под любым version-manager'ом (nvm/mise/volta). Фикс realpath-сравнения (sched bd38aab, daemon 0.3.2). NEW concepts/nvm-windows-node-switch.md — Node 22→24.19.0 рецепт: junction-свап, per-version глобалы, PATH-кэш shell'а, npm 11 allow-scripts. Оба из сессии CLI-F&F sched 2026-08-18. index.md updated (+2).
 ## [2026-08-18] ingest | NEW concepts/openapi-generator-3-1-spec-gotchas.md — из F&F openapi-client sched (2026-08-18): генерация Python-клиента из 3.1-спеки openapi-generator 7.24.0. Гочи: (1) ответы `{}` в спеке + wrapped-тело ({task/run/schedule:…}) → pydantic ValidationError, фикс — реальные схемы ответов, обход raw-транспорт + by_alias=True; (2) `const:true` → строковый enum ('true') ломает boolean; (3) oneOf+discriminator → actual_instance=None, контент только через raw JSON; Java 11+ обязателен (системная 8 падает), Windows excluded-порты 8090/8091 (EACCES), консоль cp1251 без →/«». Полные находки F-1..F-5: sched/.agents/inbox репорт 19:15Z; пример sched/examples/admin-client-python (24/24). index.md updated.
 ## [2026-08-18] ingest | NEW concepts/sched-admin-client-openapi.md — F&F раунд openapi-claim sched (по предписанию таски): Python-клиент одной командой (openapi-generator 7.24.0 из спеки verdaccio 0.1.2), сьют 24/24 + smoke 19/19 против published daemon 0.3.4 (:8127), вердикт «claim подтверждён с оговорками» (8 операций требуют raw-обхода). Код sched/examples/admin-client-python (e89e868), репорт — sched инбокс 19:15Z, находки F-1..F-5 (спеку не чинил). Таска [sched-admin-client-openapi] 🟢. Гочи генерации — concepts/openapi-generator-3-1-spec-gotchas.md. index.md updated.
+## [2026-08-18] ingest | UPDATE concepts/openapi-generator-3-1-spec-gotchas.md + concepts/sched-admin-client-openapi.md — round 2 ретест (0.2.0/daemon 0.3.5): все 5 находок F-1..F-5 закрыты, raw_ops.py удалён, 11/11 ранее-сырых операций typed-only, сьют 24/24 + smoke 19/19 (коммит sched d658ff0, репорт sched инбокс 22:55Z). Новые грабли в окружение: CLI спавнит java из PATH а не JAVA_HOME; wrapped-ответы в components.responses → InlineObjectN; info.version не бьётся с версией пакета. index.md hooks обновлены.