From 18133837240d29dea5448a694580d5f5dc664cfd Mon Sep 17 00:00:00 2001 From: Ku6epXBOCTuK Date: Thu, 3 Sep 2026 16:29:05 +0500 Subject: [PATCH] docs: update plan --- docs/plan-composite-params.md | 91 ++++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 39 deletions(-) diff --git a/docs/plan-composite-params.md b/docs/plan-composite-params.md index b3b06cf..08bb127 100644 --- a/docs/plan-composite-params.md +++ b/docs/plan-composite-params.md @@ -1,9 +1,10 @@ # План: составные типы параметров и полная типизация pipeline -> Статус: **обсуждение завершено, решения приняты. Реализация пока НЕ начата** -> (ждут готовности UI). Док отражает итоговую целевую архитектуру. +> Статус: **в реализации.** Фаза 0 (фундамент) — сделана. Следующее: Фаза 1 — +> один полноценный рабочий инструмент в preview, затем масштабирование. > -> Файлы: `web/src/lib/registry.ts` (3918 строк), `web/src/lib/preview/tool-views.ts` (193 строки). +> Файлы: `web/src/lib/registry.ts` (3918 строк), `web/src/lib/preview/tool-views.ts` (193 строки), +> `web/src/lib/registry-schema.ts`. ## Ключевая стратегия: параллельная сборка, старый UI не трогаем @@ -210,36 +211,45 @@ add-text-png, date-stamp-png > схемы (`params` остаётся), не ломает старый UI. Инструмент получает ДОПОЛНИТЕЛЬНО > новое поле `schema` + `interface Params`, старое `run`/`params` не трогаем. > Это гарантирует, что старый UI продолжает работать без регресса. +> +> **Новый подход (решение пользователя):** сначала делаем **один полноценный +> рабочий инструмент в preview** — не эталон «на бумаге», а реально юзабельный, +> чтобы руками оценить, насколько это рабочее решение и какие возникнут сложности. +> Оцениваем, при необходимости правим инфраструктуру, и только потом переводим +> остальные инструменты тем же проверенным паттерном. -### Фаза 0 — фундамент (без инструментов, ещё не мигрируем) +### Фаза 0 — фундамент ✔ (сделано) -1. **Typed field builders** (`field.slider`, `field.color`, …) + тип `Field` - — отдельный файл `web/src/lib/registry-schema.ts` (или рядом с registry). - Diff: новый файл ~60-100 строк. Только типы, без изменения registry. -2. **`toolSchema

()`** + тип `ToolSchema

` — проверка соответствия схемы - полям Params. Diff: добавление функции в тот же файл. Без изменений registry. -3. **`ToolEntry

` generic + поле `schema`** (рядом с `params`). Diff: правка - типа `ToolEntry` в registry.ts (~10 строк). Компилируется, поведения не - меняет — `schema` опционален. -4. **Новые `defaultParams`/`sanitizeParams`** для схемы (старые не трогаем). - Diff: добавление функций рядом. Никто ещё не вызывает — просто присутствуют. +Typed field builders + `Field` + `toolSchema

()` + `ToolSchema

` — +в `web/src/lib/registry-schema.ts`. `ToolEntry

` generic + опциональное +поле `schema`. Новые `defaultSchemaParams`/`sanitizeSchemaParams`. +Старый `ParamDef[]`/pipeline не тронуты. Проверено: compile-time-защита +(лишний/неверный/отсутствующий ключ ловит TS), тесты, svelte-check без новых +ошибок. -Результат фазы 0: инфраструктура готова, registry работает как раньше, ни один -инструмент не изменён. Старый UI/тесты не затронуты. +### Фаза 1 — ОДИН полноценный рабочий инструмент в preview (срез) -### Фаза 1 — эталонный инструмент (вертикальный срез) +5. **Инструмент «добавить рамку» (`add-border-png`)** — сделать полностью + рабочим в preview: + - `interface AddBorderParams { thickness: number; color: string }` + - `addBorderSchema = toolSchema(...)` + `schema: ...` в entry + (старый `params`/`run` остаются — старый UI не регрессит). + - **Новый рендер в preview** (`kit/ToolView` → `ParamControl` или новый + компонент схемы): читает `ToolSchema

`, рисует поля рамки, применение + реально работает (end-to-end до картинки). + - Дефолты/валидация/значения — из схемы (`defaultSchemaParams`, + `sanitizeSchemaParams`). + - **Ревью-оценка:** удобно ли это, что сломалось/усложнилось, что поправить + в инфраструктуре до масштабирования. Принимается макет/решение. -5. **Инструмент «добавить рамку» (`add-border-png`)** — первый пилот: - - добавить `interface AddBorderParams { thickness: number; color: string }` - - добавить `const addBorderSchema = toolSchema({...})` - - добавить `schema: addBorderSchema` в `ToolEntry` (старый `params`/`run` остаются) - Diff: ~25-35 строк в одном месте. **Ревью макета** здесь решает, как выглядит - вертикальный срез, перед масштабированием. +Результат: один реально рабочий инструмент на новой системе = доказываем паттерн, +прежде чем переводить остальных. ### Фаза 2 — простые инструменты без составных типов (1 инструмент = 1 шаг) Одиночные/небольшие инструменты, где `interface Params` + `schema` не требуют -составных типов. Каждый — отдельный маленький diff (~15-30 строк): +составных типов. Каждый — отдельный маленький diff (~15-30 строк), тем самым +проверенным в Фазе 1 паттерном: 6. add-stroke-png (color + slider) 7. find-contour-png (color + slider) @@ -279,19 +289,18 @@ add-text-png, date-stamp-png 30. `gradient` — собрать из dimension + color-pair + direction на linear-gradient (зависит от решения по gradient, см. план) -### Фаза 4 — связка с новым UI +### Фаза 4 — масштаб UI на остальные инструменты -31. Новый рендер (`kit/ParamControl`) читает `ToolSchema

`; собрать макет - на пилоте add-border-png из Фазы 1. -32. Составные виджеты (dimension, color-pair, offset, position9, font-style, - plate, gradient) — по одному, каждый с ревью. -33. Пер-инструмент layout (`schema.layout`): группировка полей рамки и т.п. -34. Для каждого переведённого инструмента — UI-макет, принимается отдельно. +31. По мере перевода инструментов в Фазе 2-3 — рендер схемы (из Фазы 1) + покрывает их автоматически; составные виджеты (dimension, color-pair, + offset, position9, font-style, plate, gradient) — по одному, каждый с ревью. +32. Пер-инструмент layout (`schema.layout`): группировка полей рамки и т.п. +33. Для каждого переведённого инструмента — UI-макет, принимается отдельно. ### Фаза 5 — зачистка -35. Поглощение `tool-views.ts` (preview/lede/layout → meta инструмента). -36. После перехода на новый дизайн — удаление старого UI и старого `ParamDef[]`. +34. Поглощение `tool-views.ts` (preview/lede/layout → meta инструмента). +35. После перехода на новый дизайн — удаление старого UI и старого `ParamDef[]`. ### Как ревьюить каждый шаг @@ -302,7 +311,8 @@ add-text-png, date-stamp-png `pnpm --dir web test` и `pnpm --dir web exec svelte-check`. - Порядок полей в `interface Params` и в `schema` совпадает; дефолты в сeme равны старым `default` из `params`. -- После принятия макета — можно делать UI инструмента, не блокируя остальных. +- Пилот из Фазы 1 проверяется **руками в preview**: применяется рамка, + дефолты/валидация/смена значений работают end-to-end. ## Поток данных (runtime) @@ -358,14 +368,17 @@ add-text-png, date-stamp-png «Пошаговый план перевода инструментов» выше. Здесь краткая сводка фаз: 1. **Фаза 0** — фундамент: builders + `toolSchema

` + `ToolEntry

.schema` + - новые default/sanitize. Ни одного инструмента не изменено. -2. **Фаза 1** — эталонный пилот «добавить рамку» (вертикальный срез), ревью. -3. **Фаза 2** — простые/одиночные инструменты, 1 инструмент = 1 диф. + новые default/sanitize. Ни одного инструмента не изменено. ✔ +2. **Фаза 1** — **один полноценный рабочий инструмент в preview** + («добавить рамку»): schema + рендер + end-to-end применение. Ручная оценка + работоспособности решения/сложностей. +3. **Фаза 2** — простые/одиночные инструменты (проверенный паттерн Фазы 1), + 1 инструмент = 1 диф. 4. **Фаза 3** — инструменты с составными типами (dimension → color-pair → offset → position9 → font-style → plate → gradient), пилот каждого типа отдельно. -5. **Фаза 4** — связка с новым UI: рендер `ToolSchema

`, составные виджеты, - пер-инструмент layout (для каждого инструмента — UI-макет). +5. **Фаза 4** — масштаб UI на остальные: составные виджеты, пер-инструмент + layout (для каждого инструмента — UI-макет). 6. **Фаза 5** — поглощение `tool-views.ts`, затем удаление старого UI/`ParamDef[]` ## Зависимости