curiositech/windags-skills

관리자 및 개발자 제품군 개발

이 스킬은 기존 패턴에 따라 관리자 대시보드를 확장하고 내부 도구를 구축하는 데 도움을 줍니다.

의사 결정 지점

탭 추가 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: "User [email protected] not found" }

// 좋음: 익명 식별자 사용
{ error: "User ID hash_123abc not found" }

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-safe 오류 처리
• 전문가가 챙기는 부분: 캐시 무효화 전략, 성능 모니터링 설정, 적절한 오류 경계

품질 게이트

• 관리자 접근 제어: 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