docs: сделать проверку типов frontend release gate и убрать известное ограничение

bundle_ui запускает `pnpm run typecheck` перед сборкой bundle. И наличие шага,
и его порядок закреплены приёмкой — вместе с требованием vue-tsc версии 3 и
выше и с запретом снова совмещать сборку и проверку в build:prod.

Из docs/02 убран раздел «Известное ограничение: проверка типов frontend почти
ничего не проверяет» и заменён описанием действующего контракта. Прогноз в нём
был близок, но неточен: ошибок оказалось 142, а не ~155, и класс DefaultRow/
PeerVo на Element Plus 2.3 не существовал вовсе — он появился вместе с
обновлением Element Plus.

docs/04 получил описание модели отображения (третий слой рядом с типизированной
моделью и сырым YAML) и раздел о том, что страница Hysteria теперь read-only на
всех уровнях, а не только визуально.

docs/11: команды проверки frontend и dev doctor в раздел запуска, семь новых
пунктов приёмки.
This commit is contained in:
2026-08-30 07:44:51 +05:00
parent 32ff47731c
commit 219bb364bc
6 changed files with 209 additions and 18 deletions
+64
View File
@@ -354,6 +354,70 @@ AES-GCM. Значение без этого префикса — не «форм
- будущие версии Hysteria не ломают экспорт только потому, что backend и frontend ещё не научились показывать новый параметр;
- это прямое следствие модели «latest stable на сборке»: схема upstream может опережать модель HY2XS.
### Третий слой: модель отображения
У типизированной модели есть подслой, о котором стоит сказать отдельно, потому
что он определяет, как устроены шаблоны страницы Hysteria.
`Hysteria2ServerConfig` описывает то, что **приходит по сети**, и почти все его
секции необязательны — ровно так же, как в upstream YAML. Форма же обращается к
ним напрямую: `dataForm.tls.cert`, `dataForm.acme.dns.config`,
`dataForm.resolver.https.sni`.
Пока проверка типов SFC-шаблонов не работала, это выглядело безобидно.
Современный `vue-tsc` даёт на этом 141 ошибку `TS18048` — и он прав: обращение
через возможно отсутствующий объект падает в рантайме. Спасало то, что форма
строится merge'ем поверх полного объекта значений по умолчанию, то есть
инвариант «секция есть всегда» существовал, но держался на порядке присваиваний
внутри компонента и нигде не был выражен типом.
Закрыто одним преобразованием на границе, а не 141 оператором `?.` и не
`as any`:
```text
ответ API (Hysteria2ServerConfig, секции необязательны)
normalizeHysteriaViewModel()
Hysteria2ServerConfigView — все секции обязательны
шаблон
```
`Hysteria2ServerConfigView` выводится из `Hysteria2ServerConfig` типом, а не
пишется вторым списком полей. Поэтому новая секция в схеме ломает компиляцию на
объекте значений по умолчанию — то есть поле upstream нельзя молча не
отобразить.
Побочное следствие: `v-if` в шаблоне перестали проверять присутствие секции и
проверяют только то, что действительно определяет выбор ветки. Например для
обфускации это `dataForm.obfs.type === 'gecko'` вместо
`dataForm.obfs.type === 'gecko' && dataForm.obfs.gecko` — вторая половина
дублировала первую и существовала только из-за необязательности типа.
Этот слой не участвует в экспорте: выгрузка идёт от исходного YAML и сохраняет
неизвестные поля, поэтому их потеря в модели отображения безвредна.
### Страница Hysteria — только чтение, и теперь это верно на всех уровнях
Страница отрисована с `:disabled="true"` и прямо сообщает, что конфигом владеет
`hy2xs-orchestrator reconfigure`. Маршрутов записи серверного конфига в API нет
— они удалены вместе с мёртвым updater/config-write слоем.
Тем не менее на ней жили три полноценных редактора: outbounds (кнопка «+»,
диалог создания, удаление), список значений (перетаскивание тегов, добавление,
удаление) и словарь «ключ — значение». Ни один не мог ничего сохранить: значения
передаются в них как `:outbounds=`, `:tags=`, `:map-object=` — без `v-model`,
то есть у их событий `update:*` нет ни одного слушателя. Оператор мог добавить
outbound, увидеть его в списке и уйти в уверенности, что изменил конфигурацию
сервера; изменения не переживали даже переключения вкладки.
Все три приведены к отображению. У одного из них цена была ещё и измеримой:
редактор списка значений работал на `vuedraggable`, которая поставляется
UMD-сборкой, поэтому её `require("vue")` разрешался в полную сборку Vue вместе с
рантайм-компилятором шаблонов — около полумегабайта в bundle ради
перетаскивания тегов в недоступной для редактирования форме.
### Санитайз экспорта
Экспортируемый файл покидает сервер, поэтому секреты из него вырезаются: