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/apperror/apperror.go

@@ -3,6 +3,7 @@ package apperror
 import "fmt"
 
 // AppError is a structured application error with an HTTP status code.
+// JSON response format: {"error": "<code>", "message": "<human-readable message>"}
 type AppError struct {
 	Code    string `json:"error"`
 	Message string `json:"message"`
@@ -23,11 +24,36 @@ func Wrap(code string, message string, status int, cause error) *AppError {
 
 // Common errors
 var (
+	ErrBadRequest   = &AppError{Code: "bad_request", Message: "잘못된 요청입니다", Status: 400}
 	ErrUnauthorized = &AppError{Code: "unauthorized", Message: "인증이 필요합니다", Status: 401}
 	ErrForbidden    = &AppError{Code: "forbidden", Message: "권한이 없습니다", Status: 403}
 	ErrNotFound     = &AppError{Code: "not_found", Message: "리소스를 찾을 수 없습니다", Status: 404}
 	ErrConflict     = &AppError{Code: "conflict", Message: "이미 존재합니다", Status: 409}
-	ErrBadRequest   = &AppError{Code: "bad_request", Message: "잘못된 요청입니다", Status: 400}
-	ErrInternal     = &AppError{Code: "internal_error", Message: "서버 오류가 발생했습니다", Status: 500}
 	ErrRateLimited  = &AppError{Code: "rate_limited", Message: "요청이 너무 많습니다", Status: 429}
+	ErrInternal     = &AppError{Code: "internal_error", Message: "서버 오류가 발생했습니다", Status: 500}
 )
+
+// BadRequest creates a 400 error with a custom message.
+func BadRequest(message string) *AppError {
+	return &AppError{Code: "bad_request", Message: message, Status: 400}
+}
+
+// Unauthorized creates a 401 error with a custom message.
+func Unauthorized(message string) *AppError {
+	return &AppError{Code: "unauthorized", Message: message, Status: 401}
+}
+
+// NotFound creates a 404 error with a custom message.
+func NotFound(message string) *AppError {
+	return &AppError{Code: "not_found", Message: message, Status: 404}
+}
+
+// Conflict creates a 409 error with a custom message.
+func Conflict(message string) *AppError {
+	return &AppError{Code: "conflict", Message: message, Status: 409}
+}
+
+// Internal creates a 500 error with a custom message.
+func Internal(message string) *AppError {
+	return &AppError{Code: "internal_error", Message: message, Status: 500}
+}

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