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 после разнесения по каталогам совпадал бы ровно с одним файлом.
2026-09-01 07:27:15 +05:00
parent a1f0db22c2
commit c0a43ae915
86 changed files with 6237 additions and 1819 deletions
@@ -12,18 +12,18 @@ func AdminHandler() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		claimsRaw, ok := c.Get("adminClaims")
 		if !ok {
-			vo.Fail(constant.UnauthorizedError, c)
+			vo.FailUnauthorized(constant.ErrCodeUnauthorized, constant.UnauthorizedError, c)
 			c.Abort()
 			return
 		}
 		claims, castOK := claimsRaw.(bo.AccountBo)
 		if !castOK {
-			vo.Fail(constant.IllegalTokenError, c)
+			vo.FailUnauthorized(constant.ErrCodeTokenInvalid, constant.IllegalTokenError, c)
 			c.Abort()
 			return
 		}
 		if !util.ArrContain(claims.Roles, "admin") {
-			vo.Fail(constant.ForbiddenError, c)
+			vo.FailForbidden(constant.ForbiddenError, c)
 			c.Abort()
 			return
 		}
@@ -1,41 +1,62 @@
 package middleware

 import (
+	"errors"
+	"strings"
+
 	"github.com/gin-gonic/gin"
 	"hy2xs-admin/model/constant"
 	"hy2xs-admin/model/vo"
 	"hy2xs-admin/service"
-	"strings"
 )

+// Отказ аутентификации несёт КОД состояния сессии.
+//
+// Раньше все ветки здесь звали vo.Fail с человеческой строкой, а код ответа
+// выводился в vo сравнением этой строки с тремя известными литералами. Под
+// условия подходил только `unauthorized`; `token expired` и `authentication
+// failed` уезжали к панели как обычная системная ошибка с кодом 50000.
+//
+// Следствие было видимым для оператора: истёкшая сессия на открытой странице
+// давала голый тост «token expired», ветка «войдите заново» не срабатывала
+// никогда, а перебросить на форму входа мог только переход по маршруту,
+// которому потребовался бы getAdminInfo. Ключ локализации `common.sessionExpired`
+// при этом существовал и был мёртвым.
 func JWTHandler() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		authHeader := c.Request.Header.Get("Authorization")
 		if authHeader == "" {
-			vo.Fail(constant.UnauthorizedError, c)
+			vo.FailUnauthorized(constant.ErrCodeUnauthorized, constant.UnauthorizedError, c)
 			c.Abort()
 			return
 		}
 		parts := strings.SplitN(authHeader, " ", 2)
 		if !(len(parts) == 2 && parts[0] == "Bearer") {
-			vo.Fail(constant.IllegalTokenError, c)
+			vo.FailUnauthorized(constant.ErrCodeTokenInvalid, constant.IllegalTokenError, c)
 			c.Abort()
 			return
 		}
 		myClaims, err := service.ParseToken(parts[1])
 		if err != nil {
-			vo.Fail(err.Error(), c)
+			vo.FailUnauthorized(tokenErrorCode(err), err.Error(), c)
 			c.Abort()
 			return
 		}
 		admin, err := service.GetAdminForTokenValidation(myClaims.Admin.Id)
 		if err != nil {
+			// Это уже не состояние сессии, а отказ чтения учётной записи:
+			// сворачивать его в «войдите заново» значило бы отправлять
+			// оператора на форму входа при недоступной базе.
 			vo.Fail(err.Error(), c)
 			c.Abort()
 			return
 		}
 		if admin.Status != nil && *admin.Status != 1 {
-			vo.Fail("this account has been disabled", c)
+			vo.FailUnauthorized(
+				constant.ErrCodeAccountDisabled,
+				"this account has been disabled",
+				c,
+			)
 			c.Abort()
 			return
 		}
@@ -44,7 +65,9 @@ func JWTHandler() gin.HandlerFunc {
 			tokenVersion = *admin.TokenVersion
 		}
 		if myClaims.Admin.TokenVersion != tokenVersion {
-			vo.Fail(constant.IllegalTokenError, c)
+			// Версия токена сменилась: пароль изменён или доступ отозван.
+			// Для оператора это неотличимо от истёкшей сессии — вход заново.
+			vo.FailUnauthorized(constant.ErrCodeSessionExpired, constant.IllegalTokenError, c)
 			c.Abort()
 			return
 		}
@@ -52,3 +75,21 @@ func JWTHandler() gin.HandlerFunc {
 		c.Next()
 	}
 }
+
+// tokenErrorCode различает истёкший токен и недействительный.
+//
+// Вопрос задаётся ЗНАЧЕНИЮ ошибки, а не её тексту: service.ParseToken
+// возвращает объявленные значения, поэтому правка формулировки сообщения не
+// может молча превратить истёкшую сессию в неизвестную ошибку.
+//
+// Отказ прочитать ключ подписи (недоступная база) сюда тоже приходит, и это
+// НЕ состояние сессии. Отдельного кода он не получает намеренно: снаружи
+// панели такой отказ неотличим от недействительного токена, и предлагать
+// оператору войти заново — единственное осмысленное действие, которое ему
+// доступно.
+func tokenErrorCode(err error) string {
+	if errors.Is(err, service.ErrTokenExpired) {
+		return constant.ErrCodeSessionExpired
+	}
+	return constant.ErrCodeTokenInvalid
+}
@@ -0,0 +1,90 @@
+package middleware
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"hy2xs-admin/model/constant"
+	"hy2xs-admin/model/vo"
+	"hy2xs-admin/service"
+)
+
+// Состояние сессии сообщается КОДОМ, а не текстом.
+//
+// Регрессия. Все отказы аутентификации звали vo.Fail с человеческой строкой, а
+// код ответа выводился сравнением этой строки с тремя известными литералами.
+// Под условия подходил только `unauthorized`; истёкший токен уезжал с кодом
+// системной ошибки 50000, панель показывала оператору голый тост
+// «token expired» и не понимала, что сессия кончилась. Ключ локализации
+// common.sessionExpired существовал и был мёртвым, а вернуть оператора на
+// форму входа мог только переход по маршруту, которому потребовался бы
+// getAdminInfo.
+
+type authResponse struct {
+	Code   int             `json:"code"`
+	Type   string          `json:"type"`
+	Errors []vo.FieldError `json:"errors"`
+}
+
+func callJWTHandler(t *testing.T, header string) authResponse {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+
+	engine := gin.New()
+	engine.GET("/guarded", JWTHandler(), func(c *gin.Context) {
+		vo.Success(nil, c)
+	})
+
+	request := httptest.NewRequest(http.MethodGet, "/guarded", nil)
+	if header != "" {
+		request.Header.Set("Authorization", header)
+	}
+	recorder := httptest.NewRecorder()
+	engine.ServeHTTP(recorder, request)
+
+	var parsed authResponse
+	if err := json.Unmarshal(recorder.Body.Bytes(), &parsed); err != nil {
+		t.Fatalf("ответ не разбирается как JSON: %s", recorder.Body.String())
+	}
+	return parsed
+}
+
+func TestJWTHandlerReportsMissingCredentials(t *testing.T) {
+	response := callJWTHandler(t, "")
+
+	if response.Code != constant.CodeUnauthorizedError {
+		t.Fatalf("код ответа %d, ожидался %d", response.Code, constant.CodeUnauthorizedError)
+	}
+	if len(response.Errors) != 1 || response.Errors[0].Code != constant.ErrCodeUnauthorized {
+		t.Fatalf("неожиданное описание отказа: %+v", response.Errors)
+	}
+}
+
+func TestJWTHandlerReportsMalformedAuthorizationHeader(t *testing.T) {
+	for _, header := range []string{"token-without-scheme", "Basic dXNlcjpwYXNz"} {
+		response := callJWTHandler(t, header)
+
+		if response.Code != constant.CodeUnauthorizedError {
+			t.Errorf("заголовок %q: код ответа %d, ожидался %d",
+				header, response.Code, constant.CodeUnauthorizedError)
+			continue
+		}
+		if len(response.Errors) != 1 || response.Errors[0].Code != constant.ErrCodeTokenInvalid {
+			t.Errorf("заголовок %q: неожиданное описание отказа: %+v", header, response.Errors)
+		}
+	}
+}
+
+// Истёкшая сессия обязана быть отличима от недействительного токена: панель
+// показывает оператору разные вещи и по-разному его возвращает на вход.
+func TestTokenErrorCodeSeparatesExpiryFromInvalidity(t *testing.T) {
+	if code := tokenErrorCode(service.ErrTokenExpired); code != constant.ErrCodeSessionExpired {
+		t.Errorf("истёкший токен получил код %q, ожидался %q", code, constant.ErrCodeSessionExpired)
+	}
+	if code := tokenErrorCode(service.ErrTokenInvalid); code != constant.ErrCodeTokenInvalid {
+		t.Errorf("недействительный токен получил код %q, ожидался %q", code, constant.ErrCodeTokenInvalid)
+	}
+}