refactor(api): introduce v1 response contract

backend/internal/httpx/response_test.go

@@ -0,0 +1,61 @@
+package httpx
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+)
+
+func TestErrorUsesStableEnvelope(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+
+	Error(ctx, http.StatusBadRequest, "invalid_request", "请求参数无效")
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+	require.JSONEq(t, `{"error":{"code":"invalid_request","message":"请求参数无效"}}`, recorder.Body.String())
+	require.True(t, ctx.IsAborted())
+}
+
+func TestIdentityParamAcceptsUUIDV7(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Params = gin.Params{{Key: "projectId", Value: "018f0c9a-7b3c-7cc1-98c8-0242ac120002"}}
+
+	identity, ok := IdentityParam(ctx, "projectId")
+
+	require.True(t, ok)
+	require.Equal(t, "018f0c9a-7b3c-7cc1-98c8-0242ac120002", identity)
+	require.False(t, ctx.IsAborted())
+}
+
+func TestIdentityParamRejectsNonUUIDV7(t *testing.T) {
+	tests := []struct {
+		name  string
+		value string
+	}{
+		{name: "internal numeric ID", value: "42"},
+		{name: "UUID v4", value: "550e8400-e29b-41d4-a716-446655440000"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gin.SetMode(gin.TestMode)
+			recorder := httptest.NewRecorder()
+			ctx, _ := gin.CreateTestContext(recorder)
+			ctx.Params = gin.Params{{Key: "projectId", Value: tt.value}}
+
+			identity, ok := IdentityParam(ctx, "projectId")
+
+			require.False(t, ok)
+			require.Empty(t, identity)
+			require.Equal(t, http.StatusBadRequest, recorder.Code)
+			require.JSONEq(t, `{"error":{"code":"invalid_request","message":"请求参数无效"}}`, recorder.Body.String())
+		})
+	}
+}