feat: harden analytics dashboard

docs/metrics.md

@@ -0,0 +1,29 @@
+# Metrics Contract
+
+All analytics endpoints filter to `logs.type = 2`.
+
+## Core Metrics
+
+- **Calls:** count of matching log rows.
+- **Input tokens:** sum of `prompt_tokens`.
+- **Output tokens:** sum of `completion_tokens`.
+- **Cache creation tokens:** `other.cache_creation_tokens`, parsed as bigint when present, otherwise `0`.
+- **Cache read tokens:** `other.cache_tokens`, parsed as bigint when present, otherwise `0`.
+- **Total tokens:** input + output + cache creation + cache read.
+- **Quota:** sum of `quota`.
+- **Cost:** quota converted to USD by `quota / 500000`.
+
+The quota conversion constant is defined in `lib/metrics.ts` as `QUOTA_UNITS_PER_USD`.
+
+## Dimensions
+
+- **User:** grouped by `logs.user_id` and `logs.username`, displayed with `users.display_name` when present.
+- **Model:** grouped by real model name. Real model is `other.upstream_model_name` when present, otherwise `logs.model_name`.
+- **Channel:** grouped by `logs.channel_id`, displayed with `channels.name` when present.
+- **Token name:** grouped by trimmed `logs.token_name`; blank values display as the localized unnamed-token label.
+
+## Time Handling
+
+Date ranges are Unix timestamps in seconds. Day, week, month, and hour buckets are computed in the `Asia/Shanghai` timezone.
+
+Invalid timestamps or reversed ranges return HTTP 400.