@wooojin/forgen 0.4.8 → 0.4.9

package/assets/dev-guide/be/skills/node/be-perf/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: be-perf-node
+description: Node.js 서비스의 p95/p99 성능 문제를 진단하고 수정. DB N+1, Event Loop 차단, GC 압박, 동기 차단, lock contention, network roundtrip 카테고리별 절차로 접근한다.
+---
+
+# be-perf (Node.js)
+
+> **호출 시점**: "p99가 800ms야 잡아줘", "메모리가 계속 올라가", "DB 쿼리가 느려졌어", "CPU가 치솟아".
+> **선행 로딩**: `principles/common.md` + `principles/node.md` 필수.
+
+## 0. 절대 금지
+
+1. 측정 없이 최적화 추측 금지 — "아마 이게 느릴 것 같아"는 근거 없음.
+2. p50만 보고 OK 선언 금지 — p95/p99 반드시 확인.
+3. 프로파일링 없이 `async/await` → callback 전환 금지 (성능 개선 미미, 가독성 손실 큼).
+
+## 1. 진단 절차
+
+### Step 1 — 현재 지표 수집
+
+먼저 수치를 확인하라. 추측으로 시작하지 마라.
+
+```bash
+# APM 또는 Prometheus 메트릭
+# http_request_duration_seconds{quantile="0.95"} — p95
+# http_request_duration_seconds{quantile="0.99"} — p99
+
+# 로드 테스트로 현재 기준선 측정
+npx autocannon -c 100 -d 30 http://localhost:3000/api/orders
+# Requests/sec, Latency 분포, Errors 확인
+```
+
+### Step 2 — 병목 카테고리 분류
+
+| 증상 | 가능한 카테고리 |
+|------|-----------------|
+| DB 쿼리가 느림 (APM에서 확인) | N+1, 인덱스 누락, 슬로우 쿼리 |
+| CPU 사용률 치솟음 | Event Loop 차단, GC 압박, 동기 연산 |
+| 메모리 지속 증가 | 메모리 누수, GC 부족 |
+| 특정 엔드포인트만 느림 | 해당 경로 분석 (외부 API, 직렬화) |
+| 모든 요청 느림 | Event Loop 차단, 연결 풀 소진 |
+
+### Step 3 — 카테고리별 진단 실행
+
+## 2. 카테고리별 진단 및 픽스
+
+### 2.1 DB N+1
+
+**탐지**: APM에서 단일 요청에 DB 쿼리 N+1개 발생. 로그에서 반복 쿼리 패턴.
+
+```typescript
+// Prisma 탐지: queryRawUnsafe 이벤트 로깅
+prisma.$on('query', (e) => {
+  if (process.env.NODE_ENV === 'development') {
+    logger.debug({ query: e.query, duration: e.duration }, 'DB query');
+  }
+});
+```
+
+**픽스**:
+```typescript
+// WRONG: N+1
+const orders = await prisma.order.findMany();
+for (const order of orders) {
+  order.user = await prisma.user.findUnique({ where: { id: order.userId } });
+}
+
+// RIGHT: include로 JOIN
+const orders = await prisma.order.findMany({
+  include: { user: { select: { id: true, name: true } } },  // 필요한 필드만
+});
+
+// 대용량: DataLoader 패턴
+import DataLoader from 'dataloader';
+const userLoader = new DataLoader<string, User>(async (ids) => {
+  const users = await prisma.user.findMany({ where: { id: { in: [...ids] } } });
+  return ids.map(id => users.find(u => u.id === id) ?? null);
+});
+```
+
+### 2.2 Event Loop 차단
+
+**탐지**: `--inspect` 플래그로 Node.js 프로파일러 실행.
+
+```bash
+node --inspect --prof app.js  # V8 프로파일 생성
+node --prof-process isolate-*.log > profile.txt  # 분석
+```
+
+또는 clinic.js (권장):
+```bash
+npx clinic doctor -- node app.js
+npx clinic flame -- node app.js  # Flamegraph
+```
+
+**픽스**:
+```typescript
+// 동기 블로킹 → 비동기
+// WRONG
+import { readFileSync } from 'node:fs';
+app.get('/config', (req, res) => {
+  const config = readFileSync('config.json', 'utf-8');  // 차단!
+  res.json(JSON.parse(config));
+});
+
+// RIGHT
+import { readFile } from 'node:fs/promises';
+app.get('/config', async (req, res) => {
+  const config = await readFile('config.json', 'utf-8');
+  res.json(JSON.parse(config));
+});
+
+// CPU 집약 작업 → worker_threads
+import { Worker } from 'node:worker_threads';
+function runInWorker(data: unknown): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker('./workers/compute.js', { workerData: data });
+    worker.on('message', resolve);
+    worker.on('error', reject);
+  });
+}
+```
+
+### 2.3 GC 압박 (메모리)
+
+**탐지**:
+```bash
+# heapdump 분석
+node --expose-gc app.js
+# 또는
+npx clinic heapprofiler -- node app.js
+```
+
+```typescript
+// 메모리 사용량 모니터링
+setInterval(() => {
+  const mem = process.memoryUsage();
+  logger.info({
+    heapUsed: Math.round(mem.heapUsed / 1024 / 1024) + 'MB',
+    heapTotal: Math.round(mem.heapTotal / 1024 / 1024) + 'MB',
+    rss: Math.round(mem.rss / 1024 / 1024) + 'MB',
+  }, 'Memory usage');
+}, 30_000);
+```
+
+**흔한 누수 패턴**:
+```typescript
+// WRONG: EventEmitter 리스너 누수
+app.on('request', handler);  // 제거 없음
+
+// RIGHT: 명시적 제거
+const handler = () => { ... };
+app.on('request', handler);
+// ... 정리 시
+app.off('request', handler);
+
+// WRONG: 클로저가 큰 객체 참조
+function processRequest(req: Request) {
+  const hugeBuffer = Buffer.alloc(1024 * 1024 * 100);  // 100MB
+  return async () => {
+    // hugeBuffer가 클로저에 갇혀 GC 불가
+    return hugeBuffer.length;
+  };
+}
+```
+
+### 2.4 외부 API 지연 (Network Roundtrip)
+
+**탐지**: OpenTelemetry span에서 external call duration 확인.
+
+**픽스**:
+```typescript
+// 병렬화 — 독립적인 외부 호출은 동시 실행
+const [user, inventory] = await Promise.all([
+  userApiClient.getUser(userId),
+  inventoryApiClient.getStock(productId),
+]);
+
+// 타임아웃 설정 (기본값 없음에 의존 금지)
+const response = await fetch(url, {
+  signal: AbortSignal.timeout(3000),  // 3초 타임아웃
+});
+
+// 서킷 브레이커 (opossum)
+import CircuitBreaker from 'opossum';
+const breaker = new CircuitBreaker(externalApiCall, {
+  timeout: 3000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30000,
+});
+```
+
+### 2.5 DB 연결 풀 소진
+
+**탐지**: DB 응답 느림 + 연결 대기 큐 증가.
+
+```typescript
+// Prisma 연결 풀 설정
+const prisma = new PrismaClient({
+  datasources: {
+    db: {
+      url: `${DATABASE_URL}?connection_limit=10&pool_timeout=10`,
+    },
+  },
+});
+
+// pg (node-postgres) 연결 풀
+import { Pool } from 'pg';
+const pool = new Pool({
+  max: 10,              // 최대 연결 수
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+// 연결 풀 모니터링
+setInterval(() => {
+  logger.info({
+    total: pool.totalCount,
+    idle: pool.idleCount,
+    waiting: pool.waitingCount,
+  }, 'Connection pool stats');
+}, 10_000);
+```
+
+### 2.6 직렬화 비용 (대용량 JSON)
+
+```typescript
+// WRONG: 대용량 객체 통째로 JSON.stringify
+res.json(await db.findManyWithAllFields());
+
+// RIGHT: 필요한 필드만 선택 (projection)
+const orders = await prisma.order.findMany({
+  select: { id: true, status: true, createdAt: true },  // 필요한 것만
+  take: 20,  // 페이지네이션
+});
+
+// 대용량 응답: 스트리밍
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+app.get('/export', async (req, res) => {
+  res.setHeader('Content-Type', 'application/x-ndjson');
+  const cursor = db.findManyCursor();  // DB 커서
+  await pipeline(cursor, res);
+});
+```
+
+## 3. 출력 형식
+
+```
+## 성능 진단 결과
+
+### 측정 기준선
+- p50: Xms / p95: Xms / p99: Xms
+- 목표 SLO: p95 < Xms (docs/slo.md)
+
+### 발견된 병목
+1. [카테고리] file:line — 설명 (예상 개선: X%)
+2. ...
+
+### 적용한 픽스
+- 변경 파일: <목록>
+- 재측정 결과: p95 Xms → Xms
+
+### 추가 권고 (이번 PR 범위 외)
+- ...
+```
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md) F섹션 (Performance Baseline)
+- 리뷰: [`skills/node/be-review/SKILL.md`](../be-review/SKILL.md)
+- 코퍼스: `sources/node-runtime/`, `sources/postgres/`

package/assets/dev-guide/be/skills/node/be-review/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: be-review-node
+description: Node.js/TypeScript PR을 사내 BE 원칙 기준으로 리뷰. [SEVERITY] file:line — 이슈 형식으로 출력하고, 머지 차단/비차단을 명확히 구분한다.
+---
+
+# be-review (Node.js)
+
+> **호출 시점**: "이 PR 리뷰해줘", "이 코드 리뷰해줘", "OWASP 관점에서 검토해줘".
+> **선행 로딩**: `principles/common.md` + `principles/node.md` 필수.
+
+## 0. 절대 금지
+
+1. 이슈 없이 "좋아 보입니다" 완료 선언 금지 — 모든 체크리스트 항목 확인.
+2. 주관적 스타일 의견을 [HIGH]로 분류 금지.
+3. 자동 수정 가능한 포매팅 이슈를 리뷰에 포함 금지 (eslint --fix 로 처리).
+
+## 1. 리뷰 출력 형식
+
+```
+## 리뷰 요약
+- 변경: N files +X -Y
+- HIGH N, MED N, LOW N / 머지 [차단|비차단]
+
+[HIGH] src/orders/order.controller.ts:42 — SQL 문자열 concat, injection 위험
+[HIGH] src/orders/order.service.ts:88 — 빈 catch 블록, 에러 묵살
+[MED]  src/orders/order.service.ts:120 — optional couponCode를 required 취급 (명세 위반)
+[LOW]  src/orders/types.ts:15 — 매직 넘버 300, 상수 추출 권장
+```
+
+### SEVERITY 기준
+
+| SEVERITY | 정의 | 머지 |
+|----------|------|------|
+| **HIGH** | 보안 취약점, 데이터 손실 가능, 명세 위반, 에러 묵살, 프로세스 불안정 | 차단 |
+| **MED** | 성능 저하(N+1), 관찰가능성 누락, 타입 안전성 위반, 에러 구조 불일치 | 권고 (팀 합의 시 통과) |
+| **LOW** | 가독성, 매직 넘버, 주석, 함수 길이 | 비차단 |
+
+## 2. 체크리스트
+
+### 2.1 보안 (HIGH 기준)
+
+```
+[ ] SQL/NoSQL injection — 문자열 concat 쿼리 없음
+[ ] 인가 검증 — 모든 리소스 접근에 소유권 확인 (OWASP API1)
+[ ] 하드코딩 시크릿 없음 — API key, password, token
+[ ] 입력 검증 — 모든 external input에 Zod/joi 검증
+[ ] 응답에 민감 필드 노출 없음 — password, hash, internal ID (OWASP API3)
+[ ] CORS 설정 — `*` 미사용 (origin allowlist)
+```
+
+### 2.2 에러 모델 (HIGH/MED)
+
+```
+[ ] 빈 catch 블록 없음 — 최소 logger.error + re-throw
+[ ] HTTP 200 + { success: false } 패턴 없음 — 4xx/5xx 적절히 사용
+[ ] 에러 응답 구조 일관성 — { error: { code, message, requestId } }
+[ ] 4xx와 5xx 경계 올바름 — 클라이언트 오류 vs 서버 오류 혼동 없음
+[ ] unhandledRejection 핸들러 존재
+```
+
+### 2.3 Node.js 특화 (MED/HIGH)
+
+```
+[ ] async/await 일관성 — callback 혼용 없음
+[ ] Event Loop 차단 없음 — 동기 I/O (readFileSync 등) 핸들러 내 미사용
+[ ] optional 필드를 required로 취급하지 않음 (명세 일치)
+[ ] TypeScript strict 통과 — any 타입 남용 없음
+[ ] 런타임 검증 — 외부 데이터에 as T 단언 미사용
+[ ] process.exit() 직접 호출 없음 (graceful shutdown 우회)
+```
+
+### 2.4 성능 (MED)
+
+```
+[ ] N+1 쿼리 없음 — 루프 내 DB 쿼리 패턴
+[ ] 트랜잭션 내 외부 API 호출 없음
+[ ] Promise.all — 독립 async 작업 병렬화
+[ ] 인덱스 없는 WHERE 조건 없음 (신규 쿼리)
+```
+
+### 2.5 관찰가능성 (MED)
+
+```
+[ ] 구조화 로그 (JSON) — console.log 미사용
+[ ] 에러 로그에 requestId 포함
+[ ] 중요 비즈니스 이벤트 로그 존재 (주문 생성, 결제 완료 등)
+[ ] 민감 정보 로그 미포함 (password, 카드번호, PII)
+```
+
+### 2.6 코드 품질 (LOW)
+
+```
+[ ] 함수 50줄 이하
+[ ] 중첩 깊이 4 이하 (early return 활용)
+[ ] 매직 넘버 상수화
+[ ] 같은 파일 3+회 수정 시 전체 재설계 검토
+```
+
+## 3. 이슈 카탈로그 (즉시 참조)
+
+| 패턴 | SEVERITY | 설명 |
+|------|----------|------|
+| `db.query("... WHERE id = " + id)` | HIGH | SQL injection |
+| `catch (err) {}` | HIGH | 에러 묵살 |
+| `res.status(200).json({ success: false })` | HIGH | 에러 응답 오용 |
+| `const user = cache.get() as User` | MED | 런타임 검증 없는 단언 |
+| `for (const x of list) { await db.findBy... }` | MED | N+1 쿼리 |
+| `await externalApi()` inside transaction | MED | 트랜잭션 내 외부 호출 |
+| `console.log(req.body)` | MED | 구조화 로그 미사용 + PII 노출 위험 |
+| `if (req.params.userId !== req.user.id)` 누락 | HIGH | OWASP API1 (소유권 검증) |
+| `res.json(await db.findUser(id))` (전체 모델) | MED | OWASP API3 (필드 노출) |
+| `fs.readFileSync(...)` in handler | MED | Event loop 차단 |
+| 함수 > 50줄 | LOW | 책임별 분리 |
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md), [`principles/node.md`](../../../principles/node.md)
+- 보안 체크리스트: [`skills/node/be-security/SKILL.md`](../be-security/SKILL.md)