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:
@@ -7,6 +7,16 @@ type BaseDto struct {
|
||||
EndTime *int64 `json:"endTime" form:"endTime" validate:"omitempty,gt=0"` // Время окончания
|
||||
}
|
||||
|
||||
// Normalize: нулевая отметка времени — это отсутствие фильтра.
|
||||
//
|
||||
// Правило `omitempty,gt=0` на указателе не пропускается (см. normalize.go),
|
||||
// поэтому пришедший `startTime=0` отказывал бы вместо того, чтобы означать
|
||||
// «без ограничения снизу».
|
||||
func (d *BaseDto) Normalize() {
|
||||
zeroToNil(&d.StartTime)
|
||||
zeroToNil(&d.EndTime)
|
||||
}
|
||||
|
||||
type IdDto struct {
|
||||
Id *int64 `json:"id" form:"id" validate:"required,gt=0"` // Первичный ключ
|
||||
}
|
||||
|
||||
@@ -4,6 +4,11 @@ type LogDto struct {
|
||||
NumLine *int `json:"numLine" form:"numLine" validate:"omitempty,min=1,max=300"`
|
||||
}
|
||||
|
||||
// Normalize: «показать 0 строк» — это не запрос, а пропущенный параметр.
|
||||
func (d *LogDto) Normalize() {
|
||||
zeroToNil(&d.NumLine)
|
||||
}
|
||||
|
||||
type LogExportDto struct {
|
||||
Option *int `json:"option" form:"option" validate:"required,oneof=0 1"`
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
package dto
|
||||
|
||||
import "testing"
|
||||
|
||||
func strPtr(v string) *string { return &v }
|
||||
func i64Ptr(v int64) *int64 { return &v }
|
||||
func intPtr(v int) *int { return &v }
|
||||
|
||||
// Граница проходит по КАЖДОМУ полю отдельно, и это главное свойство
|
||||
// нормализации.
|
||||
//
|
||||
// Общее правило «пусто → не задано» выглядит соблазнительно и молча ломает
|
||||
// смысл: у комментария пустая строка означает «убрать пометку», у флага
|
||||
// disabled ноль — «включён», у квоты ноль — «нулевая квота». Тест закрепляет,
|
||||
// что эти три случая не попали под общий гребень.
|
||||
|
||||
func TestPeerSaveNormalizeTreatsBlankSecretAsAbsent(t *testing.T) {
|
||||
for _, blank := range []string{"", " ", "\t", "\n", " \t\n "} {
|
||||
d := PeerSaveDto{Name: strPtr("client-01"), Secret: strPtr(blank)}
|
||||
d.Normalize()
|
||||
if d.Secret != nil {
|
||||
t.Errorf("секрет %q не приведён к «не задано»: %q", blank, *d.Secret)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPeerSaveNormalizeKeepsManualSecretTrimmed(t *testing.T) {
|
||||
d := PeerSaveDto{Name: strPtr("client-01"), Secret: strPtr(" s3cret-value ")}
|
||||
d.Normalize()
|
||||
|
||||
if d.Secret == nil {
|
||||
t.Fatal("заданный секрет потерян")
|
||||
}
|
||||
if *d.Secret != "s3cret-value" {
|
||||
t.Fatalf("секрет не обрезан по краям: %q", *d.Secret)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPeerSaveNormalizeKeepsBlankRemarkAsValue(t *testing.T) {
|
||||
d := PeerSaveDto{Name: strPtr("client-01"), Remark: strPtr(" ")}
|
||||
d.Normalize()
|
||||
|
||||
if d.Remark == nil {
|
||||
t.Fatal("пустая пометка превращена в «не задано»: очистить комментарий станет нечем")
|
||||
}
|
||||
if *d.Remark != "" {
|
||||
t.Fatalf("пометка не обрезана: %q", *d.Remark)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPeerUpdateNormalizeTreatsBlankIdentityFieldsAsAbsent(t *testing.T) {
|
||||
d := PeerUpdateDto{Name: strPtr(" "), Secret: strPtr("")}
|
||||
d.Normalize()
|
||||
|
||||
if d.Name != nil {
|
||||
t.Error("пустое имя при изменении обязано означать «не менять»")
|
||||
}
|
||||
if d.Secret != nil {
|
||||
t.Error("пустой секрет при изменении обязан означать «не менять»")
|
||||
}
|
||||
}
|
||||
|
||||
func TestPeerUpdateNormalizeKeepsZeroValuedFlags(t *testing.T) {
|
||||
d := PeerUpdateDto{
|
||||
Disabled: i64Ptr(0),
|
||||
QuotaBytes: i64Ptr(0),
|
||||
MaxDevices: i64Ptr(1),
|
||||
}
|
||||
d.Normalize()
|
||||
|
||||
if d.Disabled == nil || *d.Disabled != 0 {
|
||||
t.Error("disabled=0 означает «включён», а не «не задано»")
|
||||
}
|
||||
if d.QuotaBytes == nil || *d.QuotaBytes != 0 {
|
||||
t.Error("quotaBytes=0 означает нулевую квоту, а не «не задано»")
|
||||
}
|
||||
}
|
||||
|
||||
// Регрессия: очищенный крестиком фильтр отправлялся как `?name=` и отказывал
|
||||
// правилом длины, то есть список пиров ломался в один клик.
|
||||
func TestPeerPageNormalizeDropsClearedFilters(t *testing.T) {
|
||||
d := PeerPageDto{Name: strPtr(""), Remark: strPtr(" ")}
|
||||
d.Normalize()
|
||||
|
||||
if d.Name != nil || d.Remark != nil {
|
||||
t.Fatalf("очищенный фильтр не снят: name=%v remark=%v", d.Name, d.Remark)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBaseNormalizeDropsZeroTimestamps(t *testing.T) {
|
||||
d := BaseDto{StartTime: i64Ptr(0), EndTime: i64Ptr(0)}
|
||||
d.Normalize()
|
||||
|
||||
if d.StartTime != nil || d.EndTime != nil {
|
||||
t.Fatal("нулевая отметка времени означает отсутствие фильтра")
|
||||
}
|
||||
|
||||
kept := BaseDto{StartTime: i64Ptr(1), EndTime: i64Ptr(2)}
|
||||
kept.Normalize()
|
||||
if kept.StartTime == nil || kept.EndTime == nil {
|
||||
t.Fatal("заданные отметки времени потеряны")
|
||||
}
|
||||
}
|
||||
|
||||
func TestLogNormalizeDropsZeroLineCount(t *testing.T) {
|
||||
d := LogDto{NumLine: intPtr(0)}
|
||||
d.Normalize()
|
||||
if d.NumLine != nil {
|
||||
t.Fatal("«показать 0 строк» — это пропущенный параметр, а не запрос")
|
||||
}
|
||||
}
|
||||
|
||||
// Все нормализуемые DTO обязаны реализовывать интерфейс: слой контроллеров
|
||||
// вызывает Normalize через него, и забытая реализация означала бы молча
|
||||
// пропущенный шаг.
|
||||
func TestNormalizableIsImplemented(t *testing.T) {
|
||||
var _ Normalizable = (*PeerSaveDto)(nil)
|
||||
var _ Normalizable = (*PeerUpdateDto)(nil)
|
||||
var _ Normalizable = (*PeerPageDto)(nil)
|
||||
var _ Normalizable = (*BaseDto)(nil)
|
||||
var _ Normalizable = (*LogDto)(nil)
|
||||
}
|
||||
+61
-7
@@ -1,31 +1,85 @@
|
||||
package dto
|
||||
|
||||
// Имя пира проверяется правилом `peerName`, которое несёт и набор символов, и
|
||||
// длину.
|
||||
//
|
||||
// Раньше здесь стояло `min=1,max=32,validateStr`, где `validateStr` требовал
|
||||
// 6-32 символа. Два правила на одном поле противоречили друг другу: имя из
|
||||
// трёх символов проходило `min=1` и отказывалось на `validateStr`, а оператор
|
||||
// видел «invalid» и подсказку «короткий идентификатор пира». Длина живёт
|
||||
// внутри одного правила, чтобы такого расхождения больше не было.
|
||||
|
||||
type PeerPageDto struct {
|
||||
BaseDto
|
||||
Name *string `json:"name" form:"name" validate:"omitempty,min=1,max=32"`
|
||||
Name *string `json:"name" form:"name" validate:"omitempty,max=32"`
|
||||
Disabled *int64 `json:"disabled" form:"disabled" validate:"omitempty,oneof=0 1"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,min=0,max=64"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,max=64"`
|
||||
}
|
||||
|
||||
// Normalize: очищенный фильтр — это отсутствие фильтра.
|
||||
//
|
||||
// Регрессия, которую это закрывает: `el-input` с крестиком очистки ставит
|
||||
// пустую строку, axios сериализует её как `?name=`, и поиск пиров отказывал с
|
||||
// «invalid» после нажатия на крестик.
|
||||
func (d *PeerPageDto) Normalize() {
|
||||
d.BaseDto.Normalize()
|
||||
blankToNil(&d.Name)
|
||||
blankToNil(&d.Remark)
|
||||
}
|
||||
|
||||
type PeerSaveDto struct {
|
||||
Name *string `json:"name" form:"name" validate:"required,min=1,max=32,validateStr"`
|
||||
Name *string `json:"name" form:"name" validate:"required,peerName"`
|
||||
Secret *string `json:"secret" form:"secret" validate:"omitempty,min=6,max=128"`
|
||||
QuotaBytes *int64 `json:"quotaBytes" form:"quotaBytes" validate:"required,min=-1"`
|
||||
ExpiresAt *int64 `json:"expiresAt" form:"expiresAt" validate:"required,min=0"`
|
||||
MaxDevices *int64 `json:"maxDevices" form:"maxDevices" validate:"required,min=1"`
|
||||
Disabled *int64 `json:"disabled" form:"disabled" validate:"required,oneof=0 1"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,min=0,max=64"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,max=64"`
|
||||
}
|
||||
|
||||
// Normalize: пустой секрет означает «сгенерируй сам».
|
||||
//
|
||||
// Именно это обещает подпись под полем, и именно это умеет CreatePeer. Пустая
|
||||
// пометка при этом остаётся пустой пометкой — «нет комментария» и «не менять
|
||||
// комментарий» не одно и то же.
|
||||
func (d *PeerSaveDto) Normalize() {
|
||||
trimValue(d.Name)
|
||||
blankToNil(&d.Secret)
|
||||
trimValue(d.Remark)
|
||||
}
|
||||
|
||||
type PeerUpdateDto struct {
|
||||
IdDto
|
||||
Name *string `json:"name" form:"name" validate:"omitempty,min=1,max=32,validateStr"`
|
||||
// Id приходит из пути `/peers/:id`, а не из тела, поэтому здесь он
|
||||
// НЕОБЯЗАТЕЛЕН.
|
||||
//
|
||||
// Раньше сюда встраивался IdDto с правилом `required,gt=0`, и тело запроса
|
||||
// обязано было повторять идентификатор, уже указанный в адресе. Панель его
|
||||
// повторяла, поэтому расхождение не проявлялось; любой другой клиент,
|
||||
// сделавший PATCH /peers/7 без `"id": 7` в теле, получал отказ «поле id
|
||||
// обязательно» — при том, что значение из тела всё равно затирается
|
||||
// значением из пути.
|
||||
Id *int64 `json:"id" form:"id" validate:"omitempty,gt=0"`
|
||||
Name *string `json:"name" form:"name" validate:"omitempty,peerName"`
|
||||
Secret *string `json:"secret" form:"secret" validate:"omitempty,min=6,max=128"`
|
||||
QuotaBytes *int64 `json:"quotaBytes" form:"quotaBytes" validate:"omitempty,min=-1"`
|
||||
ExpiresAt *int64 `json:"expiresAt" form:"expiresAt" validate:"omitempty,min=0"`
|
||||
MaxDevices *int64 `json:"maxDevices" form:"maxDevices" validate:"omitempty,min=1"`
|
||||
Disabled *int64 `json:"disabled" form:"disabled" validate:"omitempty,oneof=0 1"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,min=0,max=64"`
|
||||
Remark *string `json:"remark" form:"remark" validate:"omitempty,max=64"`
|
||||
}
|
||||
|
||||
// Normalize: при изменении пустое имя и пустой секрет означают «не менять».
|
||||
//
|
||||
// Ровно так их и читает service.UpdatePeer (`!= nil && != ""`), поэтому
|
||||
// приведение здесь не добавляет поведения, а убирает расхождение: без него
|
||||
// правила отказывали на входе, который сервис считает законным.
|
||||
//
|
||||
// `remark` и `disabled` намеренно не трогаются: пустая пометка и ноль — это
|
||||
// значения, которые оператор устанавливает осознанно.
|
||||
func (d *PeerUpdateDto) Normalize() {
|
||||
blankToNil(&d.Name)
|
||||
blankToNil(&d.Secret)
|
||||
trimValue(d.Remark)
|
||||
}
|
||||
|
||||
type PeerKickDto struct {
|
||||
|
||||
Reference in New Issue
Block a user