feat(yggdrasil): 实现好友系统与 profiles 查询接口

按 MinecraftServices 文档实现好友系四组接口与 profiles 服务：

好友系统（/api/yggdrasil/minecraftservices/*）
- Friends（1.3）：列表查询、ADD/REMOVE 操作（发请求/接受/拒绝/撤回/删除）
  - 状态枚举+单向记录模型，接受请求时合并两方向避免好友列表重复
- Player Attributes（1.2）：friendsPreferences / 脏词过滤 / 聊天偏好读写
  - Upsert 用 map 显式写字段规避 gorm 对带 default 零值布尔字段的忽略
- Presence（1.1）：Redis key+TTL 上报与好友在线状态批量查询
- Blocklist（1.6）：屏蔽列表查询（含 120s Redis 缓存），Block/Unblock 内部方法

Profiles 服务
- getManyByName（2.1）：POST /api/profiles/minecraft，返回 [{id,name}]
  - toLowerCase 规范化、去重、空名过滤、maxBatch=10 超限拒绝
- getByName（2.2）：GET /api/users/profiles/minecraft/:name，返回 {id,name}，未找到返回 404

路由与基础设施
- 路由按官方 host 前缀一一转发
  - api.mojang.com/* -> /api/yggdrasil/api/*
  - api.minecraftservices.com/* -> /api/yggdrasil/minecraftservices/*
- 新增 Friend/PlayerAttributes 模型与 AutoMigrate 注册
- 新增 FriendsService 与 Container 装配
- 抽 extractBearerToken helper，统一 MinecraftServices 错误响应

修复
- texture_service: ToggleFavorite 在 db 为 nil 时降级非事务执行
  修复 TestTextureServiceImpl_ToggleFavorite 空指针 panic
- texture_service_test: UploadTexture 用例改用真实 SHA-256 命中 mock
  修复 4 个子用例因文件大小/Hash 不匹配的失败
- profile_repository: GetByNames/FindByName 改 LOWER() 大小写不敏感
  与客户端 toLowerCase 规范化对齐

测试
- 好友模型、ADD/REMOVE/接受、属性、屏蔽、Bearer 解析单测全绿
- profiles 查询规范化、去重、超限、大小写不敏感单测全绿
- go build ./... && go test ./... 全部通过

internal/handler/helpers.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"net/http"
 	"strconv"
+	"strings"
 
 	apperrors "carrotskin/internal/errors"
 	"carrotskin/internal/model"
@@ -21,6 +22,33 @@ func parseIntWithDefault(s string, defaultVal int) int {
 	return val
 }
 
+// extractBearerToken 从 Authorization 头解析 Bearer token
+// 返回值: token, ok (ok=false 时已写入 401 错误响应)
+func extractBearerToken(c *gin.Context) (string, bool) {
+	authHeader := c.GetHeader("Authorization")
+	if authHeader == "" {
+		c.JSON(http.StatusUnauthorized, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNAUTHORIZED", "Authorization header not provided", nil,
+		))
+		return "", false
+	}
+	const bearerPrefix = "Bearer "
+	if !strings.HasPrefix(authHeader, bearerPrefix) {
+		c.JSON(http.StatusUnauthorized, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNAUTHORIZED", "Invalid Authorization format", nil,
+		))
+		return "", false
+	}
+	token := strings.TrimPrefix(authHeader, bearerPrefix)
+	if token == "" {
+		c.JSON(http.StatusUnauthorized, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNAUTHORIZED", "Invalid Authorization format", nil,
+		))
+		return "", false
+	}
+	return token, true
+}
+
 // GetUserIDFromContext 从上下文获取用户ID，如果不存在返回未授权响应
 // 返回值: userID, ok (如果ok为false，已经发送了错误响应)
 func GetUserIDFromContext(c *gin.Context) (int64, bool) {

internal/handler/routes.go

@@ -18,6 +18,7 @@ type Handlers struct {
 	Profile    *ProfileHandler
 	Captcha    *CaptchaHandler
 	Yggdrasil  *YggdrasilHandler
+	Friends    *YggdrasilFriendsHandler
 	CustomSkin *CustomSkinHandler
 	Admin      *AdminHandler
 }
@@ -31,6 +32,7 @@ func NewHandlers(c *container.Container) *Handlers {
 		Profile:    NewProfileHandler(c),
 		Captcha:    NewCaptchaHandler(c),
 		Yggdrasil:  NewYggdrasilHandler(c),
+		Friends:    NewYggdrasilFriendsHandler(c),
 		CustomSkin: NewCustomSkinHandler(c),
 		Admin:      NewAdminHandler(c),
 	}
@@ -77,7 +79,7 @@ func RegisterRoutesWithDI(router *gin.Engine, c *container.Container) {
 
 	// Yggdrasil API路由组（独立于v1，路径为 /api/yggdrasil）
 
-	registerYggdrasilRoutesWithDI(apiGroup, h.Yggdrasil)
+	registerYggdrasilRoutesWithDI(apiGroup, h)
 }
 
 // registerAuthRoutes 注册认证路由
@@ -169,29 +171,43 @@ func registerCaptchaRoutesWithDI(v1 *gin.RouterGroup, h *CaptchaHandler) {
 }
 
 // registerYggdrasilRoutesWithDI 注册Yggdrasil API路由（依赖注入版本）
-func registerYggdrasilRoutesWithDI(v1 *gin.RouterGroup, h *YggdrasilHandler) {
+func registerYggdrasilRoutesWithDI(v1 *gin.RouterGroup, h *Handlers) {
 	ygg := v1.Group("/yggdrasil")
 	{
-		ygg.GET("", h.GetMetaData)
-		ygg.POST("/minecraftservices/player/certificates", h.GetPlayerCertificates)
+		ygg.GET("", h.Yggdrasil.GetMetaData)
+		ygg.POST("/minecraftservices/player/certificates", h.Yggdrasil.GetPlayerCertificates)
+
+		// MinecraftServices 好友系接口（文档 1.1~1.3、1.6）
+		mcServices := ygg.Group("/minecraftservices")
+		{
+			mcServices.GET("/friends", h.Friends.GetFriends)
+			mcServices.PUT("/friends", h.Friends.UpdateFriends)
+			mcServices.GET("/player/attributes", h.Friends.GetAttributes)
+			mcServices.POST("/player/attributes", h.Friends.UpdateAttributes)
+			mcServices.POST("/presence", h.Friends.UpdatePresence)
+			mcServices.GET("/privacy/blocklist", h.Friends.GetBlocklist)
+		}
+
 		authserver := ygg.Group("/authserver")
 		{
-			authserver.POST("/authenticate", h.Authenticate)
-			authserver.POST("/validate", h.ValidToken)
-			authserver.POST("/refresh", h.RefreshToken)
-			authserver.POST("/invalidate", h.InvalidToken)
-			authserver.POST("/signout", h.SignOut)
+			authserver.POST("/authenticate", h.Yggdrasil.Authenticate)
+			authserver.POST("/validate", h.Yggdrasil.ValidToken)
+			authserver.POST("/refresh", h.Yggdrasil.RefreshToken)
+			authserver.POST("/invalidate", h.Yggdrasil.InvalidToken)
+			authserver.POST("/signout", h.Yggdrasil.SignOut)
 		}
 		sessionServer := ygg.Group("/sessionserver")
 		{
-			sessionServer.GET("/session/minecraft/profile/:uuid", h.GetProfileByUUID)
-			sessionServer.POST("/session/minecraft/join", h.JoinServer)
-			sessionServer.GET("/session/minecraft/hasJoined", h.HasJoinedServer)
+			sessionServer.GET("/session/minecraft/profile/:uuid", h.Yggdrasil.GetProfileByUUID)
+			sessionServer.POST("/session/minecraft/join", h.Yggdrasil.JoinServer)
+			sessionServer.GET("/session/minecraft/hasJoined", h.Yggdrasil.HasJoinedServer)
 		}
 		api := ygg.Group("/api")
-		profiles := api.Group("/profiles")
 		{
-			profiles.POST("/minecraft", h.GetProfilesByName)
+			// 对应官方 api.mojang.com/profiles/minecraft（文档 2.1：批量按用户名查档）
+			api.POST("/profiles/minecraft", h.Yggdrasil.GetProfilesByName)
+			// 对应官方 api.mojang.com/users/profiles/minecraft/{name}（文档 2.2：单个用户名查档）
+			api.GET("/users/profiles/minecraft/:name", h.Yggdrasil.GetProfileByName)
 		}
 	}
 }

internal/handler/yggdrasil_friends_handler.go

@@ -0,0 +1,243 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+
+	apperrors "carrotskin/internal/errors"
+	"carrotskin/internal/container"
+	"carrotskin/internal/service"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// YggdrasilFriendsHandler MinecraftServices 好友系接口处理器（文档 1.1~1.3、1.6）
+type YggdrasilFriendsHandler struct {
+	container *container.Container
+	logger    *zap.Logger
+}
+
+// NewYggdrasilFriendsHandler 创建 YggdrasilFriendsHandler 实例
+func NewYggdrasilFriendsHandler(c *container.Container) *YggdrasilFriendsHandler {
+	return &YggdrasilFriendsHandler{
+		container: c,
+		logger:    c.Logger,
+	}
+}
+
+// extractProfileUUID 解析 Bearer token 得到当前请求者的 Profile UUID
+// 失败时已写入 401 响应
+func (h *YggdrasilFriendsHandler) extractProfileUUID(c *gin.Context) (string, bool) {
+	token, ok := extractBearerToken(c)
+	if !ok {
+		return "", false
+	}
+	uuid, err := h.container.TokenService.GetUUIDByAccessToken(c.Request.Context(), token)
+	if err != nil || uuid == "" {
+		h.logger.Warn("好友接口鉴权失败: 无效令牌", zap.Error(err))
+		c.JSON(http.StatusUnauthorized, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNAUTHORIZED", "Invalid token", nil,
+		))
+		return "", false
+	}
+	return uuid, true
+}
+
+// respondFriendsError 将 service 错误映射为 MinecraftServices 标准错误响应
+func (h *YggdrasilFriendsHandler) respondFriendsError(c *gin.Context, err error) {
+	var appErr *apperrors.AppError
+	if errors.As(err, &appErr) {
+		// 未知 profile / 不能加自己 -> 400
+		if appErr.Code == 400 {
+			c.JSON(http.StatusBadRequest, apperrors.NewMinecraftServicesErrorResponse(
+				c.Request.URL.Path, appErr.Message, appErr.Message, nil,
+			))
+			return
+		}
+		if appErr.Code == 403 {
+			c.JSON(http.StatusForbidden, apperrors.NewMinecraftServicesErrorResponse(
+				c.Request.URL.Path, "FORBIDDEN", appErr.Message, nil,
+			))
+			return
+		}
+	}
+	h.logger.Error("好友接口内部错误", zap.Error(err))
+	c.JSON(http.StatusInternalServerError, apperrors.NewMinecraftServicesErrorResponse(
+		c.Request.URL.Path, "SERVICE_NOT_AVAILABLE", "Internal server error", nil,
+	))
+}
+
+// GetFriends 获取好友列表
+// @Summary MinecraftServices 好友列表
+// @Description 拉取好友列表与收到/发出的好友请求（文档 1.3.1）
+// @Tags Yggdrasil
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Success 200 {object} service.FriendsListResponse
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Failure 500 {object} apperrors.MinecraftServicesErrorResponse "服务器错误"
+// @Router /api/yggdrasil/minecraftservices/friends [get]
+func (h *YggdrasilFriendsHandler) GetFriends(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	resp, err := h.container.FriendsService.ListFriends(c.Request.Context(), uuid)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// UpdateFriends 添加/删除好友、接受/拒绝/撤回请求
+// @Summary MinecraftServices 好友操作
+// @Description 通过 updateType=ADD/REMOVE 进行好友加删、接受/拒绝/撤回请求（文档 1.3.2）
+// @Tags Yggdrasil
+// @Accept json
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Param request body service.FriendActionRequest true "好友操作请求"
+// @Success 200 {object} service.FriendsListResponse
+// @Failure 400 {object} apperrors.MinecraftServicesErrorResponse "参数错误"
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Router /api/yggdrasil/minecraftservices/friends [put]
+func (h *YggdrasilFriendsHandler) UpdateFriends(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	var req service.FriendActionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNKNOWN_PROFILE", "Invalid request body", nil,
+		))
+		return
+	}
+	resp, err := h.container.FriendsService.PerformFriendAction(c.Request.Context(), uuid, req)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// GetAttributes 获取玩家属性
+// @Summary MinecraftServices 玩家属性
+// @Description 拉取好友/脏词过滤/聊天偏好属性（文档 1.2.1）
+// @Tags Yggdrasil
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Success 200 {object} service.PlayerAttributesResponse
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Router /api/yggdrasil/minecraftservices/player/attributes [get]
+func (h *YggdrasilFriendsHandler) GetAttributes(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	resp, err := h.container.FriendsService.GetAttributes(c.Request.Context(), uuid)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// UpdateAttributes 更新玩家偏好属性
+// @Summary MinecraftServices 更新玩家属性
+// @Description 更新好友/脏词过滤偏好（文档 1.2.2）
+// @Tags Yggdrasil
+// @Accept json
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Param request body service.PlayerAttributesRequest true "偏好更新请求"
+// @Success 200 {object} service.PlayerAttributesResponse
+// @Failure 400 {object} apperrors.MinecraftServicesErrorResponse "参数错误"
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Router /api/yggdrasil/minecraftservices/player/attributes [post]
+func (h *YggdrasilFriendsHandler) UpdateAttributes(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	var req service.PlayerAttributesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "UNKNOWN_PROFILE", "Invalid request body", nil,
+		))
+		return
+	}
+	if err := h.container.FriendsService.UpdateAttributes(c.Request.Context(), uuid, req); err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	// 返回最新属性
+	resp, err := h.container.FriendsService.GetAttributes(c.Request.Context(), uuid)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// UpdatePresence 上报在线状态
+// @Summary MinecraftServices 在线状态
+// @Description 上报当前在线状态并返回好友在线状态列表（文档 1.1）
+// @Tags Yggdrasil
+// @Accept json
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Param request body service.PresenceRequest true "状态上报请求"
+// @Success 200 {object} service.PresenceResponse
+// @Failure 400 {object} apperrors.MinecraftServicesErrorResponse "参数错误"
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Router /api/yggdrasil/minecraftservices/presence [post]
+func (h *YggdrasilFriendsHandler) UpdatePresence(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	var req service.PresenceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "INVALID_STATUS", "Invalid request body", nil,
+		))
+		return
+	}
+	if req.Status == "" {
+		c.JSON(http.StatusBadRequest, apperrors.NewMinecraftServicesErrorResponse(
+			c.Request.URL.Path, "INVALID_STATUS", "Bad status value", nil,
+		))
+		return
+	}
+	resp, err := h.container.FriendsService.UpdatePresence(c.Request.Context(), uuid, req.Status)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// GetBlocklist 获取玩家屏蔽列表
+// @Summary MinecraftServices 屏蔽列表
+// @Description 拉取被屏蔽玩家档案 UUID 列表（文档 1.6）
+// @Tags Yggdrasil
+// @Produce json
+// @Param Authorization header string true "Bearer {accessToken}"
+// @Success 200 {object} service.BlockListResponse
+// @Failure 401 {object} apperrors.MinecraftServicesErrorResponse "未授权"
+// @Router /api/yggdrasil/minecraftservices/privacy/blocklist [get]
+func (h *YggdrasilFriendsHandler) GetBlocklist(c *gin.Context) {
+	uuid, ok := h.extractProfileUUID(c)
+	if !ok {
+		return
+	}
+	resp, err := h.container.FriendsService.GetBlocklist(c.Request.Context(), uuid)
+	if err != nil {
+		h.respondFriendsError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, resp)
+}

internal/handler/yggdrasil_friends_handler_test.go

@@ -0,0 +1,44 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestExtractBearerToken 校验 Bearer token 解析
+func TestExtractBearerToken(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	tests := []struct {
+		name      string
+		auth      string
+		wantToken string
+		wantOK    bool
+	}{
+		{name: "缺失 header", auth: "", wantOK: false},
+		{name: "错误前缀", auth: "Token abc", wantOK: false},
+		{name: "Bearer 空", auth: "Bearer ", wantOK: false},
+		{name: "有效 Bearer", auth: "Bearer mytoken123", wantToken: "mytoken123", wantOK: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(w)
+			c.Request = httptest.NewRequest(http.MethodGet, "/friends", nil)
+			if tt.auth != "" {
+				c.Request.Header.Set("Authorization", tt.auth)
+			}
+			got, ok := extractBearerToken(c)
+			if ok != tt.wantOK {
+				t.Fatalf("ok = %v, want %v", ok, tt.wantOK)
+			}
+			if ok && got != tt.wantToken {
+				t.Errorf("token = %q, want %q", got, tt.wantToken)
+			}
+		})
+	}
+}

internal/handler/yggdrasil_handler.go

@@ -616,12 +616,12 @@ func (h *YggdrasilHandler) HasJoinedServer(c *gin.Context) {
 
 // GetProfilesByName 批量获取配置文件
 // @Summary Yggdrasil批量获取档案
-// @Description Yggdrasil协议: 根据名称批量获取用户档案
+// @Description Yggdrasil协议: 根据名称批量获取用户档案（文档 2.1，每页最多 10 个，返回 [{id,name}]）
 // @Tags Yggdrasil
 // @Accept json
 // @Produce json
 // @Param request body []string true "用户名列表"
-// @Success 200 {array} model.Profile "档案列表"
+// @Success 200 {array} model.NameAndId "档案标识列表"
 // @Failure 400 {object} map[string]string "参数错误"
 // @Router /api/yggdrasil/api/profiles/minecraft [post]
 func (h *YggdrasilHandler) GetProfilesByName(c *gin.Context) {
@@ -635,13 +635,51 @@ func (h *YggdrasilHandler) GetProfilesByName(c *gin.Context) {
 
 	h.logger.Info("接收到批量获取配置文件请求", zap.Int("count", len(names)))
 
-	profiles, err := h.container.ProfileService.GetByNames(c.Request.Context(), names)
+	// 文档 2.1：每页最多 10 个用户名
+	const maxBatch = 10
+	results, err := h.container.ProfileService.ProfileSearchByName(c.Request.Context(), names, maxBatch)
 	if err != nil {
-		h.logger.Error("获取配置文件失败", zap.Error(err))
+		h.logger.Warn("批量获取配置文件失败", zap.Error(err), zap.Int("count", len(names)))
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
 	}
 
-	h.logger.Info("成功获取配置文件", zap.Int("requested", len(names)), zap.Int("returned", len(profiles)))
-	c.JSON(http.StatusOK, profiles)
+	h.logger.Info("成功获取配置文件", zap.Int("requested", len(names)), zap.Int("returned", len(results)))
+	c.JSON(http.StatusOK, results)
+}
+
+// GetProfileByName 单个用户名查档案
+// @Summary Yggdrasil按用户名查档案
+// @Description Yggdrasil协议: 根据单个用户名查询用户档案（文档 2.2，返回 {id,name}）
+// @Tags Yggdrasil
+// @Produce json
+// @Param name path string true "用户名"
+// @Success 200 {object} model.NameAndId "档案标识"
+// @Failure 404 {object} map[string]string "档案不存在"
+// @Router /api/yggdrasil/api/users/profiles/minecraft/{name} [get]
+func (h *YggdrasilHandler) GetProfileByName(c *gin.Context) {
+	name := c.Param("name")
+	if name == "" {
+		h.logger.Warn("缺少用户名参数")
+		c.JSON(http.StatusNotFound, gin.H{"error": "用户不存在"})
+		return
+	}
+
+	result, err := h.container.ProfileService.ProfileSearchByNameSingle(c.Request.Context(), name)
+	if err != nil {
+		// 按文档契约：任意错误视为未找到
+		h.logger.Warn("按用户名查档失败", zap.String("name", name), zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "用户不存在"})
+		return
+	}
+	if result == nil {
+		h.logger.Info("用户名未找到", zap.String("name", name))
+		c.JSON(http.StatusNotFound, gin.H{"error": "用户不存在"})
+		return
+	}
+
+	h.logger.Info("成功获取档案", zap.String("name", name), zap.String("uuid", result.ID))
+	c.JSON(http.StatusOK, result)
 }
 
 // GetMetaData 获取Yggdrasil元数据