Конвенции: веб-UI на htmx (свопы, поллинг, деградация, ошибки)
Кросс-каттинг правила работы с интерфейсом на htmx: единый партиал = страница = фрагмент (+инвариант «корень define = элемент с целевым id»), ветвление обработчика по isHTMX, обязательная деградация без JS, ошибка на htmx-пути = HTTP 200 + фрагмент, самозавершающийся поллинг живых обновлений, своп сохраняет контекст / выход = навигация, различение поверхности полем surface, вендоринг/кэш статики. Блок «Статус» разделяет уже сделанное (reviewBlockAction, поллинг progress/seeding) и проектируемое в change htmx-action-swap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -19,3 +19,6 @@
|
||||
- [database.md](database.md) — БД и идентификаторы: TEXT ULID PK через
|
||||
`internal/ident` (без AUTOINCREMENT), lowercase + нормализация на границах,
|
||||
естественные ключи у деталей.
|
||||
- [web-ui.md](web-ui.md) — веб-UI на htmx: единый партиал = страница = фрагмент,
|
||||
ветвление `isHTMX`, деградация без JS, ошибка = 200 + фрагмент, самозавершающийся
|
||||
поллинг, вендоринг/кэш статики.
|
||||
|
||||
@@ -0,0 +1,180 @@
|
||||
# Веб-UI (htmx)
|
||||
|
||||
Конвенция: *как* мы пишем код веб-UI — частичный своп фрагментов, поллинг
|
||||
живых обновлений, обработчики действий, деградация без JS, ошибки. Это правила
|
||||
оформления кода (How), а не спецификация поведения — что именно UI показывает и
|
||||
какие действия обязан поддерживать, живёт в OpenSpec-спеке `web-ui`
|
||||
(`### Requirement` с `SHALL`).
|
||||
|
||||
Логирование запросов — [logging.md](logging.md) (HTTP-поля, навигационные GET на
|
||||
`DEBUG`). Трансляция доменных ошибок наружу — [errors.md](errors.md) (приватный
|
||||
канал = логи, публичный = сообщение + корреляционный ключ). Здесь — только
|
||||
специфика htmx-транспорта, без дублирования.
|
||||
|
||||
> Статус. Полностью по этой конвенции сейчас сделан только своп блока источника
|
||||
> на ревью (`reviewBlockAction` + партиал `review_source_block`) и поллинг
|
||||
> прогресса/раздачи. Общий раскат свопа на карточку списка, страницу загрузки и
|
||||
> петлю ревью (`buildCardView`/`buildDownloadView`, `surface`, `ActionError`,
|
||||
> `handleFragReview`) проектируется и внедряется в change
|
||||
> `openspec/changes/htmx-action-swap/` — там те же решения подробно. Ниже —
|
||||
> **целевой** подход; где он ещё не в коде, помечено «будем».
|
||||
|
||||
## Стек и границы
|
||||
|
||||
htmx-first: `chi` + `html/template` (server-rendered) + htmx. Ничего сверх этого:
|
||||
**без шага сборки, без Node/бандлера, без реактивных фреймворков**. htmx
|
||||
вендорится и самохостится (`go:embed`, `/static/vendor/`), без CDN.
|
||||
|
||||
- Свой JS сведён к минимуму — `web/static/js/app.js` несёт только то, что серверу
|
||||
знать не нужно (`copyHash` в буфер обмена). **Клиентского пересчёта доменного
|
||||
состояния нет** — состояние считает сервер, клиент только свопит присланную
|
||||
разметку.
|
||||
- Alpine.js/SPA сознательно **не вводим**. Решение зафиксировано в
|
||||
`openspec/changes/archive/2026-06-30-web-ui-design-port/design.md` (D3/D6):
|
||||
Alpine добавим отдельным change только когда понадобится реактивный клиентский
|
||||
виджет (ручная раскладка файл→серия), не раньше.
|
||||
|
||||
## Единый источник разметки: партиал = страница = фрагмент
|
||||
|
||||
Переиспользуемый кусок — это `{{define "name"}}` в `web/templates/partials/`. Тот
|
||||
же `{{define}}` рендерится **и** инлайн на странице (`{{template "name" .}}`),
|
||||
**и** как ответ-фрагмент того же обработчика (`s.render(w, "name", view)`).
|
||||
Отдельного markup для фрагмента не заводим — иначе он дрейфует от страницы.
|
||||
|
||||
**Инвариант: корень `{{define}}` — это элемент с целевым `id`** (`#source-block`,
|
||||
`#dl-live-{id}`, `#seeding-{id}`; будем — `#card-{id}`, `#download-main`,
|
||||
`#review-main`). `hx-swap="outerHTML"` заменяет весь корневой узел; если ответный
|
||||
фрагмент не несёт тот же корневой `id`, следующее действие/поллер не найдёт
|
||||
таргет. Разметку и `id` держим в одном партиале, чтобы страница и своп-ответ не
|
||||
разъезжались.
|
||||
|
||||
Сборку view выносим в переиспользуемую функцию (`buildReviewView`; будем —
|
||||
`buildCardView`, `buildDownloadView`) и зовём её и на полной странице, и во
|
||||
фрагменте — чтобы htmx-ветка не копипастила сборку. Часть сборки сейчас ещё
|
||||
инлайновая (`handleIndex` — карточка, `handleDownload` — страница); извлечение
|
||||
билдеров — направление рефакторинга в `htmx-action-swap`, не свершившийся факт.
|
||||
|
||||
## Обработчик действия: ветвление htmx / редирект
|
||||
|
||||
htmx-запрос определяем по заголовку — `HX-Request: true`:
|
||||
|
||||
```go
|
||||
func isHTMX(r *http.Request) bool { return r.Header.Get("HX-Request") == "true" }
|
||||
```
|
||||
|
||||
Обработчик действия зовёт доменную операцию **одинаково** в обеих ветках, а
|
||||
дальше ветвится (эталон — `reviewBlockAction`):
|
||||
|
||||
```go
|
||||
actionErr := fn(r.Context(), id) // доменный вызов идентичен для htmx и не-htmx
|
||||
|
||||
if !isHTMX(r) {
|
||||
redirectReview(w, r, id, msg) // без htmx — прежний PRG-редирект (303)
|
||||
return
|
||||
}
|
||||
rd, _ := s.deps.Reviewer.ReviewData(r.Context(), id) // перечитать актуальное состояние
|
||||
view := buildReviewView(id, rd, "") // тем же view-builder'ом
|
||||
if actionErr != nil {
|
||||
view.BlockError = userErr(r, actionErr, id) // ошибка → отдельное поле
|
||||
}
|
||||
s.render(w, "review_source_block", view) // фрагмент = тот же {{define}}
|
||||
```
|
||||
|
||||
`s.render` (`render.go`) рендерит именованный шаблон **в буфер** и только затем
|
||||
пишет ответ — при ошибке шаблона клиент не получит «полустраницу».
|
||||
|
||||
## Graceful degradation обязательна
|
||||
|
||||
Формы действий остаются обычными `<form method="post" action="...">`;
|
||||
`hx-post`/`hx-target`/`hx-swap` лишь **накладываются сверху** на ту же форму.
|
||||
Без JS всё работает через POST + редирект (PRG). Это инвариант web-ui «действия
|
||||
работают без JavaScript» — не нарушать: `action` формы всегда рабочий фолбэк, а
|
||||
не декорация.
|
||||
|
||||
Фильтр, поиск и пагинация списка — **серверные** (GET-параметры `f`/`q`/`page`/
|
||||
`all`), тоже без JS. Клиентской фильтрации нет намеренно.
|
||||
|
||||
## Ошибки на htmx-пути: HTTP 200 + фрагмент
|
||||
|
||||
htmx по умолчанию **не свопит DOM на ответы 4xx/5xx**. Поэтому при ошибке
|
||||
действия обработчик отвечает **200 с фрагментом**, несущим сообщение (эталон —
|
||||
`BlockError` в `reviewBlockAction`). Доменную ошибку на htmx-пути **не**
|
||||
транслируем в HTTP-статус (в отличие от REST API и no-JS редиректа с `?err=`).
|
||||
|
||||
- Сообщение — нейтральный текст публичного канала через `userErr`/`classifyErr`
|
||||
(см. [errors.md](errors.md)); сырой `err.Error()` наружу не идёт.
|
||||
- Ошибку кладём в **отдельное поле** под ошибку действия (`BlockError`; будем —
|
||||
`ActionError`), не перегружая доменные поля (`Note`/`error_msg`/`.Error`): у
|
||||
`target_missing` `Note` непуст и перекрыл бы сообщение.
|
||||
- **При ошибке активное состояние не меняем** — перечитанный view показывает
|
||||
прежний выбор плюс сообщение.
|
||||
|
||||
## Живой поллинг
|
||||
|
||||
Паттерн живого обновления: фрагмент-эндпоинт под `/fragments/...` + в разметке
|
||||
`hx-get` + `hx-trigger="every Ns"` + `hx-swap="outerHTML"` (эталон —
|
||||
`progress`/`seeding`, `handleFragProgress`/`handleFragSeeding`):
|
||||
|
||||
```html
|
||||
{{define "progress"}}<div id="dl-live-{{.ID}}"
|
||||
{{if .Active}} hx-get="/fragments/downloads/{{.ID}}/progress"
|
||||
hx-trigger="every 3s" hx-swap="outerHTML"{{end}}>
|
||||
...
|
||||
</div>{{end}}
|
||||
```
|
||||
|
||||
- **Поллер самозавершается.** Когда состояние выходит из «живого» (`Active`
|
||||
ложно, торрент не сидирует), фрагмент возвращается **без `hx-*`** — htmx
|
||||
больше не опрашивает. Условие «живости» ведёт store-состояние (`downloading`
|
||||
для прогресса), а не qBittorrent.
|
||||
- **`outerHTML`-своп всего фрагмента** удаляет старый узел вместе с его
|
||||
поллером и htmx `process`-инициализирует новый — двойного опроса нет **при
|
||||
условии совпадения корневого `id`** (см. инвариант выше).
|
||||
- Данные тика — из in-memory снимка воркера (`LiveStatus.Live(infohash)`), без
|
||||
БД/сети на каждый тик; узкий контракт `LiveStatus` не зависит от способа
|
||||
доставки (поллинг сейчас, путь к SSE оставлен изолированным).
|
||||
- **Инвариант: браузер не опрашивает qBittorrent напрямую** — только свой сервер,
|
||||
который читает снимок. Поллинг статуса UI логируем на `DEBUG` (рутинно-частое,
|
||||
см. [logging.md](logging.md)).
|
||||
|
||||
## Своп сохраняет контекст; выход — навигация
|
||||
|
||||
`hx-swap="outerHTML"` не сбрасывает прокрутку и не трогает серверные фильтр/
|
||||
поиск/пагинацию (они в query). Действие **не должно уводить** пользователя со
|
||||
страницы, если предмет остаётся на ней (выбор источника, уточнение) — своп на
|
||||
месте.
|
||||
|
||||
Действие, после которого предмет **покидает** страницу (`apply`/`defer`/`cancel`
|
||||
на ревью — загрузка уходит с экрана), остаётся **обычной POST-формой без `hx-*`**
|
||||
→ полная навигация/редирект. Маркер «это выход» — форма без htmx-атрибутов; так
|
||||
не нужен `HX-Redirect`, а «уйти с экрана» выражено самой навигацией.
|
||||
|
||||
**Асинхронные действия.** Если доменное действие асинхронно (переводит в
|
||||
промежуточное состояние — `recognizing` у `rerecognize`/`refine`, работу
|
||||
доделывает воркер), своп отдаёт **промежуточное** состояние, а не мнимый
|
||||
результат; готовый итог догоняем самозавершающимся поллером (будем —
|
||||
`handleFragReview`, опрос `recognizing` до `review`). Не обещаем в UI мгновенный
|
||||
итог async-операции.
|
||||
|
||||
## Различение поверхности одного действия
|
||||
|
||||
Если один роут действия зовут с разных страниц и своп-ответ должен быть разным
|
||||
фрагментом (карточка списка vs `download_main`), различаем **явным скрытым полем
|
||||
формы** `surface=list|download` (будем), а не эвристикой по `HX-Target`/`Referer`
|
||||
— поле самодокументируемо и не зависит от резолва таргета.
|
||||
|
||||
## Статика, вендоринг, кэш
|
||||
|
||||
- Ассеты встроены `go:embed` (`web/web.go`: `templates static`), отдаются под
|
||||
`/static/` с длинным иммутабельным кэшем (`staticHandler`:
|
||||
`Cache-Control: public, max-age=31536000, immutable`).
|
||||
- Меняемые ассеты (css/js) версионируются через `?v=<assetVersion>` — короткий
|
||||
sha256 их содержимого (`assetVersion`), URL строит FuncMap-хелпер
|
||||
`{{asset "css/jellybit.css"}}`. Свежий деплой не отдаёт устаревший файл.
|
||||
- Вендор (htmx 2.0.4, шрифты IBM Plex) адресуется по **неизменному имени файла**
|
||||
и версионировать через `?v=` не нужен. В git его **не коммитим** (`.gitignore`);
|
||||
`task assets` идемпотентно добывает его в `web/static/vendor/` по манифесту
|
||||
`web/assets.manifest` (строки `<путь> <url> <sha256>`, проверка sha256).
|
||||
`task build`/`task run` зависят от `task assets`.
|
||||
- Шрифты и скрипты — **self-hosted**, без внешних хостов: бинарь самодостаточен,
|
||||
внешних ресурсов времени выполнения нет.
|
||||
Reference in New Issue
Block a user