@wooojin/forgen 0.4.7 → 0.4.9

package/assets/dev-guide/be/principles/node.md

@@ -0,0 +1,388 @@
+---
+title: Node.js + TypeScript 원칙
+version: 2026-05-18
+sources:
+  - sources/node-runtime/
+---
+
+# Node.js + TypeScript 원칙
+
+> [공통 원칙](./common.md)을 먼저 따르고, 아래는 Node.js/TypeScript 특화.
+
+## N0. 의사결정 우선순위
+
+1. **비동기는 async/await 일관성** — callback 혼용 금지
+2. **process 안정성** — unhandledRejection / uncaughtException 반드시 처리
+3. **Event Loop 보호** — CPU heavy는 worker_threads로 격리
+4. **입력 경계 강화** — Zod/io-ts 런타임 검증
+5. **TypeScript strict** — 타입 시스템을 안전망으로 최대 활용
+
+---
+
+## N1. async/await 일관성
+
+**callback과 async/await를 혼용하지 마라. async/await로 통일한다.**
+
+### N1.1 기본 규칙
+
+```typescript
+// WRONG: Promise + callback 혼용
+function fetchUser(id: string, callback: (err: Error | null, user?: User) => void) {
+  db.query('SELECT * FROM users WHERE id = ?', [id])
+    .then(result => callback(null, result))
+    .catch(err => callback(err));
+}
+
+// RIGHT: async/await 통일
+async function fetchUser(id: string): Promise<User> {
+  const result = await db.query('SELECT * FROM users WHERE id = ?', [id]);
+  return result;
+}
+```
+
+### N1.2 기존 callback API 래핑
+
+Node.js 레거시 API (`fs.readFile` 등)는 `util.promisify` 또는 `fs/promises` 사용:
+
+```typescript
+import { readFile } from 'node:fs/promises';  // 모던 방식
+// 또는
+import { promisify } from 'node:util';
+import { readFile } from 'node:fs';
+const readFileAsync = promisify(readFile);     // 레거시 래핑
+```
+
+### N1.3 병렬 처리
+
+독립적인 async 작업은 `Promise.all` / `Promise.allSettled`:
+
+```typescript
+// WRONG: 순차 await (불필요한 직렬화)
+const user = await fetchUser(userId);
+const orders = await fetchOrders(userId);
+
+// RIGHT: 병렬 실행
+const [user, orders] = await Promise.all([fetchUser(userId), fetchOrders(userId)]);
+
+// 일부 실패 허용 시
+const results = await Promise.allSettled([fetchUser(userId), fetchOrders(userId)]);
+results.forEach(result => {
+  if (result.status === 'rejected') logger.warn('fetch failed', result.reason);
+});
+```
+
+---
+
+## N2. Top-Level Error Handler
+
+**process 수준 에러를 반드시 처리한다. 처리하지 않으면 서비스가 조용히 죽는다.**
+
+```typescript
+// app.ts — 진입점에서 최우선 등록
+process.on('unhandledRejection', (reason, promise) => {
+  logger.error({ reason, promise }, 'Unhandled Promise Rejection');
+  // graceful exit: 진행 중인 요청 처리 후 종료
+  gracefulShutdown(1);
+});
+
+process.on('uncaughtException', (err, origin) => {
+  logger.fatal({ err, origin }, 'Uncaught Exception — process will exit');
+  // uncaughtException 후 프로세스 상태 보장 불가 → 즉시 종료
+  process.exit(1);
+});
+
+// Graceful shutdown: SIGTERM (Docker/K8s 종료 신호)
+process.on('SIGTERM', () => {
+  logger.info('SIGTERM received, starting graceful shutdown');
+  gracefulShutdown(0);
+});
+
+async function gracefulShutdown(exitCode: number) {
+  // 1. 새 요청 거부 (load balancer 헬스체크 실패 대기)
+  server.close();
+  // 2. 진행 중 요청 완료 대기 (max 30s)
+  await new Promise(resolve => setTimeout(resolve, 30_000));
+  // 3. DB 연결 종료
+  await db.destroy();
+  process.exit(exitCode);
+}
+```
+
+### N2.1 Express/Fastify 에러 핸들러
+
+```typescript
+// Express 에러 핸들러 (4인자 필수)
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  const statusCode = err instanceof AppError ? err.statusCode : 500;
+  logger.error({ err, requestId: req.id, path: req.path }, 'Request error');
+  res.status(statusCode).json({
+    error: {
+      code: err instanceof AppError ? err.code : 'INTERNAL_ERROR',
+      message: statusCode < 500 ? err.message : '서버 오류가 발생했습니다',
+      requestId: req.id,
+    },
+  });
+});
+
+// Fastify는 setErrorHandler 사용
+fastify.setErrorHandler((err, request, reply) => {
+  request.log.error({ err }, 'Request error');
+  reply.status(err.statusCode ?? 500).send({ error: { ... } });
+});
+```
+
+---
+
+## N3. Event Loop 보호
+
+**Node.js는 단일 스레드. CPU heavy 작업이 Event Loop를 막으면 모든 요청이 멈춘다.**
+
+### N3.1 Event Loop 차단 탐지
+
+```typescript
+// 차단 탐지: toobusy-js 또는 clinic.js
+import toobusy from 'toobusy-js';
+app.use((req, res, next) => {
+  if (toobusy()) {
+    res.status(503).json({ error: { code: 'SERVICE_UNAVAILABLE', message: '일시적 과부하' } });
+    return;
+  }
+  next();
+});
+```
+
+### N3.2 CPU Heavy 작업 격리
+
+```typescript
+// worker_threads로 CPU 집약 작업 격리
+import { Worker, workerData, parentPort } from 'node:worker_threads';
+import { resolve } from 'node:path';
+
+function runHeavyTask(input: unknown): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(resolve(__dirname, 'workers/heavy-task.js'), {
+      workerData: input,
+    });
+    worker.on('message', resolve);
+    worker.on('error', reject);
+    worker.on('exit', code => {
+      if (code !== 0) reject(new Error(`Worker exited with code ${code}`));
+    });
+  });
+}
+```
+
+차단 기준: 10ms 이상 동기 CPU 연산 → worker_threads 고려.
+- 이미지 리사이징 (sharp는 내부 libuv 스레드풀 사용 → 괜찮음)
+- 암호화 (crypto 모듈 → 내부 C++ 바인딩, 대부분 OK)
+- JSON 파싱 대용량 (>1MB) → 차단 위험
+- bcrypt 해싱 → 동기 방식 금지, 비동기 사용
+
+### N3.3 setImmediate / process.nextTick 사용 기준
+
+```typescript
+// process.nextTick: 현재 operation 완료 즉시 (I/O 앞)
+// 주의: 무한 루프 가능 → 재귀 호출 금지
+process.nextTick(() => emitter.emit('ready'));
+
+// setImmediate: 현재 I/O 이벤트 사이클 이후
+// 긴 작업을 여러 tick으로 분산할 때
+function processLargeArray(arr: unknown[], callback: () => void, index = 0) {
+  if (index >= arr.length) return callback();
+  processSingleItem(arr[index]);
+  setImmediate(() => processLargeArray(arr, callback, index + 1));
+}
+```
+
+---
+
+## N4. Stream Backpressure 존중
+
+**readable.pipe()는 자동으로 backpressure를 처리한다. 수동 구현 시 반드시 확인.**
+
+```typescript
+// WRONG: backpressure 무시
+readable.on('data', chunk => {
+  writable.write(chunk); // writable buffer가 가득 차도 계속 push
+});
+
+// RIGHT: pipe 사용 (자동 backpressure)
+readable.pipe(writable);
+
+// 또는 stream.pipeline (에러 처리 포함)
+import { pipeline } from 'node:stream/promises';
+await pipeline(
+  fs.createReadStream('large-file.csv'),
+  new TransformStream(), // 변환 단계
+  fs.createWriteStream('output.csv'),
+);
+```
+
+### N4.1 고수량 스트림 패턴
+
+```typescript
+// Readable stream async iterator (Node.js 10+)
+async function processCSV(filePath: string): Promise<void> {
+  const readable = fs.createReadStream(filePath).pipe(csvParser());
+  for await (const row of readable) {
+    await processRow(row); // 처리 완료 후 다음 청크 요청 (backpressure 자연스럽게 적용)
+  }
+}
+```
+
+---
+
+## N5. 입력 경계 검증 (Zod)
+
+**런타임 검증 없는 TypeScript 타입 단언(`as User`)은 안전하지 않다.**
+
+```typescript
+import { z } from 'zod';
+
+// 스키마 정의 — single source of truth
+const CreateOrderSchema = z.object({
+  userId: z.string().uuid(),
+  items: z.array(
+    z.object({
+      productId: z.string().uuid(),
+      quantity: z.number().int().positive(),
+    })
+  ).min(1),
+  couponCode: z.string().optional(),  // 옵셔널 명시 — 검증 로직에서 required 취급 금지
+});
+
+type CreateOrderInput = z.infer<typeof CreateOrderSchema>;
+
+// 핸들러
+async function createOrder(req: Request, res: Response) {
+  const parsed = CreateOrderSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: '입력값이 올바르지 않습니다',
+        details: parsed.error.flatten().fieldErrors,
+      },
+    });
+  }
+  const input: CreateOrderInput = parsed.data;
+  // 이 시점부터 input은 타입 안전
+  await orderService.create(input);
+}
+```
+
+- **옵셔널 필드는 스키마와 비즈니스 로직에서 동일하게 처리**: `.optional()` 이면 값이 없어도 통과.
+- 응답 직렬화도 검증: `z.output` 또는 `.transform()` 으로 응답 필드 선택.
+
+---
+
+## N6. TypeScript Strict 설정
+
+```json
+// tsconfig.json — 최소 설정
+{
+  "compilerOptions": {
+    "strict": true,                        // null 체크, implicit any, 등 통합
+    "noUncheckedIndexedAccess": true,      // arr[0] 타입이 T | undefined (배열 경계 안전)
+    "exactOptionalPropertyTypes": true,    // optional: 값이 undefined일 때 assign 금지
+    "noImplicitReturns": true,             // 모든 분기에서 return 강제
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler",         // ESM + bundler 환경
+    "target": "ES2022",
+    "lib": ["ES2022"]
+  }
+}
+```
+
+### N6.1 타입 단언 규칙
+
+```typescript
+// WRONG: 타입 단언으로 런타임 오류 숨김
+const user = cache.get('user') as User;  // undefined일 수 있음
+
+// RIGHT: 명시적 가드
+const raw = cache.get('user');
+if (!raw) throw new Error('Cache miss: user');
+const user = UserSchema.parse(raw);  // 런타임 검증
+```
+
+- `as T` 단언은 외부 데이터, 레거시 코드와의 경계에서만 허용. 내부 코드에서는 타입 추론 활용.
+- `!` non-null assertion은 null/undefined가 불가능한 이유를 주석으로 설명.
+
+---
+
+## N7. 의존성 트리 관리
+
+근거: `sources/node-runtime/`
+
+### N7.1 의존성 최소화 원칙
+
+- 새 패키지 도입 전 체크리스트:
+  1. 표준 라이브러리(`node:fs`, `node:crypto`)로 해결 가능한가?
+  2. 기존 의존성으로 해결 가능한가?
+  3. 코드 10줄 미만이면 직접 구현하는 것이 낫지 않은가?
+- 번들 크기 영향: `bundlephobia.com` 또는 `npm ls --depth=0` 확인.
+
+### N7.2 보안 감사
+
+```bash
+# 의존성 취약점 감사 (CI에 포함)
+npm audit --audit-level=high
+
+# 의존성 업데이트 (weekly)
+npx npm-check-updates -u && npm install
+
+# supply chain 감사
+npx audit-ci --high
+```
+
+### N7.3 Lock 파일 정책
+
+- `package-lock.json` 또는 `pnpm-lock.yaml` 반드시 커밋.
+- CI에서 `npm ci` (lockfile 기반 설치). `npm install` 금지.
+- 의존성 업데이트는 별도 PR — 기능 PR에 섞지 않는다.
+
+---
+
+## N8. 구조화 로그 (Pino)
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  // 프로덕션: JSON 출력 (stdout)
+  // 개발: pino-pretty로 가독성 향상
+  transport: process.env.NODE_ENV === 'development'
+    ? { target: 'pino-pretty', options: { colorize: true } }
+    : undefined,
+  // 민감 정보 자동 리댁션
+  redact: ['req.headers.authorization', '*.password', '*.cardNumber'],
+  base: {
+    service: process.env.SERVICE_NAME ?? 'unknown',
+    env: process.env.NODE_ENV ?? 'development',
+  },
+});
+
+// Request logger 미들웨어 (Fastify는 내장, Express는 pino-http)
+import pinoHttp from 'pino-http';
+app.use(pinoHttp({ logger }));
+```
+
+---
+
+## N9. Node.js 안티패턴 카탈로그
+
+| 안티패턴 | 픽스 |
+|----------|------|
+| `process.on('unhandledRejection')` 미등록 | 앱 진입점에서 즉시 등록 |
+| 동기 I/O (`fs.readFileSync`) in 핸들러 | `fs/promises` 비동기 버전 |
+| `require()` 루프 내 동적 로딩 | 모듈 수준 캐싱 (require는 캐시됨, import() 동적 주의) |
+| callback + async 혼용 | async/await 통일 |
+| 런타임 검증 없는 `as T` 단언 | Zod safeParse |
+| `npm install` in CI | `npm ci` (lockfile 기반) |
+| 로그에 `req.body` 통째로 기록 | redact 설정 |
+| `bcrypt.hashSync()` | `bcrypt.hash()` (비동기) |
+| `JSON.parse(hugeString)` 동기 | 청크 분할 또는 worker_threads |
+| `tsconfig.strict: false` | strict 활성화 |

package/assets/dev-guide/be/skills/go/be-build/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: be-build-go
+description: Go 요구사항을 받아 합의된 사내 원칙대로 구현. 명세→API contract→구현→테스트 매핑을 강제하고, error-as-value·context 전파·goroutine 안전성을 적용한다.
+---
+
+# be-build (Go)
+
+> **호출 시점**: "이 API 명세대로 Go로 구현해줘", "이 서비스 Go로 만들어줘".
+> **선행 로딩**: `principles/common.md` + `principles/go.md` 필수.
+
+## 0. 절대 금지
+
+1. 명세 읽기 전에 코드 쓰지 마라.
+2. `panic` 을 일반 에러 처리에 사용 금지.
+3. `context.Context` 없는 DB/HTTP 호출 금지.
+4. goroutine 종료 조건 없이 시작 금지.
+5. 에러 무시 (`_ = err`) 금지 — 이유가 있으면 주석 필수.
+6. 인터페이스를 구현 패키지에서 정의 금지 (consumer 측 정의).
+
+## 1. 워크플로우
+
+### Step 1 — 요구사항 → 체크리스트 변환
+
+명세 받자마자, 다른 어떤 작업도 하기 전에:
+
+```markdown
+## 요구사항 체크리스트
+- [ ] R-01: <명세 원문 직접 인용>
+- [ ] R-02: ...
+```
+
+optional/required 구분 명시. optional은 "없어도 통과" 케이스 매핑.
+
+### Step 2 — API Contract 정의
+
+```go
+// types/order.go — 계약 먼저
+type CreateOrderRequest struct {
+    UserID    string      `json:"userId" validate:"required,uuid"`
+    Items     []OrderItem `json:"items"  validate:"required,min=1,dive"`
+    CouponCode *string    `json:"couponCode,omitempty"`  // optional — pointer로 absent 구분
+}
+
+type CreateOrderResponse struct {
+    OrderID   string    `json:"orderId"`
+    Status    string    `json:"status"`
+    CreatedAt time.Time `json:"createdAt"`
+}
+
+type OrderItem struct {
+    ProductID string `json:"productId" validate:"required,uuid"`
+    Quantity  int    `json:"quantity"  validate:"required,min=1"`
+}
+```
+
+### Step 3 — 체크리스트 → 테스트 매핑표
+
+```markdown
+## 매핑표
+| 요구사항 | 함수 | 테스트 파일:케이스 |
+|----------|------|---------------------|
+| R-01 | OrderHandler.Create | order_test.go:TestCreate_Success |
+| R-02 | OrderService.Validate | order_test.go:TestCreate_NoCoupon |
+```
+
+### Step 4 — 패키지 구조 결정
+
+```
+internal/
+├─ handler/    HTTP 핸들러 (입력 검증, 라우팅)
+├─ service/    비즈니스 로직 (인터페이스 정의)
+├─ repository/ DB 접근 (구현)
+└─ domain/     엔티티, 도메인 에러
+```
+
+결정 기록: "service 레이어가 트랜잭션 경계. repository는 순수 쿼리."
+
+### Step 5 — TDD (Red → Green → Refactor)
+
+```bash
+go test ./... -run TestCreate_Success  # 실패 확인
+# 구현
+go test ./... -run TestCreate_Success  # 통과 확인
+go test -race ./...                    # 레이스 컨디션 확인
+```
+
+### Step 6 — 셀프 체크리스트
+
+```markdown
+- [ ] 모든 함수 첫 인자가 context.Context (I/O 함수)
+- [ ] goroutine 시작 시 종료 조건 존재
+- [ ] 에러 래핑 — fmt.Errorf("funcName: %w", err)
+- [ ] 에러 무시 없음
+- [ ] golangci-lint 통과
+- [ ] go test -race 통과
+- [ ] optional 필드 pointer 또는 omitempty 처리
+```
+
+### Step 7 — 완료 선언
+
+매핑표 모든 행 ✅ + 테스트 green + race 없음 + lint 통과.
+
+## 2. 구현 디폴트
+
+### 2.1 HTTP 핸들러 (net/http + chi)
+
+```go
+// handler/order.go
+func (h *OrderHandler) Create(w http.ResponseWriter, r *http.Request) {
+    var req CreateOrderRequest
+    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+        respondError(w, http.StatusBadRequest, "INVALID_JSON", err.Error(), r)
+        return
+    }
+    if err := h.validate.Struct(req); err != nil {
+        respondError(w, http.StatusBadRequest, "VALIDATION_ERROR", err.Error(), r)
+        return
+    }
+
+    order, err := h.svc.CreateOrder(r.Context(), req)
+    if err != nil {
+        switch {
+        case errors.Is(err, domain.ErrUserNotFound):
+            respondError(w, http.StatusNotFound, "USER_NOT_FOUND", err.Error(), r)
+        case errors.Is(err, domain.ErrInsufficientStock):
+            respondError(w, http.StatusUnprocessableEntity, "INSUFFICIENT_STOCK", err.Error(), r)
+        default:
+            slog.ErrorContext(r.Context(), "create order failed", "err", err, "requestId", requestID(r))
+            respondError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "서버 오류가 발생했습니다", r)
+        }
+        return
+    }
+    respondJSON(w, http.StatusCreated, order)
+}
+
+func respondError(w http.ResponseWriter, status int, code, message string, r *http.Request) {
+    respondJSON(w, status, map[string]interface{}{
+        "error": map[string]interface{}{
+            "code":      code,
+            "message":   message,
+            "requestId": requestID(r),
+        },
+    })
+}
+```
+
+### 2.2 서비스 레이어 (인터페이스 + 트랜잭션)
+
+```go
+// service/order.go
+
+// consumer 측 인터페이스 정의
+type orderRepository interface {
+    Create(ctx context.Context, order *domain.Order) error
+    DecrementStock(ctx context.Context, productID string, qty int) error
+}
+
+type OrderService struct {
+    repo orderRepository
+    db   *sql.DB  // 트랜잭션용
+}
+
+func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderRequest) (*domain.Order, error) {
+    // TX: order 생성 + stock 차감 원자적 처리
+    tx, err := s.db.BeginTx(ctx, nil)
+    if err != nil {
+        return nil, fmt.Errorf("CreateOrder begin tx: %w", err)
+    }
+    defer tx.Rollback()  // 성공 시 Commit 후 Rollback은 no-op
+
+    order := &domain.Order{
+        ID:     uuid.New().String(),
+        UserID: req.UserID,
+        Status: "pending",
+    }
+    if err := s.repo.Create(ctx, order); err != nil {
+        return nil, fmt.Errorf("CreateOrder create: %w", err)
+    }
+    for _, item := range req.Items {
+        if err := s.repo.DecrementStock(ctx, item.ProductID, item.Quantity); err != nil {
+            return nil, fmt.Errorf("CreateOrder decrement stock %s: %w", item.ProductID, err)
+        }
+    }
+
+    if err := tx.Commit(); err != nil {
+        return nil, fmt.Errorf("CreateOrder commit: %w", err)
+    }
+    return order, nil
+}
+```
+
+### 2.3 에러 모델
+
+```go
+// domain/errors.go
+var (
+    ErrUserNotFound      = errors.New("user not found")
+    ErrInsufficientStock = errors.New("insufficient stock")
+    ErrOrderNotFound     = errors.New("order not found")
+)
+
+// 상세 정보가 필요한 구조체 에러
+type ValidationError struct {
+    Fields map[string]string
+}
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed: %v", e.Fields)
+}
+```
+
+### 2.4 관찰가능성
+
+```go
+import (
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/attribute"
+    "go.opentelemetry.io/otel/codes"
+    "log/slog"
+)
+
+var tracer = otel.Tracer("order-service")
+
+func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderRequest) (*domain.Order, error) {
+    ctx, span := tracer.Start(ctx, "OrderService.CreateOrder")
+    defer span.End()
+
+    span.SetAttributes(
+        attribute.String("order.userId", req.UserID),
+        attribute.Int("order.itemCount", len(req.Items)),
+    )
+
+    order, err := s.createInternal(ctx, req)
+    if err != nil {
+        span.RecordError(err)
+        span.SetStatus(codes.Error, err.Error())
+        return nil, err
+    }
+    slog.InfoContext(ctx, "order created",
+        slog.String("orderId", order.ID),
+        slog.String("userId", order.UserID),
+    )
+    return order, nil
+}
+```
+
+## 3. 출력 형식
+
+```
+## 완료 보고
+- 체크리스트: N/N ✅
+- 매핑표: 모든 행 테스트 green
+- go test -race: PASS
+- golangci-lint: 0 issues
+- 변경 파일: <목록>
+- 의사결정: <패키지 구조 1-2줄>
+```
+
+## 4. 관련 문서
+
+- 원칙: [`principles/common.md`](../../../principles/common.md), [`principles/go.md`](../../../principles/go.md)
+- 리뷰: [`skills/go/be-review/SKILL.md`](../be-review/SKILL.md)
+- 성능: [`skills/go/be-perf/SKILL.md`](../be-perf/SKILL.md)