fix: 设计原则审查修复 — DIP/ISP, LoD, DRY, OCP, URL, 301缓存

- P0 DIP+ISP: 全链路注入接口，消除零接口紧耦合
- P0 URL: auth 301→302，修复登出后浏览器缓存陷阱
- P1 DRY: JWT 认证逻辑收敛至 TokenService+中间件
- P2 DRY: 前后端角色/状态映射统一为 model 常量
- P2 LoD: 新增 SettingsController，router 不再跨层调 repo
- P2 URL: settings ?tab= → /settings/:tab 伪静态
- P3 OCP: 角色权限 map 化，告别硬编码 switch

internal/middleware/auth.go

@@ -2,12 +2,12 @@ package middleware
 
 import (
 	"log"
+	"net/http"
 	"strings"
 	"time"
 
 	"metazone.cc/metalab/internal/common"
 	"metazone.cc/metalab/internal/config"
-	"metazone.cc/metalab/internal/repository"
 
 	"github.com/gin-gonic/gin"
 	"github.com/golang-jwt/jwt/v5"
@@ -16,11 +16,11 @@ import (
 // AuthMiddleware 认证中间件（结构体模式，持有 DB 依赖用于实时令牌吊销校验）
 type AuthMiddleware struct {
 	cfg      *config.Config
-	userRepo *repository.UserRepo
+	userRepo tokenVersionStore
 }
 
 // NewAuthMiddleware 构造函数
-func NewAuthMiddleware(cfg *config.Config, userRepo *repository.UserRepo) *AuthMiddleware {
+func NewAuthMiddleware(cfg *config.Config, userRepo tokenVersionStore) *AuthMiddleware {
 	return &AuthMiddleware{cfg: cfg, userRepo: userRepo}
 }
 
@@ -28,15 +28,7 @@ func NewAuthMiddleware(cfg *config.Config, userRepo *repository.UserRepo) *AuthM
 // 令牌版本与 DB 不匹配时即时拒绝，实现实时吊销
 func (am *AuthMiddleware) Required() gin.HandlerFunc {
 	return func(c *gin.Context) {
-		tokenStr, err := c.Cookie(common.CookieName)
-		if err != nil {
-			c.AbortWithStatusJSON(401, gin.H{
-				"success": false, "message": "请先登录",
-			})
-			return
-		}
-
-		claims, err := parseToken(tokenStr, am.cfg.JWT.Secret)
+		claims, err := am.authenticateToken(c)
 		if err != nil {
 			common.ClearAuthCookies(c, am.cfg)
 			c.AbortWithStatusJSON(401, gin.H{
@@ -45,27 +37,7 @@ func (am *AuthMiddleware) Required() gin.HandlerFunc {
 			return
 		}
 
-		uid := uint(claims["uid"].(float64))
-		tokenVer := int(claims["ver"].(float64))
-
-		// 即时吊销检查：查询 DB 当前版本号，不匹配则拒绝
-		currentVer, err := am.userRepo.FindTokenVersion(uid)
-		if err != nil || tokenVer != currentVer {
-			if tokenVer != currentVer {
-				log.Printf("[AuthRequired] REVOKED: uid=%d tokenVer=%d dbVer=%d", uid, tokenVer, currentVer)
-			}
-			common.ClearAuthCookies(c, am.cfg)
-			c.AbortWithStatusJSON(401, gin.H{
-				"success": false, "message": "登录凭证已失效，请重新登录",
-			})
-			return
-		}
-
-		// 注入用户信息到上下文
-		c.Set("uid", uid)
-		c.Set("email", claims["email"])
-		c.Set("username", claims["username"])
-		c.Set("role", claims["role"])
+		injectUserContext(c, claims)
 		c.Next()
 	}
 }
@@ -73,41 +45,72 @@ func (am *AuthMiddleware) Required() gin.HandlerFunc {
 // Optional 可选认证：已登录且版本通过则注入，未登录或版本不匹配也放行（仅清除过期 Cookie）
 func (am *AuthMiddleware) Optional() gin.HandlerFunc {
 	return func(c *gin.Context) {
-		tokenStr, err := c.Cookie(common.CookieName)
+		claims, err := am.authenticateToken(c)
 		if err != nil {
-			log.Println("[AuthOptional] no cookie for", c.Request.URL.Path)
-			c.Next()
-			return
-		}
-		claims, err := parseToken(tokenStr, am.cfg.JWT.Secret)
-		if err != nil {
-			log.Printf("[AuthOptional] JWT parse failed for %s: %v", c.Request.URL.Path, err)
-			c.Next()
-			return
-		}
-
-		uid := uint(claims["uid"].(float64))
-		tokenVer := int(claims["ver"].(float64))
-
-		// 即时吊销检查
-		currentVer, err := am.userRepo.FindTokenVersion(uid)
-		if err != nil || tokenVer != currentVer {
-			log.Printf("[AuthOptional] REVOKED or err: uid=%d tokenVer=%d dbVer=%d err=%v",
-				uid, tokenVer, currentVer, err)
-			// 已吊销：清除 Cookie，但仍放行（页面视图，前端自行处理）
+			log.Printf("[AuthOptional] token invalid for %s: %v", c.Request.URL.Path, err)
 			c.Next()
 			return
 		}
 
 		log.Printf("[AuthOptional] OK: uid=%v username=%v path=%s", claims["uid"], claims["username"], c.Request.URL.Path)
-		c.Set("uid", uid)
-		c.Set("email", claims["email"])
-		c.Set("username", claims["username"])
-		c.Set("role", claims["role"])
+		injectUserContext(c, claims)
 		c.Next()
 	}
 }
 
+// AdminAuth 管理后台页面认证：失败时 302 跳首页而非返回 JSON
+func (am *AuthMiddleware) AdminAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		claims, err := am.authenticateToken(c)
+		if err != nil {
+			log.Printf("[AdminAuth] auth failed path=%s err=%v → 302", c.Request.URL.Path, err)
+			common.ClearAuthCookies(c, am.cfg)
+			c.Redirect(http.StatusFound, "/")
+			c.Abort()
+			return
+		}
+
+		log.Printf("[AdminAuth] OK: uid=%d role=%v path=%s", uint(claims["uid"].(float64)), claims["role"], c.Request.URL.Path)
+		injectUserContext(c, claims)
+		c.Next()
+	}
+}
+
+// authenticateToken 统一的认证核心流程：读 Cookie → 解析 JWT → 检查 token_version
+// 成功返回 claims，失败返回 error（调用方自行决定如何响应）
+func (am *AuthMiddleware) authenticateToken(c *gin.Context) (jwt.MapClaims, error) {
+	tokenStr, err := c.Cookie(common.CookieName)
+	if err != nil {
+		return nil, err
+	}
+
+	claims, err := parseToken(tokenStr, am.cfg.JWT.Secret)
+	if err != nil {
+		return nil, err
+	}
+
+	uid := uint(claims["uid"].(float64))
+	tokenVer := int(claims["ver"].(float64))
+
+	currentVer, err := am.userRepo.FindTokenVersion(uid)
+	if err != nil || tokenVer != currentVer {
+		if tokenVer != currentVer {
+			log.Printf("[authenticateToken] REVOKED: uid=%d tokenVer=%d dbVer=%d", uid, tokenVer, currentVer)
+		}
+		return nil, err
+	}
+
+	return claims, nil
+}
+
+// injectUserContext 将 JWT claims 中的用户信息注入 gin context
+func injectUserContext(c *gin.Context, claims jwt.MapClaims) {
+	c.Set("uid", uint(claims["uid"].(float64)))
+	c.Set("email", claims["email"])
+	c.Set("username", claims["username"])
+	c.Set("role", claims["role"])
+}
+
 // parseToken 解析并验证 JWT
 func parseToken(tokenStr, secret string) (jwt.MapClaims, error) {
 	now := time.Now()