feat(api): wrap JSON responses in envelope

Add response envelope middleware to standardize JSON responses as
`{code,data,message}` with consistent business codes across endpoints.
Update Swagger annotations and tests to reflect the new response shape.

BREAKING CHANGE: API responses are now wrapped in a response envelope; clients must read payloads from `data` and handle `code`/`message` fields.

internal/middleware/response_envelope_test.go

@@ -0,0 +1,109 @@
+package middleware
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestResponseEnvelope_DefaultMapping(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	r.Use(ResponseEnvelope())
+	r.GET("/missing", func(c *gin.Context) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not here"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/missing", nil)
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d body=%s", rr.Code, rr.Body.String())
+	}
+
+	var env struct {
+		Code    string         `json:"code"`
+		Message string         `json:"message"`
+		Data    map[string]any `json:"data"`
+	}
+	if err := json.Unmarshal(rr.Body.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal envelope: %v", err)
+	}
+	if env.Code != "not_found" {
+		t.Fatalf("expected code=not_found, got %q", env.Code)
+	}
+	if env.Message != "not here" {
+		t.Fatalf("expected message 'not here', got %q", env.Message)
+	}
+	if env.Data["error"] != "not here" {
+		t.Fatalf("expected data.error 'not here', got %v", env.Data["error"])
+	}
+}
+
+func TestResponseEnvelope_OverrideBusinessCode(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	r.Use(ResponseEnvelope())
+	r.GET("/rate-limit", func(c *gin.Context) {
+		SetBusinessCode(c, "quota_exceeded")
+		c.JSON(http.StatusTooManyRequests, gin.H{"error": "rate limited"})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/rate-limit", nil)
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected 429, got %d body=%s", rr.Code, rr.Body.String())
+	}
+
+	var env struct {
+		Code string `json:"code"`
+	}
+	if err := json.Unmarshal(rr.Body.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal envelope: %v", err)
+	}
+	if env.Code != "quota_exceeded" {
+		t.Fatalf("expected code=quota_exceeded, got %q", env.Code)
+	}
+}
+
+func TestResponseEnvelope_Idempotent(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	r.Use(ResponseEnvelope())
+	r.GET("/wrapped", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{
+			"code":    "ok",
+			"data":    gin.H{"id": 1},
+			"message": "",
+		})
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/wrapped", nil)
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", rr.Code, rr.Body.String())
+	}
+
+	var env map[string]any
+	if err := json.Unmarshal(rr.Body.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal envelope: %v", err)
+	}
+	if env["code"] != "ok" {
+		t.Fatalf("expected code=ok, got %v", env["code"])
+	}
+	data, ok := env["data"].(map[string]any)
+	if !ok || data["id"] != float64(1) {
+		t.Fatalf("unexpected data: %+v", env["data"])
+	}
+}