Merge pull request #217 from AAEE86/1233

perf: 优化请求鉴权链路并批量化统计/调度查询

tests/services/test_auth.py

@@ -8,18 +8,20 @@
 """
 
 from datetime import datetime, timedelta, timezone
+from decimal import Decimal
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import jwt
 import pytest
 
-from src.core.exceptions import ForbiddenException
 from src.core.enums import AuthSource
+from src.core.exceptions import ForbiddenException
 from src.models.database import UserRole
 from src.services.auth.service import (
     JWT_ALGORITHM,
     JWT_EXPIRATION_HOURS,
     JWT_SECRET_KEY,
+    AuthenticatedUserSnapshot,
     AuthService,
 )
 
@@ -235,6 +237,115 @@ class TestUserAuthentication:
 
         assert result is None
 
+    @pytest.mark.asyncio
+    async def test_authenticate_user_threadsafe_uses_isolated_session_for_local_login(self) -> None:
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.email = "test@example.com"
+        mock_user.username = "tester"
+        mock_user.created_at = datetime.now(timezone.utc)
+        mock_user.is_deleted = False
+        mock_user.is_active = True
+        mock_user.auth_source = AuthSource.LOCAL
+        mock_user.role = UserRole.USER
+        mock_user.verify_password.return_value = True
+
+        thread_db = MagicMock()
+        thread_db.query.return_value.filter.return_value.first.return_value = mock_user
+        route_db = MagicMock()
+
+        with patch("src.services.auth.service.create_session", return_value=thread_db):
+            with patch(
+                "src.services.auth.service.UserCacheService.invalidate_user_cache",
+                new_callable=AsyncMock,
+            ) as invalidate_cache:
+                result = await AuthService.authenticate_user_threadsafe(
+                    route_db,
+                    "test@example.com",
+                    "password123",
+                )
+
+        assert isinstance(result, AuthenticatedUserSnapshot)
+        assert result.user_id == "user-123"
+        assert result.username == "tester"
+        thread_db.commit.assert_called_once()
+        thread_db.close.assert_called_once()
+        route_db.commit.assert_not_called()
+        invalidate_cache.assert_awaited_once_with("user-123", "test@example.com")
+
+    @pytest.mark.asyncio
+    async def test_load_user_for_pipeline_threadsafe_prefetches_balance(self) -> None:
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_user.is_active = True
+        mock_user.is_deleted = False
+
+        thread_db = MagicMock()
+        thread_db.query.return_value.filter.return_value.first.return_value = mock_user
+
+        with patch("src.services.auth.service.create_session", return_value=thread_db):
+            with patch(
+                "src.services.wallet.service.WalletService.get_balance_snapshot",
+                return_value=Decimal("7.5"),
+            ):
+                result = await AuthService.load_user_for_pipeline_threadsafe(
+                    "user-123",
+                    include_balance=True,
+                )
+
+        assert result is not None
+        assert result.user == mock_user
+        assert result.balance_remaining == 7.5
+        thread_db.expunge.assert_called_with(mock_user)
+        thread_db.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_authenticate_api_key_threadsafe_returns_balance_and_access_result(self) -> None:
+        mock_user = MagicMock()
+        mock_user.id = "user-123"
+        mock_api_key = MagicMock()
+        mock_api_key.id = "key-123"
+
+        thread_db = MagicMock()
+
+        with patch("src.services.auth.service.create_session", return_value=thread_db):
+            with patch.object(
+                AuthService,
+                "authenticate_api_key",
+                return_value=(mock_user, mock_api_key),
+            ):
+                with patch(
+                    "src.services.usage.service.UsageService.check_request_balance_details",
+                    return_value=MagicMock(allowed=False, message="????", remaining=0.0),
+                ) as mock_balance_details:
+                    with patch(
+                        "src.services.wallet.service.WalletService.get_balance_snapshot"
+                    ) as mock_balance_snapshot:
+                        result = await AuthService.authenticate_api_key_threadsafe("sk-test")
+
+        assert result is not None
+        assert result.user == mock_user
+        assert result.api_key == mock_api_key
+        assert result.access_ok is False
+        assert result.balance_remaining == 0.0
+        assert result.access_message == "????"
+        mock_balance_details.assert_called_once()
+        mock_balance_snapshot.assert_not_called()
+        thread_db.expunge.assert_any_call(mock_user)
+        thread_db.expunge.assert_any_call(mock_api_key)
+        thread_db.close.assert_called_once()
+
+    def test_detach_instance_logs_debug_when_expunge_fails(self) -> None:
+        mock_db = MagicMock()
+        mock_db.expunge.side_effect = RuntimeError("expunge boom")
+        mock_instance = MagicMock()
+
+        with patch("src.services.auth.service.logger.debug") as mock_debug:
+            AuthService._detach_instance(mock_db, mock_instance)
+
+        mock_debug.assert_called_once()
+        assert "expunge failed" in mock_debug.call_args[0][0]
+
 
 class TestAPIKeyAuthentication:
     """测试 API Key 认证"""

tests/services/test_model_cache_service.py

@@ -1,36 +1,45 @@
+from types import SimpleNamespace
+from typing import Any, Callable, cast
+
 import pytest
 
-from src.core.cache_service import CacheService
 from src.models.database import GlobalModel, Model
 from src.services.cache.model_cache import ModelCacheService
+from src.core.cache_service import CacheService
 
 
 class _FakeQuery:
-    def __init__(self, *, first_result=None, all_result=None, on_all=None):
+    def __init__(
+        self,
+        *,
+        first_result: Any = None,
+        all_result: list[Any] | None = None,
+        on_all: Callable[[], None] | None = None,
+    ) -> None:
         self._first_result = first_result
         self._all_result = all_result if all_result is not None else []
         self._on_all = on_all
 
-    def join(self, *_args, **_kwargs):
+    def join(self, *_args: object, **_kwargs: object) -> "_FakeQuery":
         return self
 
-    def filter(self, *_args, **_kwargs):
+    def filter(self, *_args: object, **_kwargs: object) -> "_FakeQuery":
         return self
 
-    def first(self):
+    def first(self) -> Any:
         return self._first_result
 
-    def all(self):
+    def all(self) -> list[Any]:
         if self._on_all:
             self._on_all()
         return self._all_result
 
 
 class _FakeSession:
-    def __init__(self, *, direct_match: GlobalModel):
+    def __init__(self, *, direct_match: GlobalModel) -> None:
         self._direct_match = direct_match
 
-    def query(self, *entities):
+    def query(self, *entities: object) -> "_FakeQuery":
         if entities == (GlobalModel,):
             return _FakeQuery(first_result=self._direct_match)
 
@@ -43,12 +52,43 @@ class _FakeSession:
         raise AssertionError(f"Unexpected query entities: {entities}")
 
 
+class _MappingIndexSession:
+    def __init__(
+        self,
+        *,
+        provider_mapping_rows: list[tuple[object, GlobalModel]],
+    ) -> None:
+        self._provider_mapping_rows = provider_mapping_rows
+        self.provider_mapping_scan_count = 0
+        self.model_global_query_count = 0
+
+    def query(self, *entities: object) -> "_FakeQuery":
+        if entities == (GlobalModel,):
+            return _FakeQuery(first_result=None, all_result=[])
+
+        if entities == (Model, GlobalModel):
+            self.model_global_query_count += 1
+            if self.model_global_query_count in {1, 3}:
+                return _FakeQuery(all_result=[])
+            if self.model_global_query_count == 2:
+                return _FakeQuery(
+                    all_result=self._provider_mapping_rows,
+                    on_all=self._record_provider_mapping_scan,
+                )
+            raise AssertionError("provider_model_mappings 全量扫描被重复触发")
+
+        raise AssertionError(f"Unexpected query entities: {entities}")
+
+    def _record_provider_mapping_scan(self) -> None:
+        self.provider_mapping_scan_count += 1
+
+
 @pytest.mark.asyncio
-async def test_resolve_global_model_prefers_direct_match(monkeypatch) -> None:
-    async def _fake_get(_key: str):
+async def test_resolve_global_model_prefers_direct_match(monkeypatch: pytest.MonkeyPatch) -> None:
+    async def _fake_get(_key: str) -> None:
         return None
 
-    async def _fake_set(_key: str, _value, ttl_seconds: int = 60):  # noqa: ARG001
+    async def _fake_set(_key: str, _value: object, ttl_seconds: int = 60) -> bool:  # noqa: ARG001
         return True
 
     monkeypatch.setattr(CacheService, "get", staticmethod(_fake_get))
@@ -67,6 +107,98 @@ async def test_resolve_global_model_prefers_direct_match(monkeypatch) -> None:
     db = _FakeSession(direct_match=global_model)
 
     resolved = await ModelCacheService.resolve_global_model_by_name_or_mapping(
-        db, global_model.name
+        cast(Any, db),
+        cast(str, global_model.name),
     )
     assert resolved is global_model
+
+
+@pytest.mark.asyncio
+async def test_resolve_global_model_reuses_provider_mapping_index_cache(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    cache_store: dict[str, object] = {}
+
+    async def _fake_get(key: str) -> object | None:
+        return cache_store.get(key)
+
+    async def _fake_set(key: str, value: object, ttl_seconds: int = 60) -> bool:  # noqa: ARG001
+        cache_store[key] = value
+        return True
+
+    monkeypatch.setattr(CacheService, "get", staticmethod(_fake_get))
+    monkeypatch.setattr(CacheService, "set", staticmethod(_fake_set))
+
+    global_model_one = GlobalModel(
+        id="gm-1",
+        name="gpt-4o",
+        display_name="GPT-4o",
+        supported_capabilities=[],
+        config={},
+        default_tiered_pricing=None,
+        default_price_per_request=None,
+        is_active=True,
+    )
+    global_model_two = GlobalModel(
+        id="gm-2",
+        name="claude-3-7-sonnet",
+        display_name="Claude 3.7 Sonnet",
+        supported_capabilities=[],
+        config={},
+        default_tiered_pricing=None,
+        default_price_per_request=None,
+        is_active=True,
+    )
+
+    model_one = SimpleNamespace(
+        id="m-1",
+        provider_model_mappings=[{"name": "mapped-one"}],
+    )
+    model_two = SimpleNamespace(
+        id="m-2",
+        provider_model_mappings=[{"name": "mapped-two"}],
+    )
+
+    db = _MappingIndexSession(
+        provider_mapping_rows=[
+            (model_one, global_model_one),
+            (model_two, global_model_two),
+        ]
+    )
+
+    resolved_one = await ModelCacheService.resolve_global_model_by_name_or_mapping(
+        cast(Any, db), "mapped-one"
+    )
+    resolved_two = await ModelCacheService.resolve_global_model_by_name_or_mapping(
+        cast(Any, db), "mapped-two"
+    )
+
+    assert resolved_one is not None
+    assert resolved_one.name == "gpt-4o"
+    assert resolved_two is not None
+    assert resolved_two.name == "claude-3-7-sonnet"
+    assert db.provider_mapping_scan_count == 1
+
+
+@pytest.mark.asyncio
+async def test_invalidate_model_cache_clears_provider_mapping_index(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    deleted_keys: list[str] = []
+
+    async def _fake_delete(key: str) -> bool:
+        deleted_keys.append(key)
+        return True
+
+    monkeypatch.setattr(CacheService, "delete", staticmethod(_fake_delete))
+
+    await ModelCacheService.invalidate_model_cache(
+        model_id="model-1",
+        provider_model_name="provider-model",
+        provider_model_mappings=[{"name": "alias-model"}],
+    )
+
+    assert "model:id:model-1" in deleted_keys
+    assert "global_model:resolve:provider-model" in deleted_keys
+    assert "global_model:resolve:alias-model" in deleted_keys
+    assert ModelCacheService.PROVIDER_MAPPING_INDEX_CACHE_KEY in deleted_keys

tests/services/test_stats_aggregator_optimization.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from datetime import date, datetime, time, timedelta, timezone
+from types import SimpleNamespace
+from typing import Any, cast
+
+import pytest
+
+from src.models.database import StatsDaily, StatsUserDaily
+from src.services.system.stats_aggregator import (
+    AggregatedStats,
+    StatsAggregatorService,
+    query_stats_hybrid,
+)
+from src.services.system.time_range import TimeRangeParams
+
+
+class _FakeQuery:
+    def __init__(self, *, all_result: list[Any] | None = None) -> None:
+        self._all_result = all_result if all_result is not None else []
+
+    def filter(self, *_args: object, **_kwargs: object) -> _FakeQuery:
+        return self
+
+    def group_by(self, *_args: object, **_kwargs: object) -> _FakeQuery:
+        return self
+
+    def all(self) -> list[Any]:
+        return self._all_result
+
+
+class _HybridQuerySession:
+    def __init__(self, stats_daily_rows: list[SimpleNamespace]) -> None:
+        self._stats_daily_rows = stats_daily_rows
+        self.stats_daily_query_count = 0
+
+    def query(self, entity: object) -> _FakeQuery:
+        if entity is StatsDaily:
+            self.stats_daily_query_count += 1
+            return _FakeQuery(all_result=self._stats_daily_rows)
+        raise AssertionError(f"Unexpected query entity: {entity}")
+
+
+class _BatchUserStatsSession:
+    def __init__(
+        self, existing_rows: list[StatsUserDaily], aggregated_rows: list[SimpleNamespace]
+    ) -> None:
+        self._responses: list[list[Any]] = [list(existing_rows), list(aggregated_rows)]
+        self.added: list[StatsUserDaily] = []
+        self.commit_count = 0
+
+    def query(self, *_entities: object) -> _FakeQuery:
+        if not self._responses:
+            raise AssertionError("Unexpected extra query")
+        return _FakeQuery(all_result=self._responses.pop(0))
+
+    def add(self, row: StatsUserDaily) -> None:
+        self.added.append(row)
+
+    def commit(self) -> None:
+        self.commit_count += 1
+
+
+def test_query_stats_hybrid_batches_statsdaily_lookup_and_merges_realtime_ranges(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    today = datetime.now(timezone.utc).date()
+    historical_cached_day = today - timedelta(days=4)
+    historical_missing_day = today - timedelta(days=3)
+    realtime_day = today
+
+    cached_row = SimpleNamespace(
+        date=datetime.combine(historical_cached_day, time.min, tzinfo=timezone.utc),
+        total_requests=10,
+        success_requests=9,
+        error_requests=1,
+        input_tokens=100,
+        output_tokens=50,
+        cache_creation_tokens=5,
+        cache_read_tokens=3,
+        cache_creation_cost=1.2,
+        cache_read_cost=0.8,
+        total_cost=3.5,
+        actual_total_cost=3.0,
+        avg_response_time_ms=200.0,
+    )
+    db = _HybridQuerySession(stats_daily_rows=[cached_row])
+
+    calls: list[tuple[datetime, datetime]] = []
+
+    def _fake_aggregate_usage_range(
+        _db: object,
+        start_utc: datetime,
+        end_utc: datetime,
+        filters: object | None = None,  # noqa: ARG001
+    ) -> AggregatedStats:
+        calls.append((start_utc, end_utc))
+        return AggregatedStats(total_requests=1, success_requests=1)
+
+    class _FakeParams:
+        def get_complete_utc_dates(self) -> tuple[list[date], None, None]:
+            return [historical_cached_day, historical_missing_day, realtime_day], None, None
+
+    monkeypatch.setattr(
+        "src.services.system.stats_aggregator.aggregate_usage_range",
+        _fake_aggregate_usage_range,
+    )
+
+    result = query_stats_hybrid(cast(Any, db), cast(Any, _FakeParams()))
+
+    assert db.stats_daily_query_count == 1
+    assert calls == [
+        (
+            datetime.combine(historical_missing_day, time.min, tzinfo=timezone.utc),
+            datetime.combine(
+                historical_missing_day + timedelta(days=1), time.min, tzinfo=timezone.utc
+            ),
+        ),
+        (
+            datetime.combine(realtime_day, time.min, tzinfo=timezone.utc),
+            datetime.combine(realtime_day + timedelta(days=1), time.min, tzinfo=timezone.utc),
+        ),
+    ]
+    assert result.total_requests == 12
+    assert result.success_requests == 11
+
+
+def test_aggregate_user_daily_stats_batch_updates_all_users_in_two_queries() -> None:
+    target_day = datetime(2026, 3, 1, tzinfo=timezone.utc)
+    aggregated_rows = [
+        SimpleNamespace(
+            user_id="user-1",
+            username="alice",
+            total_requests=4,
+            error_requests=1,
+            input_tokens=20,
+            output_tokens=8,
+            cache_creation_tokens=2,
+            cache_read_tokens=1,
+            total_cost=1.5,
+        )
+    ]
+    db = _BatchUserStatsSession(existing_rows=[], aggregated_rows=aggregated_rows)
+
+    result = StatsAggregatorService.aggregate_user_daily_stats_batch(
+        cast(Any, db),
+        target_day,
+        ["user-1", "user-2"],
+        commit=True,
+    )
+
+    assert len(result) == 2
+    assert db.commit_count == 1
+    assert len(db.added) == 2
+
+    user_one = next(row for row in result if row.user_id == "user-1")
+    user_two = next(row for row in result if row.user_id == "user-2")
+
+    assert user_one.username == "alice"
+    assert user_one.total_requests == 4
+    assert user_one.success_requests == 3
+    assert user_one.total_cost == 1.5
+
+    assert user_two.total_requests == 0
+    assert user_two.success_requests == 0
+    assert user_two.error_requests == 0
+    assert user_two.total_cost == 0.0
+
+
+def test_compute_percentiles_by_local_day_returns_sqlite_fallback_without_queries() -> None:
+    db = SimpleNamespace(bind=SimpleNamespace(dialect=SimpleNamespace(name="sqlite")))
+    time_range = TimeRangeParams(
+        start_date=date(2026, 3, 1),
+        end_date=date(2026, 3, 3),
+        timezone="Asia/Singapore",
+    )
+
+    result = StatsAggregatorService.compute_percentiles_by_local_day(cast(Any, db), time_range)
+
+    assert [row["date"] for row in result] == ["2026-03-01", "2026-03-02", "2026-03-03"]
+    assert all(row["p50_response_time_ms"] is None for row in result)
+    assert all(row["p50_first_byte_time_ms"] is None for row in result)

tests/services/test_usage_service.py

@@ -8,7 +8,7 @@ UsageService 测试
 """
 
 from decimal import Decimal
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 
@@ -146,6 +146,58 @@ class TestBalanceCheck:
 
         assert is_ok is True
 
+    def test_check_request_balance_details_returns_remaining(self) -> None:
+        """Balance detail helper returns remaining."""
+        mock_user = MagicMock()
+        mock_user.role = MagicMock()
+        mock_user.role.value = "user"
+
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+
+        mock_db = MagicMock()
+
+        with patch(
+            "src.services.wallet.WalletService.check_request_allowed",
+            return_value=WalletAccessResult(
+                False, Decimal("12.5"), "\u94b1\u5305\u4f59\u989d\u4e0d\u8db3"
+            ),
+        ):
+            result = UsageService.check_request_balance_details(
+                mock_db, mock_user, api_key=mock_api_key
+            )
+
+        assert result.allowed is False
+        assert result.remaining == 12.5
+        assert "\u4f59\u989d\u4e0d\u8db3" in result.message
+
+    def test_check_request_balance_details_maps_overdue_message(self) -> None:
+        """欠费状态应映射为对外统一文案。"""
+        mock_user = MagicMock()
+        mock_api_key = MagicMock()
+        mock_api_key.is_standalone = False
+        mock_db = MagicMock()
+
+        with patch(
+            "src.services.wallet.WalletService.check_request_allowed",
+            return_value=WalletAccessResult(False, Decimal("-1"), "钱包欠费，请先充值"),
+        ):
+            normal_result = UsageService.check_request_balance_details(
+                mock_db, mock_user, api_key=mock_api_key
+            )
+
+        mock_api_key.is_standalone = True
+        with patch(
+            "src.services.wallet.WalletService.check_request_allowed",
+            return_value=WalletAccessResult(False, Decimal("-1"), "钱包欠费，请先充值"),
+        ):
+            standalone_result = UsageService.check_request_balance_details(
+                mock_db, mock_user, api_key=mock_api_key
+            )
+
+        assert normal_result.message == "账户欠费，请先充值"
+        assert standalone_result.message == "Key欠费，请先调账或充值"
+
     def test_check_request_balance_exceeded(self) -> None:
         """测试余额耗尽时拦截新请求"""
         mock_user = MagicMock()

tests/services/test_wallet_service_rules.py

@@ -1,5 +1,6 @@
 from decimal import Decimal
 from types import SimpleNamespace
+from typing import Any, cast
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -52,7 +53,9 @@ def test_get_or_create_wallet_prefers_user_owner_for_non_standalone_key() -> Non
     user = SimpleNamespace(id="user-1")
     api_key = SimpleNamespace(id="key-1", is_standalone=False)
 
-    wallet = WalletService.get_or_create_wallet(db, user=user, api_key=api_key)
+    wallet = WalletService.get_or_create_wallet(
+        db, user=cast(Any, user), api_key=cast(Any, api_key)
+    )
 
     assert wallet is not None
     assert wallet.user_id == "user-1"
@@ -68,13 +71,35 @@ def test_get_or_create_wallet_uses_api_key_owner_for_standalone_key() -> None:
     user = SimpleNamespace(id="user-1")
     api_key = SimpleNamespace(id="key-1", is_standalone=True)
 
-    wallet = WalletService.get_or_create_wallet(db, user=user, api_key=api_key)
+    wallet = WalletService.get_or_create_wallet(
+        db, user=cast(Any, user), api_key=cast(Any, api_key)
+    )
 
     assert wallet is not None
     assert wallet.user_id is None
     assert wallet.api_key_id == "key-1"
 
 
+def test_get_wallets_by_user_ids_returns_mapping() -> None:
+    db = MagicMock()
+    wallet_1 = SimpleNamespace(user_id="user-1")
+    wallet_2 = SimpleNamespace(user_id="user-2")
+    db.query.return_value.filter.return_value.all.return_value = [wallet_1, wallet_2]
+
+    result = WalletService.get_wallets_by_user_ids(db, ["user-1", "user-2"])
+
+    assert result == {"user-1": wallet_1, "user-2": wallet_2}
+
+
+def test_get_wallets_by_user_ids_skips_query_for_empty_ids() -> None:
+    db = MagicMock()
+
+    result = WalletService.get_wallets_by_user_ids(db, [])
+
+    assert result == {}
+    db.query.assert_not_called()
+
+
 def test_check_request_allowed_denies_when_recharge_negative_even_total_positive() -> None:
     wallet = _build_wallet(recharge="-1", gift="10", limit_mode="finite")
     db = MagicMock()
@@ -104,7 +129,7 @@ def test_admin_adjust_balance_negative_from_gift_spills_to_recharge() -> None:
 
     tx = WalletService.admin_adjust_balance(
         db,
-        wallet=wallet,
+        wallet=cast(Any, wallet),
         amount_usd=Decimal("-10"),
         balance_type="gift",
         operator_id="admin-1",
@@ -127,7 +152,7 @@ def test_admin_adjust_balance_negative_from_recharge_then_gift() -> None:
 
     tx = WalletService.admin_adjust_balance(
         db,
-        wallet=wallet,
+        wallet=cast(Any, wallet),
         amount_usd=Decimal("-4"),
         balance_type="recharge",
         operator_id="admin-1",
@@ -148,7 +173,7 @@ def test_admin_adjust_balance_positive_adds_to_selected_bucket_without_offset()
 
     tx = WalletService.admin_adjust_balance(
         db,
-        wallet=wallet,
+        wallet=cast(Any, wallet),
         amount_usd=Decimal("1"),
         balance_type="gift",
         operator_id="admin-1",
@@ -181,7 +206,9 @@ def test_apply_usage_charge_prefers_gift_then_recharge() -> None:
     db = _build_locked_db(wallet)
 
     with patch.object(WalletService, "_resolve_wallet_for_usage", return_value=wallet):
-        before, after = WalletService.apply_usage_charge(db, usage=usage, amount_usd=Decimal("6"))
+        before, after = WalletService.apply_usage_charge(
+            db, usage=cast(Any, usage), amount_usd=Decimal("6")
+        )
 
     assert before == Decimal("8.00000000")
     assert after == Decimal("2.00000000")
@@ -212,7 +239,9 @@ def test_apply_usage_charge_unlimited_wallet_keeps_balances() -> None:
     db = _build_locked_db(wallet)
 
     with patch.object(WalletService, "_resolve_wallet_for_usage", return_value=wallet):
-        before, after = WalletService.apply_usage_charge(db, usage=usage, amount_usd=Decimal("4"))
+        before, after = WalletService.apply_usage_charge(
+            db, usage=cast(Any, usage), amount_usd=Decimal("4")
+        )
 
     assert before == Decimal("8.00000000")
     assert after == Decimal("8.00000000")
@@ -237,7 +266,7 @@ def test_complete_refund_requires_processing_status() -> None:
     db.query.return_value = query
 
     with pytest.raises(ValueError, match="processing"):
-        WalletService.complete_refund(db, refund=refund)
+        WalletService.complete_refund(db, refund=cast(Any, refund))
 
 
 def test_get_or_create_wallet_reuses_existing_after_integrity_error() -> None:
@@ -252,7 +281,7 @@ def test_get_or_create_wallet_reuses_existing_after_integrity_error() -> None:
     with patch.object(WalletService, "get_wallet", side_effect=[None, existing_wallet]):
         wallet = WalletService.get_or_create_wallet(
             db,
-            user=SimpleNamespace(id="user-1"),
+            user=cast(Any, SimpleNamespace(id="user-1")),
             api_key=None,
         )
 
@@ -287,18 +316,20 @@ def test_create_refund_request_rejects_uncredited_payment_order() -> None:
 
     db.query.side_effect = _query
 
-    with patch.object(WalletService, "_get_pending_refund_reserved_amount", return_value=Decimal("0")):
+    with patch.object(
+        WalletService, "_get_pending_refund_reserved_amount", return_value=Decimal("0")
+    ):
         with pytest.raises(ValueError, match="payment order is not refundable"):
             WalletService.create_refund_request(
                 db,
-                wallet=wallet,
+                wallet=cast(Any, wallet),
                 user_id="user-1",
                 amount_usd=Decimal("2"),
                 refund_no="rf-1",
                 source_type="payment_order",
                 source_id="order-1",
                 refund_mode="original_channel",
-                payment_order=payment_order,
+                payment_order=cast(Any, payment_order),
             )
 
 
@@ -326,7 +357,7 @@ def test_create_refund_request_reserves_pending_wallet_amount() -> None:
         with pytest.raises(ValueError, match="available refundable recharge balance"):
             WalletService.create_refund_request(
                 db,
-                wallet=wallet,
+                wallet=cast(Any, wallet),
                 user_id="user-1",
                 amount_usd=Decimal("2"),
                 refund_no="rf-2",
@@ -372,14 +403,14 @@ def test_create_refund_request_reserves_pending_order_amount() -> None:
         with pytest.raises(ValueError, match="available refundable amount"):
             WalletService.create_refund_request(
                 db,
-                wallet=wallet,
+                wallet=cast(Any, wallet),
                 user_id="user-1",
                 amount_usd=Decimal("2"),
                 refund_no="rf-3",
                 source_type="payment_order",
                 source_id="order-1",
                 refund_mode="original_channel",
-                payment_order=payment_order,
+                payment_order=cast(Any, payment_order),
             )
 
 
@@ -430,9 +461,13 @@ def test_move_refund_to_processing_rejects_double_transition() -> None:
     tx = SimpleNamespace(id="tx-1")
 
     with patch.object(WalletService, "create_wallet_transaction", return_value=tx) as create_tx:
-        first_tx = WalletService.move_refund_to_processing(db, refund=refund, operator_id="admin-1")
+        first_tx = WalletService.move_refund_to_processing(
+            db, refund=cast(Any, refund), operator_id="admin-1"
+        )
         with pytest.raises(ValueError, match="not approvable"):
-            WalletService.move_refund_to_processing(db, refund=refund, operator_id="admin-1")
+            WalletService.move_refund_to_processing(
+                db, refund=cast(Any, refund), operator_id="admin-1"
+            )
 
     assert first_tx is tx
     assert create_tx.call_count == 1
@@ -488,7 +523,9 @@ def test_move_refund_to_processing_rechecks_payment_order_refundable_amount() ->
 
     with patch.object(WalletService, "create_wallet_transaction") as create_tx:
         with pytest.raises(ValueError, match="refund amount exceeds refundable amount"):
-            WalletService.move_refund_to_processing(db, refund=refund, operator_id="admin-1")
+            WalletService.move_refund_to_processing(
+                db, refund=cast(Any, refund), operator_id="admin-1"
+            )
 
     create_tx.assert_not_called()
     assert refund.status == "pending_approval"
@@ -531,14 +568,14 @@ def test_fail_refund_rejects_invalid_status_after_first_failure() -> None:
     with patch.object(WalletService, "create_wallet_transaction", return_value=tx) as create_tx:
         first_tx = WalletService.fail_refund(
             db,
-            refund=refund,
+            refund=cast(Any, refund),
             reason="first-failure",
             operator_id="admin-1",
         )
         with pytest.raises(ValueError, match="cannot fail refund in status: failed"):
             WalletService.fail_refund(
                 db,
-                refund=refund,
+                refund=cast(Any, refund),
                 reason="retry-failure",
                 operator_id="admin-1",
             )
@@ -577,7 +614,7 @@ def test_fail_refund_rejects_succeeded_status() -> None:
     with pytest.raises(ValueError, match="cannot fail refund in status: succeeded"):
         WalletService.fail_refund(
             db,
-            refund=refund,
+            refund=cast(Any, refund),
             reason="should-not-override",
             operator_id="admin-1",
         )