curiositech/windags-skills

Admin & Developer Suite 開発

このスキルは、確立されたパターンに従って、管理ダッシュボードを拡張し、内部ツールを構築するのに役立ちます。

決定ポイント

タブ追加 vs エンドポイント修正 vs 新規ツール作成のタイミング

管理機能の追加:
├─ ユーザーが読み取り専用のデータ表示を必要とする場合？
│  ├─ データが現在のAPIに存在する？ → 既存のタブを修正
│  ├─ 新しいデータタイプが必要？ → 新しいタブ + 新しいエンドポイントを追加
│  └─ 複雑な分析が必要？ → 専用の分析タブを作成
│
├─ ユーザーがシステムデータを変更する必要がある場合？
│  ├─ 単純なCRUD操作？ → 管理タブを追加
│  ├─ バルク操作が必要？ → 運用コンソールタブを作成
│  └─ マルチステップのワークフロー？ → ウィザードコンポーネントを構築
│
├─ 内部開発者ツール？
│  ├─ コードインスペクション/ドキュメント？ → /dev ポータルに追加
│  ├─ システム監視？ → /ops コンソールに追加
│  └─ ユーザーサポートツール？ → 管理ダッシュボードに追加
│
└─ 外部ユーザー向け機能？
   → 停止: 代わりに frontend-development スキルを使用

タブコンテンツ実装戦略

タブ複雑性評価:
├─ 単純な統計表示（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 req/min）
• 監査ログ: 管理者アクションが正しいアクションタイプで 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