feat: 보상 재시도 + TX 확정 대기 + 에러 포맷 통일 + 품질 고도화

- 보상 지급 실패 시 즉시 재시도(3회 backoff) + DB 기록 + 백그라운드 워커 재시도
- WaitForTx 폴링으로 블록체인 TX 확정 대기, SendTxAndWait 편의 메서드
- chain 트랜잭션 코드 중복 제거 (userTx/operatorTx 헬퍼, 50% 감소)
- AppError 기반 에러 응답 포맷 통일 (8개 코드, 전 핸들러 마이그레이션)
- TX 에러 분류 + 한국어 사용자 메시지 매핑 (11가지 패턴)
- player 서비스 테스트 20개 + chain WaitForTx 테스트 10개 추가

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pkg/middleware/auth.go

@@ -7,6 +7,7 @@ import (
 	"log"
 	"strings"
 
+	"a301_server/pkg/apperror"
 	"a301_server/pkg/config"
 	"a301_server/pkg/database"
 	"github.com/gofiber/fiber/v2"
@@ -16,7 +17,7 @@ import (
 func Auth(c *fiber.Ctx) error {
 	header := c.Get("Authorization")
 	if !strings.HasPrefix(header, "Bearer ") {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "인증이 필요합니다"})
+		return apperror.ErrUnauthorized
 	}
 	tokenStr := strings.TrimPrefix(header, "Bearer ")
 
@@ -27,24 +28,24 @@ func Auth(c *fiber.Ctx) error {
 		return []byte(config.C.JWTSecret), nil
 	})
 	if err != nil || !token.Valid {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 토큰입니다"})
+		return apperror.Unauthorized("유효하지 않은 토큰입니다")
 	}
 
 	claims, ok := token.Claims.(jwt.MapClaims)
 	if !ok {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 토큰입니다"})
+		return apperror.Unauthorized("유효하지 않은 토큰입니다")
 	}
 	userIDFloat, ok := claims["user_id"].(float64)
 	if !ok {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 토큰입니다"})
+		return apperror.Unauthorized("유효하지 않은 토큰입니다")
 	}
 	username, ok := claims["username"].(string)
 	if !ok {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 토큰입니다"})
+		return apperror.Unauthorized("유효하지 않은 토큰입니다")
 	}
 	role, ok := claims["role"].(string)
 	if !ok {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 토큰입니다"})
+		return apperror.Unauthorized("유효하지 않은 토큰입니다")
 	}
 	userID := uint(userIDFloat)
 
@@ -54,7 +55,7 @@ func Auth(c *fiber.Ctx) error {
 	key := fmt.Sprintf("session:%d", userID)
 	stored, err := database.RDB.Get(ctx, key).Result()
 	if err != nil || stored != tokenStr {
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "만료되었거나 로그아웃된 세션입니다"})
+		return apperror.Unauthorized("만료되었거나 로그아웃된 세션입니다")
 	}
 
 	c.Locals("userID", userID)
@@ -65,7 +66,7 @@ func Auth(c *fiber.Ctx) error {
 
 func AdminOnly(c *fiber.Ctx) error {
 	if c.Locals("role") != "admin" {
-		return c.Status(fiber.StatusForbidden).JSON(fiber.Map{"error": "관리자 권한이 필요합니다"})
+		return apperror.ErrForbidden
 	}
 	return c.Next()
 }
@@ -77,7 +78,7 @@ func ServerAuth(c *fiber.Ctx) error {
 	expected := config.C.InternalAPIKey
 	if key == "" || expected == "" || subtle.ConstantTimeCompare([]byte(key), []byte(expected)) != 1 {
 		log.Printf("ServerAuth 실패: IP=%s, Path=%s", c.IP(), c.Path())
-		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "유효하지 않은 API 키입니다"})
+		return apperror.Unauthorized("유효하지 않은 API 키입니다")
 	}
 	return c.Next()
 }

pkg/middleware/idempotency.go

@@ -7,6 +7,7 @@ import (
 	"log"
 	"time"
 
+	"a301_server/pkg/apperror"
 	"a301_server/pkg/database"
 	"github.com/gofiber/fiber/v2"
 )
@@ -23,9 +24,7 @@ type cachedResponse struct {
 // then delegates to Idempotency for cache/replay logic.
 func IdempotencyRequired(c *fiber.Ctx) error {
 	if c.Get("Idempotency-Key") == "" {
-		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
-			"error": "Idempotency-Key 헤더가 필요합니다",
-		})
+		return apperror.BadRequest("Idempotency-Key 헤더가 필요합니다")
 	}
 	return Idempotency(c)
 }
@@ -38,7 +37,7 @@ func Idempotency(c *fiber.Ctx) error {
 		return c.Next()
 	}
 	if len(key) > 256 {
-		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "Idempotency-Key가 너무 깁니다"})
+		return apperror.BadRequest("Idempotency-Key가 너무 깁니다")
 	}
 
 	// userID가 있으면 키에 포함하여 사용자 간 캐시 충돌 방지
@@ -66,10 +65,10 @@ func Idempotency(c *fiber.Ctx) error {
 
 		cached, err := database.RDB.Get(getCtx, redisKey).Bytes()
 		if err != nil {
-			return c.Status(fiber.StatusConflict).JSON(fiber.Map{"error": "요청이 처리 중입니다"})
+			return apperror.Conflict("요청이 처리 중입니다")
 		}
 		if string(cached) == "processing" {
-			return c.Status(fiber.StatusConflict).JSON(fiber.Map{"error": "요청이 처리 중입니다"})
+			return apperror.Conflict("요청이 처리 중입니다")
 		}
 		var cr cachedResponse
 		if json.Unmarshal(cached, &cr) == nil {
@@ -77,7 +76,7 @@ func Idempotency(c *fiber.Ctx) error {
 			c.Set("X-Idempotent-Replay", "true")
 			return c.Status(cr.StatusCode).Send(cr.Body)
 		}
-		return c.Status(fiber.StatusConflict).JSON(fiber.Map{"error": "요청이 처리 중입니다"})
+		return apperror.Conflict("요청이 처리 중입니다")
 	}
 
 	// We claimed the key — process the request