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
@@ -117,6 +117,70 @@ Hardening-проход перед релизом `1.0.0`. Основная те
`versions.env` и раньше; машина разработчика не проверялась никак, и
расхождение обнаруживалось на Debian, внутри release-сборки.
### Изменено — модернизация frontend
Известное ограничение «проверка типов frontend почти ничего не проверяет»
закрыто и удалено из документации.
- **`vue-tsc` стал настоящим release gate.** Он был версии `0.35.0` (2022 год) и
шаблоны Vue не типизировал: проверка проходила зелёной, не давая обещанной
гарантии. На Vue 3.5 она к тому же ломается сама, не зная `vue/jsx-runtime`, —
то есть пережить обновление Vue не могла в любом случае.
Современный `vue-tsc 3.3` на том же коде дал **142 ошибки**, а не ~155 из
прогноза, и картина оказалась однороднее: 141 × `TS18048` и одна `TS2322`,
всё в двух файлах представления Hysteria. Ожидавшегося класса «`DefaultRow`
несовместим с `PeerVo`» на Element Plus 2.3 не существовало — он появился
вместе с обновлением Element Plus до 2.14.
Скрипты разделены: `typecheck`, `build:prod`, `verify`. Сборка запускает
проверку типов **до** bundle; раньше `vite build && vue-tsc` сначала тратил
время на production bundle и только потом сообщал о типовой ошибке.
- **Нормализация конфига Hysteria на границе API.** Все 142 ошибки — обращения
к необязательным секциям конфига в шаблоне. Необязательны они правильно: так
устроен upstream YAML. Инвариант «секция есть всегда» существовал, но держался
на порядке присваиваний внутри компонента и типом не выражался. Введён
`Hysteria2ServerConfigView`, выводимый из модели ответа типом, а не вторым
списком полей, — вместо 141 оператора `?.` или `as any`.
- **Убраны три редактора, которые ничего не сохраняли.** Outbounds, список
значений и словарь «ключ — значение» на странице конфига Hysteria: страница
отрисована с `:disabled="true"`, значения передаются без `v-model`, маршрутов
записи серверного конфига в API нет. Оператор мог добавить outbound, увидеть
его в списке и уйти в уверенности, что изменил конфигурацию сервера.
У одного цена была ещё и измеримой: `vuedraggable` поставляется UMD-сборкой,
поэтому её `require("vue")` разрешался в полную сборку Vue с
рантайм-компилятором — около полумегабайта в bundle ради перетаскивания тегов
в недоступной для редактирования форме.
- **`pnpm audit` по всему графу: 33 предупреждения → 0.** Из них четыре
затрагивали production-зависимости (`vue-i18n`, `echarts`), остальные —
build-цепочку. Среди последних был rollup GHSA DOM clobbering, а он
затрагивает **генерируемый bundle**, то есть уезжает в production: `pnpm audit
--prod`, на который смотрит gate сборки, его не показывал.
Обновлены: Vue 3.2 → 3.5, TypeScript 4.9 → 5.9, Element Plus 2.3 → 2.14,
Vue Router 4.1 → 4.6, Pinia 2.0 → 2.3, VueUse 9 → 14, echarts 5 → 6,
Vite 4.3 → 7.3, eslint 8 → 10 (с переходом на flat config), stylelint 15 → 17.
Pinia 3, Vue Router 5 и Vite 8 сознательно не берутся: Vite 8 — это переезд на
Rolldown, остальные не дают проекту ничего, кроме номера версии.
- **`vite-plugin-svg-icons` заменён собственным спрайтом.** Плагин не
обновлялся с 2022 года и тянул `svgo 2.8`, `postcss 5.2.18` и
`image-size 0.5.5`, у которой advisory сообщает `Patched versions: <0.0.0`
исправленной версии не существует. Проверка на реальных ассетах поймала то,
что иначе уехало бы в релиз: три иконки из семнадцати не объявляют `viewBox`,
и без его синтеза из `width`/`height` отрисовывались бы обрезанными.
- **Разбор bundle через sourcemap** нашёл вторую потерю: `@vueuse/core`
собирался дважды — наш и тот, что тянет Element Plus. Версии сведены.
Итог по размеру: 2 819 722 байта против 2 404 202 на исходной базовой линии.
Рост в 17% — цена Vue 3.5, Element Plus 2.14, echarts 6 и rollup 4;
промежуточное состояние до двух исправлений выше было 3 046 172.
### Исправлено — сборка не собиралась
- **`build.sh` детектировал сам себя и падал шестым шагом из четырнадцати.**