HY2XS_flamy/docs/acceptance/2026-09-01-v1.0.0-rc1-ux-findings.md

1.0.0-rc1 — дефекты приёмки и их закрытие

Относится к прогону 2026-09-01, v1.0.0-rc1.

Ни один из перечисленных дефектов не является P0 safety blocker и не дискредитирует пройденную server acceptance. Все они заметно ухудшают работу оператора и закрыты до финального v1.0.0.

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

Сводка

ID	Дефект	Приоритет	Статус
UX-01	Некорректный цвет SVG-иконок	P1	закрыт
UX-02	Необязательный секрет пира фактически обязателен	P1	закрыт
UX-03	Сообщение Invalid неинформативно	P1	закрыт
UX-04	Плейсхолдеры слишком персонализированы	P2	закрыт
UX-05	Нет атрибуции Flamy в боковом меню	P1	закрыт
EX-01	Фильтр списка пиров ломается после очистки	P1	закрыт
EX-02	Правила имени пира противоречили друг другу	P1	закрыт
EX-03	Набор символов имени пира допускал / : ; . ,	P1	закрыт
EX-04	Истечение сессии не обрабатывалось	P1	закрыт
EX-05	id требовался и в пути, и в теле запроса	P2	закрыт
EX-06	Обработчик транспортных ошибок падал сам	P2	закрыт

---

UX-01 — некорректный цвет SVG-иконок

Наблюдалось: иконки логина и бокового меню отображались почти чёрными и не соответствовали теме.

Корневая причина. Контракт currentColor в панели УЖЕ существовал — fill: currentcolor объявлен и в SvgIcon/index.vue, и в styles/sidebar.scss. Он не действовал, потому что восемь из семнадцати ассетов несли литеральный атрибут fill="#000000" прямо на <path>, а атрибут представления перебивает унаследованное CSS-свойство. Под это попали ВСЕ семь иконок бокового меню (report, users, hysteria, setting, error, log-system, log-hysteria) на фоне --menuBg: #181818, а также user на форме входа. Соседняя password литерального цвета не несёт и рисовалась белой — отсюда и ощущение, что иконки не соответствуют друг другу.

Ни одна существующая проверка этого не видела: гейт приёмки проверял у ассетов только наличие системы координат.

Как закрыто.

1. Литеральный цвет убран из монохромных ассетов: они несут fill="currentColor".
2. Многоцветные ассеты (download, upload) объявлены явным списком MULTICOLOR_ICONS и под проверку цвета не попадают — их палитра является частью ассета.
3. Преобразование файла в <symbol> и контракт ассета вынесены в чистый модуль SvgIcon/symbol.ts: без Vite и DOM, поэтому проверяются тестом и гейтом, а не только глазами на живой странице.
4. У SvgIcon убран проп color и атрибут fill на <use> — он приглашал чинить цвет точечно в обход общего контракта.
5. Цвета в рантайме НЕ переписываются: источник истины — файл. Молчаливая нормализация скрывала бы ровно тот дефект, который контракт обязан делать видимым.

Чем закреплено: tools/test/frontend-sprite.test.ts (контракт всех ассетов, обе ветки нормализации, наличие обеих половин контракта — ассета и CSS, запрет CSS-фильтров и селекторов по имени иконки) и соответствующие гейты приёмки в tools/build/lib/acceptance.sh.

Что проверяется вручную (машина этого не докажет): фактический цвет на светлой и тёмной теме, в состояниях hover и active, в свёрнутом меню.

---

UX-02 — необязательный секрет фактически обязателен

Наблюдалось: подпись под полем обещает «оставьте пустым — сгенерируем автоматически», пустое поле блокирует создание пира и выдаёт Invalid.

Корневая причина. Не отсутствие автогенерации: service.CreatePeer умел генерировать секрет и делал это. Запрос до неё не доходил.

В go-playground/validator тег omitempty НЕ пропускает правило, если поле объявлено указателем и указатель не nil. Помощник hasValue (baked_in.go):

if fl.(*validate).fldIsPointer && getValue(field) != nil {
    return true
}

Для *string, указывающего на пустую строку, это возвращает «значение есть». Панель отправляет secret: "", правило min=6 применяется к пустой строке и отказывает.

Как закрыто. Не тегом на одном поле, а механизмом: между разбором тела и проверкой правил добавлен шаг нормализации DTO (dto.Normalizable). Он приводит «поле отсутствует», «пустая строка» и «одни пробелы» к одному состоянию для тех полей, где отсутствие значения законно.

Граница проходит по каждому полю ОТДЕЛЬНО и это существенно: у remark пустая строка означает «убрать пометку», у disabled ноль означает «включён», у quotaBytes ноль — нулевую квоту. Общее правило «пусто → не задано» молча сломало бы все три.

Генерация названа явным шагом сервисного слоя — service.GeneratePeerSecret на базе util.RandomString (crypto/rand с отбрасыванием смещённых байтов). Тот же вызов используется импортом: пир, созданный формой, и пир, импортированный без секрета, теперь неотличимы.

Чем закреплено: матрица «отсутствует / пусто / пробелы / перевод строки → генерируется», границы 5 → отказ, 6 → приём, 128 → приём, 129 → отказ, неповторяемость сгенерированных секретов и — главное — проверка того, что сгенерированный секрет НЕМЕДЛЕННО аутентифицирует пира через service.Hysteria2Auth. То, что секрет записан, ничего не значит, пока по нему не проходит доступ.

---

UX-03 — сообщение Invalid неинформативно

Корневая причина. validateField схлопывал любую ошибку любого поля в constant.InvalidError = "invalid", а vo.Fail определял HTTP-семантику СРАВНЕНИЕМ текста сообщения с тремя известными литералами — тот же антипаттерн, который запрещён панели, только на сервере.

Как закрыто.

• Ответ об ошибке несёт errors: [{code, field, message, params}].
• Отказ разбора тела (body_invalid) отделён от нарушения правила.
• Коды правил различают границы числа и границы длины строки (min / min_length): оператору это разные фразы.
• Доменные отказы получили коды: peer_name_taken, peer_name_reserved, peer_bootstrap_identity_locked, invalid_credentials.
• vo больше не выводит код из текста — код передаётся аргументом.
• Панель выбирает локализованную фразу ПО КОДУ и подставляет причины под соответствующие поля формы; текст сервера остаётся ответом для клиента без UI и запасным вариантом для неизвестного кода.
• Числа правил приходят в params, поэтому второй копии границ в панели нет.

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

---

UX-04 — плейсхолдеры слишком персонализированы

Заменено на нейтральный компактный baseline:

Поле	Было	Стало
Имя	например, ivan-laptop	client-01
Комментарий	например, Ноутбук Ивана, отдел продаж	ноутбук

Префикс «например,» убран: плейсхолдер и так является примером. Подсказки под полями остались подробными; подсказка имени теперь называет фактические границы (6-32 символа).

---

UX-05 — атрибуция Flamy в боковом меню

Внизу бокового меню добавлена подпись «Разработано во Flamy», где Flamy — ссылка на https://flamy.studio фирменным цветом, с target="_blank" и rel="noopener noreferrer".

Адрес объявлен ОДИН раз в apps/frontend/src/constants/branding.ts и принадлежит приложению: он не читается ни из hy2xs.env, ни из config API, ни из таблицы config, ни из настроек панели. Оператор HY2XS не должен иметь возможности переназначить, куда ведёт подпись разработчика.

Вёрстка: высота области прокрутки меню вычитает $sidebarFooterHeight, поэтому пункты меню не могут наехать на подпись даже при длинном списке — им физически некуда. В свёрнутом меню (54 px) остаётся только имя-ссылка; на узком экране меню уходит в off-canvas на полную ширину.

Чем закреплено: tools/test/frontend-contract.test.ts — единственность адреса в исходниках панели, отсутствие его в операторских поверхностях, наличие футера в меню, учёт его высоты, атрибуты безопасности внешней ссылки. Плюс гейты приёмки.

---

Найдено сверх отчёта

EX-01 — фильтр списка пиров ломался после очистки

el-input с крестиком очистки ставит пустую строку, axios сериализует её как ?name=, и та же ловушка omitempty на указателе (см. UX-02) отказывала поиску пиров с invalid. Список пиров ломался в один клик по крестику.

Закрыто тем же механизмом нормализации; закреплено регрессионным тестом.

EX-02 — правила имени пира противоречили друг другу

На поле стояли min=1,max=32 И validateStr, требовавший 6-32 символа. Имя из трёх символов проходило одно правило и отказывалось на другом, а оператор видел invalid рядом с подсказкой «короткий идентификатор пира».

Длина перенесена внутрь одного правила peerName. Действующая граница — 6-32, то есть та, которая уже была задокументирована и закреплена тестами импорта.

EX-03 — набор символов имени пира допускал / : ; . ,

Слой контроллеров нёс собственную копию правила:

^[a-zA-Z0-9!@#$%^&*()_+-=]{6,32}$

с комментарием «тот же набор символов, что и у импорта». Набор был другим: дефис внутри класса не экранирован, поэтому +-= образует ДИАПАЗОН и впускает , - . / 0-9 : ; < =. Через панель проходило имя peer/name, которое импорт того же пира отклонял, — при том что имя пира уезжает во fragment клиентской ссылки и в автогенерируемый секрет.

Правило объявлено один раз (service.IsValidPeerName) и используется обеими дверями в таблицу пиров.

Набор символов ЛОГИНА администратора при этом сознательно НЕ сужен: он записан явно, но повторяет прежнее фактическое множество. Имя администратора приходит из HY2XS_ADMIN_USER, оркестратор его не ограничивает, и сужение правила означало бы, что установка с логином вроде admin.ops перестаёт пускать оператора в панель. Это закреплено отдельным тестом, чтобы попытка «навести порядок» роняла сборку, а не вход на живом сервере.

EX-04 — истечение сессии не обрабатывалось

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

Вдобавок истёкший токен уезжал с кодом системной ошибки: vo не узнавал token expired среди трёх известных строк.

Закрыто: ParseToken возвращает объявленные значения ошибок вместо свежих строк, middleware различает истечение и недействительность через errors.Is, ответ несёт код session_expired, панель показывает диалог и возвращает на форму входа. Диалог показывается один раз, даже когда истёкший токен уронил несколько параллельных запросов страницы.

Побочно: сброс сессии больше не зовёт localStorage.clear(), который заодно стирал выбранный оператором язык панели.

EX-05 — id требовался и в пути, и в теле

PeerUpdateDto встраивал IdDto с правилом required, поэтому тело запроса обязано было повторять идентификатор из адреса. Панель его повторяла, поэтому расхождение не проявлялось; любой другой клиент, сделавший PATCH /peers/7 без "id": 7 в теле, получал отказ — при том что значение из тела всё равно затирается значением из пути.

Заодно убрана недостижимая запасная ветка resolveID, читавшая идентификатор из тела: она вызывала разбор тела, которое обработчик читает следом второй раз, а gin его не буферизует. То есть запасной путь не сработал бы ровно тогда, когда понадобился бы.

EX-06 — обработчик транспортных ошибок падал сам

Обработчик читал error.response.data, не проверив error.response. При обрыве соединения или таймауте он падал с TypeError и подменял настоящую причину отказом внутри себя. Теперь сетевой отказ отличается от отказа сервера и сообщается отдельной фразой.

---

Что осталось сделать до финального v1.0.0

1. пересобрать rc2 и повторить build/security acceptance;
2. установить rc2 на тестовый хост;
3. проверить визуально: цвет иконок в обеих темах, hover/active, свёрнутое меню, подпись Flamy на узком экране;
4. проверить создание пира с пустым секретом и работоспособность его share URI на живом сервере;
5. выполнить reconfigure/fault matrix D1-D1h на rc2;
6. выполнить reboot acceptance;
7. отдельно проверить Salamander fallback;
8. после готовности HY2XS Desktop — внешний Gecko E2E;
9. удалить или пересоздать тестовый пир, чья URI была выведена за пределы admin UI во время прогона rc1.