admin-dashboard

管理员与开发者套件开发

此技能可帮助你扩展管理面板，并按照既定模式构建内部工具。

架构概览

/admin     - Admin Dashboard (user metrics, access control, audit)
/dev       - Developer Portal (docs, code browser, feature map) [PLANNED]
/ops       - Operations Console (infrastructure, logs, incidents) [PLANNED]

完整设计规范请参阅 docs/ADMIN-DEVELOPER-SUITE.md。

当前管理面板结构

位置：src/app/admin/page.tsx

现有标签页

标签页	用途	数据源
概览	快速统计（用户、签到、消息）	/api/admin/stats
漏斗	用户参与度瀑布图	/api/admin/stats
页面浏览量	按页面路径统计的分析数据	/api/admin/stats
用户	带活动信息的用户列表	/api/admin/stats
访问申请	待处理／已批准／已拒绝的申请	/api/admin/access-requests
允许的邮箱	邮箱白名单管理	/api/admin/allowed-emails
邮件模板	预览系统邮件	本地数据

计划中的标签页（来自设计方案）

标签页	用途	状态
生产环境健康状况	API 延迟、Core Web Vitals	待处理
错误跟踪	符合 HIPAA 要求的错误聚合	待处理
外部服务	Anthropic、数据库、推送状态	待处理
AI 分析	对话指标、令牌	待处理
审计日志	HIPAA 合规性查看器	待处理

添加新的管理标签页

1. 创建标签页内容组件

// In src/app/admin/page.tsx, add a new tab component

function ProductionHealthTab() {
  const [metrics, setMetrics] = useState<APIMetrics | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchMetrics() {
      const res = await fetch('/api/admin/metrics');
      const data = await res.json();
      setMetrics(data);
      setLoading(false);
    }
    fetchMetrics();
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <StatCard label="Uptime" value={metrics.uptime} />
        <StatCard label="Avg Latency" value={`${metrics.avgLatency}ms`} />
        <StatCard label="Errors (24h)" value={metrics.errorCount} />
        <StatCard label="Active Users" value={metrics.activeUsers} />
      </div>
      {/* More content */}
    </div>
  );
}

2. 将标签页添加到标签页列表

const tabs = [
  { id: 'overview', label: 'Overview' },
  { id: 'health', label: 'Production Health' }, // NEW
  { id: 'funnel', label: 'Funnel' },
  // ...
];

3. 添加标签页内容渲染器

function renderTabContent(tabId: string) {
  switch (tabId) {
    case 'overview':
      return <OverviewTab stats={stats} />;
    case 'health':
      return <ProductionHealthTab />; // NEW
    // ...
  }
}

创建管理 API 端点

模式：管理统计端点

// src/app/api/admin/metrics/route.ts
import { requireAdmin } from '@/db/secure-db';
import { createRateLimiter } from '@/lib/rate-limit';
import { logAdminAction } from '@/lib/hipaa/audit';

const rateLimiter = createRateLimiter({
  windowMs: 60000,
  maxRequests: 60,
  keyPrefix: 'admin:metrics'
});

export async function GET(request: Request) {
  // 1. Check admin access
  const admin = await requireAdmin();
  if (!admin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 2. Apply rate limiting
  const rateLimitResult = await rateLimiter.check(admin.id);
  if (!rateLimitResult.allowed) {
    return Response.json(
      { error: 'Rate limit exceeded' },
      { status: 429, headers: rateLimitResult.headers }
    );
  }

  // 3. Log admin action
  await logAdminAction(
    admin.id,
    AuditAction.ADMIN_STATS_VIEW,
    'metrics',
    null
  );

  // 4. Fetch and return data
  const metrics = await getAPIMetrics();
  return Response.json(metrics);
}

关键模式

StatCard 组件

function StatCard({
  label,
  value,
  trend,
  status
}: {
  label: string;
  value: string | number;
  trend?: 'up' | 'down' | 'neutral';
  status?: 'good' | 'warning' | 'error';
}) {
  return (
    <div className="rounded-lg border bg-card p-4">
      <div className="text-sm text-muted-foreground">{label}</div>
      <div className="text-2xl font-bold">{value}</div>
      {trend && <TrendIndicator direction={trend} />}
      {status && <StatusBadge status={status} />}
    </div>
  );
}

数据获取模式

// Use SWR or React Query for real-time updates
import useSWR from 'swr';

function useAdminMetrics() {
  const { data, error, isLoading } = useSWR(
    '/api/admin/metrics',
    fetcher,
    { refreshInterval: 30000 } // Refresh every 30s
  );

  return { metrics: data, error, isLoading };
}

符合 HIPAA 要求的错误显示

// Never show user-specific error details
function ErrorList({ errors }: { errors: AggregatedError[] }) {
  return (
    <div>
      {errors.map(error => (
        <div key={error.hash}>
          <span className="font-mono">{error.type}</span>
          <span>{error.path}</span>
          <span>{error.count} occurrences</span>
          <span>{error.affectedUsers} users</span>
          {/* NO user IDs, NO error messages with PHI */}
        </div>
      ))}
    </div>
  );
}

管理功能的数据库表

现有表：

• adminUsers - 管理员角色分配
• allowedEmails - 邮箱白名单
• accessRequests - 访问申请队列
• auditLog - HIPAA 审计跟踪
• pageViews - 导航分析数据

计划中的表（来自设计方案）：

• api_metrics - API 计时数据
• app_errors - 聚合错误
• service_health - 外部服务状态
• conversation_analytics - AI 聊天元数据
• incidents - 事件跟踪

访问控制

// Always use requireAdmin() for admin routes
import { requireAdmin } from '@/db/secure-db';

// For super-admin only features
const admin = await requireAdmin();
if (admin.role !== 'super_admin') {
  return Response.json({ error: 'Super admin required' }, { status: 403 });
}

测试管理功能

// Mock admin authentication for tests
vi.mock('@/db/secure-db', () => ({
  requireAdmin: vi.fn().mockResolvedValue({
    id: 'test-admin',
    role: 'admin'
  })
}));

describe('Admin Metrics Endpoint', () => {
  it('returns metrics for authenticated admin', async () => {
    const response = await GET(mockRequest);
    expect(response.status).toBe(200);
  });

  it('returns 403 for non-admin', async () => {
    vi.mocked(requireAdmin).mockResolvedValueOnce(null);
    const response = await GET(mockRequest);
    expect(response.status).toBe(403);
  });
});

设计资源

• 完整设计规范：docs/ADMIN-DEVELOPER-SUITE.md
• 设计系统：使用 src/components/ui/ 中的现有组件
• 颜色：遵循疗愈色调（海军蓝、青绿色、珊瑚色、奶油色）