# 1단계: 프로젝트 구조 파악
ls -la
# .gitignore, package.json, pom.xml 등으로 기술 스택 추측

# 2단계: README 확인
cat README.md
# "TODO: Add readme" (2018년에 쓴 마지막 커밋)

# 3단계: 어떻게 실행하는지 모름
npm start  # 에러
npm run dev  # 에러
# 의존성 설치가 안 됨
# Node.js 버전이 안 맞음
# 환경 변수가 없음
# DB가 필요한데 설정이 없음

# 4단계: git log 확인
git log --oneline -20
# fix
# fix
# hotfix
# asdf
# WIP
# temp
# ㅋㅋ
# 금요일 퇴근
# .
# update

# 특정 파일의 각 줄을 누가 마지막으로 수정했는지 확인
git blame src/services/payment.ts

# 결과 예시:
# a3b4c5d (김개발 2023-03-15) function processPayment(order) {
# a3b4c5d (김개발 2023-03-15)   if (order.amount <= 0) {
# f1e2d3c (이시니어 2023-06-01)     throw new Error('금액 오류');
# a3b4c5d (김개발 2023-03-15)   }
# 7a8b9c0 (박인턴 2023-09-20)   // 임시 주석: 왜인지 모르겠는데
# 7a8b9c0 (박인턴 2023-09-20)   // 이거 빼면 에러남
# 7a8b9c0 (박인턴 2023-09-20)   order.amount = Math.floor(order.amount);

# 특정 커밋의 상세 내용 확인
git show f1e2d3c
# commit f1e2d3c
# Author: 이시니어
# Date: 2023-06-01
# Message: fix
# (... 이게 끝임. 왜 수정했는지 모름)

# 특정 파일의 변경 이력
git log --follow -p -- src/services/payment.ts

# 특정 기간의 변경 사항
git log --after="2023-06-01" --before="2023-07-01" --oneline

# 특정 함수가 언제 추가/수정됐는지
git log -p -S "processPayment" --all

# 누가 가장 많이 커밋했는지 (핵심 기여자 파악)
git shortlog -sn --no-merges

# 가장 자주 수정되는 파일 (핫스팟 = 문제의 근원)
git log --format=format: --name-only | sort | uniq -c | sort -rn | head -20
# 자주 수정되는 파일 = 버그가 많거나 설계가 잘못된 파일

# 디렉토리 구조로 아키텍처 추론
tree -d -L 3
# src/
#   controllers/    → MVC 패턴의 Controller
#   models/         → 데이터 모델
#   services/       → 비즈니스 로직
#   repositories/   → DB 접근
#   middlewares/     → 미들웨어
#   utils/          → 유틸리티
#   config/         → 설정
#   routes/         → 라우팅

# 엔트리 포인트 찾기
# package.json의 "main" 또는 "scripts.start" 확인
# app.ts, index.ts, server.ts, main.ts 등

# 의존성 분석
cat package.json | jq '.dependencies'
# express → REST API 서버
# sequelize → ORM (DB 접근)
# jsonwebtoken → JWT 인증
# redis → 캐싱
# bull → 작업 큐

// 테스트 코드가 있다면 이것이 최고의 문서임
// "이 함수가 어떻게 동작해야 하는지"를 정확히 알려줌

describe('PaymentService', () => {
  describe('processPayment', () => {
    it('정상 결제 시 영수증을 반환해야 함', async () => {
      const order = {
        id: 'ORD-001',
        amount: 50000,
        method: 'card',
      };

      const receipt = await paymentService.processPayment(order);

      expect(receipt.status).toBe('completed');
      expect(receipt.transactionId).toBeDefined();
    });

    it('금액이 0 이하면 에러를 던져야 함', async () => {
      const order = { id: 'ORD-002', amount: -1000 };

      await expect(
        paymentService.processPayment(order)
      ).rejects.toThrow('금액 오류');
    });

    it('재고 부족 시 결제를 거부해야 함', async () => {
      // 이 테스트를 통해 결제와 재고 관리가 연결되어 있음을 알 수 있음
      mockInventory.setStock('PROD-001', 0);

      await expect(
        paymentService.processPayment(outOfStockOrder)
      ).rejects.toThrow('재고 부족');
    });
  });
});

-- 테이블 구조를 보면 비즈니스 도메인이 보임
SHOW TABLES;

-- users, orders, products, payments, coupons,
-- shipping_addresses, reviews, cart_items...
-- → 이커머스 시스템이구나

-- 테이블 관계 파악
DESCRIBE orders;
-- id, user_id, total_amount, status, coupon_id,
-- shipping_address_id, created_at, updated_at

-- status 컬럼의 가능한 값 확인
SELECT DISTINCT status FROM orders;
-- pending, paid, preparing, shipping, delivered,
-- cancelled, refunded
-- → 주문 상태 머신이 있음

-- 외래 키 관계 확인
SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME
FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_NAME IS NOT NULL;

# Express 라우트 찾기
grep -rn "router\.\(get\|post\|put\|delete\|patch\)" src/routes/

# 결과에서 API 맵 만들기:
# GET    /api/users           → 사용자 목록
# POST   /api/users           → 사용자 생성
# GET    /api/users/:id       → 사용자 상세
# GET    /api/orders           → 주문 목록
# POST   /api/orders           → 주문 생성
# PUT    /api/orders/:id/status → 주문 상태 변경
# POST   /api/payments         → 결제 처리
# POST   /api/payments/refund  → 환불 처리

# .env.example 또는 코드에서 환경 변수 찾기
grep -rn "process\.env\." src/

# 결과 분석:
# DB_HOST, DB_PORT       → 데이터베이스
# REDIS_URL              → Redis 캐시/세션
# AWS_S3_BUCKET          → S3 파일 저장소
# SMTP_HOST              → 이메일 발송
# SLACK_WEBHOOK          → Slack 알림
# PG_API_KEY             → PG사 결제 연동
# GOOGLE_CLIENT_ID       → 구글 소셜 로그인
# SENTRY_DSN             → 에러 모니터링

// 가격을 계산한다
function calculateDiscount(user: User, items: CartItem[]) {
  // ↑ 함수명은 할인 계산인데 주석은 가격 계산이라고 함
  // 누군가 함수를 리팩토링하면서 주석을 안 바꿨음

  // 할인율은 10%이다
  const discountRate = 0.15;
  // ↑ 주석은 10%인데 실제 코드는 15%
  // 어느 게 맞는 거임?

  // 아래 코드는 사용하지 않음 (2022-03-15 김개발)
  // 하지만 삭제하면 안 됨
  if (user.level === 'VIP') {
    // VIP 할인 추가
    return items.reduce((sum, item) =>
      sum + item.price * 0.2, 0
    );
  }
  // ↑ "사용하지 않음"이라면서 실제로는 VIP 유저일 때 실행됨
  // 주석이 거짓말하고 있음

  return items.reduce((sum, item) =>
    sum + item.price * discountRate, 0
  );
}

// TODO: 나중에 리팩토링 (2019-05-10)
// TODO: 성능 개선 필요 (2020-01-15)
// TODO: 이 부분 보안 취약점 있음 (2020-06-30)
// FIXME: 동시성 문제 있음, 빨리 고쳐야 함 (2021-03-01)
// HACK: 임시 해결. 제대로 된 솔루션 필요 (2021-08-15)
// XXX: 왜 이렇게 동작하는지 모르겠음 (2022-01-20)
// TODO: 위의 모든 TODO를 해결한다 (2022-06-01)
// ... (2024년 현재, 아무것도 해결되지 않음)

function processOrder(order: Order) {
  // HACK: 특정 고객사에서 주문 금액이 음수로 들어오는 버그
  // 원인을 못 찾아서 일단 절대값으로 처리
  // 2021-04-10 박인턴
  order.amount = Math.abs(order.amount);

  // TODO: 왜 여기서 setTimeout을 쓰는지 모르겠음
  // 빼면 결제가 안 됨
  // 2020-12-01 김개발 (퇴사)
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(submitPayment(order));
    }, 100);
  });
}

function calculateShipping(weight: number, distance: number) {
  if (weight <= 3) {
    return 3000;  // 3kg 이하? 3000원?
  } else if (weight <= 10) {
    return 5000;  // 10kg 이하? 5000원?
  } else if (weight <= 30) {
    return 8000;  // 왜 이 금액인지 아무도 모름
  }

  // 거리 기반 추가 요금
  if (distance > 100) {
    return 15000;  // 100km? 100miles?
  } else if (distance > 50) {
    return 12000;
  }

  // 이 37.5는 뭐임?
  const surcharge = weight * 37.5;
  return Math.ceil(surcharge / 100) * 100;  // 100원 단위 올림?
}

# 1. 기술 스택 확인
cat package.json  # Node.js
cat pom.xml       # Java/Maven
cat requirements.txt  # Python

# 2. 의존성 설치
npm install  # 에러 나면 Node.js 버전 확인

# 3. 환경 변수 설정
# .env.example이 없으면 코드에서 찾기
grep -rn "process.env" src/ | sort -u

# 4. DB 스키마 확인
# migration 파일이 있으면 실행
# 없으면 SQL 덤프 파일 찾기

# 5. 실행
npm run dev
# 에러 메시지를 하나씩 해결

// 가장 중요한 비즈니스 흐름을 추적
// 이커머스라면: 회원가입 → 상품 조회 → 장바구니 → 결제

// 엔트리 포인트에서 시작
// POST /api/orders 요청이 들어오면 어떤 코드가 실행되는지
// 라우터 → 미들웨어 → 컨트롤러 → 서비스 → 리포지토리 순으로 추적

// 각 단계에서 console.log를 넣어서 실행 흐름 확인
console.log('=== OrderController.create 진입 ===');
console.log('요청 데이터:', JSON.stringify(req.body, null, 2));

시스템 지도 (직접 만들어야 함):

[클라이언트]
    |
    v
[Nginx] → 정적 파일 서빙
    |
    v
[Express 서버]
    ├── /api/auth/*     → AuthService → users 테이블
    ├── /api/products/* → ProductService → products 테이블
    ├── /api/orders/*   → OrderService
    │                      ├── products 테이블 (재고 확인)
    │                      ├── orders 테이블
    │                      ├── PaymentGateway (외부 PG)
    │                      └── NotificationService
    │                           ├── 이메일 (SMTP)
    │                           └── Slack (Webhook)
    └── /api/admin/*    → AdminService → 관리자 기능

외부 의존성:
- PostgreSQL (메인 DB)
- Redis (세션 + 캐시)
- AWS S3 (이미지 저장)
- 토스페이먼츠 (결제)
- SendGrid (이메일)

function processRefund(order: Order, reason: string) {
  // 이 if문들이 비즈니스 규칙임
  if (order.status !== 'delivered') {
    // 규칙 1: 배송 완료 상태에서만 환불 가능
    throw new Error('배송 완료 후에만 환불 가능');
  }

  const daysSinceDelivery = getDaysSince(order.deliveredAt);

  if (daysSinceDelivery > 7) {
    // 규칙 2: 배송 후 7일 이내만 환불 가능
    throw new Error('환불 기간 초과');
  }

  if (order.items.some(item => item.category === 'food')) {
    // 규칙 3: 식품은 환불 불가
    throw new Error('식품류는 환불 불가');
  }

  if (order.usedCoupon && order.items.length === 1) {
    // 규칙 4: 쿠폰 사용 주문의 마지막 상품은
    // 환불 시 쿠폰도 함께 회수
    revokeCoupon(order.couponId);
  }

  // 규칙 5: 부분 환불 시 배송비는 환불 안 됨
  const refundAmount = order.totalAmount - order.shippingFee;

  return createRefund(order.id, refundAmount, reason);
}

// catch 블록, 에러 핸들러, 유효성 검사에 숨겨진 비즈니스 규칙

function createOrder(cart: Cart, user: User) {
  // 유효성 검사 = 비즈니스 규칙
  if (cart.items.length === 0) {
    throw new Error('장바구니가 비어있습니다');
  }

  if (cart.totalAmount < 10000) {
    // 비즈니스 규칙: 최소 주문 금액 10,000원
    throw new Error('최소 주문 금액은 10,000원입니다');
  }

  if (user.point < cart.usedPoint) {
    // 비즈니스 규칙: 사용 포인트 > 보유 포인트 불가
    throw new Error('포인트가 부족합니다');
  }

  const maxItems = user.level === 'VIP' ? 50 : 20;
  if (cart.items.length > maxItems) {
    // 비즈니스 규칙: VIP는 50개, 일반은 20개까지
    throw new Error(`최대 ${maxItems}개까지 주문 가능합니다`);
  }

  // 재고 체크
  for (const item of cart.items) {
    const stock = getStock(item.productId);
    if (stock < item.quantity) {
      // 비즈니스 규칙: 재고 부족 시 주문 불가
      throw new Error(`${item.name} 재고 부족`);
    }
  }

  // ... 주문 생성 로직
}

# ADR-001: 결제 시스템을 토스페이먼츠로 변경

## 상태: 승인됨

## 맥락
- 기존 PG사(이니시스)의 API가 불안정하고 문서가 부실함
- 토스페이먼츠가 개발자 친화적인 API를 제공함
- 수수료 차이: 이니시스 3.3% vs 토스페이먼츠 3.0%

## 결정
- 신규 결제는 토스페이먼츠로 처리
- 기존 정기결제는 이니시스 유지 (마이그레이션 비용 높음)
- 3개월간 양쪽 병행 후 이니시스 완전 종료

## 결과
- 결제 실패율 5% → 1.2%로 개선
- 개발 시간 40% 단축 (API 문서 품질 차이)

// BAD: 코드가 하는 일을 반복하는 주석
// i를 1 증가시킨다
i++;

// BAD: 의미 없는 주석
// 생성자
constructor() {}

// GOOD: "왜"를 설명하는 주석
// 토스페이먼츠 API는 금액을 정수로만 받아서
// 소수점 이하를 버림 (반올림하면 금액 불일치 발생)
const amount = Math.floor(order.totalAmount);

// GOOD: 비즈니스 규칙을 설명하는 주석
// 정책: VIP 고객은 주문 취소 시 수수료 면제
// (2023-06-01 마케팅팀 요청, JIRA-1234)
if (user.level === 'VIP') {
  cancellationFee = 0;
}

// GOOD: 비직관적인 코드의 이유를 설명
// setTimeout이 없으면 PG사 응답이 누락되는 경우가 있음
// PG사 측에서 최소 100ms 딜레이를 권장 (2023-03-15 기술지원 답변)
await new Promise(resolve => setTimeout(resolve, 100));

# 프로젝트 온보딩 가이드

## 1. 환경 설정
- Node.js v20 이상
- PostgreSQL 15
- Redis 7

## 2. 실행 방법
npm install
cp .env.example .env  # 환경 변수 설정
npm run db:migrate     # DB 마이그레이션
npm run db:seed        # 테스트 데이터
npm run dev            # 개발 서버

## 3. 핵심 아키텍처
[간단한 다이어그램]

## 4. 주요 비즈니스 규칙
- 최소 주문 금액: 10,000원
- 환불 기한: 배송 후 7일
- VIP 할인율: 15%
- 식품류 환불 불가

## 5. 알려진 기술 부채
- PaymentService 리팩토링 필요
- 테스트 커버리지 30% (목표 70%)
- API 응답 형식 통일 필요

## 6. 핵심 연락처
- 결제 관련: 토스페이먼츠 기술지원 (xxx-xxxx)
- 인프라: DevOps팀 (Slack #infra)