fix(usage): 统一使用记录与仪表盘的缓存命中率计算口径

- 新增归一化总输入上下文计算逻辑，按 provider 区分 OpenAI/Gemini 与 Claude 的 cache token 语义
- 将管理端使用聚合、用户使用记录、仪表盘缓存统计、缓存亲和性分析统一为 token 级缓存命中率
- 修正 total_input_context 字段，避免 cache_read 在部分 provider 上被重复计入分母
- 同步更新相关 Rust 单元测试与网关集成测试断言
- 调整前端 dashboard mock 中 cache_hit_rate 的单位为百分比

apps/aether-gateway/src/handlers/admin/observability/usage/analytics_routes/cache_affinity_hit_analysis.rs

@@ -4,8 +4,9 @@ use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
 use crate::handlers::admin::shared::query_param_value;
 use crate::GatewayError;
 use aether_admin::observability::usage::{
-    admin_usage_bad_request_response, admin_usage_data_unavailable_response,
-    admin_usage_matches_optional_id, admin_usage_parse_recent_hours,
+    admin_usage_bad_request_response, admin_usage_cache_creation_tokens,
+    admin_usage_data_unavailable_response, admin_usage_matches_optional_id,
+    admin_usage_parse_recent_hours, admin_usage_total_input_context,
     ADMIN_USAGE_DATA_UNAVAILABLE_DETAIL,
 };
 use axum::{
@@ -50,10 +51,9 @@ pub(super) async fn build_admin_usage_cache_affinity_hit_analysis_response(
         .iter()
         .map(|item| item.cache_read_input_tokens)
         .sum();
-    let total_cache_creation_tokens: u64 = filtered
-        .iter()
-        .map(|item| item.cache_creation_input_tokens)
-        .sum();
+    let total_cache_creation_tokens: u64 =
+        filtered.iter().map(admin_usage_cache_creation_tokens).sum();
+    let total_input_context: u64 = filtered.iter().map(admin_usage_total_input_context).sum();
     let total_cache_read_cost: f64 = filtered.iter().map(|item| item.cache_read_cost_usd).sum();
     let total_cache_creation_cost: f64 = filtered
         .iter()
@@ -63,12 +63,11 @@ pub(super) async fn build_admin_usage_cache_affinity_hit_analysis_response(
         .iter()
         .filter(|item| item.cache_read_input_tokens > 0)
         .count();
-    let total_context_tokens = total_input_tokens.saturating_add(total_cache_read_tokens);
-    let token_cache_hit_rate = if total_context_tokens == 0 {
+    let token_cache_hit_rate = if total_input_context == 0 {
         0.0
     } else {
         round_to(
-            total_cache_read_tokens as f64 / total_context_tokens as f64 * 100.0,
+            total_cache_read_tokens as f64 / total_input_context as f64 * 100.0,
             2,
         )
     };

apps/aether-gateway/src/handlers/public/support/dashboard_filters.rs

@@ -2,6 +2,7 @@ use super::{
     build_auth_error_response, query_param_value, resolve_authenticated_local_user, AppState,
     GatewayError, GatewayPublicRequestContext,
 };
+use aether_billing::normalize_total_input_context_for_cache_hit_rate;
 use aether_data_contracts::repository::usage::{StoredRequestUsageAudit, UsageAuditListQuery};
 use axum::{
     body::Body,
@@ -28,6 +29,7 @@ struct DashboardUsageTotals {
     total_tokens: u64,
     cache_creation_tokens: u64,
     cache_read_tokens: u64,
+    cache_hit_total_input_context: u64,
     cache_creation_cost_usd: f64,
     cache_read_cost_usd: f64,
     total_cost_usd: f64,
@@ -69,12 +71,14 @@ pub(super) fn decision_route_kind(request_context: &GatewayPublicRequestContext)
 
 impl DashboardUsageTotals {
     fn record(&mut self, item: &StoredRequestUsageAudit) {
+        let cache_creation_tokens = dashboard_cache_creation_tokens(item);
         self.requests += 1;
         self.input_tokens += item.input_tokens;
         self.output_tokens += item.output_tokens;
         self.total_tokens += item.total_tokens;
-        self.cache_creation_tokens += item.cache_creation_input_tokens;
+        self.cache_creation_tokens += cache_creation_tokens;
         self.cache_read_tokens += item.cache_read_input_tokens;
+        self.cache_hit_total_input_context += dashboard_total_input_context(item);
         self.cache_creation_cost_usd += item.cache_creation_cost_usd;
         self.cache_read_cost_usd += item.cache_read_cost_usd;
         self.total_cost_usd += item.total_cost_usd;
@@ -102,15 +106,45 @@ impl DashboardUsageTotals {
     }
 
     fn cache_hit_rate(&self) -> f64 {
-        let total_cache_tokens = self.cache_creation_tokens + self.cache_read_tokens;
-        if total_cache_tokens == 0 {
+        if self.cache_hit_total_input_context == 0 {
             0.0
         } else {
-            dashboard_round_f64(self.cache_read_tokens as f64 / total_cache_tokens as f64, 4)
+            dashboard_round_f64(
+                self.cache_read_tokens as f64 / self.cache_hit_total_input_context as f64 * 100.0,
+                2,
+            )
         }
     }
 }
 
+fn dashboard_cache_creation_tokens(item: &StoredRequestUsageAudit) -> u64 {
+    let classified = item
+        .cache_creation_ephemeral_5m_input_tokens
+        .saturating_add(item.cache_creation_ephemeral_1h_input_tokens);
+    if item.cache_creation_input_tokens == 0 && classified > 0 {
+        classified
+    } else {
+        item.cache_creation_input_tokens
+    }
+}
+
+fn dashboard_total_input_context(item: &StoredRequestUsageAudit) -> u64 {
+    let api_format = item
+        .endpoint_api_format
+        .as_deref()
+        .or(item.api_format.as_deref());
+    let input_tokens = i64::try_from(item.input_tokens).unwrap_or(i64::MAX);
+    let cache_creation_tokens =
+        i64::try_from(dashboard_cache_creation_tokens(item)).unwrap_or(i64::MAX);
+    let cache_read_tokens = i64::try_from(item.cache_read_input_tokens).unwrap_or(i64::MAX);
+    normalize_total_input_context_for_cache_hit_rate(
+        api_format,
+        input_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+    ) as u64
+}
+
 fn dashboard_round_f64(value: f64, decimals: u32) -> f64 {
     let factor = 10_f64.powi(i32::try_from(decimals).unwrap_or_default());
     (value * factor).round() / factor

apps/aether-gateway/src/handlers/public/support/user_me_usage.rs

@@ -1,6 +1,8 @@
 use std::collections::{BTreeMap, BTreeSet};
 
-use aether_billing::normalize_input_tokens_for_billing;
+use aether_billing::{
+    normalize_input_tokens_for_billing, normalize_total_input_context_for_cache_hit_rate,
+};
 use aether_data_contracts::repository::usage::{StoredRequestUsageAudit, UsageAuditListQuery};
 use axum::{
     body::Body,
@@ -101,9 +103,20 @@ fn users_me_usage_cache_creation_tokens(item: &StoredRequestUsageAudit) -> u64 {
 }
 
 fn users_me_usage_total_input_context(item: &StoredRequestUsageAudit) -> u64 {
-    item.input_tokens
-        .saturating_add(users_me_usage_cache_creation_tokens(item))
-        .saturating_add(item.cache_read_input_tokens)
+    let api_format = item
+        .endpoint_api_format
+        .as_deref()
+        .or(item.api_format.as_deref());
+    let input_tokens = i64::try_from(item.input_tokens).unwrap_or(i64::MAX);
+    let cache_creation_tokens =
+        i64::try_from(users_me_usage_cache_creation_tokens(item)).unwrap_or(i64::MAX);
+    let cache_read_tokens = i64::try_from(item.cache_read_input_tokens).unwrap_or(i64::MAX);
+    normalize_total_input_context_for_cache_hit_rate(
+        api_format,
+        input_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+    ) as u64
 }
 
 fn users_me_usage_effective_input_tokens(item: &StoredRequestUsageAudit) -> u64 {

apps/aether-gateway/src/tests/control/admin/usage.rs

@@ -393,11 +393,11 @@ async fn gateway_handles_admin_usage_aggregation_stats_locally_with_trusted_admi
     assert_eq!(items[0]["request_count"], 2);
     assert_eq!(items[0]["output_tokens"], 40);
     assert_eq!(items[0]["effective_input_tokens"], 150);
-    assert_eq!(items[0]["total_input_context"], 200);
+    assert_eq!(items[0]["total_input_context"], 160);
     assert_eq!(items[0]["cache_creation_tokens"], 30);
     assert_eq!(items[0]["cache_creation_ephemeral_5m_tokens"], 12);
     assert_eq!(items[0]["cache_creation_ephemeral_1h_tokens"], 18);
-    assert_eq!(items[0]["cache_hit_rate"], 5.0);
+    assert_eq!(items[0]["cache_hit_rate"], 6.25);
     assert_eq!(items[1]["model"], "claude-3-7");
     assert_eq!(items[1]["output_tokens"], 20);
 
@@ -1498,7 +1498,7 @@ async fn gateway_handles_admin_usage_cache_affinity_hit_analysis_locally_with_tr
     assert_eq!(payload["total_input_tokens"], 140);
     assert_eq!(payload["total_cache_read_tokens"], 50);
     assert_eq!(payload["total_cache_creation_tokens"], 15);
-    assert_eq!(payload["token_cache_hit_rate"], 26.32);
+    assert_eq!(payload["token_cache_hit_rate"], 35.71);
     assert_eq!(payload["total_cache_read_cost_usd"], 0.02);
     assert_eq!(payload["total_cache_creation_cost_usd"], 0.015);
     assert_eq!(payload["estimated_savings_usd"], 0.18);

apps/aether-gateway/src/tests/frontdoor/public_support.rs

@@ -4763,7 +4763,7 @@ async fn gateway_handles_users_me_usage_locally_without_proxying_upstream() {
         payload["summary_by_model"][0]["effective_input_tokens"],
         105
     );
-    assert_eq!(payload["summary_by_model"][0]["total_input_context"], 145);
+    assert_eq!(payload["summary_by_model"][0]["total_input_context"], 120);
     assert_eq!(payload["billing"]["id"], "wallet-auth-1");
     assert_eq!(*upstream_hits.lock().expect("mutex should lock"), 0);