Add admin provider cost attribution analytics

[RWDai]

Summary

Add an admin-facing provider cost attribution section to help operators understand which usage subjects contribute to each provider's cost within a selected time range. This should be presented as a general cost attribution and usage auditing feature, not as a domain-specific workflow.

Motivation

Aether already exposes several useful admin analytics views:

• Cost Analysis shows cost trends, quota progress, API key usage ranking, and provider-level usage statistics.
• User Stats shows user-level totals and trends.
• Usage Records supports detailed filtering by user, provider, model, status, and time range.
• Dashboard shows high-level provider cost distribution.

What is currently missing is a direct way to answer: for a selected provider and time range, which users or API keys contributed to that provider's usage and cost, and what share did each subject represent?

This would help with cost attribution, provider bill reconciliation, usage auditing, and identifying abnormal usage patterns.

Proposed UX

Place the feature inside the existing Admin > Cost Analysis page rather than adding a new top-level navigation item. The feature belongs with cost-oriented analytics and can reuse the page's existing time range controls and provider statistics.

Suggested layout for CostAnalysis.vue:

1. Keep the existing top summary cards.
2. Keep the existing two-column row:
   • Cost forecast
   • Quota progress
3. Add or refactor the provider section into a two-column attribution row:
   • Left: provider cost/usage distribution or provider summary list
   • Right: selected provider attribution breakdown
4. Keep API key leaderboard as a full-width section below, or allow it to share the same attribution data model later.

Suggested behavior:

• Select a provider from the provider summary/distribution area.
• Show attribution for that provider in the selected time range.
• Support metric switching:
  • actual cost
  • billed/display cost
  • tokens
  • requests
• For small result sets, show a doughnut/share chart.
• For larger result sets, show Top N + Others and a ranked table/bar layout.
• Always include a table with subject, requests, tokens, cost, and share.

Suggested API shape

A generic endpoint would keep this extensible:

GET /api/admin/usage/attribution

Query parameters:

start_date
end_date
preset
timezone
tz_offset_minutes
provider_name or provider_id
group_by=user | api_key
metric=actual_cost | total_cost | tokens | requests
limit

Example response shape:

{
  "provider": {
    "id": "provider-id",
    "name": "Provider Name"
  },
  "group_by": "user",
  "metric": "actual_cost",
  "total": 123.45,
  "items": [
    {
      "id": "user-id",
      "name": "User Name",
      "requests": 120,
      "total_tokens": 3200000,
      "total_cost": 12.34,
      "actual_cost": 10.80,
      "share": 0.421
    }
  ],
  "others": {
    "requests": 12,
    "total_tokens": 200000,
    "total_cost": 1.23,
    "actual_cost": 1.05,
    "share": 0.04
  }
}

Implementation notes

Backend:

• Reuse existing usage facts and aggregation infrastructure where possible.
• The underlying usage data already includes user, provider, tokens, total cost, and actual cost dimensions.
• Prefer a generic attribution query over a one-off UI-specific endpoint.
• Support at least group_by=user in the first iteration.
• Leave room for group_by=api_key as a natural extension.
• Normalize share calculation server-side so clients can render consistent percentages.

Frontend:

• Add a reusable attribution component under the cost analysis area.
• Reuse existing TimeRangePicker, chart components, formatting helpers, and table styles.
• Avoid adding a new top-level sidebar item initially.
• Integrate with existing provider statistics instead of duplicating a separate provider picker where possible.
• Use adaptive visualization:
  • doughnut chart when item count is small
  • ranked table/bar layout when item count is large
  • Top N + Others aggregation for readability

Acceptance criteria

• Admins can select a time range and provider from the Cost Analysis page.
• Admins can see which users contributed to that provider's usage in the selected range.
• The view shows requests, tokens, total cost, actual cost, and percentage share.
• The visualization remains readable when there are many users by using Top N + Others or a ranked table.
• Existing Cost Analysis, User Stats, Usage Records, and Dashboard responsibilities remain clear and are not duplicated unnecessarily.
• The implementation is generic enough to support additional attribution dimensions such as API keys in a future iteration.

Non-goals

• This should not introduce a separate domain-specific workflow.
• This should not add a new top-level navigation entry unless the feature grows beyond the Cost Analysis page.
• This should not replace the existing Usage Records or User Stats pages.