Перенос дизайна в server-rendered веб-UI (web-ui)

Новая capability web-ui: презентационный перенос готового дизайна (семантический HTML + единый jellybit.css, тёмная тема по настройке ОС) в html/template без шага сборки. - Встроенная (go:embed) отдача статики под /static с Cache-Control и cache-busting (?v=<hash> по содержимому css/js). - Шрифты IBM Plex self-hosted (@font-face, cyrillic+latin), без CDN. - Наколеночный менеджер зависимостей: вендор (htmx + шрифты) не хранится в репо (gitignore), идемпотентно добывается `task assets` по web/assets.manifest с проверкой sha256; task build/run зависят от assets. - Общие партиалы: шапка, бейдж статуса (карта всех 14 состояний), виджет «файл источника → раскладка» (общий для review и download). - Страницы: список с фильтром/поиском, ревью, новая страница просмотра загрузки (/download/{id}). deleted скрыт по умолчанию. - Превью раскладки берётся из единой логики internal/layout (buildFileRows), без дублирования правил имён в шаблонах. - Убраны meta-refresh и инлайн-стили; copyHash на vanilla с fallback на execCommand и честной индикацией (целевой деплой — HTTP LAN). Вне scope (отдельный change): живые обновления прогресса и раздел раздачи, клиентский режим ручной раскладки файл→серия (с Alpine.js). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-30 19:59:19 +03:00
parent d190072647
commit 4e2593ac31
26 changed files with 1960 additions and 303 deletions
@@ -0,0 +1,155 @@
+## Context
+
+Веб-UI — тонкий транспорт над ядром (приём в `ingest`, команды в `worker`,
+чтение в `store`). Рендер server-rendered через `html/template`, ассеты
+встраиваются `go:embed` (`web/web.go`). Сейчас встроены только шаблоны;
+статика (CSS/JS/шрифты) не отдаётся, «живость» сделана грубым
+`<meta http-equiv="refresh" content="5">`, оформление — инлайн-`<style>` с
+хардкодом цветов.
+
+Готов дизайн (`tmp/design/`): семантический HTML + единый `jellybit.css`
+(токены, тёмная тема по ОС), спроектированный под этот стек — без сборки,
+npm, React. Превью целевых путей раскладки уже считается на сервере через
+`internal/layout.BuildLinks` (поле `reviewView.Preview`) — это источник истины
+имён, дублировать его нельзя (инвариант: превью = реальная раскладка).
+
+Стек зафиксирован с заказчиком: htmx (через манифест с checksum, без Node),
+шрифты self-hosted, статика через `go:embed`. Реактивных фреймворков нет:
+клиентский режим ручной раскладки файл→серия отложен (операция редкая), вместе
+с ним отложен и Alpine.js — его добавим, когда виджет понадобится. Живые
+обновления прогресса — отдельный change (`web-live-updates`), здесь meta-refresh
+просто убирается.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Перенести дизайн `tmp/design/` в прод-шаблоны без шага сборки.
+- Встроить и отдавать статику (CSS, htmx, Alpine, шрифты) из одного бинаря.
+- Единая дизайн-система: один CSS, токены, тёмная тема по ОС, бейджи статусов.
+- Общие партиалы (шапка, бейдж, виджет «файл→раскладка») вместо дублей.
+- Добавить страницу `download` (просмотр одной загрузки).
+- Превью путей на ревью — показ из единого серверного расчёта `internal/layout`.
+
+**Non-Goals:**
+- Живые обновления прогресса/SSE (отдельный change).
+- Клиентский режим ручной раскладки файл→серия (S·E, нумерация, live-превью) и
+  Alpine.js под него — отложены до реальной необходимости (операция редкая).
+- Изменение доменного поведения (приём, распознавание, петля ревью, команды).
+- Авторизация веб-UI (остаётся вне scope, доверенная LAN).
+- npm/бандлер/CSS-постпроцессинг.
+
+## Decisions
+
+### D1. Статика через `go:embed` + `http.FileServer` под `/static/`
+
+`web/web.go` встраивает `static/*` рядом с `templates/*`. Роут
+`r.Handle("/static/*", http.StripPrefix("/static/", fileServer))` с
+`Cache-Control` (длинный max-age для вендорных файлов и шрифтов; для CSS —
+умеренный, либо cache-busting через `?v=<hash>`, посчитанный при старте).
+
+*Альтернативы:* отдавать с диска — отвергнуто (ломает однобинарность);
+CDN для htmx/Alpine — отвергнуто (внешняя сеть, инвариант self-host).
+
+### D2. Шрифты self-hosted через `@font-face`
+
+IBM Plex Sans/Mono кладём в `web/static/fonts/`, подключаем `@font-face` в
+`jellybit.css`. Из шаблонов убираем `<link>` на Google Fonts.
+
+*Почему:* umbar — домашний сервер, не зависим от внешней сети, не утекает
+referrer. Handoff сам это рекомендует.
+
+### D3. Зависимости фронта — наколеночный менеджер: gitignore + идемпотентный фетч
+
+Вендорные ассеты (htmx + шрифты IBM Plex) **не храним в репозитории** —
+`web/static/vendor/` в gitignore. Источник истины — манифест `web/assets.manifest`
+(строки `<путь под web/static/>  <url>  <sha256>`). `task assets` идемпотентен:
+для каждой записи — если файл есть и sha256 совпал, берём с диска; иначе качаем и
+сверяем (несовпадение валит таргет). Node/бандлер не вводим. Alpine.js не вводим
+— реактивных виджетов в этом change нет (см. Non-Goals).
+
+**Граница вендора.** В vendor только фетчабельные третьесторонние пакеты (htmx,
+woff2-шрифты). Авторские `jellybit.css` (с вшитым `@font-face` на `../vendor/
+fonts/`) и `app.js` — наш исходник, коммитятся как обычно (качать неоткуда).
+
+**Сборка.** `go:embed templates static` встраивает и vendor, поэтому файлы должны
+быть на диске к моменту `go build`. `task build`/`task run` зависят от `task
+assets`. Бинарь остаётся самодостаточным (всё встроено), репозиторий — без
+вендора. Размен: канонична сборка через Task; голый `go build` без `task assets`
+соберёт бинарь с неполной статикой (css есть, шрифтов/htmx нет) — это принято.
+
+*Альтернативы:* (1) коммитить результат фетча — отвергнуто заказчиком (не хотим
+вендор в репо). (2) npm + бандлер (Parcel/esbuild) через Docker — отвергнуто
+сейчас: бандлить нечего (htmx — готовый `<script>`, своего JS ~ноль), целый
+рантайм ради пары файлов. Дорастёт фронт до своих компонентов — отдельный change
+и esbuild (проще Parcel; есть Go-биндинги, можно без Node).
+
+### D4. Партиалы через `template.ParseFS` нескольких файлов
+
+Выносим общие куски в `web/templates/partials/`: `header.html`,
+`status_badge.html` (карта `state→class/подпись`), `layout_widget.html`
+(виджет «файл источника → раскладка», общий для review и download). Бейдж
+рендерится по `state` — карту держим в одном партиале (`{{define}}`), не
+дублируем по страницам. Текущий `add`-FuncMap сохраняем; при нужде добавляем
+маленькие чистые функции-хелперы.
+
+*Почему:* handoff (п. 7) прямо просит вынести шапку, бейдж и виджет в общие
+партиалы — сейчас они продублированы.
+
+### D5. `download.html` — новая страница `/download/{id}`
+
+Новый GET-хендлер + view-структура: распознавание, файлы→раскладка (тот же
+партиал), раздача, история/таймлайн. Действия — по состоянию (как в index),
+формы переиспользуют уже существующие `/ui/downloads/{id}/*` эндпоинты.
+
+### D6. Ручная раскладка файл→серия — отложена
+
+Клиентский режим ручного редактирования (S·E по файлам, нумерация,
+live-превью) в этот change не входит — операция редкая, не оправдывает
+реактивный виджет и Alpine.js сейчас. На ревью остаётся показ файлов и
+серверного превью (read-only) + существующие действия через формы/htmx
+(уточнить/перераспознать/выбрать кандидата/применить/позже/отклонить).
+
+*Когда понадобится* — заведём отдельный change: тогда же выберем подход
+(клиентская валидация + серверный dry-run превью переиспользует
+`layout.BuildLinks`, чтобы не дублировать правила имён в JS) и добавим Alpine.
+
+### D7. Убрать meta-refresh и инлайн-стили
+
+`<meta http-equiv="refresh">` и `<style>` удаляются. До change живых
+обновлений список статичен (обновление — перезагрузкой). Это осознанный
+временный шаг, чтобы не смешивать презентацию с поведенческим изменением.
+
+## Risks / Trade-offs
+
+- **Устаревание/дрейф htmx** → версия и sha256 в манифесте; обновление
+  осознанное (правка манифеста + `task assets` с проверкой хеша).
+- **URL-rot / офлайн-сборка** (vendor не в репо) → первая сборка требует сети,
+  дальше файлы кэшируются на диске (идемпотентно). Митигация: пиннинг версий +
+  два рабочих зеркала (unpkg/jsdelivr), URL правится в манифесте. Если понадобится
+  жёсткая офлайн-воспроизводимость — внутреннее зеркало или возврат к коммиту.
+- **Регресс действий при переносе шаблонов** (поле без `name`, не та форма) →
+  опираемся на разметку `<!-- action: … -->` в прототипах и существующие
+  хендлеры; проверяем каждое действие по состоянию; ревью кода до archive.
+- **Временная потеря авто-обновления** (D7) → приемлемо, закрывается
+  следующим change; список обновляется перезагрузкой.
+- **Рассинхрон карты статусов** между бейджем и доменом → карта в одном
+  партиале + спека требует полноты покрытия всех состояний.
+
+## Migration Plan
+
+1. Манифест + идемпотентный `task assets` (фетч htmx и шрифтов в gitignored
+   `web/static/vendor/` с проверкой sha256); `task build`/`run` зависят от
+   `assets`; добавить авторские `web/static/{css,js}`, расширить `go:embed`.
+2. Роут `/static/*` + `Cache-Control`.
+3. Партиалы (header, status_badge, layout_widget); переключить index/review.
+4. Добавить `download.html` + хендлер `/download/{id}`.
+5. Убрать meta-refresh и инлайн-стили.
+6. `task lint` + `task test`; ручная проверка действий по состояниям.
+
+Откат — презентационный, без миграций БД и схемы: revert коммита
+восстанавливает прежние шаблоны.
+
+## Open Questions
+
+- Cache-busting CSS: `?v=<hash>` при старте или фиксированный `Cache-Control`
+  с коротким max-age. Решим при реализации D1 (склонность — хеш при старте).