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

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

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)