[P-Reinforce] 2026-04-20: Advanced System Architecture & Debugging Protocols Established

2026-04-20 16:29:58 +09:00
parent 27cd6b1d14
commit 1df45e1e0e
9 changed files with 202 additions and 0 deletions
@@ -0,0 +1,17 @@
+# 🏗️ 시스템 설계 원칙: [프로젝트명] 프로젝트 아키텍처 가이드라인
+
+## 🎯 목표: 관심사의 분리 (Separation of Concerns - SoC)의 극대화
+시스템을 구성하는 각 부분이 독립적으로 작동하며, 서로에게 최소한의 영향만 주도록 구조를 설계해야 합니다.
+
+### 🧩 핵심 레이어 정의
+1.  **Domain Engine Layer (핵심 규칙):**
+    *   **역할:** 게임/시뮬레이션의 모든 물리적 규칙(충돌, 중력, 점수 계산 등)을 담당합니다. **외부 환경에 의존해서는 안 됩니다.**
+    *   **구현 원칙:** 반드시 Web Worker와 같은 별도의 스레드에서 구동하여 메인 UI 스레드의 부하를 분리해야 합니다.
+2.  **State Management Layer (진실의 출처):**
+    *   **역할:** 시스템이 현재 어떤 상태인지(State)에 대한 단 하나의 공식 기록을 유지합니다. 모든 데이터 변경은 오직 이 레이어를 통해서만 이루어져야 합니다.
+    *   **원칙:** **단일 진실 공급원 (Single Source of Truth, SSOT)** 원칙 준수.
+3.  **Presentation Layer (렌더링):**
+    *   **역할:** State Manager가 제공하는 데이터만 받아와서 사용자에게 보여줍니다. 비즈니스 로직은 절대 포함해서는 안 됩니다.
+
+## 🔁 핵심 설계 패턴 적용 지침
+*   **명령어/이벤트 기반 통신:** 컴포넌트 간의 직접적인 호출(Direct Call) 대신, 메시지/이벤트를 통해 느슨하게 결합해야 합니다. (Decoupling).
@@ -0,0 +1,18 @@
+# 📡 시스템 통신 프로토콜 및 상태 전이 관리 매뉴얼 (Protocols & State Flow)
+
+## 📜 1. 표준화된 데이터 교환 규약 (Standardized Message Protocol)
+*   **원칙:** 모든 컴포넌트 간의 메시지는 반드시 다음 JSON 구조를 따라야 합니다.
+    `{ type: 'ACTION_TYPE', payload: { data: value } }`
+*   **필수 정의 예시:**
+    *   `INIT`: 시스템 초기화 요청 및 데이터 교환 시작 신호.
+    *   `KEY_INPUT`: 사용자 입력이 발생했을 때의 키 코드 전송.
+    *   `UPDATE`: 엔진에서 계산 완료 후, 새로운 상태(Board State)를 전달하는 신호.
+
+## 🔄 2. 시스템 생명 주기 (Life Cycle Management)
+시스템은 다음의 명확한 상태 흐름을 거쳐야 합니다:
+1.  **[Initialization]**: 초기 설정 $\rightarrow$ 엔진 시작 요청 (`INIT` 메시지 전송).
+2.  **[Active Loop]**: 입력 감지 및 타이머 기반 루프 실행 (State Update & Redraw Cycle).
+3.  **[Termination]**: 게임 오버, 다음 단계 진입 등 명확한 종료 신호 발생 시 모든 리소스를 정리(Cleanup)해야 합니다.
+
+## 🚨 State Machine 필수 적용
+시스템의 복잡도가 높아질수록 **상태 머신(State Machine)**을 도입하여, 현재 시스템이 어떤 상태에 있는지 (예: `READY`, `RUNNING`, `PAUSED`, `GAME_OVER`)를 명확히 정의하고 제어해야 합니다.
@@ -0,0 +1,18 @@
+# 🐛 개발 프로세스 진단 체크리스트 (Troubleshooting Checklist)
+
+## 🔍 단계별 문제 해결 순서 (The Diagnostic Flowchart)
+
+### Step 1: 환경/파일 시스템 무결성 검증 (L1 - Low Level Check)
+*   **확인 대상:** 브라우저 Console의 빨간색 에러 메시지 (`404 Not Found`, `SyntaxError`).
+*   **진단 목표:** 코드가 아니라, **'실행 가능한 파일 자체가 존재하는가?'**를 확인합니다.
+*   **조치:** 캐시 문제 의심 $\rightarrow$ **강제 새로고침 (Ctrl + F5)** 후, 서버 재시작(`Ctrl + C` 후 `npm start`)을 필수로 수행한다.
+
+### Step 2: 통신 프로토콜 검증 (L2 - Communication Check)
+*   **확인 대상:** `onmessage` 핸들러의 동작 여부.
+*   **진단 목표:** '메시지 A'가 발생했을 때, '예상된 메시지 B'로 변환되는 과정이 정상적인지 확인한다.
+*   **조치:** 로그(`console.log`)를 통해 **데이터 흐름 자체**에 문제가 없는지 추적한다.
+
+### Step 3: 로직 및 시스템 검증 (L3 - High Level Logic Check)
+*   **확인 대상:** 핵심 비즈니스 규칙(충돌 판정, 점수 계산 등).
+*   **진단 목표:** 코드가 논리적으로 완벽한지 확인한다.
+*   **조치:** 가장 단순화된 **최소 실행 예제(Minimum Reproducible Example)**를 만들어 테스트하며 로직을 검증한다.
@@ -0,0 +1,33 @@
+# 🏆 프로젝트 회고 및 개발 프로토콜: 테트리스 게임 (P-Reinforce)
+
+## 📄 개요 및 목표 (Objective & Architecture Goal)
+본 문서는 테트리스 게임을 완성하는 과정에서 발견된 **'실제 작동 가능한 고성능 웹 애플리케이션 아키텍처 설계 원칙'**과 **'개발 디버깅 방법론'**을 기록한 회고록입니다.
+
+*   **최종 목표:** 사용자 입력(키보드)에 즉각적으로 반응하는, 시각적 애니메이션이 포함된 실시간 게임 구현.
+*   **핵심 아키텍처 원칙:** **[Web Worker 기반의 관심사의 분리 (Separation of Concerns)]**. 계산 로직(Engine)과 렌더링/UI 로직(React App)을 완전히 분리하여, 메인 스레드 부하를 최소화하고 성능을 극대화했습니다.
+
+## ⚠️ 발견된 핵심 실패 지점 및 해결 원칙 (Failure & Debugging Protocol)
+이번 프로젝트의 가장 큰 교훈은 '논리가 완벽해도 실행 환경이 무너지면 아무 의미가 없다'는 것입니다. 따라서 다음 디버깅 프로토콜을 모든 프로젝트에 적용해야 합니다.
+
+### 1. [프로토콜 1] 파일 경로/내용물 무결성 검증 (The Integrity Check)
+*   **문제:** `Unexpected token '<'` 에러 발생.
+*   **원인 분석:** Web Worker가 기대하는 것은 순수한 JavaScript 코드여야 하는데, 실제로는 서버의 HTML 에러 페이지(`<html>`)를 받고 실행하려고 시도함. (파일 경로/내용물 불일치).
+*   **해결책:** `public` 폴더에 파일이 **물리적으로 존재하며**, 내용물이 100% 순수 JS 코드여야 함을 원칙화합니다.
+
+### 2. [프로토콜 2] 통신 규약 설계 (The Communication Protocol Design)
+*   **문제:** 메인 스레드(React)와 Worker 간의 상호작용이 체계적이지 못함.
+*   **해결책:** 모든 데이터 교환은 **`postMessage({ type: 'COMMAND', payload: {} })`** 형태의 표준화된 JSON 규약을 따릅니다. (e.g., `INIT`, `KEY_INPUT`, `UPDATE`)
+
+### 3. [프로토콜 3] 개발 환경 재설정 루틴 (The Restart Ritual)
+*   가장 흔한 오류는 '캐싱' 또는 '서버의 미인식'입니다. 다음 절차를 반드시 수행해야 합니다:
+    1.  **Ctrl + C** 로 서버 완전히 종료.
+    2.  `npm start`로 재시작.
+
+## 🎮 최종 성공 아키텍처 요약 (Final Architecture Summary)
+| 컴포넌트 | 역할 | 기술적 구현 원칙 | 담당 파일 |
+| :--- | :--- | :--- | :--- |
+| **GameEngine** | 물리 계산, 규칙 처리, 상태 전이 관리. | Web Worker (`gameWorker.js`) 사용. 메인 스레드와 분리. | `public/gameWorker.js` |
+| **State Manager** | UI 상태의 유일한 진실 공급원 (Single Source of Truth). | React State (`useState`). 워커로부터 받은 데이터만 신뢰함. | `src/App.js` |
+| **Renderer** | 시각적 표현 담당. | Props 기반 렌더링 (`GameBoard.jsx`). 성능 최적화(Virtual DOM)를 고려해야 함. | `src/components/GameBoard.jsx` |
+
+---