feat: harden analytics dashboard

2026-05-27 15:19:31 +08:00
parent 5e0ca6a504
commit 356039d9cf
34 changed files with 1424 additions and 879 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,57 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# New API Analytics

-## Getting Started
+Internal analytics dashboard for New API usage logs. The app reads PostgreSQL log data and visualizes calls, token consumption, model usage, channel usage, per-user aggregation, and raw request logs.

-First, run the development server:
+## Requirements
+
+- Bun for local development and tests.
+- Node.js 20 for the production Docker image.
+- PostgreSQL database with New API tables described in `docs/database.md`.
+- `PG_CONNECTION_STRING` set to a PostgreSQL connection string.
+
+## Local Development

 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+bun install
+bun run dev
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open `http://localhost:3000`.

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Verification

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```bash
+bun test
+bun run lint
+bun run build
+```

-## Learn More
+`bun test` covers parser helpers, metric conversion, query behavior, cache behavior, theme helpers, and selected API route guardrails.

-To learn more about Next.js, take a look at the following resources:
+## Configuration

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Create an environment file or export:

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+```bash
+PG_CONNECTION_STRING=postgres://user:password@host:5432/database
+```

-## Deploy on Vercel
+The app uses this variable in `lib/db.ts` to create a `pg` connection pool.

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Deployment

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+The included Dockerfile builds a standalone Next.js output and starts `server.js` on port `8019`.
+
+```bash
+docker compose up -d --build
+```
+
+`docker-compose.yml` expects `.env.production` and an external Docker network named `sinobridge`.
+
+## Operational Notes
+
+- API query parameters are validated at the route layer. Invalid integers or reversed date ranges return HTTP 400.
+- Ranking limits are capped at 100 rows per request.
+- Log page size is capped at 200 rows per request.
+- Query results are cached in-process for 120 seconds with a 500-entry cap.
+- Metric definitions and quota conversion are documented in `docs/metrics.md`.
--- a/app/api/aggregation/route.ts
+++ b/app/api/aggregation/route.ts
@@ -1,12 +1,17 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parseTimestampRange } from "@/lib/api-params";
 import { getUserRanking } from "@/lib/queries";

 export async function GET(req: NextRequest) {
-  const sp = req.nextUrl.searchParams;
-  const startTs = sp.get("start") ? Number(sp.get("start")) : undefined;
-  const endTs = sp.get("end") ? Number(sp.get("end")) : undefined;
+  try {
+    const range = parseTimestampRange(req.nextUrl.searchParams);
+    if (!range.ok) return jsonError(range.field);

-  // Get ALL users (no limit) for aggregation view
-  const data = await getUserRanking(startTs, endTs, 500);
-  return NextResponse.json(data);
+    // Get all visible users for aggregation view, capped by query-layer safeguards.
+    const data = await getUserRanking(range.value.startTs, range.value.endTs, 500);
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load aggregation", error);
+    return jsonError(undefined, 500);
+  }
 }
--- a/app/api/date-range/route.ts
+++ b/app/api/date-range/route.ts
@@ -1,7 +1,13 @@
 import { NextResponse } from "next/server";
+import { jsonError } from "@/lib/api-params";
 import { getDateRange } from "@/lib/queries";

 export async function GET() {
-  const data = await getDateRange();
-  return NextResponse.json(data);
+  try {
+    const data = await getDateRange();
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load date range", error);
+    return jsonError(undefined, 500);
+  }
 }
--- a/app/api/detail/[type]/[id]/route.ts
+++ b/app/api/detail/[type]/[id]/route.ts
@@ -1,29 +1,38 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parseTimestampRange } from "@/lib/api-params";
 import { getUserDetail, getModelDetail, getChannelDetail } from "@/lib/queries";

 export async function GET(
  req: NextRequest,
  { params }: { params: Promise<{ type: string; id: string }> }
 ) {
-  const { type, id } = await params;
-  const sp = req.nextUrl.searchParams;
-  const startTs = sp.get("start") ? Number(sp.get("start")) : undefined;
-  const endTs = sp.get("end") ? Number(sp.get("end")) : undefined;
+  try {
+    const { type, id } = await params;
+    const range = parseTimestampRange(req.nextUrl.searchParams);
+    if (!range.ok) return jsonError(range.field);

-  let data;
-  switch (type) {
-    case "user":
-      data = await getUserDetail(decodeURIComponent(id), startTs, endTs);
-      break;
-    case "model":
-      data = await getModelDetail(decodeURIComponent(id), startTs, endTs);
-      break;
-    case "channel":
-      data = await getChannelDetail(Number(id), startTs, endTs);
-      break;
-    default:
-      return NextResponse.json({ error: "Invalid type" }, { status: 400 });
+    let data;
+    switch (type) {
+      case "user":
+        data = await getUserDetail(decodeURIComponent(id), range.value.startTs, range.value.endTs);
+        break;
+      case "model":
+        data = await getModelDetail(decodeURIComponent(id), range.value.startTs, range.value.endTs);
+        break;
+      case "channel": {
+        if (!/^\d+$/.test(id)) return jsonError("id");
+        const channelId = Number(id);
+        if (!Number.isSafeInteger(channelId) || channelId < 1) return jsonError("id");
+        data = await getChannelDetail(channelId, range.value.startTs, range.value.endTs);
+        break;
+      }
+      default:
+        return jsonError("type");
+    }
+
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load detail", error);
+    return jsonError(undefined, 500);
  }
-
-  return NextResponse.json(data);
 }
--- a/app/api/logs/route.test.ts
+++ b/app/api/logs/route.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { NextRequest } from "next/server";
+
+const getLogsMock = mock(async () => ({ logs: [], total: 0, page: 1, page_size: 100 }));
+const getUserRankingMock = mock(async () => []);
+const getModelRankingMock = mock(async () => []);
+const getChannelRankingMock = mock(async () => []);
+
+mock.module("@/lib/queries", () => ({
+  getLogs: getLogsMock,
+  getUserRanking: getUserRankingMock,
+  getModelRanking: getModelRankingMock,
+  getChannelRanking: getChannelRankingMock,
+}));
+
+const { GET } = await import("./route");
+
+function request(path: string) {
+  return { nextUrl: new URL(`http://localhost${path}`) } as NextRequest;
+}
+
+describe("/api/logs", () => {
+  test("rejects reversed date ranges", async () => {
+    const res = await GET(request("/api/logs?start=200&end=100"));
+
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({
+      error: "Invalid query parameter",
+      field: "range",
+    });
+  });
+
+  test("clamps page size before querying", async () => {
+    getLogsMock.mockClear();
+
+    const res = await GET(request("/api/logs?page=2&page_size=10000"));
+
+    expect(res.status).toBe(200);
+    expect(getLogsMock.mock.calls[0][0]).toMatchObject({
+      page: 2,
+      pageSize: 200,
+    });
+  });
+});
--- a/app/api/logs/route.ts
+++ b/app/api/logs/route.ts
@@ -1,19 +1,46 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parseOptionalInt, parsePositiveInt, parseTimestampRange } from "@/lib/api-params";
 import { getLogs } from "@/lib/queries";

 export async function GET(req: NextRequest) {
-  const sp = req.nextUrl.searchParams;
+  try {
+    const sp = req.nextUrl.searchParams;
+    const range = parseTimestampRange(sp);
+    if (!range.ok) return jsonError(range.field);

-  const data = await getLogs({
-    page: sp.get("page") ? Number(sp.get("page")) : 1,
-    pageSize: sp.get("page_size") ? Number(sp.get("page_size")) : 100,
-    startTs: sp.get("start") ? Number(sp.get("start")) : undefined,
-    endTs: sp.get("end") ? Number(sp.get("end")) : undefined,
-    username: sp.get("username") || undefined,
-    model: sp.get("model") || undefined,
-    channelId: sp.get("channel_id") ? Number(sp.get("channel_id")) : undefined,
-    tokenName: sp.get("token_name") || undefined,
-  });
+    const page = parsePositiveInt(sp.get("page"), {
+      field: "page",
+      defaultValue: 1,
+      min: 1,
+    });
+    if (!page.ok) return jsonError(page.field);

-  return NextResponse.json(data);
+    const pageSize = parsePositiveInt(sp.get("page_size"), {
+      field: "page_size",
+      defaultValue: 100,
+      min: 1,
+      max: 200,
+    });
+    if (!pageSize.ok) return jsonError(pageSize.field);
+
+    const channelId = parseOptionalInt(sp.get("channel_id"), "channel_id");
+    if (!channelId.ok) return jsonError(channelId.field);
+    if (channelId.value === 0) return jsonError("channel_id");
+
+    const data = await getLogs({
+      page: page.value,
+      pageSize: pageSize.value,
+      startTs: range.value.startTs,
+      endTs: range.value.endTs,
+      username: sp.get("username") || undefined,
+      model: sp.get("model") || undefined,
+      channelId: channelId.value,
+      tokenName: sp.get("token_name") || undefined,
+    });
+
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load logs", error);
+    return jsonError(undefined, 500);
+  }
 }
--- a/app/api/overview/route.ts
+++ b/app/api/overview/route.ts
@@ -1,11 +1,16 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parseTimestampRange } from "@/lib/api-params";
 import { getOverview } from "@/lib/queries";

 export async function GET(req: NextRequest) {
-  const sp = req.nextUrl.searchParams;
-  const startTs = sp.get("start") ? Number(sp.get("start")) : undefined;
-  const endTs = sp.get("end") ? Number(sp.get("end")) : undefined;
+  try {
+    const range = parseTimestampRange(req.nextUrl.searchParams);
+    if (!range.ok) return jsonError(range.field);

-  const data = await getOverview(startTs, endTs);
-  return NextResponse.json(data);
+    const data = await getOverview(range.value.startTs, range.value.endTs);
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load overview", error);
+    return jsonError(undefined, 500);
+  }
 }
--- a/app/api/rankings/route.test.ts
+++ b/app/api/rankings/route.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { NextRequest } from "next/server";
+
+const getUserRankingMock = mock(async () => []);
+const getModelRankingMock = mock(async () => []);
+const getChannelRankingMock = mock(async () => []);
+const getLogsMock = mock(async () => ({ logs: [], total: 0, page: 1, page_size: 100 }));
+
+mock.module("@/lib/queries", () => ({
+  getUserRanking: getUserRankingMock,
+  getModelRanking: getModelRankingMock,
+  getChannelRanking: getChannelRankingMock,
+  getLogs: getLogsMock,
+}));
+
+const { GET } = await import("./route");
+
+function request(path: string) {
+  return { nextUrl: new URL(`http://localhost${path}`) } as NextRequest;
+}
+
+describe("/api/rankings", () => {
+  test("rejects invalid limit", async () => {
+    const res = await GET(request("/api/rankings?limit=abc"));
+
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({
+      error: "Invalid query parameter",
+      field: "limit",
+    });
+  });
+
+  test("clamps oversized limit before querying", async () => {
+    getUserRankingMock.mockClear();
+
+    const res = await GET(request("/api/rankings?limit=500"));
+
+    expect(res.status).toBe(200);
+    expect(getUserRankingMock.mock.calls[0]).toEqual([undefined, undefined, 100]);
+  });
+});
--- a/app/api/rankings/route.ts
+++ b/app/api/rankings/route.ts
@@ -1,24 +1,37 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parsePositiveInt, parseTimestampRange } from "@/lib/api-params";
 import { getUserRanking, getModelRanking, getChannelRanking } from "@/lib/queries";

 export async function GET(req: NextRequest) {
-  const sp = req.nextUrl.searchParams;
-  const type = sp.get("type") || "user";
-  const startTs = sp.get("start") ? Number(sp.get("start")) : undefined;
-  const endTs = sp.get("end") ? Number(sp.get("end")) : undefined;
-  const limit = sp.get("limit") ? Number(sp.get("limit")) : 50;
+  try {
+    const sp = req.nextUrl.searchParams;
+    const type = sp.get("type") || "user";
+    const range = parseTimestampRange(sp);
+    if (!range.ok) return jsonError(range.field);

-  let data;
-  switch (type) {
-    case "model":
-      data = await getModelRanking(startTs, endTs, limit);
-      break;
-    case "channel":
-      data = await getChannelRanking(startTs, endTs, limit);
-      break;
-    default:
-      data = await getUserRanking(startTs, endTs, limit);
+    const limit = parsePositiveInt(sp.get("limit"), {
+      field: "limit",
+      defaultValue: 50,
+      min: 1,
+      max: 100,
+    });
+    if (!limit.ok) return jsonError(limit.field);
+
+    let data;
+    switch (type) {
+      case "model":
+        data = await getModelRanking(range.value.startTs, range.value.endTs, limit.value);
+        break;
+      case "channel":
+        data = await getChannelRanking(range.value.startTs, range.value.endTs, limit.value);
+        break;
+      default:
+        data = await getUserRanking(range.value.startTs, range.value.endTs, limit.value);
+    }
+
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load rankings", error);
+    return jsonError(undefined, 500);
  }
-
-  return NextResponse.json(data);
 }
--- a/app/api/trends/route.ts
+++ b/app/api/trends/route.ts
@@ -1,22 +1,31 @@
 import { NextRequest, NextResponse } from "next/server";
+import { jsonError, parseOptionalInt, parseTimestampRange } from "@/lib/api-params";
 import { getTrends, type TrendGranularity } from "@/lib/queries";

 const GRANULARITIES: TrendGranularity[] = ["hour", "day", "week", "month"];

 export async function GET(req: NextRequest) {
-  const sp = req.nextUrl.searchParams;
-  const requestedGranularity = sp.get("granularity");
-  const granularity = GRANULARITIES.includes(requestedGranularity as TrendGranularity)
-    ? requestedGranularity as TrendGranularity
-    : "day";
-  const startTs = sp.get("start") ? Number(sp.get("start")) : undefined;
-  const endTs = sp.get("end") ? Number(sp.get("end")) : undefined;
-  const channelId = sp.get("channel_id") ? Number(sp.get("channel_id")) : undefined;
+  try {
+    const sp = req.nextUrl.searchParams;
+    const requestedGranularity = sp.get("granularity");
+    const granularity = GRANULARITIES.includes(requestedGranularity as TrendGranularity)
+      ? requestedGranularity as TrendGranularity
+      : "day";
+    const range = parseTimestampRange(sp);
+    if (!range.ok) return jsonError(range.field);

-  const data = await getTrends(granularity, startTs, endTs, {
-    username: sp.get("username") || undefined,
-    model: sp.get("model") || undefined,
-    channelId: Number.isFinite(channelId) ? channelId : undefined,
-  });
-  return NextResponse.json(data);
+    const channelId = parseOptionalInt(sp.get("channel_id"), "channel_id");
+    if (!channelId.ok) return jsonError(channelId.field);
+    if (channelId.value === 0) return jsonError("channel_id");
+
+    const data = await getTrends(granularity, range.value.startTs, range.value.endTs, {
+      username: sp.get("username") || undefined,
+      model: sp.get("model") || undefined,
+      channelId: channelId.value,
+    });
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error("Failed to load trends", error);
+    return jsonError(undefined, 500);
+  }
 }
--- a/app/detail/[...slug]/page.tsx
+++ b/app/detail/[...slug]/page.tsx
@@ -12,6 +12,7 @@ import { buildQuery, formatNumber, formatTokens, formatUSD } from "@/lib/utils";
 import { sortDetailBreakdown, type DetailBreakdownItem, type DetailBreakdownSortKey } from "@/lib/detail-sort";
 import { getPrimaryModelNames, getSharePercent, getTokenDisplayName, getTokenRowKey, shouldShowTokenTab, sortTokenBreakdown, type TokenBreakdownItem } from "@/lib/token-breakdown";
 import { getDetailStats, type DetailStatKey } from "@/lib/detail-stats";
+import { quotaToUsd } from "@/lib/metrics";
 import { useTimeRange } from "@/lib/time-range-context";
 import { useI18n } from "@/lib/i18n";

@@ -170,7 +171,7 @@ export default function DetailPage() {
                  </td>
                  <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatNumber(item.calls)}</td>
                  <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-primary)" }}>{formatTokens(item.total_tokens)}</td>
-                  <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatUSD(item.quota / 500000)}</td>
+                  <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatUSD(quotaToUsd(item.quota))}</td>
                  <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-muted)" }}>{userShare.toFixed(1)}%</td>
                  <td className="px-5 py-3 text-xs" style={{ color: "var(--text-muted)" }}>{getPrimaryModelNames(item.models) || t("common.noData")}</td>
                </tr>
@@ -196,7 +197,7 @@ export default function DetailPage() {
                                  <td className="px-4 py-2 font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-accent)", opacity: 0.75 }}>{model.name}</td>
                                  <td className="px-4 py-2 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-secondary)" }}>{formatNumber(model.calls)}</td>
                                  <td className="px-4 py-2 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-primary)" }}>{formatTokens(model.total_tokens)}</td>
-                                  <td className="px-4 py-2 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-secondary)" }}>{formatUSD(model.quota / 500000)}</td>
+                                  <td className="px-4 py-2 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-secondary)" }}>{formatUSD(quotaToUsd(model.quota))}</td>
                                  <td className="px-4 py-2 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-muted)" }}>{modelShare.toFixed(1)}%</td>
                                </tr>
                              );
@@ -311,7 +312,7 @@ export default function DetailPage() {
                        <td className="px-5 py-3" style={{ color: "var(--text-accent)", opacity: 0.8 }}>{item.name}</td>
                        <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatNumber(item.calls)}</td>
                        <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)]" style={{ color: "var(--text-primary)" }}>{formatTokens(item.total_tokens)}</td>
-                        <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatUSD(item.quota / 500000)}</td>
+                        <td className="px-5 py-3 text-right tabular-nums font-[family-name:var(--font-geist-mono)] text-xs" style={{ color: "var(--text-secondary)" }}>{formatUSD(quotaToUsd(item.quota))}</td>
                      </tr>
                    ))}
                  </tbody>
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -8,6 +8,7 @@ import { TimeRangeSelector } from "@/components/TimeRangeSelector";
 import { TrendChart } from "@/components/charts/TrendChart";
 import { RankingBar } from "@/components/charts/RankingBar";
 import { buildQuery } from "@/lib/utils";
+import { quotaToUsd } from "@/lib/metrics";
 import { useTimeRange } from "@/lib/time-range-context";
 import { useI18n } from "@/lib/i18n";

@@ -82,19 +83,19 @@ export default function DashboardPage() {
        <div className="grid grid-cols-2 gap-4 md:grid-cols-5">
          <StatsCard title={t("dash.totalCalls")} value={overview.total_calls} icon={Hash} delay={0} />
          <StatsCard title={t("dash.tokenUsage")} value={overview.total_tokens} format="tokens" icon={Zap} delay={0.05} />
-          <StatsCard title={t("dash.totalCost")} value={overview.total_quota / 500000} format="usd" icon={DollarSign} delay={0.1} />
+          <StatsCard title={t("dash.totalCost")} value={quotaToUsd(overview.total_quota)} format="usd" icon={DollarSign} delay={0.1} />
          <StatsCard title={t("dash.activeUsers")} value={overview.active_users} icon={Users} delay={0.15} />
          <StatsCard title={t("dash.activeModels")} value={overview.active_models} icon={Cpu} delay={0.2} />
        </div>
      )}

      <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} transition={{ delay: 0.15 }} className="glass p-5">
-        <div className="mb-4 flex items-center justify-between">
+        <div className="mb-4 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
          <div className="flex items-center gap-2">
            <TrendingUp className="h-4 w-4" style={{ color: "var(--accent)", opacity: 0.6 }} />
            <h2 className="text-sm font-semibold" style={{ color: "var(--text-primary)" }}>{t("dash.trend")}</h2>
          </div>
-          <div className="flex gap-3">
+          <div className="flex max-w-full flex-wrap gap-2 sm:gap-3">
            <div className="flex gap-1 rounded-md p-0.5" style={{ background: "var(--row-hover)", border: "1px solid var(--surface-border)" }}>
              {grans.map(g => (
                <button key={g.key} onClick={() => setGranularity(g.key)}
--- a/components/ClientProviders.tsx
+++ b/components/ClientProviders.tsx
@@ -20,7 +20,7 @@ export function ClientProviders({ children }: { children: ReactNode }) {
          ) : (
            <>
              <Sidebar />
-              <main className="ml-[220px] min-h-screen p-6 lg:p-8">{children}</main>
+              <main className="min-h-screen px-4 pb-6 pt-24 sm:px-6 lg:ml-[220px] lg:p-8">{children}</main>
            </>
          )}
        </TimeRangeProvider>
--- a/components/Sidebar.tsx
+++ b/components/Sidebar.tsx
@@ -26,9 +26,9 @@ export function Sidebar() {
  ];

  return (
-    <aside className="fixed left-0 top-0 z-30 flex h-screen w-[220px] flex-col glass !rounded-none !border-l-0 !border-t-0 !border-b-0">
+    <aside className="fixed left-0 top-0 z-30 flex h-20 w-full flex-row glass !rounded-none !border-l-0 !border-t-0 lg:h-screen lg:w-[220px] lg:flex-col lg:!border-b-0">
      {/* Logo */}
-      <div className="flex h-16 items-center gap-3 border-b border-t px-5" style={{ borderColor: "var(--surface-border)" }}>
+      <div className="flex h-full shrink-0 items-center gap-3 border-r px-4 lg:h-16 lg:border-b lg:border-r-0 lg:border-t lg:px-5" style={{ borderColor: "var(--surface-border)" }}>
        <div className="flex h-8 w-8 items-center justify-center rounded-lg border" style={{ borderColor: "var(--surface-border)", background: "var(--btn-active-bg)" }}>
          <Activity className="h-4 w-4 text-t-accent" style={{ color: "var(--accent)" }} />
        </div>
@@ -38,14 +38,14 @@ export function Sidebar() {
        </div>
      </div>

-      <nav className="flex-1 space-y-1 p-3 pt-4">
+      <nav className="flex flex-1 items-center gap-1 overflow-x-auto px-2 lg:block lg:space-y-1 lg:p-3 lg:pt-4">
        {nav.map((item) => {
          const active = item.href === "/" ? pathname === "/" : pathname.startsWith(item.href);
          const Icon = item.icon;
          return (
            <Link key={item.href} href={item.href}>
              <motion.div
-                className="relative flex items-center gap-3 rounded-lg px-3 py-2.5 text-sm transition-colors"
+                className="relative flex min-w-max items-center gap-2 rounded-lg px-3 py-2 text-sm transition-colors lg:gap-3 lg:py-2.5"
                style={{ color: active ? "var(--text-accent)" : "var(--text-muted)" }}
                whileHover={{ x: 2 }}
                transition={{ type: "spring", stiffness: 400, damping: 30 }}
@@ -59,10 +59,10 @@ export function Sidebar() {
                  />
                )}
                <Icon className="relative z-10 h-4 w-4" />
-                <span className="relative z-10 font-medium">{item.label}</span>
+                <span className="relative z-10 hidden font-medium sm:inline">{item.label}</span>
                {active && (
                  <motion.div
-                    className="absolute left-0 top-1/2 h-5 w-[2px] -translate-y-1/2 rounded-full"
+                    className="absolute bottom-0 left-1/2 h-[2px] w-5 -translate-x-1/2 rounded-full lg:left-0 lg:top-1/2 lg:h-5 lg:w-[2px] lg:-translate-x-0 lg:-translate-y-1/2"
                    style={{ background: "var(--accent)" }}
                    layoutId="sidebar-indicator"
                    transition={{ type: "spring", stiffness: 350, damping: 30 }}
@@ -75,7 +75,7 @@ export function Sidebar() {
      </nav>

      {/* Controls */}
-      <div className="space-y-3 p-4 border-t" style={{ borderColor: "var(--surface-border)" }}>
+      <div className="hidden space-y-3 border-t p-4 lg:block" style={{ borderColor: "var(--surface-border)" }}>
        {!isEmbedded && (
          <div className="flex gap-1 rounded-lg p-0.5" style={{ background: "var(--row-hover)", border: "1px solid var(--surface-border)" }}>
            {themes.map(({ value, icon: Icon }) => (
--- a/components/charts/RankingBar.tsx
+++ b/components/charts/RankingBar.tsx
@@ -11,6 +11,7 @@ import {
  Cell,
 } from "recharts";
 import { formatTokens } from "@/lib/utils";
+import { useI18n } from "@/lib/i18n";

 interface RankItem {
  name: string;
@@ -31,6 +32,7 @@ export function RankingBar({
  data: RankItem[];
  title: string;
 }) {
+  const { t } = useI18n();
  if (!data.length) return null;
  const sliced = data.slice(0, 10);

@@ -54,7 +56,7 @@ export function RankingBar({
              color: "#c8d6e5",
              fontSize: "12px",
            }}
-            formatter={(v) => [formatTokens(Number(v)), "Total Tokens"]}
+            formatter={(v) => [formatTokens(Number(v)), t("th.totalToken")]}
          />
          <Bar dataKey="total_tokens" radius={[0, 4, 4, 0]}>
            {sliced.map((_, i) => (
--- a/components/charts/TrendChart.tsx
+++ b/components/charts/TrendChart.tsx
@@ -2,6 +2,7 @@

 import { ResponsiveContainer, LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend } from "recharts";
 import { formatTokens, formatUSD } from "@/lib/utils";
+import { quotaToUsd } from "@/lib/metrics";
 import { useI18n } from "@/lib/i18n";

 interface TrendPoint { date: string; calls: number; total_tokens: number; prompt_tokens: number; completion_tokens: number; quota?: number; }
@@ -105,11 +106,11 @@ export function TrendChart({ data, metric = "total_tokens" }: { data: TrendPoint
        <LineChart data={data} margin={{ top: 5, right: 20, left: 10, bottom: 5 }}>
          <CartesianGrid strokeDasharray="3 3" stroke="var(--chart-grid)" />
          <XAxis dataKey="date" tickFormatter={formatDateLabel} tick={{ fontSize: 11 }} stroke="var(--chart-grid)" />
-          <YAxis tickFormatter={(v) => formatUSD(v / 500000)} tick={{ fontSize: 11 }} stroke="var(--chart-grid)" />
+          <YAxis tickFormatter={(v) => formatUSD(quotaToUsd(v))} tick={{ fontSize: 11 }} stroke="var(--chart-grid)" />
          <Tooltip
            contentStyle={tooltipStyle}
            labelFormatter={(label) => formatTooltipLabel(String(label))}
-            formatter={(value) => [formatUSD(Number(value) / 500000), t("th.cost")]}
+            formatter={(value) => [formatUSD(quotaToUsd(Number(value))), t("th.cost")]}
          />
          <Legend />
          <Line type="monotone" dataKey="quota" name={t("th.cost")} stroke="var(--accent)" strokeWidth={2} dot={false} />
--- a/docs/database.md
+++ b/docs/database.md
@@ -0,0 +1,71 @@
+# Database Contract
+
+This app reads an existing New API PostgreSQL schema. It does not own migrations.
+
+## Required Environment
+
+```bash
+PG_CONNECTION_STRING=postgres://user:password@host:5432/database
+```
+
+## Tables Read By The App
+
+### `logs`
+
+Primary analytics source. Only rows with `type = 2` are included.
+
+Expected columns:
+
+- `id`: monotonically increasing log id, used for latest-first log pagination.
+- `created_at`: Unix timestamp in seconds.
+- `type`: log type; analytics filters to `2`.
+- `user_id`: user id.
+- `username`: username captured on the log row.
+- `model_name`: requested model name.
+- `channel_id`: upstream channel id.
+- `prompt_tokens`: input token count.
+- `completion_tokens`: output token count.
+- `quota`: New API quota units.
+- `use_time`: request latency in milliseconds.
+- `is_stream`: stream flag.
+- `token_name`: API token display name.
+- `other`: JSON text with optional `upstream_model_name`, `cache_creation_tokens`, and `cache_tokens`.
+
+### `users`
+
+Used for display-name enrichment.
+
+Expected columns:
+
+- `id`
+- `username`
+- `display_name`
+
+### `channels`
+
+Used for channel-name enrichment.
+
+Expected columns:
+
+- `id`
+- `name`
+
+## Recommended Indexes
+
+For large `logs` tables, add or verify indexes that match dashboard filters:
+
+```sql
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_logs_type_created_at
+  ON logs (type, created_at);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_logs_type_username_created_at
+  ON logs (type, username, created_at);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_logs_type_channel_created_at
+  ON logs (type, channel_id, created_at);
+
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_logs_type_id_desc
+  ON logs (type, id DESC);
+```
+
+Model filtering uses the real-model expression derived from `other::jsonb->>'upstream_model_name'` with fallback to `model_name`. Add an expression index only after validating the exact production column type and query plan.
--- a/docs/metrics.md
+++ b/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.
--- a/lib/api-params.test.ts
+++ b/lib/api-params.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import {
+  parseOptionalInt,
+  parsePositiveInt,
+  parseTimestampRange,
+} from "./api-params";
+
+describe("API parameter parsing", () => {
+  test("uses defaults and clamps positive integer ranges", () => {
+    expect(parsePositiveInt(null, { field: "limit", defaultValue: 50, min: 1, max: 100 })).toEqual({
+      ok: true,
+      value: 50,
+    });
+    expect(parsePositiveInt("500", { field: "limit", defaultValue: 50, min: 1, max: 100 })).toEqual({
+      ok: true,
+      value: 100,
+    });
+    expect(parsePositiveInt("0", { field: "page", defaultValue: 1, min: 1 })).toEqual({
+      ok: true,
+      value: 1,
+    });
+  });
+
+  test("rejects NaN, decimals, and negative values", () => {
+    expect(parseOptionalInt("abc", "start")).toEqual({
+      ok: false,
+      field: "start",
+    });
+    expect(parsePositiveInt("1.5", { field: "page", defaultValue: 1, min: 1 })).toEqual({
+      ok: false,
+      field: "page",
+    });
+    expect(parsePositiveInt("-2", { field: "page", defaultValue: 1, min: 1 })).toEqual({
+      ok: false,
+      field: "page",
+    });
+  });
+
+  test("rejects reversed timestamp ranges", () => {
+    expect(parseTimestampRange(new URLSearchParams("start=200&end=100"))).toEqual({
+      ok: false,
+      field: "range",
+    });
+  });
+});
--- a/lib/api-params.ts
+++ b/lib/api-params.ts
@@ -0,0 +1,62 @@
+import { NextResponse } from "next/server";
+
+export type ParseResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; field: string };
+
+interface PositiveIntOptions {
+  field: string;
+  defaultValue: number;
+  min: number;
+  max?: number;
+}
+
+function parseInteger(raw: string | null, field: string): ParseResult<number | undefined> {
+  if (raw === null || raw === "") return { ok: true, value: undefined };
+  if (!/^-?\d+$/.test(raw)) return { ok: false, field };
+
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value)) return { ok: false, field };
+  return { ok: true, value };
+}
+
+export function parseOptionalInt(raw: string | null, field: string): ParseResult<number | undefined> {
+  const parsed = parseInteger(raw, field);
+  if (!parsed.ok || parsed.value === undefined) return parsed;
+  if (parsed.value < 0) return { ok: false, field };
+  return parsed;
+}
+
+export function parsePositiveInt(raw: string | null, options: PositiveIntOptions): ParseResult<number> {
+  const parsed = parseInteger(raw, options.field);
+  if (!parsed.ok) return parsed;
+
+  let value = parsed.value ?? options.defaultValue;
+  if (value < 0) return { ok: false, field: options.field };
+  if (value < options.min) value = options.min;
+  if (options.max !== undefined && value > options.max) value = options.max;
+  return { ok: true, value };
+}
+
+export function parseTimestampRange(
+  searchParams: URLSearchParams
+): ParseResult<{ startTs?: number; endTs?: number }> {
+  const start = parseOptionalInt(searchParams.get("start"), "start");
+  if (!start.ok) return start;
+
+  const end = parseOptionalInt(searchParams.get("end"), "end");
+  if (!end.ok) return end;
+
+  if (start.value !== undefined && end.value !== undefined && start.value > end.value) {
+    return { ok: false, field: "range" };
+  }
+
+  return { ok: true, value: { startTs: start.value, endTs: end.value } };
+}
+
+export function jsonError(field?: string, status = 400) {
+  const body = field
+    ? { error: "Invalid query parameter", field }
+    : { error: "Internal server error" };
+  return NextResponse.json(body, { status });
+}
--- a/lib/detail-stats.ts
+++ b/lib/detail-stats.ts
@@ -1,4 +1,5 @@
 import type { TranslationKey } from "@/lib/i18n";
+import { quotaToUsd } from "@/lib/metrics";

 export type DetailStatKey =
  | "calls"
@@ -32,7 +33,7 @@ export function getDetailStats(data: DetailStatsData): DetailStatItem[] {
  return [
    { key: "calls", labelKey: "dash.totalCalls", value: data.calls },
    { key: "total_tokens", labelKey: "th.totalToken", value: data.total_tokens, format: "tokens" },
-    { key: "quota", labelKey: "th.cost", value: data.quota / 500000, format: "usd" },
+    { key: "quota", labelKey: "th.cost", value: quotaToUsd(data.quota), format: "usd" },
    { key: "prompt_tokens", labelKey: "th.input", value: data.prompt_tokens, format: "tokens" },
    { key: "completion_tokens", labelKey: "th.output", value: data.completion_tokens, format: "tokens" },
    { key: "cache_creation_tokens", labelKey: "th.cacheCreation", value: data.cache_creation_tokens, format: "tokens" },
--- a/lib/metrics.test.ts
+++ b/lib/metrics.test.ts
@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test";
+import { QUOTA_UNITS_PER_USD, quotaToUsd } from "./metrics";
+
+describe("metric conversions", () => {
+  test("converts quota units to USD", () => {
+    expect(QUOTA_UNITS_PER_USD).toBe(500000);
+    expect(quotaToUsd(500000)).toBe(1);
+    expect(quotaToUsd(250000)).toBe(0.5);
+  });
+});
--- a/lib/metrics.ts
+++ b/lib/metrics.ts
@@ -0,0 +1,5 @@
+export const QUOTA_UNITS_PER_USD = 500000;
+
+export function quotaToUsd(quota: number): number {
+  return quota / QUOTA_UNITS_PER_USD;
+}
--- a/lib/queries.test.ts
+++ b/lib/queries.test.ts
@@ -16,7 +16,7 @@ mock.module("./db", () => ({
  query: queryMock,
 }));

-const { getTrends, getUserDetail } = await import("./queries");
+const { getLogs, getTrends, getUserDetail } = await import("./queries");

 describe("getTrends", () => {
  beforeEach(() => {
@@ -123,3 +123,38 @@ describe("getUserDetail", () => {
    expect(queryMock.mock.calls.some(([sql]) => String(sql).includes("token_name"))).toBe(true);
  });
 });
+
+describe("getLogs", () => {
+  beforeEach(() => {
+    queryMock.mockClear();
+    queryMock.mockImplementation(async (sql: string) => {
+      if (sql.includes("COUNT(*)::int as total")) {
+        return [{ total: 0 }];
+      }
+      if (sql.includes("SELECT id, display_name FROM users")) {
+        return [];
+      }
+      if (sql.includes("SELECT id, name FROM channels")) {
+        return [];
+      }
+      return [];
+    });
+  });
+
+  test("caps page size for direct query callers", async () => {
+    const result = await getLogs({ page: 1, pageSize: 10000 });
+    const dataQuery = queryMock.mock.calls.find(([sql]) => String(sql).includes("ORDER BY id DESC"));
+
+    expect(result.page_size).toBe(200);
+    expect(dataQuery?.[1]).toEqual([200, 0]);
+  });
+
+  test("normalizes non-finite direct pagination inputs", async () => {
+    const result = await getLogs({ page: Number.NaN, pageSize: Number.POSITIVE_INFINITY });
+    const dataQuery = queryMock.mock.calls.find(([sql]) => String(sql).includes("ORDER BY id DESC"));
+
+    expect(result.page).toBe(1);
+    expect(result.page_size).toBe(100);
+    expect(dataQuery?.[1]).toEqual([100, 0]);
+  });
+});
--- a/lib/queries.ts
+++ b/lib/queries.ts
@@ -1,764 +1,6 @@
-import { query } from "./db";
-
-// ── 查询缓存 ─────────────────────────────────────────────────
-const queryCache = new Map<string, { data: unknown; ts: number }>();
-const CACHE_TTL = 120_000; // 2 分钟
-
-function cached<T>(key: string, fn: () => Promise<T>): Promise<T> {
-  const hit = queryCache.get(key);
-  if (hit && Date.now() - hit.ts < CACHE_TTL) return Promise.resolve(hit.data as T);
-  return fn().then((data) => {
-    queryCache.set(key, { data, ts: Date.now() });
-    return data;
-  });
-}
-
-function cacheKey(...parts: unknown[]): string {
-  return parts.map((p) => String(p ?? "")).join(":");
-}
-
-// 真实模型名表达式：优先取 other 里的 upstream_model_name
-const REAL_MODEL = `COALESCE(
-  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'upstream_model_name'
-       THEN other::jsonb->>'upstream_model_name' END,
-  model_name)`;
-
-const CACHE_CREATION = `COALESCE(
-  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'cache_creation_tokens'
-       THEN (other::jsonb->>'cache_creation_tokens')::bigint END,
-  0)`;
-
-const CACHE_READ = `COALESCE(
-  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'cache_tokens'
-       THEN (other::jsonb->>'cache_tokens')::bigint END,
-  0)`;
-
-const TOKEN_NAME = `COALESCE(NULLIF(BTRIM(token_name), ''), '')`;
-
-// ── 数据时间边界 ────────────────────────────────────────────────
-
-export async function getDateRange(): Promise<{ minDate: string; maxDate: string }> {
-  const rows = await query(
-    `SELECT
-       ((MIN(to_timestamp(created_at)) AT TIME ZONE 'Asia/Shanghai')::date)::text as min_date,
-       ((MAX(to_timestamp(created_at)) AT TIME ZONE 'Asia/Shanghai')::date)::text as max_date
-     FROM logs WHERE type = 2`
-  );
-  return { minDate: rows[0]?.min_date ?? "", maxDate: rows[0]?.max_date ?? "" };
-}
-
-// 时间条件构建
-function timeWhere(
-  params: (string | number | boolean | null)[],
-  startTs?: number,
-  endTs?: number
-): string {
-  let where = "type = 2";
-  if (startTs) {
-    params.push(startTs);
-    where += ` AND created_at >= $${params.length}`;
-  }
-  if (endTs) {
-    params.push(endTs);
-    where += ` AND created_at <= $${params.length}`;
-  }
-  return where;
-}
-
-// ── 总览 ──────────────────────────────────────────────────────
-
-export interface OverviewData {
-  total_calls: number;
-  total_tokens: number;
-  total_prompt: number;
-  total_completion: number;
-  total_cache_creation: number;
-  total_cache_read: number;
-  total_quota: number;
-  active_users: number;
-  active_models: number;
-  active_channels: number;
-}
-
-export function getOverview(
-  startTs?: number,
-  endTs?: number
-): Promise<OverviewData> {
-  return cached(cacheKey("overview", startTs, endTs), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-
-  const rows = await query(
-    `SELECT
-       COUNT(*)::int as total_calls,
-       COALESCE(SUM(prompt_tokens + completion_tokens), 0)::bigint as total_tokens,
-       COALESCE(SUM(prompt_tokens), 0)::bigint as total_prompt,
-       COALESCE(SUM(completion_tokens), 0)::bigint as total_completion,
-       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as total_cache_creation,
-       COALESCE(SUM(${CACHE_READ}), 0)::bigint as total_cache_read,
-       COALESCE(SUM(quota), 0)::bigint as total_quota,
-       COUNT(DISTINCT user_id)::int as active_users,
-       COUNT(DISTINCT ${REAL_MODEL})::int as active_models,
-       COUNT(DISTINCT channel_id)::int as active_channels
-     FROM logs WHERE ${where}`,
-    params
-  );
-  const r = rows[0];
-  return {
-    total_calls: Number(r.total_calls),
-    total_tokens: Number(r.total_tokens) + Number(r.total_cache_creation) + Number(r.total_cache_read),
-    total_prompt: Number(r.total_prompt),
-    total_completion: Number(r.total_completion),
-    total_cache_creation: Number(r.total_cache_creation),
-    total_cache_read: Number(r.total_cache_read),
-    total_quota: Number(r.total_quota),
-    active_users: Number(r.active_users),
-    active_models: Number(r.active_models),
-    active_channels: Number(r.active_channels),
-  };
-  });
-}
-
-// ── 趋势 ──────────────────────────────────────────────────────
-
-export interface TrendPoint {
-  date: string;
-  calls: number;
-  prompt_tokens: number;
-  completion_tokens: number;
-  cache_creation_tokens: number;
-  cache_read_tokens: number;
-  total_tokens: number;
-  quota: number;
-}
-
-export type TrendGranularity = "hour" | "day" | "week" | "month";
-
-export interface TrendFilters {
-  username?: string;
-  model?: string;
-  channelId?: number;
-}
-
-function appendTrendFilters(
-  where: string,
-  params: (string | number | boolean | null)[],
-  filters: TrendFilters = {}
-): string {
-  if (filters.username) {
-    params.push(filters.username);
-    where += ` AND username = $${params.length}`;
-  }
-  if (filters.model) {
-    params.push(filters.model);
-    where += ` AND ${REAL_MODEL} = $${params.length}`;
-  }
-  if (filters.channelId !== undefined) {
-    params.push(filters.channelId);
-    where += ` AND channel_id = $${params.length}`;
-  }
-  return where;
-}
-
-export function getTrends(
-  granularity: TrendGranularity = "day",
-  startTs?: number,
-  endTs?: number,
-  filters: TrendFilters = {}
-): Promise<TrendPoint[]> {
-  return cached(cacheKey("trends", granularity, startTs, endTs, filters.username, filters.model, filters.channelId), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = appendTrendFilters(timeWhere(params, startTs, endTs), params, filters);
-
-  const truncExpr =
-    granularity === "hour"
-      ? `to_char(date_trunc('hour', to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai'), 'YYYY-MM-DD HH24:00')`
-      : granularity === "day"
-        ? `((to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai')::date)::text`
-        : `(date_trunc('${granularity}', to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai')::date)::text`;
-
-  const rows = await query(
-    `SELECT
-       ${truncExpr} as date,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt_tokens,
-       COALESCE(SUM(completion_tokens), 0)::bigint as completion_tokens,
-       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation_tokens,
-       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read_tokens,
-       COALESCE(SUM(quota), 0)::bigint as quota
-     FROM logs WHERE ${where}
-     GROUP BY date ORDER BY date`,
-    params
-  );
-
-  return rows.map((r) => ({
-    date: String(r.date).slice(0, granularity === "hour" ? 16 : 10),
-    calls: Number(r.calls),
-    prompt_tokens: Number(r.prompt_tokens),
-    completion_tokens: Number(r.completion_tokens),
-    cache_creation_tokens: Number(r.cache_creation_tokens),
-    cache_read_tokens: Number(r.cache_read_tokens),
-    total_tokens: Number(r.prompt_tokens) + Number(r.completion_tokens) + Number(r.cache_creation_tokens) + Number(r.cache_read_tokens),
-    quota: Number(r.quota),
-  }));
-  });
-}// ── 排名 ──────────────────────────────────────────────────────
-
-export interface RankingItem {
-  rank: number;
-  name: string;
-  id?: number;
-  calls: number;
-  prompt_tokens: number;
-  completion_tokens: number;
-  cache_creation_tokens: number;
-  cache_read_tokens: number;
-  total_tokens: number;
-  quota: number;
-  quota_usd: number;
-}
-
-// 用户显示名称映射
-async function getDisplayNames(): Promise<Record<number, string>> {
-  const rows = await query(
-    "SELECT id, display_name FROM users WHERE display_name IS NOT NULL AND display_name != ''"
-  );
-  return Object.fromEntries(rows.map((r) => [r.id, r.display_name]));
-}
-
-// 渠道名称映射
-async function getChannelNames(): Promise<Record<number, string>> {
-  const rows = await query("SELECT id, name FROM channels");
-  return Object.fromEntries(rows.map((r) => [r.id, r.name]));
-}
-
-export function getUserRanking(
-  startTs?: number,
-  endTs?: number,
-  limit = 50
-): Promise<RankingItem[]> {
-  return cached(cacheKey("userRank", startTs, endTs, limit), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(limit);
-
-  const displayNames = await getDisplayNames();
-
-  const rows = await query(
-    `SELECT user_id, username,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
-       COALESCE(SUM(quota), 0)::bigint as quota
-     FROM logs WHERE ${where}
-     GROUP BY user_id, username
-     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
-     LIMIT $${params.length}`,
-    params
-  );
-
-  return rows.map((r, i) => ({
-    rank: i + 1,
-    name: displayNames[r.user_id] || r.username,
-    username: r.username as string,
-    id: Number(r.user_id),
-    calls: Number(r.calls),
-    prompt_tokens: Number(r.prompt),
-    completion_tokens: Number(r.completion),
-    cache_creation_tokens: Number(r.cache_creation),
-    cache_read_tokens: Number(r.cache_read),
-    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
-    quota: Number(r.quota),
-    quota_usd: Number(r.quota) / 500000,
-  }));
-  });
-}
-
-export function getModelRanking(
-  startTs?: number,
-  endTs?: number,
-  limit = 50
-): Promise<RankingItem[]> {
-  return cached(cacheKey("modelRank", startTs, endTs, limit), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(limit);
-
-  const rows = await query(
-    `SELECT ${REAL_MODEL} as model,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
-       COALESCE(SUM(quota), 0)::bigint as quota
-     FROM logs WHERE ${where}
-     GROUP BY model
-     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
-     LIMIT $${params.length}`,
-    params
-  );
-
-  return rows.map((r, i) => ({
-    rank: i + 1,
-    name: r.model || "(unknown)",
-    calls: Number(r.calls),
-    prompt_tokens: Number(r.prompt),
-    completion_tokens: Number(r.completion),
-    cache_creation_tokens: Number(r.cache_creation),
-    cache_read_tokens: Number(r.cache_read),
-    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
-    quota: Number(r.quota),
-    quota_usd: Number(r.quota) / 500000,
-  }));
-  });
-}
-
-export function getChannelRanking(
-  startTs?: number,
-  endTs?: number,
-  limit = 50
-): Promise<RankingItem[]> {
-  return cached(cacheKey("channelRank", startTs, endTs, limit), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(limit);
-
-  const channelNames = await getChannelNames();
-
-  const rows = await query(
-    `SELECT channel_id,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
-       COALESCE(SUM(quota), 0)::bigint as quota
-     FROM logs WHERE ${where}
-     GROUP BY channel_id
-     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
-     LIMIT $${params.length}`,
-    params
-  );
-
-  return rows.map((r, i) => ({
-    rank: i + 1,
-    name: channelNames[r.channel_id] || `已删除(${r.channel_id})`,
-    id: Number(r.channel_id),
-    calls: Number(r.calls),
-    prompt_tokens: Number(r.prompt),
-    completion_tokens: Number(r.completion),
-    cache_creation_tokens: Number(r.cache_creation),
-    cache_read_tokens: Number(r.cache_read),
-    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
-    quota: Number(r.quota),
-    quota_usd: Number(r.quota) / 500000,
-  }));
-  });
-}
-
-// ── 下钻详情 ──────────────────────────────────────────────────
-
-export interface DetailBreakdown {
-  name: string;
-  calls: number;
-  total_tokens: number;
-  quota: number;
-}
-
-export interface TokenDetailBreakdown extends DetailBreakdown {
-  models: DetailBreakdown[];
-}
-
-export function getUserDetail(
-  username: string,
-  startTs?: number,
-  endTs?: number
-) {
-  return cached(cacheKey("userDetail", username, startTs, endTs), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(username);
-
-  // 用户总览
-  const overview = await query(
-    `SELECT COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens),0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where} AND username = $${params.length}`,
-    params
-  );
-
-  // 用户的模型分布
-  const params2: (string | number | boolean | null)[] = [];
-  const where2 = timeWhere(params2, startTs, endTs);
-  params2.push(username);
-
-  const models = await query(
-    `SELECT ${REAL_MODEL} as model,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where2} AND username = $${params2.length}
-     GROUP BY model
-     ORDER BY tokens DESC LIMIT 20`,
-    params2
-  );
-
-  const params3: (string | number | boolean | null)[] = [];
-  const where3 = timeWhere(params3, startTs, endTs);
-  params3.push(username);
-
-  const tokens = await query(
-    `SELECT ${TOKEN_NAME} as token_name,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where3} AND username = $${params3.length}
-     GROUP BY token_name
-     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC, token_name ASC
-     LIMIT 50`,
-    params3
-  );
-
-  const params4: (string | number | boolean | null)[] = [];
-  const where4 = timeWhere(params4, startTs, endTs);
-  params4.push(username);
-
-  const tokenModels = await query(
-    `WITH filtered_logs AS (
-       SELECT ${TOKEN_NAME} as token_name,
-          ${REAL_MODEL} as model,
-          prompt_tokens,
-          completion_tokens,
-          ${CACHE_CREATION} as cache_creation,
-          ${CACHE_READ} as cache_read,
-          quota
-       FROM logs WHERE ${where4} AND username = $${params4.length}
-     ),
-     top_tokens AS (
-       SELECT token_name
-       FROM filtered_logs
-       GROUP BY token_name
-       ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(cache_creation),0) + COALESCE(SUM(cache_read),0) DESC, token_name ASC
-       LIMIT 50
-     ),
-     token_models AS (
-       SELECT filtered_logs.token_name,
-          filtered_logs.model,
-          COUNT(*)::int as calls,
-          COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
-          COALESCE(SUM(cache_creation),0)::bigint as cache_creation,
-          COALESCE(SUM(cache_read),0)::bigint as cache_read,
-          COALESCE(SUM(quota),0)::bigint as quota
-       FROM filtered_logs
-       INNER JOIN top_tokens ON filtered_logs.token_name = top_tokens.token_name
-       GROUP BY filtered_logs.token_name, filtered_logs.model
-     ),
-     ranked AS (
-       SELECT *,
-          ROW_NUMBER() OVER (PARTITION BY token_name ORDER BY tokens + cache_creation + cache_read DESC, model ASC) as rn
-       FROM token_models
-     )
-     SELECT token_name, model, calls, tokens, cache_creation, cache_read, quota
-     FROM ranked
-     WHERE rn <= 10
-     ORDER BY token_name ASC, tokens + cache_creation + cache_read DESC, model ASC`,
-    params4
-  );
-
-  const modelsByToken = new Map<string, DetailBreakdown[]>();
-  for (const row of tokenModels) {
-    const tokenName = String(row.token_name ?? "");
-    const rows = modelsByToken.get(tokenName) ?? [];
-    rows.push({
-      name: String(row.model || "(unknown)"),
-      calls: Number(row.calls),
-      total_tokens: Number(row.tokens) + Number(row.cache_creation) + Number(row.cache_read),
-      quota: Number(row.quota),
-    });
-    modelsByToken.set(tokenName, rows);
-  }
-
-  const displayNames = await getDisplayNames();
-  const userRow = await query(
-    "SELECT id FROM users WHERE username = $1 LIMIT 1",
-    [username]
-  );
-  const displayName =
-    userRow.length > 0 ? displayNames[userRow[0].id] || username : username;
-
-  const o = overview[0];
-  return {
-    display_name: displayName,
-    calls: Number(o.calls),
-    prompt_tokens: Number(o.prompt),
-    completion_tokens: Number(o.completion),
-    cache_creation_tokens: Number(o.cache_creation),
-    cache_read_tokens: Number(o.cache_read),
-    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
-    quota: Number(o.quota),
-    models: models.map((m) => ({
-      name: m.model,
-      calls: Number(m.calls),
-      total_tokens: Number(m.tokens) + Number(m.cache_creation) + Number(m.cache_read),
-      quota: Number(m.quota),
-    })),
-    tokens: tokens.map((token): TokenDetailBreakdown => {
-      const name = String(token.token_name ?? "");
-      return {
-        name,
-        calls: Number(token.calls),
-        total_tokens: Number(token.tokens) + Number(token.cache_creation) + Number(token.cache_read),
-        quota: Number(token.quota),
-        models: modelsByToken.get(name) ?? [],
-      };
-    }),
-  };
-  });
-}
-
-export function getModelDetail(
-  model: string,
-  startTs?: number,
-  endTs?: number
-) {
-  return cached(cacheKey("modelDetail", model, startTs, endTs), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(model);
-
-  const overview = await query(
-    `SELECT COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens),0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where} AND ${REAL_MODEL} = $${params.length}`,
-    params
-  );
-
-  const params2: (string | number | boolean | null)[] = [];
-  const where2 = timeWhere(params2, startTs, endTs);
-  params2.push(model);
-
-  const displayNames = await getDisplayNames();
-  const users = await query(
-    `SELECT user_id, username,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where2} AND ${REAL_MODEL} = $${params2.length}
-     GROUP BY user_id, username
-     ORDER BY tokens DESC LIMIT 20`,
-    params2
-  );
-
-  const o = overview[0];
-  return {
-    calls: Number(o.calls),
-    prompt_tokens: Number(o.prompt),
-    completion_tokens: Number(o.completion),
-    cache_creation_tokens: Number(o.cache_creation),
-    cache_read_tokens: Number(o.cache_read),
-    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
-    quota: Number(o.quota),
-    users: users.map((u) => ({
-      name: displayNames[u.user_id] || u.username,
-      calls: Number(u.calls),
-      total_tokens: Number(u.tokens) + Number(u.cache_creation) + Number(u.cache_read),
-      quota: Number(u.quota),
-    })),
-  };
-  });
-}
-
-export function getChannelDetail(
-  channelId: number,
-  startTs?: number,
-  endTs?: number
-) {
-  return cached(cacheKey("channelDetail", channelId, startTs, endTs), async () => {
-  const params: (string | number | boolean | null)[] = [];
-  const where = timeWhere(params, startTs, endTs);
-  params.push(channelId);
-
-  const channelNames = await getChannelNames();
-
-  const overview = await query(
-    `SELECT COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
-       COALESCE(SUM(completion_tokens),0)::bigint as completion,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where} AND channel_id = $${params.length}`,
-    params
-  );
-
-  const params2: (string | number | boolean | null)[] = [];
-  const where2 = timeWhere(params2, startTs, endTs);
-  params2.push(channelId);
-
-  const models = await query(
-    `SELECT ${REAL_MODEL} as model,
-       COUNT(*)::int as calls,
-       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
-       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
-       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
-       COALESCE(SUM(quota),0)::bigint as quota
-     FROM logs WHERE ${where2} AND channel_id = $${params2.length}
-     GROUP BY model
-     ORDER BY tokens DESC LIMIT 20`,
-    params2
-  );
-
-  const o = overview[0];
-  return {
-    channel_name: channelNames[channelId] || `已删除(${channelId})`,
-    calls: Number(o.calls),
-    prompt_tokens: Number(o.prompt),
-    completion_tokens: Number(o.completion),
-    cache_creation_tokens: Number(o.cache_creation),
-    cache_read_tokens: Number(o.cache_read),
-    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
-    quota: Number(o.quota),
-    models: models.map((m) => ({
-      name: m.model,
-      calls: Number(m.calls),
-      total_tokens: Number(m.tokens) + Number(m.cache_creation) + Number(m.cache_read),
-      quota: Number(m.quota),
-    })),
-  };
-  });
-}
-
-// ── 明细日志 ──────────────────────────────────────────────────
-
-export interface LogEntry {
-  id: number;
-  created_at: string;
-  username: string;
-  display_name: string;
-  real_model: string;
-  request_model: string;
-  channel_name: string;
-  channel_id: number;
-  prompt_tokens: number;
-  completion_tokens: number;
-  cache_creation_tokens: number;
-  cache_read_tokens: number;
-  total_tokens: number;
-  quota: number;
-  quota_usd: number;
-  use_time: number;
-  is_stream: boolean;
-  token_name: string;
-}
-
-export interface LogsResult {
-  logs: LogEntry[];
-  total: number;
-  page: number;
-  page_size: number;
-}
-
-export async function getLogs(options: {
-  page?: number;
-  pageSize?: number;
-  startTs?: number;
-  endTs?: number;
-  username?: string;
-  model?: string;
-  channelId?: number;
-  tokenName?: string;
-}): Promise<LogsResult> {
-  const ck = cacheKey("logs", options.page, options.pageSize, options.startTs, options.endTs, options.username, options.model, options.channelId, options.tokenName);
-  return cached(ck, async () => {
-  const { page = 1, pageSize = 100 } = options;
-  const params: (string | number | boolean | null)[] = [];
-  let where = timeWhere(params, options.startTs, options.endTs);
-
-  if (options.username) {
-    params.push(options.username);
-    where += ` AND username = $${params.length}`;
-  }
-  if (options.model) {
-    params.push(options.model);
-    where += ` AND ${REAL_MODEL} = $${params.length}`;
-  }
-  if (options.channelId) {
-    params.push(options.channelId);
-    where += ` AND channel_id = $${params.length}`;
-  }
-  if (options.tokenName) {
-    params.push(`%${options.tokenName}%`);
-    where += ` AND token_name ILIKE $${params.length}`;
-  }
-
-  // Count
-  const countRows = await query(
-    `SELECT COUNT(*)::int as total FROM logs WHERE ${where}`,
-    params
-  );
-  const total = Number(countRows[0].total);
-
-  // Data
-  const offset = (page - 1) * pageSize;
-  const dataParams = [...params, pageSize, offset];
-
-  const displayNames = await getDisplayNames();
-  const channelNames = await getChannelNames();
-
-  const rows = await query(
-    `SELECT id, created_at, user_id, username, model_name,
-       ${REAL_MODEL} as real_model,
-       channel_id, prompt_tokens, completion_tokens, quota,
-       ${CACHE_CREATION} as cache_creation,
-       ${CACHE_READ} as cache_read,
-       use_time, is_stream, token_name
-     FROM logs WHERE ${where}
-     ORDER BY id DESC
-     LIMIT $${dataParams.length - 1} OFFSET $${dataParams.length}`,
-    dataParams
-  );
-
-  return {
-    total,
-    page,
-    page_size: pageSize,
-    logs: rows.map((r) => ({
-      id: Number(r.id),
-      created_at: new Date(Number(r.created_at) * 1000).toISOString(),
-      username: r.username,
-      display_name: displayNames[r.user_id] || r.username,
-      real_model: r.real_model || r.model_name,
-      request_model: r.model_name,
-      channel_name: channelNames[r.channel_id] || `已删除(${r.channel_id})`,
-      channel_id: Number(r.channel_id),
-      prompt_tokens: Number(r.prompt_tokens),
-      completion_tokens: Number(r.completion_tokens),
-      cache_creation_tokens: Number(r.cache_creation),
-      cache_read_tokens: Number(r.cache_read),
-      total_tokens: Number(r.prompt_tokens) + Number(r.completion_tokens) + Number(r.cache_creation) + Number(r.cache_read),
-      quota: Number(r.quota),
-      quota_usd: Number(r.quota) / 500000,
-      use_time: Number(r.use_time),
-      is_stream: Boolean(r.is_stream),
-      token_name: r.token_name || "",
-    })),
-  };
-  });
-}
+export { getDateRange } from "./query-date-range";
+export { getOverview, type OverviewData } from "./query-overview";
+export { getTrends, type TrendFilters, type TrendGranularity, type TrendPoint } from "./query-trends";
+export { getChannelRanking, getModelRanking, getUserRanking, type RankingItem } from "./query-rankings";
+export { getChannelDetail, getModelDetail, getUserDetail, type DetailBreakdown, type TokenDetailBreakdown } from "./query-details";
+export { getLogs, type LogEntry, type LogsResult } from "./query-logs";
--- a/lib/query-cache.test.ts
+++ b/lib/query-cache.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { createQueryCache } from "./query-cache";
+
+describe("query cache", () => {
+  test("returns cached values inside TTL", async () => {
+    let now = 1_000;
+    const cache = createQueryCache({ ttlMs: 100, maxEntries: 10, now: () => now });
+    let calls = 0;
+
+    const first = await cache.cached("key", async () => {
+      calls += 1;
+      return { value: "first" };
+    });
+    now += 50;
+    const second = await cache.cached("key", async () => {
+      calls += 1;
+      return { value: "second" };
+    });
+
+    expect(first).toEqual({ value: "first" });
+    expect(second).toEqual({ value: "first" });
+    expect(calls).toBe(1);
+  });
+
+  test("refreshes expired values", async () => {
+    let now = 1_000;
+    const cache = createQueryCache({ ttlMs: 100, maxEntries: 10, now: () => now });
+
+    await cache.cached("key", async () => "first");
+    now += 101;
+    const second = await cache.cached("key", async () => "second");
+
+    expect(second).toBe("second");
+  });
+
+  test("evicts oldest entries beyond max size", async () => {
+    const cache = createQueryCache({ ttlMs: 1_000, maxEntries: 2, now: () => 1_000 });
+    let calls = 0;
+
+    await cache.cached("a", async () => "a");
+    await cache.cached("b", async () => "b");
+    await cache.cached("c", async () => "c");
+    const value = await cache.cached("a", async () => {
+      calls += 1;
+      return "new-a";
+    });
+
+    expect(value).toBe("new-a");
+    expect(calls).toBe(1);
+  });
+});
--- a/lib/query-cache.ts
+++ b/lib/query-cache.ts
@@ -0,0 +1,39 @@
+export interface QueryCacheOptions {
+  ttlMs: number;
+  maxEntries: number;
+  now?: () => number;
+}
+
+export function createQueryCache(options: QueryCacheOptions) {
+  const now = options.now ?? Date.now;
+  const entries = new Map<string, { data: unknown; ts: number }>();
+
+  async function cached<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const hit = entries.get(key);
+    if (hit && now() - hit.ts < options.ttlMs) {
+      return hit.data as T;
+    }
+
+    const data = await fn();
+    entries.set(key, { data, ts: now() });
+
+    while (entries.size > options.maxEntries) {
+      const oldestKey = entries.keys().next().value;
+      if (oldestKey === undefined) break;
+      entries.delete(oldestKey);
+    }
+
+    return data;
+  }
+
+  function clear() {
+    entries.clear();
+  }
+
+  return { cached, clear };
+}
+
+export const queryCache = createQueryCache({
+  ttlMs: 120_000,
+  maxEntries: 500,
+});
--- a/lib/query-date-range.ts
+++ b/lib/query-date-range.ts
@@ -0,0 +1,13 @@
+import { query } from "./db";
+
+// ── 数据时间边界 ────────────────────────────────────────────────
+
+export async function getDateRange(): Promise<{ minDate: string; maxDate: string }> {
+  const rows = await query(
+    `SELECT
+       ((MIN(to_timestamp(created_at)) AT TIME ZONE 'Asia/Shanghai')::date)::text as min_date,
+       ((MAX(to_timestamp(created_at)) AT TIME ZONE 'Asia/Shanghai')::date)::text as max_date
+     FROM logs WHERE type = 2`
+  );
+  return { minDate: rows[0]?.min_date ?? "", maxDate: rows[0]?.max_date ?? "" };
+}
--- a/lib/query-details.ts
+++ b/lib/query-details.ts
@@ -0,0 +1,287 @@
+import { query } from "./db";
+import { CACHE_CREATION, CACHE_READ, REAL_MODEL, TOKEN_NAME, cacheKey, cached, getChannelNames, getDisplayNames, timeWhere } from "./query-shared";
+
+// ── 下钻详情 ──────────────────────────────────────────────────
+
+export interface DetailBreakdown {
+  name: string;
+  calls: number;
+  total_tokens: number;
+  quota: number;
+}
+export interface TokenDetailBreakdown extends DetailBreakdown {
+  models: DetailBreakdown[];
+}
+
+export function getUserDetail(
+  username: string,
+  startTs?: number,
+  endTs?: number
+) {
+  return cached(cacheKey("userDetail", username, startTs, endTs), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(username);
+
+  // 用户总览
+  const overview = await query(
+    `SELECT COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens),0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where} AND username = $${params.length}`,
+    params
+  );
+
+  // 用户的模型分布
+  const params2: (string | number | boolean | null)[] = [];
+  const where2 = timeWhere(params2, startTs, endTs);
+  params2.push(username);
+
+  const models = await query(
+    `SELECT ${REAL_MODEL} as model,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where2} AND username = $${params2.length}
+     GROUP BY model
+     ORDER BY tokens DESC LIMIT 20`,
+    params2
+  );
+
+  const params3: (string | number | boolean | null)[] = [];
+  const where3 = timeWhere(params3, startTs, endTs);
+  params3.push(username);
+
+  const tokens = await query(
+    `SELECT ${TOKEN_NAME} as token_name,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where3} AND username = $${params3.length}
+     GROUP BY token_name
+     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC, token_name ASC
+     LIMIT 50`,
+    params3
+  );
+
+  const params4: (string | number | boolean | null)[] = [];
+  const where4 = timeWhere(params4, startTs, endTs);
+  params4.push(username);
+
+  const tokenModels = await query(
+    `WITH filtered_logs AS (
+       SELECT ${TOKEN_NAME} as token_name,
+          ${REAL_MODEL} as model,
+          prompt_tokens,
+          completion_tokens,
+          ${CACHE_CREATION} as cache_creation,
+          ${CACHE_READ} as cache_read,
+          quota
+       FROM logs WHERE ${where4} AND username = $${params4.length}
+     ),
+     top_tokens AS (
+       SELECT token_name
+       FROM filtered_logs
+       GROUP BY token_name
+       ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(cache_creation),0) + COALESCE(SUM(cache_read),0) DESC, token_name ASC
+       LIMIT 50
+     ),
+     token_models AS (
+       SELECT filtered_logs.token_name,
+          filtered_logs.model,
+          COUNT(*)::int as calls,
+          COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
+          COALESCE(SUM(cache_creation),0)::bigint as cache_creation,
+          COALESCE(SUM(cache_read),0)::bigint as cache_read,
+          COALESCE(SUM(quota),0)::bigint as quota
+       FROM filtered_logs
+       INNER JOIN top_tokens ON filtered_logs.token_name = top_tokens.token_name
+       GROUP BY filtered_logs.token_name, filtered_logs.model
+     ),
+     ranked AS (
+       SELECT *,
+          ROW_NUMBER() OVER (PARTITION BY token_name ORDER BY tokens + cache_creation + cache_read DESC, model ASC) as rn
+       FROM token_models
+     )
+     SELECT token_name, model, calls, tokens, cache_creation, cache_read, quota
+     FROM ranked
+     WHERE rn <= 10
+     ORDER BY token_name ASC, tokens + cache_creation + cache_read DESC, model ASC`,
+    params4
+  );
+
+  const modelsByToken = new Map<string, DetailBreakdown[]>();
+  for (const row of tokenModels) {
+    const tokenName = String(row.token_name ?? "");
+    const rows = modelsByToken.get(tokenName) ?? [];
+    rows.push({
+      name: String(row.model || "(unknown)"),
+      calls: Number(row.calls),
+      total_tokens: Number(row.tokens) + Number(row.cache_creation) + Number(row.cache_read),
+      quota: Number(row.quota),
+    });
+    modelsByToken.set(tokenName, rows);
+  }
+
+  const displayNames = await getDisplayNames();
+  const userRow = await query(
+    "SELECT id FROM users WHERE username = $1 LIMIT 1",
+    [username]
+  );
+  const displayName =
+    userRow.length > 0 ? displayNames[userRow[0].id] || username : username;
+
+  const o = overview[0];
+  return {
+    display_name: displayName,
+    calls: Number(o.calls),
+    prompt_tokens: Number(o.prompt),
+    completion_tokens: Number(o.completion),
+    cache_creation_tokens: Number(o.cache_creation),
+    cache_read_tokens: Number(o.cache_read),
+    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
+    quota: Number(o.quota),
+    models: models.map((m) => ({
+      name: m.model,
+      calls: Number(m.calls),
+      total_tokens: Number(m.tokens) + Number(m.cache_creation) + Number(m.cache_read),
+      quota: Number(m.quota),
+    })),
+    tokens: tokens.map((token): TokenDetailBreakdown => {
+      const name = String(token.token_name ?? "");
+      return {
+        name,
+        calls: Number(token.calls),
+        total_tokens: Number(token.tokens) + Number(token.cache_creation) + Number(token.cache_read),
+        quota: Number(token.quota),
+        models: modelsByToken.get(name) ?? [],
+      };
+    }),
+  };
+  });
+}
+
+export function getModelDetail(
+  model: string,
+  startTs?: number,
+  endTs?: number
+) {
+  return cached(cacheKey("modelDetail", model, startTs, endTs), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(model);
+
+  const overview = await query(
+    `SELECT COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens),0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where} AND ${REAL_MODEL} = $${params.length}`,
+    params
+  );
+
+  const params2: (string | number | boolean | null)[] = [];
+  const where2 = timeWhere(params2, startTs, endTs);
+  params2.push(model);
+
+  const displayNames = await getDisplayNames();
+  const users = await query(
+    `SELECT user_id, username,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where2} AND ${REAL_MODEL} = $${params2.length}
+     GROUP BY user_id, username
+     ORDER BY tokens DESC LIMIT 20`,
+    params2
+  );
+
+  const o = overview[0];
+  return {
+    calls: Number(o.calls),
+    prompt_tokens: Number(o.prompt),
+    completion_tokens: Number(o.completion),
+    cache_creation_tokens: Number(o.cache_creation),
+    cache_read_tokens: Number(o.cache_read),
+    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
+    quota: Number(o.quota),
+    users: users.map((u) => ({
+      name: displayNames[u.user_id] || u.username,
+      calls: Number(u.calls),
+      total_tokens: Number(u.tokens) + Number(u.cache_creation) + Number(u.cache_read),
+      quota: Number(u.quota),
+    })),
+  };
+  });
+}
+
+export function getChannelDetail(
+  channelId: number,
+  startTs?: number,
+  endTs?: number
+) {
+  return cached(cacheKey("channelDetail", channelId, startTs, endTs), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(channelId);
+
+  const channelNames = await getChannelNames();
+
+  const overview = await query(
+    `SELECT COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens),0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens),0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where} AND channel_id = $${params.length}`,
+    params
+  );
+
+  const params2: (string | number | boolean | null)[] = [];
+  const where2 = timeWhere(params2, startTs, endTs);
+  params2.push(channelId);
+
+  const models = await query(
+    `SELECT ${REAL_MODEL} as model,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens + completion_tokens),0)::bigint as tokens,
+       COALESCE(SUM(${CACHE_CREATION}),0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}),0)::bigint as cache_read,
+       COALESCE(SUM(quota),0)::bigint as quota
+     FROM logs WHERE ${where2} AND channel_id = $${params2.length}
+     GROUP BY model
+     ORDER BY tokens DESC LIMIT 20`,
+    params2
+  );
+
+  const o = overview[0];
+  return {
+    channel_name: channelNames[channelId] || `已删除(${channelId})`,
+    calls: Number(o.calls),
+    prompt_tokens: Number(o.prompt),
+    completion_tokens: Number(o.completion),
+    cache_creation_tokens: Number(o.cache_creation),
+    cache_read_tokens: Number(o.cache_read),
+    total_tokens: Number(o.prompt) + Number(o.completion) + Number(o.cache_creation) + Number(o.cache_read),
+    quota: Number(o.quota),
+    models: models.map((m) => ({
+      name: m.model,
+      calls: Number(m.calls),
+      total_tokens: Number(m.tokens) + Number(m.cache_creation) + Number(m.cache_read),
+      quota: Number(m.quota),
+    })),
+  };
+  });
+}
--- a/lib/query-logs.ts
+++ b/lib/query-logs.ts
@@ -0,0 +1,129 @@
+import { query } from "./db";
+import { quotaToUsd } from "./metrics";
+import { CACHE_CREATION, CACHE_READ, REAL_MODEL, cacheKey, cached, getChannelNames, getDisplayNames, timeWhere } from "./query-shared";
+
+// ── 明细日志 ──────────────────────────────────────────────────
+
+export interface LogEntry {
+  id: number;
+  created_at: string;
+  username: string;
+  display_name: string;
+  real_model: string;
+  request_model: string;
+  channel_name: string;
+  channel_id: number;
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_creation_tokens: number;
+  cache_read_tokens: number;
+  total_tokens: number;
+  quota: number;
+  quota_usd: number;
+  use_time: number;
+  is_stream: boolean;
+  token_name: string;
+}
+
+export interface LogsResult {
+  logs: LogEntry[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+function normalizePositiveInteger(value: number | undefined, defaultValue: number, max?: number): number {
+  if (!Number.isFinite(value)) return defaultValue;
+  const positive = Math.max(1, Math.trunc(value ?? defaultValue));
+  return max === undefined ? positive : Math.min(max, positive);
+}
+
+export async function getLogs(options: {
+  page?: number;
+  pageSize?: number;
+  startTs?: number;
+  endTs?: number;
+  username?: string;
+  model?: string;
+  channelId?: number;
+  tokenName?: string;
+}): Promise<LogsResult> {
+  const ck = cacheKey("logs", options.page, options.pageSize, options.startTs, options.endTs, options.username, options.model, options.channelId, options.tokenName);
+  return cached(ck, async () => {
+  const page = normalizePositiveInteger(options.page, 1);
+  const pageSize = normalizePositiveInteger(options.pageSize, 100, 200);
+  const params: (string | number | boolean | null)[] = [];
+  let where = timeWhere(params, options.startTs, options.endTs);
+
+  if (options.username) {
+    params.push(options.username);
+    where += ` AND username = $${params.length}`;
+  }
+  if (options.model) {
+    params.push(options.model);
+    where += ` AND ${REAL_MODEL} = $${params.length}`;
+  }
+  if (options.channelId) {
+    params.push(options.channelId);
+    where += ` AND channel_id = $${params.length}`;
+  }
+  if (options.tokenName) {
+    params.push(`%${options.tokenName}%`);
+    where += ` AND token_name ILIKE $${params.length}`;
+  }
+
+  // Count
+  const countRows = await query(
+    `SELECT COUNT(*)::int as total FROM logs WHERE ${where}`,
+    params
+  );
+  const total = Number(countRows[0].total);
+
+  // Data. For large production tables, add indexes on logs(created_at),
+  // logs(username, created_at), logs(channel_id, created_at), and the real-model expression.
+  const offset = (page - 1) * pageSize;
+  const dataParams = [...params, pageSize, offset];
+
+  const displayNames = await getDisplayNames();
+  const channelNames = await getChannelNames();
+
+  const rows = await query(
+    `SELECT id, created_at, user_id, username, model_name,
+       ${REAL_MODEL} as real_model,
+       channel_id, prompt_tokens, completion_tokens, quota,
+       ${CACHE_CREATION} as cache_creation,
+       ${CACHE_READ} as cache_read,
+       use_time, is_stream, token_name
+     FROM logs WHERE ${where}
+     ORDER BY id DESC
+     LIMIT $${dataParams.length - 1} OFFSET $${dataParams.length}`,
+    dataParams
+  );
+
+  return {
+    total,
+    page,
+    page_size: pageSize,
+    logs: rows.map((r) => ({
+      id: Number(r.id),
+      created_at: new Date(Number(r.created_at) * 1000).toISOString(),
+      username: r.username,
+      display_name: displayNames[r.user_id] || r.username,
+      real_model: r.real_model || r.model_name,
+      request_model: r.model_name,
+      channel_name: channelNames[r.channel_id] || `已删除(${r.channel_id})`,
+      channel_id: Number(r.channel_id),
+      prompt_tokens: Number(r.prompt_tokens),
+      completion_tokens: Number(r.completion_tokens),
+      cache_creation_tokens: Number(r.cache_creation),
+      cache_read_tokens: Number(r.cache_read),
+      total_tokens: Number(r.prompt_tokens) + Number(r.completion_tokens) + Number(r.cache_creation) + Number(r.cache_read),
+      quota: Number(r.quota),
+      quota_usd: quotaToUsd(Number(r.quota)),
+      use_time: Number(r.use_time),
+      is_stream: Boolean(r.is_stream),
+      token_name: r.token_name || "",
+    })),
+  };
+  });
+}
--- a/lib/query-overview.ts
+++ b/lib/query-overview.ts
@@ -0,0 +1,55 @@
+import { query } from "./db";
+import { CACHE_CREATION, CACHE_READ, REAL_MODEL, cacheKey, cached, timeWhere } from "./query-shared";
+
+// ── 总览 ──────────────────────────────────────────────────────
+
+export interface OverviewData {
+  total_calls: number;
+  total_tokens: number;
+  total_prompt: number;
+  total_completion: number;
+  total_cache_creation: number;
+  total_cache_read: number;
+  total_quota: number;
+  active_users: number;
+  active_models: number;
+  active_channels: number;
+}
+export function getOverview(
+  startTs?: number,
+  endTs?: number
+): Promise<OverviewData> {
+  return cached(cacheKey("overview", startTs, endTs), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+
+  const rows = await query(
+    `SELECT
+       COUNT(*)::int as total_calls,
+       COALESCE(SUM(prompt_tokens + completion_tokens), 0)::bigint as total_tokens,
+       COALESCE(SUM(prompt_tokens), 0)::bigint as total_prompt,
+       COALESCE(SUM(completion_tokens), 0)::bigint as total_completion,
+       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as total_cache_creation,
+       COALESCE(SUM(${CACHE_READ}), 0)::bigint as total_cache_read,
+       COALESCE(SUM(quota), 0)::bigint as total_quota,
+       COUNT(DISTINCT user_id)::int as active_users,
+       COUNT(DISTINCT ${REAL_MODEL})::int as active_models,
+       COUNT(DISTINCT channel_id)::int as active_channels
+     FROM logs WHERE ${where}`,
+    params
+  );
+  const r = rows[0];
+  return {
+    total_calls: Number(r.total_calls),
+    total_tokens: Number(r.total_tokens) + Number(r.total_cache_creation) + Number(r.total_cache_read),
+    total_prompt: Number(r.total_prompt),
+    total_completion: Number(r.total_completion),
+    total_cache_creation: Number(r.total_cache_creation),
+    total_cache_read: Number(r.total_cache_read),
+    total_quota: Number(r.total_quota),
+    active_users: Number(r.active_users),
+    active_models: Number(r.active_models),
+    active_channels: Number(r.active_channels),
+  };
+  });
+}
--- a/lib/query-rankings.ts
+++ b/lib/query-rankings.ts
@@ -0,0 +1,145 @@
+import { query } from "./db";
+import { quotaToUsd } from "./metrics";
+import { CACHE_CREATION, CACHE_READ, REAL_MODEL, cacheKey, cached, getChannelNames, getDisplayNames, timeWhere } from "./query-shared";
+
+// ── 排名 ──────────────────────────────────────────────────────
+
+export interface RankingItem {
+  rank: number;
+  name: string;
+  id?: number;
+  calls: number;
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_creation_tokens: number;
+  cache_read_tokens: number;
+  total_tokens: number;
+  quota: number;
+  quota_usd: number;
+}
+export function getUserRanking(
+  startTs?: number,
+  endTs?: number,
+  limit = 50
+): Promise<RankingItem[]> {
+  return cached(cacheKey("userRank", startTs, endTs, limit), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(limit);
+
+  const displayNames = await getDisplayNames();
+
+  const rows = await query(
+    `SELECT user_id, username,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
+       COALESCE(SUM(quota), 0)::bigint as quota
+     FROM logs WHERE ${where}
+     GROUP BY user_id, username
+     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
+     LIMIT $${params.length}`,
+    params
+  );
+
+  return rows.map((r, i) => ({
+    rank: i + 1,
+    name: displayNames[r.user_id] || r.username,
+    username: r.username as string,
+    id: Number(r.user_id),
+    calls: Number(r.calls),
+    prompt_tokens: Number(r.prompt),
+    completion_tokens: Number(r.completion),
+    cache_creation_tokens: Number(r.cache_creation),
+    cache_read_tokens: Number(r.cache_read),
+    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
+    quota: Number(r.quota),
+    quota_usd: quotaToUsd(Number(r.quota)),
+  }));
+  });
+}
+
+export function getModelRanking(
+  startTs?: number,
+  endTs?: number,
+  limit = 50
+): Promise<RankingItem[]> {
+  return cached(cacheKey("modelRank", startTs, endTs, limit), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(limit);
+
+  const rows = await query(
+    `SELECT ${REAL_MODEL} as model,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
+       COALESCE(SUM(quota), 0)::bigint as quota
+     FROM logs WHERE ${where}
+     GROUP BY model
+     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
+     LIMIT $${params.length}`,
+    params
+  );
+
+  return rows.map((r, i) => ({
+    rank: i + 1,
+    name: r.model || "(unknown)",
+    calls: Number(r.calls),
+    prompt_tokens: Number(r.prompt),
+    completion_tokens: Number(r.completion),
+    cache_creation_tokens: Number(r.cache_creation),
+    cache_read_tokens: Number(r.cache_read),
+    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
+    quota: Number(r.quota),
+    quota_usd: quotaToUsd(Number(r.quota)),
+  }));
+  });
+}
+
+export function getChannelRanking(
+  startTs?: number,
+  endTs?: number,
+  limit = 50
+): Promise<RankingItem[]> {
+  return cached(cacheKey("channelRank", startTs, endTs, limit), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = timeWhere(params, startTs, endTs);
+  params.push(limit);
+
+  const channelNames = await getChannelNames();
+
+  const rows = await query(
+    `SELECT channel_id,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt,
+       COALESCE(SUM(completion_tokens), 0)::bigint as completion,
+       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation,
+       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read,
+       COALESCE(SUM(quota), 0)::bigint as quota
+     FROM logs WHERE ${where}
+     GROUP BY channel_id
+     ORDER BY COALESCE(SUM(prompt_tokens),0) + COALESCE(SUM(completion_tokens),0) + COALESCE(SUM(${CACHE_CREATION}),0) + COALESCE(SUM(${CACHE_READ}),0) DESC
+     LIMIT $${params.length}`,
+    params
+  );
+
+  return rows.map((r, i) => ({
+    rank: i + 1,
+    name: channelNames[r.channel_id] || `已删除(${r.channel_id})`,
+    id: Number(r.channel_id),
+    calls: Number(r.calls),
+    prompt_tokens: Number(r.prompt),
+    completion_tokens: Number(r.completion),
+    cache_creation_tokens: Number(r.cache_creation),
+    cache_read_tokens: Number(r.cache_read),
+    total_tokens: Number(r.prompt) + Number(r.completion) + Number(r.cache_creation) + Number(r.cache_read),
+    quota: Number(r.quota),
+    quota_usd: quotaToUsd(Number(r.quota)),
+  }));
+  });
+}
--- a/lib/query-shared.ts
+++ b/lib/query-shared.ts
@@ -0,0 +1,54 @@
+import { query } from "./db";
+import { queryCache } from "./query-cache";
+
+export const cached = queryCache.cached;
+
+export function cacheKey(...parts: unknown[]): string {
+  return parts.map((p) => String(p ?? "")).join(":");
+}
+
+export const REAL_MODEL = `COALESCE(
+  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'upstream_model_name'
+       THEN other::jsonb->>'upstream_model_name' END,
+  model_name)`;
+
+export const CACHE_CREATION = `COALESCE(
+  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'cache_creation_tokens'
+       THEN (other::jsonb->>'cache_creation_tokens')::bigint END,
+  0)`;
+
+export const CACHE_READ = `COALESCE(
+  CASE WHEN other IS NOT NULL AND other != '' AND other::jsonb ? 'cache_tokens'
+       THEN (other::jsonb->>'cache_tokens')::bigint END,
+  0)`;
+
+export const TOKEN_NAME = `COALESCE(NULLIF(BTRIM(token_name), ''), '')`;
+
+export function timeWhere(
+  params: (string | number | boolean | null)[],
+  startTs?: number,
+  endTs?: number
+): string {
+  let where = "type = 2";
+  if (startTs) {
+    params.push(startTs);
+    where += ` AND created_at >= $${params.length}`;
+  }
+  if (endTs) {
+    params.push(endTs);
+    where += ` AND created_at <= $${params.length}`;
+  }
+  return where;
+}
+
+export async function getDisplayNames(): Promise<Record<number, string>> {
+  const rows = await query(
+    "SELECT id, display_name FROM users WHERE display_name IS NOT NULL AND display_name != ''"
+  );
+  return Object.fromEntries(rows.map((r) => [r.id, r.display_name]));
+}
+
+export async function getChannelNames(): Promise<Record<number, string>> {
+  const rows = await query("SELECT id, name FROM channels");
+  return Object.fromEntries(rows.map((r) => [r.id, r.name]));
+}
--- a/lib/query-trends.ts
+++ b/lib/query-trends.ts
@@ -0,0 +1,87 @@
+import { query } from "./db";
+import { CACHE_CREATION, CACHE_READ, REAL_MODEL, cacheKey, cached, timeWhere } from "./query-shared";
+
+// ── 趋势 ──────────────────────────────────────────────────────
+
+export interface TrendPoint {
+  date: string;
+  calls: number;
+  prompt_tokens: number;
+  completion_tokens: number;
+  cache_creation_tokens: number;
+  cache_read_tokens: number;
+  total_tokens: number;
+  quota: number;
+}
+
+export type TrendGranularity = "hour" | "day" | "week" | "month";
+
+export interface TrendFilters {
+  username?: string;
+  model?: string;
+  channelId?: number;
+}
+
+function appendTrendFilters(
+  where: string,
+  params: (string | number | boolean | null)[],
+  filters: TrendFilters = {}
+): string {
+  if (filters.username) {
+    params.push(filters.username);
+    where += ` AND username = $${params.length}`;
+  }
+  if (filters.model) {
+    params.push(filters.model);
+    where += ` AND ${REAL_MODEL} = $${params.length}`;
+  }
+  if (filters.channelId !== undefined) {
+    params.push(filters.channelId);
+    where += ` AND channel_id = $${params.length}`;
+  }
+  return where;
+}
+
+export function getTrends(
+  granularity: TrendGranularity = "day",
+  startTs?: number,
+  endTs?: number,
+  filters: TrendFilters = {}
+): Promise<TrendPoint[]> {
+  return cached(cacheKey("trends", granularity, startTs, endTs, filters.username, filters.model, filters.channelId), async () => {
+  const params: (string | number | boolean | null)[] = [];
+  const where = appendTrendFilters(timeWhere(params, startTs, endTs), params, filters);
+
+  const truncExpr =
+    granularity === "hour"
+      ? `to_char(date_trunc('hour', to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai'), 'YYYY-MM-DD HH24:00')`
+      : granularity === "day"
+        ? `((to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai')::date)::text`
+        : `(date_trunc('${granularity}', to_timestamp(created_at) AT TIME ZONE 'Asia/Shanghai')::date)::text`;
+
+  const rows = await query(
+    `SELECT
+       ${truncExpr} as date,
+       COUNT(*)::int as calls,
+       COALESCE(SUM(prompt_tokens), 0)::bigint as prompt_tokens,
+       COALESCE(SUM(completion_tokens), 0)::bigint as completion_tokens,
+       COALESCE(SUM(${CACHE_CREATION}), 0)::bigint as cache_creation_tokens,
+       COALESCE(SUM(${CACHE_READ}), 0)::bigint as cache_read_tokens,
+       COALESCE(SUM(quota), 0)::bigint as quota
+     FROM logs WHERE ${where}
+     GROUP BY date ORDER BY date`,
+    params
+  );
+
+  return rows.map((r) => ({
+    date: String(r.date).slice(0, granularity === "hour" ? 16 : 10),
+    calls: Number(r.calls),
+    prompt_tokens: Number(r.prompt_tokens),
+    completion_tokens: Number(r.completion_tokens),
+    cache_creation_tokens: Number(r.cache_creation_tokens),
+    cache_read_tokens: Number(r.cache_read_tokens),
+    total_tokens: Number(r.prompt_tokens) + Number(r.completion_tokens) + Number(r.cache_creation_tokens) + Number(r.cache_read_tokens),
+    quota: Number(r.quota),
+  }));
+  });
+}