feat(billing): 完成异步结算与请求执行闭环

统一任务成功、Attempt 与结算 Outbox 的事务边界，增加多实例安全结算、人工复核、请求幂等与执行租约。钱包决策使用九位精确金额，并通过审计保护约束保留流水事实；同时补充管理接口、指标与 PostgreSQL 集成测试。

apps/api/internal/httpapi/billing_admin_handlers.go

@@ -13,7 +13,7 @@ import (
 
 type walletBalanceRequest struct {
 	Currency       string         `json:"currency" example:"USD"`
-	Balance        float64        `json:"balance" example:"100"`
+	Balance        json.Number    `json:"balance" swaggertype:"number" example:"100"`
 	Reason         string         `json:"reason" example:"manual recharge"`
 	IdempotencyKey string         `json:"idempotencyKey" example:"wallet-set-20260514-001"`
 	Metadata       map[string]any `json:"metadata"`
@@ -21,7 +21,7 @@ type walletBalanceRequest struct {
 
 type walletRechargeRequest struct {
 	Currency       string         `json:"currency" example:"resource"`
-	Amount         float64        `json:"amount" example:"100"`
+	Amount         json.Number    `json:"amount" swaggertype:"number" example:"100"`
 	Reason         string         `json:"reason" example:"manual recharge"`
 	IdempotencyKey string         `json:"idempotencyKey" example:"wallet-recharge-20260514-001"`
 	Metadata       map[string]any `json:"metadata"`
@@ -50,10 +50,6 @@ func (s *Server) setUserWalletBalance(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "invalid json body")
 		return
 	}
-	if input.Balance < 0 {
-		writeError(w, http.StatusBadRequest, "wallet balance cannot be negative")
-		return
-	}
 	gatewayUserID := strings.TrimSpace(r.PathValue("userID"))
 	reason := strings.TrimSpace(input.Reason)
 	if reason == "" {
@@ -67,7 +63,7 @@ func (s *Server) setUserWalletBalance(w http.ResponseWriter, r *http.Request) {
 		next, err := s.store.SetUserWalletBalanceTx(r.Context(), tx, store.WalletBalanceAdjustmentInput{
 			GatewayUserID:  gatewayUserID,
 			Currency:       input.Currency,
-			Balance:        input.Balance,
+			BalanceText:    input.Balance.String(),
 			Reason:         reason,
 			IdempotencyKey: input.IdempotencyKey,
 			Metadata:       input.Metadata,
@@ -89,6 +85,10 @@ func (s *Server) setUserWalletBalance(w http.ResponseWriter, r *http.Request) {
 			writeError(w, http.StatusNotFound, "user not found")
 		case errors.Is(err, store.ErrWalletBalanceUnchanged):
 			writeError(w, http.StatusBadRequest, "wallet balance is unchanged")
+		case errors.Is(err, store.ErrInvalidWalletAmount):
+			writeError(w, http.StatusBadRequest, "wallet balance must be a non-negative decimal with at most nine fractional digits", "invalid_wallet_amount")
+		case errors.Is(err, store.ErrBalanceBelowFrozen):
+			writeError(w, http.StatusConflict, "wallet balance cannot be below frozen balance", "balance_below_frozen")
 		default:
 			s.logger.Error("set user wallet balance failed", "error", err)
 			writeError(w, http.StatusInternalServerError, "set user wallet balance failed")
@@ -126,10 +126,6 @@ func (s *Server) rechargeUserWalletBalance(w http.ResponseWriter, r *http.Reques
 		writeError(w, http.StatusBadRequest, "invalid json body")
 		return
 	}
-	if input.Amount <= 0 {
-		writeError(w, http.StatusBadRequest, "wallet recharge amount must be positive")
-		return
-	}
 	gatewayUserID := strings.TrimSpace(r.PathValue("userID"))
 	reason := strings.TrimSpace(input.Reason)
 	if reason == "" {
@@ -143,7 +139,7 @@ func (s *Server) rechargeUserWalletBalance(w http.ResponseWriter, r *http.Reques
 		next, err := s.store.RechargeUserWalletBalanceTx(r.Context(), tx, store.WalletRechargeInput{
 			GatewayUserID:  gatewayUserID,
 			Currency:       input.Currency,
-			Amount:         input.Amount,
+			AmountText:     input.Amount.String(),
 			Reason:         reason,
 			IdempotencyKey: input.IdempotencyKey,
 			Metadata:       input.Metadata,
@@ -163,6 +159,8 @@ func (s *Server) rechargeUserWalletBalance(w http.ResponseWriter, r *http.Reques
 		switch {
 		case store.IsNotFound(err):
 			writeError(w, http.StatusNotFound, "user not found")
+		case errors.Is(err, store.ErrInvalidWalletAmount):
+			writeError(w, http.StatusBadRequest, "wallet recharge amount must be a positive decimal with at most nine fractional digits", "invalid_wallet_amount")
 		default:
 			s.logger.Error("recharge user wallet balance failed", "error", err)
 			writeError(w, http.StatusInternalServerError, "recharge user wallet balance failed")

apps/api/internal/httpapi/billing_settlement_handlers.go

@@ -0,0 +1,145 @@
+package httpapi
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/easyai/easyai-ai-gateway/apps/api/internal/auth"
+	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
+	"github.com/google/uuid"
+)
+
+// listBillingSettlements godoc
+// @Summary 查询计费结算队列
+// @Description 管理端分页查询待结算、重试失败和人工复核记录。
+// @Tags billing
+// @Produce json
+// @Security BearerAuth
+// @Param status query string false "结算状态"
+// @Param action query string false "动作：settle 或 release"
+// @Param page query int false "页码" default(1)
+// @Param pageSize query int false "每页数量" default(50)
+// @Success 200 {object} BillingSettlementListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/billing-settlements [get]
+func (s *Server) listBillingSettlements(w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+	page, err := positiveQueryInt(query.Get("page"), 1)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "invalid page", "invalid_request")
+		return
+	}
+	pageSize, err := positiveQueryInt(query.Get("pageSize"), 50)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "invalid pageSize", "invalid_request")
+		return
+	}
+	result, err := s.store.ListBillingSettlements(r.Context(), store.BillingSettlementListFilter{
+		Status: query.Get("status"), Action: query.Get("action"), Page: page, PageSize: pageSize,
+	})
+	if err != nil {
+		s.logger.Error("list billing settlements failed", "error_category", "billing_settlement_list_failed")
+		writeError(w, http.StatusInternalServerError, "list billing settlements failed", "billing_settlement_list_failed")
+		return
+	}
+	writeJSON(w, http.StatusOK, result)
+}
+
+// retryBillingSettlement godoc
+// @Summary 重试计费结算
+// @Description Manager 使用单值 Idempotency-Key 将重试失败或人工复核记录重新放入队列，并记录审计日志。
+// @Tags billing
+// @Produce json
+// @Security BearerAuth
+// @Param settlementId path string true "结算记录 ID"
+// @Param Idempotency-Key header string true "幂等键"
+// @Success 200 {object} BillingSettlementRetryResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 409 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/runtime/billing-settlements/{settlementId}/retry [post]
+func (s *Server) retryBillingSettlement(w http.ResponseWriter, r *http.Request) {
+	key, ok := singleIdempotencyKey(r)
+	if !ok {
+		writeError(w, http.StatusBadRequest, "a single Idempotency-Key is required", "idempotency_key_required")
+		return
+	}
+	keyHash := sha256.Sum256([]byte(key))
+	settlementID := strings.TrimSpace(r.PathValue("settlementId"))
+	if _, err := uuid.Parse(settlementID); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid billing settlement ID", "invalid_request")
+		return
+	}
+	actor, _ := auth.UserFromContext(r.Context())
+	var item store.BillingSettlement
+	var audit store.AuditLog
+	var replayed bool
+	err := s.store.InTx(r.Context(), func(tx store.Tx) error {
+		var err error
+		item, replayed, err = s.store.RetryBillingSettlementTx(r.Context(), tx, settlementID, hex.EncodeToString(keyHash[:]))
+		if err != nil || replayed {
+			return err
+		}
+		audit, err = s.store.RecordAuditLogTx(r.Context(), tx, billingSettlementRetryAuditInput(r, actor, item))
+		return err
+	})
+	if err != nil {
+		switch {
+		case store.IsNotFound(err):
+			writeError(w, http.StatusNotFound, "billing settlement not found", "billing_settlement_not_found")
+		case errors.Is(err, store.ErrBillingSettlementNotRetryable):
+			writeError(w, http.StatusConflict, "billing settlement is not retryable", "billing_settlement_not_retryable")
+		default:
+			s.logger.Error("retry billing settlement failed", "settlementID", settlementID, "error_category", "billing_settlement_retry_failed")
+			writeError(w, http.StatusInternalServerError, "retry billing settlement failed", "billing_settlement_retry_failed")
+		}
+		return
+	}
+	if replayed {
+		w.Header().Set("Idempotent-Replayed", "true")
+	}
+	response := map[string]any{"settlement": item}
+	if !replayed {
+		response["auditLog"] = audit
+	}
+	writeJSON(w, http.StatusOK, response)
+}
+
+func singleIdempotencyKey(r *http.Request) (string, bool) {
+	values := r.Header.Values("Idempotency-Key")
+	if len(values) != 1 {
+		return "", false
+	}
+	value := strings.TrimSpace(values[0])
+	if value == "" || len(value) > 255 || strings.Contains(value, ",") {
+		return "", false
+	}
+	return value, true
+}
+
+func billingSettlementRetryAuditInput(r *http.Request, actor *auth.User, item store.BillingSettlement) store.AuditLogInput {
+	input := store.AuditLogInput{
+		Category: "billing", Action: "billing.settlement.retry",
+		TargetType: "billing_settlement", TargetID: item.ID,
+		RequestIP: requestIP(r), UserAgent: r.UserAgent(),
+		AfterState: map[string]any{"status": item.Status, "attempts": item.Attempts},
+		Metadata:   map[string]any{"taskId": item.TaskID, "action": item.Action, "currency": item.Currency},
+	}
+	if actor != nil {
+		input.ActorGatewayUserID = uuidText(firstNonEmptyText(actor.GatewayUserID, actor.ID))
+		input.ActorUserID = actor.ID
+		input.ActorUsername = actor.Username
+		input.ActorSource = actor.Source
+		input.ActorRoles = actor.Roles
+	}
+	return input
+}

apps/api/internal/httpapi/billing_settlement_handlers_test.go

@@ -0,0 +1,21 @@
+package httpapi
+
+import (
+	"net/http/httptest"
+	"testing"
+)
+
+func TestSingleIdempotencyKey(t *testing.T) {
+	t.Parallel()
+
+	request := httptest.NewRequest("POST", "/", nil)
+	request.Header.Add("Idempotency-Key", "retry-1")
+	if got, ok := singleIdempotencyKey(request); !ok || got != "retry-1" {
+		t.Fatalf("got key=%q ok=%v", got, ok)
+	}
+
+	request.Header.Add("Idempotency-Key", "retry-2")
+	if _, ok := singleIdempotencyKey(request); ok {
+		t.Fatal("multiple Idempotency-Key values must be rejected")
+	}
+}

apps/api/internal/httpapi/core_flow_integration_test.go

@@ -444,7 +444,6 @@ VALUES ($1, 5, '{"purpose":"core-flow"}'::jsonb)`, inviteCode); err != nil {
 		t.Fatalf("unexpected compatible chat response: %+v", compatChat)
 	}
 
-	cancelMarker := "cancel-stream-" + suffixText
 	cancelCtx, cancelRequest := context.WithCancel(context.Background())
 	cancelPayload := map[string]any{
 		"model":                defaultTextModel,
@@ -453,7 +452,6 @@ VALUES ($1, 5, '{"purpose":"core-flow"}'::jsonb)`, inviteCode); err != nil {
 		"stream":               true,
 		"simulation":           true,
 		"simulationDurationMs": 250,
-		"cancelTestId":         cancelMarker,
 	}
 	cancelRaw, err := json.Marshal(cancelPayload)
 	if err != nil {
@@ -466,15 +464,27 @@ VALUES ($1, 5, '{"purpose":"core-flow"}'::jsonb)`, inviteCode); err != nil {
 	cancelReq.Header.Set("Authorization", "Bearer "+apiKeyResponse.Secret)
 	cancelReq.Header.Set("Content-Type", "application/json")
 	cancelErrCh := make(chan error, 1)
+	cancelTaskIDCh := make(chan string, 1)
 	go func() {
 		resp, err := http.DefaultClient.Do(cancelReq)
 		if resp != nil {
+			cancelTaskIDCh <- strings.TrimSpace(resp.Header.Get("X-Gateway-Task-Id"))
 			_, _ = io.ReadAll(resp.Body)
 			_ = resp.Body.Close()
+		} else {
+			cancelTaskIDCh <- ""
 		}
 		cancelErrCh <- err
 	}()
-	cancelTaskID := waitForTaskIDByRequestMarker(t, ctx, testPool, cancelMarker, 2*time.Second)
+	var cancelTaskID string
+	select {
+	case cancelTaskID = <-cancelTaskIDCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("cancelled stream did not return response headers")
+	}
+	if cancelTaskID == "" {
+		t.Fatal("cancelled stream response did not expose X-Gateway-Task-Id")
+	}
 	cancelRequest()
 	select {
 	case <-cancelErrCh:
@@ -845,7 +855,7 @@ WHERE gateway_user_id = $1::uuid
 	}
 	doAPIV1ChatCompletionAndLoadTask(t, ctx, testPool, server.URL, apiKeyResponse.Secret, map[string]any{
 		"model":                pricingModel,
-		"runMode":              "simulation",
+		"runMode":              "production",
 		"simulation":           true,
 		"simulationDurationMs": 5,
 		"messages":             []map[string]any{{"role": "user", "content": "priced ping"}},
@@ -853,6 +863,20 @@ WHERE gateway_user_id = $1::uuid
 	if pricingTask.Task.Status != "succeeded" || !floatNear(pricingTask.Task.FinalChargeAmount, 0.028) {
 		t.Fatalf("custom pricing rule set should drive text billing, got task=%+v", pricingTask.Task)
 	}
+	settlementDeadline := time.Now().Add(3 * time.Second)
+	for {
+		var billingStatus string
+		if err := testPool.QueryRow(ctx, `SELECT billing_status FROM gateway_tasks WHERE id = $1::uuid`, pricingTask.Task.ID).Scan(&billingStatus); err != nil {
+			t.Fatalf("read pricing task billing status: %v", err)
+		}
+		if billingStatus == "settled" {
+			break
+		}
+		if time.Now().After(settlementDeadline) {
+			t.Fatalf("pricing task billing did not settle before deadline, status=%s", billingStatus)
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
 	var walletBalanceAfter float64
 	var walletSpentAfter float64
 	if err := testPool.QueryRow(ctx, `
@@ -1484,7 +1508,7 @@ WHERE m.platform_id = $1::uuid
 		t.Fatalf("workspace task list should include persisted task records, got %+v", workspaceTaskList.Items)
 	}
 
-	req, err := http.NewRequest(http.MethodGet, server.URL+"/api/v1/tasks/"+taskResponse.Task.ID+"/events", nil)
+	req, err := http.NewRequest(http.MethodGet, server.URL+"/api/v1/tasks/"+pricingTask.Task.ID+"/events", nil)
 	if err != nil {
 		t.Fatalf("build events request: %v", err)
 	}
@@ -1864,7 +1888,7 @@ func doJSON(t *testing.T, baseURL string, method string, path string, token stri
 	doJSONWithHeaders(t, baseURL, method, path, token, payload, nil, expectedStatus, out)
 }
 
-func doJSONWithHeaders(t *testing.T, baseURL string, method string, path string, token string, payload any, headers map[string]string, expectedStatus int, out any) {
+func doJSONWithHeaders(t *testing.T, baseURL string, method string, path string, token string, payload any, headers map[string]string, expectedStatus int, out any) http.Header {
 	t.Helper()
 	var body io.Reader
 	if payload != nil {
@@ -1901,16 +1925,22 @@ func doJSONWithHeaders(t *testing.T, baseURL string, method string, path string,
 			t.Fatalf("decode %s %s response: %v body=%s", method, path, err, string(raw))
 		}
 	}
+	return resp.Header.Clone()
 }
 
 func doAPIV1ChatCompletionAndLoadTask(t *testing.T, ctx context.Context, pool *pgxpool.Pool, baseURL string, token string, payload map[string]any, marker string, expectedStatus int, responseOut any, taskDetailOut any) string {
 	t.Helper()
-	payload["integrationTestMarker"] = marker
+	_ = ctx
+	_ = pool
+	_ = marker
 	if responseOut == nil {
 		responseOut = &map[string]any{}
 	}
-	doJSON(t, baseURL, http.MethodPost, "/api/v1/chat/completions", token, payload, expectedStatus, responseOut)
-	taskID := waitForTaskIDByRequestField(t, ctx, pool, "integrationTestMarker", marker, 2*time.Second)
+	responseHeaders := doJSONWithHeaders(t, baseURL, http.MethodPost, "/api/v1/chat/completions", token, payload, nil, expectedStatus, responseOut)
+	taskID := strings.TrimSpace(responseHeaders.Get("X-Gateway-Task-Id"))
+	if taskID == "" {
+		t.Fatal("chat completion response did not expose X-Gateway-Task-Id")
+	}
 	if taskDetailOut != nil {
 		doJSON(t, baseURL, http.MethodGet, "/api/v1/tasks/"+taskID, token, nil, http.StatusOK, taskDetailOut)
 	}
@@ -2046,11 +2076,6 @@ func waitForTaskStatus(t *testing.T, baseURL string, token string, taskID string
 	return detail
 }
 
-func waitForTaskIDByRequestMarker(t *testing.T, ctx context.Context, pool *pgxpool.Pool, marker string, timeout time.Duration) string {
-	t.Helper()
-	return waitForTaskIDByRequestField(t, ctx, pool, "cancelTestId", marker, timeout)
-}
-
 func waitForTaskIDByRequestField(t *testing.T, ctx context.Context, pool *pgxpool.Pool, key string, value string, timeout time.Duration) string {
 	t.Helper()
 	deadline := time.Now().Add(timeout)

apps/api/internal/httpapi/gemini_compat.go

@@ -4,6 +4,7 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"mime"
@@ -94,6 +95,11 @@ func (s *Server) geminiGenerateContent(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusForbidden, "api key scope does not allow this capability")
 		return
 	}
+	idempotencyKey, hasIdempotencyKey, err := optionalTaskIdempotencyKey(r)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "Idempotency-Key must contain one non-empty value", "invalid_idempotency_key")
+		return
+	}
 	prepared, err := s.prepareTaskRequest(r.Context(), r, user, mapping.Body)
 	if err != nil {
 		s.logger.Warn("prepare gemini task request failed", "kind", mapping.Kind, "error", err)
@@ -104,7 +110,7 @@ func (s *Server) geminiGenerateContent(w http.ResponseWriter, r *http.Request) {
 		writeError(w, status, err.Error(), clients.ErrorCode(err))
 		return
 	}
-	task, err := s.store.CreateTask(r.Context(), store.CreateTaskInput{
+	createInput := store.CreateTaskInput{
 		Kind:            mapping.Kind,
 		Model:           mapping.Model,
 		RunMode:         runModeFromRequest(prepared.Body),
@@ -113,10 +119,33 @@ func (s *Server) geminiGenerateContent(w http.ResponseWriter, r *http.Request) {
 		ConversationID:  prepared.ConversationID,
 		NewMessageCount: prepared.NewMessageCount,
 		MessageRefs:     prepared.MessageRefs,
-	}, user)
+	}
+	if hasIdempotencyKey {
+		createInput.IdempotencyKeyHash = taskIdempotencyKeyHash(idempotencyKey)
+		createInput.IdempotencyRequestHash = taskIdempotencyRequestHash(mapping.Kind, false, false, prepared.Body)
+	}
+	created, err := s.store.CreateTaskIdempotent(r.Context(), createInput, user)
 	if err != nil {
-		s.logger.Error("create gemini task failed", "kind", mapping.Kind, "error", err)
-		writeError(w, http.StatusInternalServerError, "create task failed")
+		if errors.Is(err, store.ErrIdempotencyKeyReused) {
+			writeError(w, http.StatusConflict, "Idempotency-Key was reused for a different request", "idempotency_key_reused")
+			return
+		}
+		s.logger.Error("create gemini task failed", "kind", mapping.Kind, "error_category", "task_create_failed")
+		writeError(w, http.StatusInternalServerError, "create task failed", "task_create_failed")
+		return
+	}
+	task := created.Task
+	if created.Replayed {
+		if s.billingMetrics != nil {
+			s.billingMetrics.ObserveBillingEvent("idempotent_replay")
+		}
+		w.Header().Set("Idempotent-Replayed", "true")
+		w.Header().Set("X-Gateway-Task-Id", task.ID)
+		if task.Status == "succeeded" {
+			writeJSON(w, http.StatusOK, geminiGenerateContentResponse(task.Result, mapping.Model))
+			return
+		}
+		writeIdempotentTaskReplay(w, task, true)
 		return
 	}
 	runCtx, cancelRun := s.requestExecutionContext(r)

apps/api/internal/httpapi/handlers.go

@@ -917,7 +917,13 @@ func (s *Server) estimatePricing(w http.ResponseWriter, r *http.Request) {
 	}
 	estimate, err := s.runner.Estimate(r.Context(), kind, model, body, user)
 	if err != nil {
+		if s.billingMetrics != nil {
+			s.billingMetrics.ObserveBillingEvent("estimate_failed")
+		}
 		if runner.IsPricingUnavailable(err) {
+			if s.billingMetrics != nil {
+				s.billingMetrics.ObserveBillingEvent("pricing_unavailable")
+			}
 			writeErrorWithDetails(w, http.StatusServiceUnavailable, runErrorMessage(err), runErrorDetails(err), "pricing_unavailable")
 			return
 		}
@@ -982,6 +988,7 @@ func (s *Server) listModelRateLimitStatuses(w http.ResponseWriter, r *http.Reque
 // @Produce json
 // @Security BearerAuth
 // @Param X-Async header bool false "true 时异步创建任务并返回 202"
+// @Param Idempotency-Key header string false "可选请求幂等键；同一用户范围内唯一"
 // @Param input body TaskRequest true "AI 任务请求，字段随任务类型变化"
 // @Success 200 {object} CompatibleResponse
 // @Success 202 {object} TaskAcceptedResponse
@@ -1050,6 +1057,11 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 			return
 		}
 		responsePlan := planTaskResponse(kind, compatible, body, r)
+		idempotencyKey, hasIdempotencyKey, err := optionalTaskIdempotencyKey(r)
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "Idempotency-Key must contain one non-empty value", "invalid_idempotency_key")
+			return
+		}
 		prepared, err := s.prepareTaskRequest(r.Context(), r, user, body)
 		if err != nil {
 			s.logger.Warn("prepare task request failed", "kind", kind, "error", err)
@@ -1061,7 +1073,7 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 			return
 		}
 
-		task, err := s.store.CreateTask(r.Context(), store.CreateTaskInput{
+		createInput := store.CreateTaskInput{
 			Kind:            kind,
 			Model:           model,
 			RunMode:         runModeFromRequest(prepared.Body),
@@ -1070,10 +1082,32 @@ func (s *Server) createTask(kind string, compatible bool) http.Handler {
 			ConversationID:  prepared.ConversationID,
 			NewMessageCount: prepared.NewMessageCount,
 			MessageRefs:     prepared.MessageRefs,
-		}, user)
+		}
+		if hasIdempotencyKey {
+			createInput.IdempotencyKeyHash = taskIdempotencyKeyHash(idempotencyKey)
+			createInput.IdempotencyRequestHash = taskIdempotencyRequestHash(kind, responsePlan.asyncMode, responsePlan.streamMode, prepared.Body)
+		}
+		created, err := s.store.CreateTaskIdempotent(r.Context(), createInput, user)
 		if err != nil {
-			s.logger.Error("create task failed", "kind", kind, "error", err)
-			writeError(w, http.StatusInternalServerError, "create task failed")
+			if errors.Is(err, store.ErrIdempotencyKeyReused) {
+				writeError(w, http.StatusConflict, "Idempotency-Key was reused for a different request", "idempotency_key_reused")
+				return
+			}
+			s.logger.Error("create task failed", "kind", kind, "error_category", "task_create_failed")
+			writeError(w, http.StatusInternalServerError, "create task failed", "task_create_failed")
+			return
+		}
+		task := created.Task
+		if created.Replayed {
+			if s.billingMetrics != nil {
+				s.billingMetrics.ObserveBillingEvent("idempotent_replay")
+			}
+			w.Header().Set("Idempotent-Replayed", "true")
+			if responsePlan.streamMode {
+				writeError(w, http.StatusConflict, "streaming idempotent replay is not supported", "idempotency_stream_replay_unsupported")
+				return
+			}
+			writeIdempotentTaskReplay(w, task, responsePlan.compatibleMode)
 			return
 		}
 		if responsePlan.asyncMode {
@@ -1388,6 +1422,8 @@ func scopeForTaskKind(kind string) string {
 
 func statusFromRunError(err error) int {
 	switch {
+	case clients.ErrorCode(err) == "billing_hold":
+		return http.StatusServiceUnavailable
 	case runner.IsPricingUnavailable(err):
 		return http.StatusServiceUnavailable
 	case clients.ErrorCode(err) == "invalid_previous_response_id" || clients.ErrorCode(err) == "response_chain_too_deep" || clients.ErrorCode(err) == "unsupported_model_protocol" || clients.ErrorCode(err) == "unsupported_response_tool" || clients.ErrorCode(err) == "unsupported_response_parameter":

apps/api/internal/httpapi/oidc_jit_integration_test.go

@@ -43,7 +43,7 @@ func TestOIDCJITFullGatewayUserFlowAndSecurityBoundary(t *testing.T) {
 	if err != nil {
 		t.Fatalf("connect store: %v", err)
 	}
-	defer db.Close()
+	t.Cleanup(db.Close)
 
 	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
 	if err != nil {
@@ -247,6 +247,9 @@ DELETE FROM gateway_users WHERE source = 'oidc' AND external_user_id = ANY($1::t
 		t.Fatalf("rejected OIDC tokens created %d local users", rejectedWrites)
 	}
 
+	if _, err := db.DisableActiveIdentityRevision(ctx, activeRevision.Version, "oidc-jit-disabled", "oidc-jit-disabled"); err != nil {
+		t.Fatalf("disable initial OIDC JIT revision: %v", err)
+	}
 	disabledJITRevision := prepareOIDCJITRevision(t, ctx, db, baseConfig, issuer, "default", false)
 	testRevisionIDs = append(testRevisionIDs, disabledJITRevision.ID)
 	disabledJITRevision, _, err = db.ActivateIdentityRevision(ctx, disabledJITRevision.ID, disabledJITRevision.Version, "oidc-jit-disabled", "oidc-jit-disabled")
@@ -298,6 +301,9 @@ func prepareOIDCJITRevision(t *testing.T, ctx context.Context, db *store.Store,
 	if err := secrets.Put(ctx, sessionReference, bytes.Repeat([]byte{8}, 32)); err != nil {
 		t.Fatalf("store OIDC JIT session key: %v", err)
 	}
+	if err := db.QueueIdentitySecretCleanup(ctx, sessionReference, time.Now().Add(10*time.Minute)); err != nil {
+		t.Fatalf("stage OIDC JIT session key for adoption: %v", err)
+	}
 	draft, err = db.ApplyIdentityManifest(ctx, draft.ID, draft.Version, identity.ManifestApplication{
 		Manifest: identity.ManifestV1{
 			SchemaVersion: 1, Issuer: issuer, TenantID: oidcJITTenantID, ApplicationID: uuid.NewString(),
@@ -360,6 +366,10 @@ var currentOIDCTestNonce string
 
 func createOIDCBFFSessionCookie(t *testing.T, baseURL string) *http.Cookie {
 	t.Helper()
+	parsedBaseURL, err := url.Parse(baseURL)
+	if err != nil {
+		t.Fatal(err)
+	}
 	jar, err := cookiejar.New(nil)
 	if err != nil {
 		t.Fatal(err)
@@ -371,6 +381,11 @@ func createOIDCBFFSessionCookie(t *testing.T, baseURL string) *http.Cookie {
 		if len(via) > 10 {
 			return errors.New("too many redirects")
 		}
+		// Follow the synthetic issuer's authorization redirect, then stop before
+		// the callback redirects the browser to the separately hosted web app.
+		if request.URL.Host != parsedBaseURL.Host && request.URL.Path != "/authorize" {
+			return http.ErrUseLastResponse
+		}
 		return nil
 	}}
 	response, err := client.Get(baseURL + "/api/v1/auth/oidc/login?returnTo=%2Fapi%2Fv1%2Fme")
@@ -378,11 +393,10 @@ func createOIDCBFFSessionCookie(t *testing.T, baseURL string) *http.Cookie {
 		t.Fatalf("complete OIDC BFF login: %v", err)
 	}
 	defer response.Body.Close()
-	if response.StatusCode != http.StatusOK {
+	if response.StatusCode != http.StatusOK && response.StatusCode != http.StatusSeeOther {
 		body, _ := io.ReadAll(response.Body)
 		t.Fatalf("OIDC BFF login status = %d, want 200: %s", response.StatusCode, body)
 	}
-	parsedBaseURL, _ := url.Parse(baseURL)
 	for _, cookie := range jar.Cookies(parsedBaseURL) {
 		if cookie.Name == auth.OIDCSessionCookieName {
 			if strings.Count(cookie.Value, ".") == 2 {

apps/api/internal/httpapi/openapi_models.go

@@ -114,6 +114,18 @@ type AuditLogListResponse struct {
 	Items []store.AuditLog `json:"items"`
 }
 
+type BillingSettlementListResponse struct {
+	Items    []store.BillingSettlement `json:"items"`
+	Total    int                       `json:"total" example:"42"`
+	Page     int                       `json:"page" example:"1"`
+	PageSize int                       `json:"pageSize" example:"50"`
+}
+
+type BillingSettlementRetryResponse struct {
+	Settlement store.BillingSettlement `json:"settlement"`
+	AuditLog   store.AuditLog          `json:"auditLog"`
+}
+
 type WalletTransactionListResponse struct {
 	Items    []store.GatewayWalletTransaction `json:"items"`
 	Total    int                              `json:"total" example:"42"`

apps/api/internal/httpapi/server.go

@@ -43,6 +43,7 @@ type Server struct {
 	identityTestRevision       identity.Revision
 	identityTestCookieSecure   bool
 	identityTestBrowserEnabled bool
+	billingMetrics             *ssfreceiver.Metrics
 }
 
 type oidcPublicClient interface {
@@ -66,18 +67,19 @@ func NewServer(cfg config.Config, db *store.Store, logger *slog.Logger) http.Han
 }
 
 func NewServerWithContext(ctx context.Context, cfg config.Config, db *store.Store, logger *slog.Logger) http.Handler {
+	securityEventMetrics := &ssfreceiver.Metrics{}
 	server := &Server{
 		ctx:              ctx,
 		cfg:              cfg,
 		store:            db,
 		oidcUserResolver: db,
 		auth:             auth.New(cfg.JWTSecret, cfg.ServerMainBaseURL, cfg.ServerMainInternalToken),
-		runner:           runner.New(cfg, db, logger),
+		runner:           runner.New(cfg, db, logger, securityEventMetrics),
 		logger:           logger,
+		billingMetrics:   securityEventMetrics,
 	}
 	server.auth.ServerMainInternalKey = cfg.ServerMainInternalKey
 	server.auth.ServerMainInternalSecret = cfg.ServerMainInternalSecret
-	securityEventMetrics := &ssfreceiver.Metrics{}
 	secretStore, err := identitySecretStore(cfg)
 	if err != nil {
 		panic("invalid identity SecretStore: " + err.Error())
@@ -118,6 +120,7 @@ func NewServerWithContext(ctx context.Context, cfg config.Config, db *store.Stor
 	}
 	server.auth.LocalAPIKeyVerifier = db.VerifyLocalAPIKey
 	server.runner.StartAsyncQueueWorker(ctx)
+	server.runner.StartBillingSettlementWorker(ctx)
 	server.startLocalTempAssetCleanup(ctx)
 	server.startOIDCSessionCleanup(ctx)
 
@@ -204,6 +207,8 @@ func NewServerWithContext(ctx context.Context, cfg config.Config, db *store.Stor
 	mux.Handle("DELETE /api/admin/runtime/policy-sets/{policySetID}", server.requireAdmin(auth.PermissionManager, http.HandlerFunc(server.deleteRuntimePolicySet)))
 	mux.Handle("GET /api/admin/runtime/runner-policy", server.requireAdmin(auth.PermissionPower, http.HandlerFunc(server.getRunnerPolicy)))
 	mux.Handle("PATCH /api/admin/runtime/runner-policy", server.requireAdmin(auth.PermissionManager, http.HandlerFunc(server.updateRunnerPolicy)))
+	mux.Handle("GET /api/admin/runtime/billing-settlements", server.requireAdmin(auth.PermissionPower, http.HandlerFunc(server.listBillingSettlements)))
+	mux.Handle("POST /api/admin/runtime/billing-settlements/{settlementId}/retry", server.requireAdmin(auth.PermissionManager, http.HandlerFunc(server.retryBillingSettlement)))
 	mux.Handle("POST /api/admin/runtime/model-rate-limits/{platformModelID}/restore", server.requireAdmin(auth.PermissionManager, http.HandlerFunc(server.restorePlatformModelRuntimeStatus)))
 	mux.Handle("GET /api/admin/config/network-proxy", server.requireAdmin(auth.PermissionPower, http.HandlerFunc(server.getNetworkProxyConfig)))
 	mux.Handle("GET /api/admin/system/file-storage/settings", server.requireAdmin(auth.PermissionPower, http.HandlerFunc(server.getFileStorageSettings)))

apps/api/internal/httpapi/task_idempotency.go

@@ -0,0 +1,85 @@
+package httpapi
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
+)
+
+var errInvalidTaskIdempotencyKey = errors.New("invalid Idempotency-Key header")
+
+func optionalTaskIdempotencyKey(r *http.Request) (string, bool, error) {
+	values := r.Header.Values("Idempotency-Key")
+	if len(values) == 0 {
+		return "", false, nil
+	}
+	if len(values) != 1 {
+		return "", false, errInvalidTaskIdempotencyKey
+	}
+	value := strings.TrimSpace(values[0])
+	if value == "" || len(value) > 255 || strings.Contains(value, ",") {
+		return "", false, errInvalidTaskIdempotencyKey
+	}
+	return value, true, nil
+}
+
+func taskIdempotencyKeyHash(key string) string {
+	digest := sha256.Sum256([]byte(key))
+	return hex.EncodeToString(digest[:])
+}
+
+func taskIdempotencyRequestHash(kind string, async bool, stream bool, body map[string]any) string {
+	payload, _ := json.Marshal(map[string]any{
+		"kind": kind, "async": async, "stream": stream, "request": body,
+	})
+	digest := sha256.Sum256(payload)
+	return hex.EncodeToString(digest[:])
+}
+
+func writeIdempotentTaskReplay(w http.ResponseWriter, task store.GatewayTask, compatible bool) {
+	w.Header().Set("Idempotent-Replayed", "true")
+	w.Header().Set("X-Gateway-Task-Id", task.ID)
+	if !compatible || task.AsyncMode || (task.Status != "succeeded" && task.Status != "failed" && task.Status != "cancelled") {
+		writeTaskAccepted(w, task)
+		return
+	}
+	if task.Status == "succeeded" {
+		writeJSON(w, http.StatusOK, task.Result)
+		return
+	}
+	status := storedTaskErrorStatus(task.ErrorCode)
+	message := strings.TrimSpace(task.ErrorMessage)
+	if message == "" {
+		message = strings.TrimSpace(task.Error)
+	}
+	if message == "" {
+		message = "task failed"
+	}
+	code := strings.TrimSpace(task.ErrorCode)
+	if code == "" {
+		code = "task_failed"
+	}
+	writeError(w, status, message, code)
+}
+
+func storedTaskErrorStatus(code string) int {
+	switch strings.TrimSpace(code) {
+	case "pricing_unavailable", "response_chain_unavailable", "billing_hold":
+		return http.StatusServiceUnavailable
+	case "insufficient_balance":
+		return http.StatusPaymentRequired
+	case "bad_request", "invalid_parameter", "invalid_previous_response_id", "unsupported_operation":
+		return http.StatusBadRequest
+	case "no_model_candidate", "cloned_voice_not_found":
+		return http.StatusNotFound
+	case "rate_limit", "platform_cooling_down", "model_cooling_down":
+		return http.StatusTooManyRequests
+	default:
+		return http.StatusBadGateway
+	}
+}

apps/api/internal/httpapi/task_idempotency_test.go

@@ -0,0 +1,31 @@
+package httpapi
+
+import (
+	"net/http/httptest"
+	"testing"
+)
+
+func TestOptionalTaskIdempotencyKeyRejectsMultipleValues(t *testing.T) {
+	t.Parallel()
+	request := httptest.NewRequest("POST", "/", nil)
+	if _, present, err := optionalTaskIdempotencyKey(request); err != nil || present {
+		t.Fatalf("missing key present=%v err=%v", present, err)
+	}
+	request.Header.Add("Idempotency-Key", "one")
+	request.Header.Add("Idempotency-Key", "two")
+	if _, _, err := optionalTaskIdempotencyKey(request); err == nil {
+		t.Fatal("multiple keys must be rejected")
+	}
+}
+
+func TestTaskIdempotencyRequestHashIsCanonical(t *testing.T) {
+	t.Parallel()
+	first := map[string]any{"model": "m", "n": float64(1), "nested": map[string]any{"b": true, "a": "x"}}
+	second := map[string]any{"nested": map[string]any{"a": "x", "b": true}, "n": float64(1), "model": "m"}
+	if taskIdempotencyRequestHash("images.generations", false, false, first) != taskIdempotencyRequestHash("images.generations", false, false, second) {
+		t.Fatal("equivalent JSON objects must have the same request hash")
+	}
+	if taskIdempotencyRequestHash("images.generations", true, false, first) == taskIdempotencyRequestHash("images.generations", false, false, first) {
+		t.Fatal("async response semantics must be part of the request hash")
+	}
+}