构建使用量分析仪表板

// packages/platform/db/prisma/schema.prisma

model UsageSnapshot {
  id         String   @id @default(cuid())
  tenantId   String
  date       DateTime @db.Date
  meterId    String           // 例如 "api_calls"、"storage_bytes"
  value      BigInt
  createdAt  DateTime @default(now())

  @@unique([tenantId, date, meterId])
  @@index([tenantId, meterId, date])
}

pnpm db:generate

pnpm db:migrate --name add-usage-snapshot

// backends/gateway/src/routes/analytics.ts
import { Hono } from "hono";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";
import { requirePermission } from "@nebutra/permissions";
import { getMetering } from "@nebutra/metering";
import { getCurrentTenant } from "@nebutra/tenant";

const analyticsRouter = new Hono();

const usageQuerySchema = z.object({
  meterId: z.string().default("api_calls"),
  days:    z.coerce.number().int().min(1).max(90).default(30),
});

analyticsRouter.get(
  "/usage",
  requirePermission("analytics:read"),
  zValidator("query", usageQuerySchema),
  async (c) => {
    const { meterId, days } = c.req.valid("query");
    const { tenantId } = getCurrentTenant();

    const metering = await getMetering();
    const since = new Date();
    since.setDate(since.getDate() - days);

    const series = await metering.getTimeSeries(tenantId, meterId, {
      from: since,
      to: new Date(),
      granularity: "day",
    });

    return c.json({
      success: true,
      data: {
        meterId,
        tenantId,
        series: series.map((point) => ({
          date:  point.timestamp.toISOString().split("T")[0],
          value: Number(point.value),
        })),
      },
    });
  }
);

export { analyticsRouter };

// backends/gateway/src/index.ts
import { analyticsRouter } from "./routes/analytics";

app.route("/api/v1/analytics", analyticsRouter);

mkdir -p apps/web/src/app/\(dashboard\)/analytics

// apps/web/src/app/(dashboard)/analytics/page.tsx
import { Suspense } from "react";
import { PageHeader } from "@nebutra/ui/layout";
import { LoadingState, ErrorState } from "@nebutra/ui/layout";
import { requireAuth, getTenantContext } from "@/lib/auth";
import { getTypedApi } from "@/lib/api/client";
import { AnalyticsChart } from "./_components/analytics-chart";

export const metadata = { title: "分析" };

async function AnalyticsData() {
  const { tenantId } = await getTenantContext();
  const api = await getTypedApi();

  const { data, error } = await api.GET("/api/v1/analytics/usage", {
    params: { query: { meterId: "api_calls", days: 30 } },
    next: { revalidate: 300 },   // 缓存 5 分钟
  });

  if (error || !data?.success) {
    return <ErrorState message="加载分析数据失败" />;
  }

  return <AnalyticsChart series={data.data.series} />;
}

export default async function AnalyticsPage() {
  await requireAuth();

  return (
    <div className="space-y-6">
      <PageHeader
        title="分析"
        description="过去 30 天的 API 使用情况"
      />
      <Suspense fallback={<LoadingState message="正在加载使用数据…" />}>
        <AnalyticsData />
      </Suspense>
    </div>
  );
}

// apps/web/src/app/(dashboard)/analytics/loading.tsx
import { LoadingState } from "@nebutra/ui/layout";
export default function Loading() {
  return <LoadingState message="正在加载分析数据…" />;
}

// apps/web/src/app/(dashboard)/analytics/error.tsx
"use client";
import { ErrorState } from "@nebutra/ui/layout";
export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return <ErrorState message={error.message} onRetry={reset} />;
}

mkdir -p apps/web/src/app/\(dashboard\)/analytics/_components

// apps/web/src/app/(dashboard)/analytics/_components/analytics-chart.tsx
"use client";

import {
  AreaChart,
  Area,
  XAxis,
  YAxis,
  CartesianGrid,
  Tooltip,
  ResponsiveContainer,
} from "recharts";
import { AnimateIn } from "@nebutra/ui/components";

interface DataPoint {
  date: string;
  value: number;
}

interface AnalyticsChartProps {
  series: DataPoint[];
}

function formatDate(dateStr: string): string {
  return new Date(dateStr).toLocaleDateString("zh-CN", {
    month: "short",
    day: "numeric",
  });
}

function formatValue(value: number): string {
  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
  if (value >= 1_000) return `${(value / 1_000).toFixed(1)}k`;
  return String(value);
}

export function AnalyticsChart({ series }: AnalyticsChartProps) {
  return (
    <AnimateIn preset="emerge" inView>
      <div className="rounded-xl border border-[var(--neutral-7)] bg-[var(--neutral-1)] p-6 shadow-sm">
        <h2 className="mb-4 text-sm font-medium text-[var(--neutral-11)]">
          API 调用次数 — 过去 30 天
        </h2>
        <ResponsiveContainer width="100%" height={280}>
          <AreaChart data={series} margin={{ top: 4, right: 4, bottom: 0, left: 0 }}>
            <defs>
              <linearGradient id="usageGradient" x1="0" y1="0" x2="0" y2="1">
                <stop offset="5%"  stopColor="var(--brand-primary)" stopOpacity={0.25} />
                <stop offset="95%" stopColor="var(--brand-primary)" stopOpacity={0} />
              </linearGradient>
            </defs>
            <CartesianGrid
              strokeDasharray="3 3"
              stroke="var(--neutral-7)"
              vertical={false}
            />
            <XAxis
              dataKey="date"
              tickFormatter={formatDate}
              tick={{ fill: "var(--neutral-11)", fontSize: 12 }}
              axisLine={false}
              tickLine={false}
            />
            <YAxis
              tickFormatter={formatValue}
              tick={{ fill: "var(--neutral-11)", fontSize: 12 }}
              axisLine={false}
              tickLine={false}
              width={48}
            />
            <Tooltip
              contentStyle={{
                background: "var(--neutral-2)",
                border: "1px solid var(--neutral-7)",
                borderRadius: "8px",
                color: "var(--neutral-12)",
                fontSize: "13px",
              }}
              labelFormatter={formatDate}
              formatter={(value: number) => [formatValue(value), "API 调用次数"]}
            />
            <Area
              type="monotone"
              dataKey="value"
              stroke="var(--brand-primary)"
              strokeWidth={2}
              fill="url(#usageGradient)"
              dot={false}
              activeDot={{ r: 4, fill: "var(--brand-primary)" }}
            />
          </AreaChart>
        </ResponsiveContainer>
      </div>
    </AnimateIn>
  );
}

// packages/iam/permissions/src/roles.ts
export const ROLE_PERMISSIONS = {
  OWNER:  ["*"],
  ADMIN:  ["analytics:read", "analytics:export", /* …其他管理员权限 */],
  MEMBER: ["analytics:read"],
  VIEWER: [],                   // 访客不能查看分析数据
} as const;

// apps/web/src/app/(dashboard)/analytics/page.tsx
import { PlanGate } from "@/components/plan-gate";

// 在页面组件内，用以下代码包裹内容：
<PlanGate
  plans={["starter", "pro", "enterprise"]}
  fallback={
    <EmptyState
      icon="lock"
      title="免费套餐不包含分析功能"
      description="升级到 Starter 或更高套餐以访问使用量分析。"
      action={<UpgradeButton />}
    />
  }
>
  <Suspense fallback={<LoadingState message="正在加载使用数据…" />}>
    <AnalyticsData />
  </Suspense>
</PlanGate>