fix(admin): закрыть обещания панели, которые продукт не выполнял

Девятый проход, по итогам приёмки v1.0.0-rc1 на живом Debian 13. Общая тема:
интерфейс обещал оператору то, что продукт умел, но до чего не доходило
управление.

Секрет пира. Подпись под полем предлагала оставить его пустым, сервер умел его
сгенерировать, и генерация была недостижима: в go-playground/validator тег
omitempty НЕ пропускает правило, если поле объявлено указателем и указатель не
nil — hasValue считает указатель на пустую строку «значением». Правило min=6
применялось к пустой строке и отказывало. Ловушка закрыта общим шагом
нормализации DTO, а не тегом на одном поле: та же ловушка ломала фильтр списка
пиров, где очищенный крестиком el-input отправляет `?name=`. Граница проходит по
каждому полю отдельно — у remark пустая строка означает «убрать пометку», у
disabled ноль означает «включён».

Отказы. Любая ошибка любого поля превращалась в слово `invalid`, а слой vo
определял код ответа СРАВНЕНИЕМ текста сообщения — тот же антипаттерн, который
запрещён панели, только на сервере. Ответ несёт errors[{code, field, message,
params}]; панель выбирает фразу по коду и подставляет причины под поля.

Сессия. Ветка «войдите заново» была недостижима дважды: сервер отвечает HTTP 200
на любой отказ, поэтому обработчик ошибок axios не вызывался, а условие в нём
проверяло code === "A0230" и поле msg, которых в этом API никогда не было.
Истёкший токен вдобавок уезжал с кодом системной ошибки.

Иконки. Контракт currentColor был объявлен в двух местах и не действовал: восемь
ассетов несли литеральный fill="#000000" на <path>, а атрибут представления
перебивает унаследованное CSS-свойство. Под это попадали все семь иконок
бокового меню на фоне #181818.

Имя пира. Два правила на одном поле противоречили друг другу (min=1 против
6-32), а копия набора символов в слое контроллеров несла неэкранированный дефис
и впускала `, - . / : ; <` — через панель проходило имя peer/name, которое
импорт того же пира отклонял. Набор символов ЛОГИНА сознательно не сужен и
закреплён тестом: он приходит из HY2XS_ADMIN_USER и оркестратором не
ограничивается.

Добавлены подпись «Разработано во Flamy» с адресом, принадлежащим приложению, и
контрактные тесты панели как обязательный шаг сборки. Их исполняет Bun, а не
vitest: jsdom не вычисляет currentColor и визуальной корректности не доказал бы,
зато vitest привёл бы в граф pnpm audit сотню транзитивных зависимостей.

docs/ разложена по слоям, 11-testing-and-acceptance.md (117 КБ) разбит на пять
частей, добавлен docs/acceptance/ с отчётом о прогоне rc1 и перечнем дефектов.
Обход документации в приёмке стал рекурсивным: плоский docs/*.md после
разнесения по каталогам совпадал бы ровно с одним файлом.
This commit is contained in:
2026-09-01 07:27:15 +05:00
parent a1f0db22c2
commit c0a43ae915
86 changed files with 6237 additions and 1819 deletions
+81
View File
@@ -0,0 +1,81 @@
package dto
import "strings"
// Приведение входа к каноничному виду ДО проверки правил.
//
// Зачем это нужно. В go-playground/validator тег `omitempty` НЕ пропускает
// правило, если поле объявлено указателем, а указатель не nil. Помощник
// `hasValue` (baked_in.go) устроен так:
//
// if fl.(*validate).fldIsPointer && getValue(field) != nil {
// return true
// }
//
// Для `*string`, указывающего на пустую строку, это возвращает true, то есть
// «значение есть». В результате `omitempty,min=6` на поле `Secret` срабатывало
// именно тогда, когда оператор НИЧЕГО не ввёл: панель отправляла `secret: ""`,
// правило `min=6` применялось к пустой строке и отказывало. Панель при этом
// писала под полем «оставьте пустым — сгенерируем автоматически», а сервер
// умел это сделать: генерация в CreatePeer существовала и была недостижима.
//
// Чинить это тегом на одном поле бессмысленно: ловушка одинаково стоит на
// фильтре списка пиров (очищенный `el-input` шлёт `?name=`, правило `min=1`
// отказывает поиску), на необязательных отметках времени и на всяком будущем
// необязательном поле-указателе. Поэтому нормализация — общий шаг конвейера, а
// не особый случай «если пусто, подставь строку».
//
// Правило формулируется ПОФАКТИЧЕСКИ, для каждого поля отдельно, и это
// сознательно. Пустая строка не везде означает «не задано»: у `remark` она
// означает «очистить пометку», и общее «пусто → nil» молча лишило бы оператора
// возможности её убрать. Ноль у `disabled` и `quotaBytes` — законное значение,
// а не пропуск.
// Normalizable — DTO, приводящее свой вход к каноничному виду.
//
// Вызывается слоем контроллеров между разбором тела и проверкой правил, то
// есть ровно один раз и для всех дверей одинаково.
type Normalizable interface {
Normalize()
}
// blankToNil: «пусто или одни пробелы» становится «не задано».
//
// Применяется к полям, у которых отсутствие значения — законный вход.
func blankToNil(field **string) {
if *field == nil {
return
}
trimmed := strings.TrimSpace(**field)
if trimmed == "" {
*field = nil
return
}
*field = &trimmed
}
// trimValue убирает окружающие пробелы, сохраняя само поле заданным.
//
// Применяется к обязательным полям и к тем, у которых пустая строка — это
// значение, а не пропуск. Пустой ввод после тримминга остаётся пустым и
// получит внятный отказ от `required`, а не молча превратится в «не задано».
func trimValue(field *string) {
if field == nil {
return
}
*field = strings.TrimSpace(*field)
}
// zeroToNil: ноль у необязательного числового поля означает «не задано».
//
// Применяется ТОЛЬКО там, где ноль не является осмысленным значением:
// «показать 0 строк журнала» и «время начала — 1 января 1970 года» — это
// пропуск фильтра, а не запрос.
func zeroToNil[T int | int64](field **T) {
if *field == nil {
return
}
if **field == 0 {
*field = nil
}
}