테트리스 게임 - 문서 인덱스

테트리스 게임 프로젝트의 완전한 아키텍처 및 개발 문서입니다.

📚 문서 구조

1. ARCHITECTURE.md - 시스템 아키텍처 설계

프로젝트의 전체 구조를 이해하고 싶을 때 읽으세요.

주요 내용:

• 전체 시스템 아키텍처 (5계층)
• 핵심 컴포넌트 설명
• 디렉토리 구조
• 데이터 흐름
• 설계 원칙 (SOLID)
• 확장 가능성

누가 읽어야 하나요?

• 프로젝트 리더
• 아키텍처 설계자
• 새로운 팀원

---

2. API.md - API 명세서

각 클래스와 함수의 상세 사용법을 알고 싶을 때 읽으세요.

주요 내용:

• Game, Board, Tetromino, Piece, Collision 클래스 API
• LineClear, Scoring, Gravity, Rotation, Input 시스템 API
• 모델 타입 정의
• 유틸리티 함수
• 사용 예시

누가 읽어야 하나요?

• 개발자 (구현 중)
• API 사용자

---

3. GAME_RULES.md - 게임 규칙 상세

게임의 규칙과 메커니즘을 정확히 이해하고 싶을 때 읽으세요.

주요 내용:

• 기본 게임 규칙
• 게임 보드 구조
• 7가지 테트로미노 블록 상세
• 블록 움직임 및 충돌
• 라인 클리어 메커니즘
• 점수 시스템
• 난이도 시스템
• 고급 규칙 (T-스핀, 벽 킥 등)

누가 읽어야 하나요?

• 게임 개발자
• 게임 디자이너
• QA 테스터

---

4. DEVELOPMENT.md - 개발 가이드

실제로 코드를 작성하고 개발할 때 읽으세요.

주요 내용:

• 개발 환경 설정
• 프로젝트 초기화
• TypeScript 코딩 컨벤션
• 모듈 개발 가이드
• 테스트 작성 방법
• 디버깅 팁
• 성능 최적화
• 배포 가이드

누가 읽어야 하나요?

• 개발자 (모두)
• 테스트 담당자
• DevOps 엔지니어

---

5. PROJECT_STRUCTURE.md - 프로젝트 구조 개요

파일과 폴더의 조직을 빠르게 이해하고 싶을 때 읽으세요.

주요 내용:

• 빠른 참고 (디렉토리 맵)
• 계층별 상세 구조
• 파일별 구현 예시
• 모듈 간 통신
• 테스트 구조
• 빌드 및 배포
• 파일 생성 순서
• 의존성 그래프

누가 읽어야 하나요?

• 신규 개발자 (온보딩)
• 코드 리뷰어
• 프로젝트 매니저

---

6. MVP_SPECIFICATION.md - MVP 기능 명세서

MVP로 구현할 기능과 범위를 정확히 알고 싶을 때 읽으세요.

주요 내용:

• MVP 범위 정의 (포함/제외 기능)
• 10가지 핵심 기능 상세 명세
  • 게임 보드 및 피스
  • 피스 조작
  • 게임 로직
  • 점수 시스템
  • 난이도 시스템
  • 게임 상태 관리
  • UI/렌더링
  • 입력 처리
  • 게임 루프
  • 기본 컨트롤
• 성능 요구사항
• 구현 체크리스트
• 개발 일정
• 승인 기준

누가 읽어야 하나요?

• 프로젝트 관리자
• 제품 담당자
• 개발팀 리더
• 테스트 엔지니어

---

🎯 상황별 추천 읽기 순서

MVP 기능 이해

1. MVP_SPECIFICATION.md (MVP 범위 및 기능 이해)
2. GAME_RULES.md (게임 규칙 상세)
3. API.md (API 명세)

신규 개발자 온보딩

1. PROJECT_STRUCTURE.md (프로젝트 이해)
2. MVP_SPECIFICATION.md (MVP 범위 이해)
3. ARCHITECTURE.md (전체 구조 이해)
4. GAME_RULES.md (게임 규칙 이해)
5. DEVELOPMENT.md (개발 환경 설정)
6. API.md (API 참고하며 개발)

기능 개발

1. MVP_SPECIFICATION.md (해당 기능이 MVP에 포함되는지 확인)
2. GAME_RULES.md (구현할 기능의 규칙 확인)
3. API.md (관련 API 확인)
4. DEVELOPMENT.md (테스트 작성 가이드)

버그 수정

1. MVP_SPECIFICATION.md (버그가 있는 기능 확인)
2. ARCHITECTURE.md (영향 범위 확인)
3. API.md (클래스 동작 확인)
4. DEVELOPMENT.md (디버깅 팁)

성능 최적화

1. MVP_SPECIFICATION.md (성능 요구사항 확인)
2. ARCHITECTURE.md (병목 지점 파악)
3. DEVELOPMENT.md (최적화 기법)

배포 준비

1. MVP_SPECIFICATION.md (MVP 승인 기준 확인)
2. DEVELOPMENT.md (배포 가이드)
3. 모든 문서 검토 (문서 최신화)

---

📋 빠른 참고

핵심 클래스 위치

src/core/game.ts          ← 게임 메인 클래스
src/core/board.ts         ← 게임 보드
src/core/tetromino.ts     ← 블록 정의
src/core/piece.ts         ← 떨어지는 블록
src/core/collision.ts     ← 충돌 감지

주요 시스템 위치

src/systems/line-clear.ts    ← 라인 클리어
src/systems/scoring.ts       ← 점수 계산
src/systems/gravity.ts       ← 자동 하강
src/systems/rotation.ts      ← 회전 시스템
src/systems/input.ts         ← 입력 처리

타입 정의 위치

src/models/types.ts           ← 기본 타입
src/models/game-state.ts      ← 게임 상태
src/models/tetromino-data.ts  ← 블록 데이터

---

🔄 계층 구조

┌─────────────────────────────────┐
│     UI Layer (화면/입력)        │
├─────────────────────────────────┤
│   Game Control (게임 제어)      │
├─────────────────────────────────┤
│   Core Logic (핵심 게임 로직)    │
│ (Board, Tetromino, Piece, etc)  │
├─────────────────────────────────┤
│   Systems (게임 시스템)         │
│ (Score, Gravity, LineCllear)    │
├─────────────────────────────────┤
│   Models (데이터 모델)          │
├─────────────────────────────────┤
│   Utils (유틸리티/상수)         │
└─────────────────────────────────┘

---

✅ 문서 사용 팁

효율적인 학습

1. 전체 그림 먼저: ARCHITECTURE.md로 전체 구조 이해
2. 상세 파고들기: 관심 영역의 상세 문서 읽기
3. 구현하며 참고: API.md를 참고하며 코드 작성
4. 문제 해결: DEVELOPMENT.md의 문제 해결 섹션

검색 팁

• Ctrl+F (또는 Cmd+F)로 키워드 검색
• "게임 오버", "라인 클리어", "점수 계산" 등 검색
• 각 문서의 목차를 활용한 빠른 네비게이션

코드와 함께 읽기

• API.md의 코드 예시를 실제 구현과 비교
• DEVELOPMENT.md의 패턴을 프로젝트에 적용
• ARCHITECTURE.md의 구조를 실제 파일 구조와 매칭

---

📊 문서 커버리지

주제	문서	커버리지
MVP 기능 명세	MVP_SPECIFICATION.md	100%
게임 규칙	GAME_RULES.md	100%
아키텍처	ARCHITECTURE.md	100%
API 명세	API.md	100%
개발 프로세스	DEVELOPMENT.md	100%
프로젝트 구조	PROJECT_STRUCTURE.md	100%
성능 요구사항	MVP_SPECIFICATION.md	100%
성능 최적화	DEVELOPMENT.md	80%
배포	DEVELOPMENT.md	90%

---

🚀 시작하기

1단계: 문서 읽기

# PROJECT_STRUCTURE.md부터 시작
cat docs/PROJECT_STRUCTURE.md

2단계: 환경 설정

npm install
npm run build
npm test

3단계: 게임 실행

npm run dev
# http://localhost:8080 접속

4단계: 코드 탐색

• src/ 디렉토리 구조 확인
• src/core/game.ts 읽기
• 테스트 파일로 동작 이해

---

📌 중요 개념

불변성 (Immutability)

Board와 Piece는 상태를 직접 변경하지 않습니다. 대신 새로운 인스턴스를 반환합니다.

// ✓ 옳은 방식
const newBoard = board.placePiece(piece)

// ✗ 잘못된 방식
board.placePiece(piece)  // 새 인스턴스 반환 안 함

단방향 의존성

상위 계층이 하위 계층에만 의존합니다.

Game (상위)
  ↓
Core (중간)
  ↓
Models (하위)

Models는 Core에 의존하지 않음

테스트 가능성

각 모듈을 독립적으로 테스트할 수 있습니다.

// Board를 Game 없이 테스트 가능
const board = new Board(10, 20)
expect(board.isEmpty()).toBe(true)

---

🔗 관련 링크

내부 링크

• 프로젝트 루트
• 소스 코드
• 테스트 코드

외부 참고

• 클래식 테트리스 규칙
• TypeScript 공식 문서
• Jest 공식 문서

---

❓ FAQ

Q: 어느 문서부터 읽어야 하나요?

A: 신규 개발자라면 PROJECT_STRUCTURE.md부터 시작하세요.

Q: 게임 규칙을 정확히 알고 싶어요.

A: GAME_RULES.md가 가장 상세합니다.

Q: API 사용법을 알고 싶어요.

A: API.md의 해당 클래스 섹션을 읽으세요.

Q: 새 기능을 추가하려면?

A: DEVELOPMENT.md의 "모듈 개발 가이드" 섹션을 따르세요.

Q: 버그를 찾았어요.

A: DEVELOPMENT.md의 "디버깅 팁" 섹션을 참고하세요.

---

📝 문서 유지보수

문서 업데이트 규칙

1. 새 기능 추가 시 관련 문서 업데이트
2. API 변경 시 API.md 동시 수정
3. 아키텍처 변경 시 ARCHITECTURE.md 업데이트
4. 버그 패턴 발견 시 DEVELOPMENT.md에 추가

문서 버전

• 최종 업데이트: 2024년
• 현재 버전: 1.0

---

이 문서를 통해 테트리스 게임 프로젝트를 완전히 이해하고 개발할 수 있습니다.

Happy Coding! 🎮