fix: 统一缓存token计费口径，避免OpenAI错误计费 (#144)

* fix: 统一缓存token计费口径，避免OpenAI错误计费

* fix: 添加 Gemini 缓存 token 归一化支持，优化代码结构

- Gemini 的 promptTokenCount 包含 cachedContentTokenCount，需要扣除
- 合并重复的 helper 函数为 _get_api_family()
- 将 import 移到文件顶部
- 补充 Gemini 测试用例

---------

Co-authored-by: fawney19 <elky0401@gmail.com>

src/services/billing/token_normalization.py

@@ -0,0 +1,47 @@
+"""
+计费相关 token 归一化工具。
+"""
+
+from __future__ import annotations
+
+from src.core.api_format.enums import ApiFamily
+from src.core.api_format.signature import parse_signature_key
+
+
+def _get_api_family(api_format: str | None) -> ApiFamily | None:
+    """解析 api_format 字符串，返回对应的 ApiFamily 枚举。"""
+    if not api_format:
+        return None
+    text = str(api_format).strip()
+    if not text:
+        return None
+    sig = parse_signature_key(text)
+    return sig.api_family
+
+
+def normalize_input_tokens_for_billing(
+    api_format: str | None,
+    input_tokens: int,
+    cache_read_tokens: int,
+) -> int:
+    """
+    归一化 `input_tokens`，使其在计费中表示"非缓存输入 token"。
+
+    计费口径：`input_tokens`=非缓存输入 token；`cache_read_tokens`=缓存命中 token（折扣/免费维度）。
+
+    - Claude 系：保持上游口径（不扣除），因为 Claude API 的 input_tokens 本身就不包含缓存部分。
+    - OpenAI 系：`input_tokens` 包含缓存命中部分，需要扣除 `cache_read_tokens`。
+    - Gemini 系：`promptTokenCount` 包含 `cachedContentTokenCount`，需要扣除。
+    """
+    if input_tokens <= 0:
+        return 0 if input_tokens == 0 else input_tokens
+    if cache_read_tokens <= 0:
+        return input_tokens
+
+    api_family = _get_api_family(api_format)
+    if api_family == ApiFamily.CLAUDE:
+        return input_tokens
+    if api_family in (ApiFamily.OPENAI, ApiFamily.GEMINI):
+        return max(input_tokens - cache_read_tokens, 0)
+    # 未知格式，保守处理，不扣除
+    return input_tokens

src/services/usage/service.py

@@ -25,6 +25,7 @@ from src.models.database import (
     User,
     UserRole,
 )
+from src.services.billing.token_normalization import normalize_input_tokens_for_billing
 from src.services.model.cost import ModelCostService
 from src.services.system.config import SystemConfigService
 from src.services.usage.error_classifier import classify_error
@@ -843,9 +844,28 @@ class UsageService:
         Returns:
             (usage_params 字典, total_cost 总成本)
         """
+        # 计费口径以 Provider 为准（优先 endpoint_api_format）
+        billing_api_format: str | None = None
+        if params.endpoint_api_format:
+            try:
+                billing_api_format = normalize_signature_key(str(params.endpoint_api_format))
+            except Exception:
+                billing_api_format = None
+        if billing_api_format is None and params.api_format:
+            try:
+                billing_api_format = normalize_signature_key(str(params.api_format))
+            except Exception:
+                billing_api_format = None
+
+        input_tokens_for_billing = normalize_input_tokens_for_billing(
+            billing_api_format,
+            params.input_tokens,
+            params.cache_read_input_tokens,
+        )
+
         # 获取费率倍数和是否免费套餐（传递 api_format 支持按格式配置的倍率）
         actual_rate_multiplier, is_free_tier = await cls._get_rate_multiplier_and_free_tier(
-            params.db, params.provider_api_key_id, params.provider_id, params.api_format
+            params.db, params.provider_api_key_id, params.provider_id, billing_api_format
         )
 
         metadata = dict(params.metadata or {})
@@ -884,7 +904,7 @@ class UsageService:
 
             request_count = 0 if is_failed_request else 1
             dims: dict[str, Any] = {
-                "input_tokens": params.input_tokens,
+                "input_tokens": input_tokens_for_billing,
                 "output_tokens": params.output_tokens,
                 "cache_creation_input_tokens": params.cache_creation_input_tokens,
                 "cache_read_input_tokens": params.cache_read_input_tokens,
@@ -956,11 +976,11 @@ class UsageService:
                 db=params.db,
                 provider=params.provider,
                 model=params.model,
-                input_tokens=params.input_tokens,
+                input_tokens=input_tokens_for_billing,
                 output_tokens=params.output_tokens,
                 cache_creation_input_tokens=params.cache_creation_input_tokens,
                 cache_read_input_tokens=params.cache_read_input_tokens,
-                api_format=params.api_format,
+                api_format=billing_api_format,
                 cache_ttl_minutes=params.cache_ttl_minutes,
                 use_tiered_pricing=params.use_tiered_pricing,
                 is_failed_request=is_failed_request,
@@ -989,8 +1009,8 @@ class UsageService:
                         provider_id=params.provider_id,
                         model=params.model,
                         task_type=billing_task_type,
-                        api_format=params.api_format,
-                        input_tokens=params.input_tokens,
+                        api_format=billing_api_format,
+                        input_tokens=input_tokens_for_billing,
                         output_tokens=params.output_tokens,
                         cache_creation_input_tokens=params.cache_creation_input_tokens,
                         cache_read_input_tokens=params.cache_read_input_tokens,
@@ -1019,7 +1039,7 @@ class UsageService:
             api_key=params.api_key,
             provider=params.provider,
             model=params.model,
-            input_tokens=params.input_tokens,
+            input_tokens=input_tokens_for_billing,
             output_tokens=params.output_tokens,
             cache_creation_input_tokens=params.cache_creation_input_tokens,
             cache_read_input_tokens=params.cache_read_input_tokens,