管理后台与开发者套件开发

管理后台与开发者套件开发 是做什么的？

此技能帮助您按照既定模式扩展管理后台并构建内部工具。

决策点

何时添加标签 vs 修改端点 vs 创建新工具

添加新的管理功能：
├─ 用户需要只读数据视图？
│  ├─ 数据存在于当前API中？ → 修改现有标签
│  ├─ 需要新数据类型？ → 添加新标签 + 新端点
│  └─ 需要复杂分析？ → 创建专用分析标签
│
├─ 用户需要修改系统数据？
│  ├─ 简单CRUD操作？ → 添加管理标签
│  ├─ 需要批量操作？ → 创建运维控制台标签
│  └─ 多步骤工作流？ → 构建向导组件
│
├─ 内部开发者工具？
│  ├─ 代码检查/文档？ → 添加到 /dev 门户
│  ├─ 系统监控？ → 添加到 /ops 控制台
│  └─ 用户支持工具？ → 添加到管理面板
│
└─ 外部用户功能？
   → 停止：改用前端开发技能

标签内容实现策略

标签复杂度评估：
├─ 简单统计显示（< 5个指标）？
│  → 使用 StatCard 网格模式
│
├─ 带过滤的数据表格？
│  ├─ < 1000行？ → 客户端过滤
│  └─ > 1000行？ → 服务端分页 + 搜索
│
├─ 实时监控？
│  ├─ 每30秒以上更新一次？ → 使用带刷新间隔的 SWR
│  └─ 每5秒更新一次？ → 使用 WebSocket 连接
│
└─ 交互式控件？
   ├─ 简单的切换/按钮？ → 内联操作
   └─ 复杂表单？ → 模态对话框 + 确认流程

故障模式

1. 数据库查询性能下降螺旋

症状： 管理面板超时或加载缓慢（超过5秒） 检测： 监控 /api/admin/* 响应时间超过3秒 修复： 添加数据库索引，实现分页，缓存聚合统计数据

-- 错误：全表扫描
SELECT COUNT(*) FROM pageViews WHERE userId = ?

-- 正确：使用索引时间范围
SELECT COUNT(*) FROM pageViews WHERE createdAt > NOW() - INTERVAL 24 HOUR

2. 缓存过期导致显示错误数据

症状： 管理员看到过时的指标，与最近活动不符 检测： 用户报告在已知操作后统计信息未变化 修复： 在数据变更时实现缓存失效，添加"最后更新时间"时间戳

// 在变更中添加缓存破坏
await updateUserData(userId);
await revalidateTag('admin-stats'); // 清除缓存

3. 缺少审计日志

症状： 管理员操作未记录到 auditLog 表中 检测： 检查过去24小时内管理员操作的 auditLog 条目 修复： 在所有管理端点中添加 logAdminAction() 调用

// 每个管理端点中必须调用
await logAdminAction(admin.id, AuditAction.USER_DATA_VIEW, 'users', userId);

4. HIPAA违规导致数据泄露

症状： 错误消息、日志或聚合视图中出现PHI（受保护健康信息） 检测： 错误中包含用户电子邮件/电话/医疗数据 修复： 清理所有错误响应，在管理视图中使用哈希标识符

// 错误：暴露用户电子邮件
{ error: "用户 [email protected] 未找到" }

// 正确：使用匿名标识符
{ error: "用户ID hash_123abc 未找到" }

5. 管理员权限提升

症状： 普通用户可以访问管理端点 检测： 非管理员用户收到管理数据而非403错误 修复： 在每个管理端点的第一行添加 requireAdmin() 检查

export async function GET(request: Request) {
  const admin = await requireAdmin(); // 必须放在第一行
  if (!admin) return Response.json({ error: 'Forbidden' }, { status: 403 });
  // ... 其余处理程序
}

工作示例

添加生产健康监控标签

场景： 添加实时API健康监控，包含延迟指标、错误率和服务状态。

1. 决策点导航：

• 用户需要实时监控 → 使用带30秒刷新间隔的 SWR
• 系统数据，非用户数据 → 添加到管理面板
• 新数据类型（API指标）→ 创建新标签 + 端点

2. 实现步骤：

使用所需模式创建端点：

// src/app/api/admin/health/route.ts
export async function GET(request: Request) {
  const admin = await requireAdmin(); // 先确保安全
  if (!admin) return Response.json({ error: 'Forbidden' }, { status: 403 });
  
  const rateLimitResult = await rateLimiter.check(admin.id); // 频率限制
  if (!rateLimitResult.allowed) return Response.json({}, { status: 429 });
  
  await logAdminAction(admin.id, 'HEALTH_VIEW', 'metrics', null); // 审计
  
  const metrics = await getHealthMetrics(); // 数据获取
  return Response.json(metrics);
}

创建标签组件：

function ProductionHealthTab() {
  const { data: health, error } = useSWR('/api/admin/health', fetcher, {
    refreshInterval: 30000 // 实时更新
  });
  
  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <StatCard label="API 正常时间" value="99.9%" status="good" />
        <StatCard label="平均延迟" value="45ms" trend="down" />
        <StatCard label="错误率" value="0.1%" status="warning" />
        <StatCard label="活跃服务" value="12/12" status="good" />
      </div>
    </div>
  );
}

3. 专家与新手差异：

• 新手遗漏： 审计日志、频率限制、HIPAA安全的错误处理
• 专家会考虑： 缓存失效策略、性能监控设置、正确的错误边界

质量门禁

• 管理访问控制：requireAdmin() 检查对管理员用户通过，对普通用户失败
• 频率限制：当超出频率限制时端点返回429错误（默认60请求/分钟）
• 审计日志：管理员操作记录到 auditLog 表中，带有正确的操作类型
• 性能基线：在真实数据量下标签加载时间小于2秒
• HIPAA合规：无PHI暴露在错误消息或调试输出中
• 数据验证：无效请求返回正确的400错误及安全消息
• 缓存行为：后台变更后数据在30秒内更新
• 错误边界：UI优雅地处理API失败而不崩溃
• 移动端响应：标签布局在平板尺寸屏幕（768px+）上工作正常
• 实时更新：自动刷新在10分钟以上无内存泄漏

非使用边界

此技能不应用于：

• 外部用户功能 → 使用 frontend-development 技能
• 认证/登录流程 → 使用 auth-security 技能
• 数据库模式变更 → 使用 database-operations 技能
• 电子邮件/通知系统 → 使用 communications 技能
• API频率限制配置 → 使用 backend-api 技能
• HIPAA合规设置 → 使用 security-compliance 技能
• 性能优化 → 使用 optimization 技能

在以下情况下委托给其他技能：

• 添加公共用户功能 → frontend-development
• 修改用户认证 → auth-security
• 创建新的供外部使用的API端点 → backend-api
• 设置监控基础设施 → devops-infrastructure