transcriber/openspec/changes/archive/2026-08-15-spa-skeleton/design.md

# Дизайн: каркас приложения

## Контекст

Фреймворк и способ раздачи выбраны разведкой `spa-framework-choice` и записаны
решением [ADR-2026-08-11-spa-on-vue](../../../docs/adr/ADR-2026-08-11-spa-on-vue.md):
Vue 3 с роутером пятой версии, сборка Vite, статика внутри бинарника, шаг сборки
в наборе проверок и в образе. Отвергнутые кандидаты — Svelte и React — названы
там же с ценой отказа и здесь не пересматриваются. Правила кода приложения лежат
в [conventions/web-ui.md](../../../docs/conventions/web-ui.md).

Эта задача решает не «на чём писать», а «чем сервис отдаёт написанное и что он
отвечает на пути, которого не знает».

## Что человек увидит иначе

Сегодня браузер, открывший адрес сервиса, получает отказ: сервис отвечает только
на своих адресах, и ни один из них страницы не отдаёт. После изменения тот же
адрес открывает приложение, а обновление страницы посреди приложения возвращает
тот же экран, а не ошибку. Вошедший видит своё имя, не вошедший — предложение
войти.

## Решения

### Один корневой маршрут вместо готовой раздачи библиотеки

У библиотеки есть готовый обработчик статики с подстановкой `index.html` на
непопавший путь. Он **не берётся**, и причин две.

Первая — устройство роутера. Сборка маршрутов сама вешает на путь `/` отказ
«ничего не совпало», если такого маршрута ещё нет. Образец `/` в стандартном
мультиплексоре покрывает все пути, и второй всепокрывающий образец рядом с ним —
`/{path...}` — либо конфликтует с ним, либо разрешается правилом, которое мы не
задаём. Поэтому маршрут ставится ровно на `/`: тем самым он занимает место
библиотечного отказа, а не спорит с ним.

Вторая — подстановка `index.html` слепа. Она не различает «человек обновил
страницу приложения» и «программа ошиблась адресом под корнем хранилища»: оба
случая непопавшие, и оба получили бы разметку с кодом `200`. Перечень корней
знает только сервис, и проверять его обязан он.

Отвергнуто: `apis.Static(fsys, true)` на `/{path...}` — по обеим причинам выше.

### Корни сервиса перечислены одним местом

Правило неизвестного пути обязано перечислять **все** корни (`archive`, «Адреса
приложения живут своим пространством»), а корней сегодня четыре плюс два
отдельных адреса наблюдения. Перечень заводится единой точкой в пакете
транспорта: разложенный по обработчикам, он теряет корень молча, и потерянный
корень означает разметку вместо отказа — то есть ровно ту поломку, от которой
правило и поставлено.

Что делает обработчик по порядку:

1. путь принадлежит корню сервиса или совпадает с адресом наблюдения — отказ
   `404` формой библиотеки, то есть **тем же, чем он отвечает сегодня**. Своей
   формы отказа здесь не заводится: под корнем приложения она уже есть и её даёт
   собственный перехват `/app/`, а под чужими корнями наша форма была бы второй;
2. метод не `GET` и не `HEAD` — отказ `405`;
3. путь ведёт под каталог ресурсов, а файла там нет — отказ `404`;
4. путь совпал с файлом собранного приложения — файл;
5. прочее — разметка приложения.

**Принадлежность корню — два условия, и оба обязательны:** точное совпадение либо
префикс вместе с косой чертой. По одному префиксу корню `/app` достался бы
посторонний `/apple`; по одному префиксу с косой чертой голый `/api` не достался
бы никому и уехал бы разметкой. Проверено прогоном мультиплексора на раскладке
этого дизайна.

**Шаг 3 закрывает случай, ради которого писано правило кэширования.** Разметка
прежней сборки называет ресурсы прежней сборки; после выкладки их имена другие, и
без этого шага браузер получил бы на несуществующий ресурс `200` с разметкой,
отверг бы её по типу содержимого и показал пустой экран — а в кодах ответов
сервиса не осталось бы ничего.

**Перечень не описывает регистрацию, а порождает её.** Наши маршруты — проба
здоровья, метрики, группа приложения и группа входа — вешаются из перечня;
корни библиотеки (`/api`, `/_`) остаются её литералами и держатся своим тестом.
Иначе перечень был бы вторым описанием таблицы маршрутов, которую сегодня ведут
три места, и разошлись бы они молча: корень, заведённый регистрацией и забытый в
перечне, отдаёт разметку с кодом `200` там, где программа ждёт отказ контракта, а
компилятор не видит ничего. Заодно уходит второе перечисление адресов
наблюдения — сегодня уровень журнала называет пробу здоровья и метрики отдельно.

Цена названа: задача трогает сборку маршрутов сверх первоначальных границ.
Принято решением владельца на чекпоинте 2026-08-15; отвергнуты правило-сканер
(ловит только литералы и добавляет шаг проверок) и перечень описанием
(расхождение обнаружил бы клиент).

**В журнал этот маршрут пишет исход, а не путь.** Путь здесь целиком задаёт
спрашивающий, и до изменения он ловился отказом маршрутизатора, а теперь
становится успешным ответом: дословная строка сделала бы журнал местом, куда
аноним пишет свой текст. Пишется исход — разметка, ресурс, отказ — и длина пути.

### Приложение живёт каталогом `web/`, а вшивается своим пакетом Go

Исходники, зависимости и настройка сборки — `web/`; вшиваемый каталог —
`web/embed`; собранное сборщик кладёт в `web/embed/dist`. Вшивает его файл
`web/embed.go` пакетом `web`. Транспорт получает готовую файловую систему
параметром, а не тянет пакет сам: так тест подставляет свою сборку, не собирая
приложение.

Отвергнуто: держать исходники приложения под `internal/`. Каталог означает
«внутреннее для Go», а приложение к сборке Go отношения не имеет; сборщик
фронтенда пришлось бы учить писать результат в чужое дерево.

### Собранного приложения в git нет, а сборка Go без него не ломается

Собранное не коммитится: это производное, и его версия в git разошлась бы с
исходниками молча. Но вшивание требует, чтобы каталог существовал в момент сборки
Go, иначе `go build ./...` отказывает у всякого, кто приложение не собирал.

Отсюда раскладка в два этажа. В git лежит **пустой каталог с меткой** —
`web/embed/.gitkeep`, — а сборщик пишет в `web/embed/dist`, то есть **этажом
ниже метки**. Так очистка выходного каталога, которую сборщик делает перед каждой
сборкой, метки не касается: положенная рядом с собранным, она уехала бы первым же
прогоном, а следом — удалённой в ближайший коммит, и `go build ./...` отказал бы
у всякого, кто клонировал заново.

Обработчик, не нашедший разметки, отвечает `503` и честной страницей «приложение
не собрано» — плюс строка в журнале при подъёме. Молча отдавать `404` он не
вправе: инвариант о неслучившемся молчании относится и к этому случаю.

**Что за сборка вшита, видно снаружи.** При подъёме в журнал уходит отпечаток
вшитой разметки. Иначе бинарник молча несёт вчерашнюю сборку — вне набора
проверок порядок шагов ничем не задан, и `go run .` вшивает то, что лежит с
прошлого раза, — а отличить «не та сборка» от «та» нечем: приложение открывается
и ведёт себя как прежняя версия.

Отвергнуто: **коммитить собранное** — производное в git, расходится с
исходниками. Отвергнуто: **ронять старт** без собранного приложения — сломало бы
`go test ./...` и `go run .` у того, кто правит только Go, а команды эти
объявлены в `CLAUDE.md` работающими.

### Заголовки кэширования назначаются, а не достаются умолчанию

Отдача файла в библиотеке заголовка кэширования не ставит вовсе, а вшитый файл не
несёт и времени правки: браузер остаётся с собственной догадкой о том, сколько
хранить копию. Догадка эта разная у разных браузеров, и проверить её со стороны
сервиса нечем.

Поэтому: **признаком служит каталог, а не вид файла.** Ресурс из каталога,
который наполняет сборщик, отдаётся с долгим сроком и пометкой «неизменяемо» —
имена там строит сборщик и несёт в них отпечаток содержимого, поэтому устареть
такой ответ не может. Всё прочее, включая разметку, — с требованием спрашивать
заново.

Признак назван каталогом потому, что вид файла его не даёт: в сборке лежат и
файлы с постоянными именами — иконка, манифест, а после `installable-pwa` ещё и
service worker, у которого отпечатка не бывает по устройству. Такой файл,
однажды отданный как «неизменяемый», не отзывается со стороны сервиса ничем:
запросов он больше не увидит, а у установленного на телефон приложения залипший
service worker означает, что новая сборка не доходит вовсе.

**Отпечаток в именах здесь не нормируется.** Его делает сборщик, сервис имён не
выбирает и их нарушения не заметит — значит это правило конвенции приложения, а
не спеки: спеки нормируют поведение сервиса, а инструмент, которым его собирают,
не нормируют вовсе (`architecture.md`, преамбула).

Долгий срок — год. Число живёт настройкой в [database.md](../../../docs/database.md),
«Настройки с числовым значением», как и прочие числа проекта.

### Node приходит отдельной ступенью образа

Ступеней в образе становится три: сборка приложения, сборка бинарника, рабочий
слой. Приложение собирается **до** бинарника, потому что вшивание требует
готового каталога. Рабочего слоя это не касается: Node в нём не остаётся.

Цена названа решением ADR и здесь только подтверждается: во что слой обходится
образу по времени и по весу, не замерялось — замер делает эта задача.

### Node не ставится на машину, а зовётся контейнером

Шаг сборки приложения гоняет установщик пакетов и сборщик **внутри контейнера**,
а не вызывает их из `PATH`. Требованием к машине разработчика становится docker,
которым и так собирается образ, — второго устанавливаемого окружения сверх
`ffmpeg` не появляется вовсе.

Так снимается расхождение, которое иначе завелось бы молча: версия Node на машине
разработчика и версия в образе — два разных числа, и собранное ими приложение
различается ровно тогда, когда различаются они. Обёртка берёт **тот же** образ,
которым собирает ступень `Dockerfile`.

Отсюда три частности, каждая из которых иначе кусается на первом же прогоне:

- **имя образа берётся из `Dockerfile`**, а не объявляется вторым числом в
  `Taskfile.yml`: второй дом версии разошёлся бы с первым, и сверять их было бы
  нечем — своего шага сверки у него, в отличие от версий Go, нет;
- **контейнер ходит под тем же пользователем, что и вызвавший**, иначе каталог
  зависимостей и собранное лягут от `root`, и убрать их с машины обычными
  средствами не выйдет;
- **кэш установщика уводится наружу контейнера**, в каталог под `/tmp`: под
  чужим пользователем домашнего каталога у контейнера нет, и установка иначе
  отказывает, а кэш внутри контейнера не пережил бы прогон — каждый набор
  проверок тянул бы зависимости заново, включая задачи, приложения не
  касающиеся. В git каталог не попадает по построению: он вне дерева проекта.

**Зависимости ставятся из файла замка командой, которая его не правит.** Иначе
шаг набора проверок правит отслеживаемый файл: обновление зависимости приезжает в
коммит без чьего-либо решения, а собранное в наборе проверок перестаёт совпадать
с собранным в образе. Обе половины молчаливы — набор проверок зелёный в обоих
случаях. Ту же команду зовёт и ступень `Dockerfile`.

**Шаг ходит в сеть, и это второй такой шаг в наборе проверок.** Установщик
обращается к реестру пакетов, а docker — к реестру образов; без сети шаг
краснеет. Отказ сети и реестра — **отказ окружения, код 3**, отдельно от красной
сборки, у которой код 1. Утверждение `CLAUDE.md` «шагу `vulns` нужна сеть, и он
один такой» перестаёт быть верным и правится этой же задачей: иначе следующий
читатель раздела «Гейт» получит неверную посылку.

Решение правит **последствие** [ADR-2026-08-11-spa-on-vue](../../../docs/adr/ADR-2026-08-11-spa-on-vue.md):
там записано, что Node и его установщик становятся нужны на машине
разработчика. Нужен docker; сам ADR при этом не пересматривается — выбор
фреймворка и наличие шага сборки остаются прежними.

Отвергнуто: **ставить Node на машину** — вводит второе устанавливаемое окружение
и разъезжается с версией в образе. Отвергнуто: **дать выбор — контейнер или
локальный Node** — это второй способ делать одно и то же, и собранное ими
различалось бы в зависимости от того, у кого что стоит.

### Код приложения проверяется машиной, а не глазами

Проверок у приложения две, и обе входят в набор проверок наравне со сборкой:
**Biome** — форматирование и статический анализ, **юнит-тесты Vue** — поведение
экрана, включая показ вошедшего и три ветки ответа на вопрос «кто вошёл».
Гоняются они тем же контейнером, что и сборка, — второго окружения не заводится.

Без них требование «приложение показывает вошедшего» — единственное, ради чего
задача заводится, — не проверял бы ни один шаг: набор проверок судил бы только
раздачу из Go и оставался зелёным на сломанном приложении. Ручная проверка эту
дыру не закрывает: следующая задача её не повторит.

Оговорка на Biome одна и проверяется первым же прогоном: если он не покрывает
разметку однофайловых компонентов, инструмент меняется. Решением владельца на
чекпоинте 2026-08-15 взят он, а замена — отдельное решение, не подстановка по
ходу.

### Шаг сборки приложения — первый в наборе проверок

Он стоит **перед** сборкой Go по той же причине: вшивается то, что собрано.
Недостающий docker — отказ окружения, код 3 по общему словарю (`CLAUDE.md`,
«Гейт»), наравне с недостающим компилятором C у шага тестов; красная сборка
приложения — код 1, отказ проверки наравне с `go build`.

## Границы

Экранов, кроме показа вошедшего, не делается: их заводят `upload-and-status-screen`
и `records-list-screen`. Установка на телефон, service worker и версионирование
статики — `installable-pwa`. Готовый набор компонентов не берётся: он не выбран,
а способен удвоить собранный файл.

## Открытые вопросы

- **Набор компонентов и стили** — не решено, дом вопроса
  [conventions/web-ui.md](../../../docs/conventions/web-ui.md), «Что не решено».
- **Во что слой Node обходится образу** — замеряется этой задачей, число уезжает
  в решение ADR последствием.