[P-Reinforce] 2026-04-20: Advanced System Architecture & Debugging Protocols Established
This commit is contained in:
@@ -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` |
|
||||
|
||||
---
|
||||
+4
@@ -178,6 +178,10 @@
|
||||
},
|
||||
"active": "5e19c94f304a33d1",
|
||||
"lastOpenFiles": [
|
||||
"Tetris_Project_Retrospective.md",
|
||||
"System_Debugging_Protocol.md",
|
||||
"System_Protocol_Standard.md",
|
||||
"Project_Architecture_Guidelines.md",
|
||||
"Systemic_Simulation_Principles.md",
|
||||
"DevOps_Environment_Setup.md",
|
||||
"Separation_of_Concerns.md",
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: 시스템 설계 가이드라인 (Separation of Concerns)
|
||||
category: Software Architecture
|
||||
tags: [Architecture, SoC, Modular Design, Layered Architecture]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 시스템 설계 가이드라인 (아키텍처 레이어링)
|
||||
|
||||
## 🎯 핵심 목표
|
||||
시스템의 각 부분이 독립적으로 작동하며 서로에게 최소한의 영향만 주도록 하는 **관심사의 분리(SoC)**를 극대화합니다.
|
||||
|
||||
## 🧱 핵심 레이어 (The Three Pillars)
|
||||
1. **Domain Engine (핵심 규칙)**:
|
||||
* 물리 법칙, 비즈니스 로직 담당.
|
||||
* 원칙: **외부 환경 비의존성**. Web Worker 등을 통한 스레드 독립성 확보.
|
||||
2. **State Management (진실의 출처)**:
|
||||
* **단일 진실 공급원(SSOT)** 패턴 준수.
|
||||
* 원칙: 모든 데이터 변경은 오직 이 레이어를 통해서만 발생함.
|
||||
3. **Presentation Layer (렌더링)**:
|
||||
* 데이터 가시화 담당.
|
||||
* 원칙: 비즈니스 로직 포함 금지. 순수하게 받은 데이터만 표현.
|
||||
|
||||
## 🔁 통신 지침
|
||||
- **Decoupling**: 컴포넌트 간 직접 호출 대신 메시지/이벤트 기반 통신 지향.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[System_Protocol_Standard]]
|
||||
- [[WebWorker_Performance]]
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: 단계별 시스템 디버깅 체크리스트 (L1~L3)
|
||||
category: Software Architecture
|
||||
tags: [Debugging, Troubleshooting, Checklist, Process]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 단계별 시스템 디버깅 체크리스트 (The Diagnostic Flowchart)
|
||||
|
||||
## 🔍 L1: 환경 및 무결성 검증 (Low Level)
|
||||
- **대상**: 404 Error, Syntax Error, 파일 경로.
|
||||
- **목표**: **'실행 가능한 물리적 토대'**가 마련되어 있는가?
|
||||
- **필수 조치**: 강제 새로고침(Ctrl + F5), 서버 재시작(Restart Ritual).
|
||||
|
||||
## 🔍 L2: 통신 및 데이터 흐름 검증 (Communication)
|
||||
- **대상**: `onmessage`, `postMessage`, 비동기 처리.
|
||||
- **목표**: 메시지가 의도한 대로 흐르고 있는가?
|
||||
- **필수 조치**: 데이터 흐름 추적(`console.log`), 핸들러 동작 유무 확인.
|
||||
|
||||
## 🔍 L3: 논리 엔진 및 비즈니스 검증 (High Level)
|
||||
- **대상**: 비즈니스 로직, 수학적 공식, 물리 엔진.
|
||||
- **목표**: 코드가 논리적으로 무결한가?
|
||||
- **필수 조치**: 최소 실행 예제(MRE)를 통한 격리 테스트.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[Tetris_Project_Retrospective]]
|
||||
- [[DevOps_Environment_Setup]]
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 표준 시스템 통신 프로토콜 및 상태 제어
|
||||
category: Software Architecture
|
||||
tags: [Protocol, State Machine, Data Exchange, Lifecycle]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 표준 시스템 통신 프로토콜 및 상태 제어
|
||||
|
||||
## 📡 데이터 교환 규약 (Standard Protocol)
|
||||
모든 컴포넌트 간 통신은 예측 가능한 형태를 유지해야 합니다.
|
||||
- **포맷**: `{ type: 'ACTION_TYPE', payload: { data: value } }`
|
||||
- **주요 액션 타입**:
|
||||
- `INIT`: 시스템 초기화 및 동기화 시작.
|
||||
- `KEY_INPUT`: 사용자 인터랙션 데이터 전송.
|
||||
- `UPDATE`: 엔진 계산 결과의 브로드캐스트.
|
||||
|
||||
## 🔄 시스템 생명 주기 (Life Cycle)
|
||||
시스템은 [초기화 $\rightarrow$ 활성 루프 $\rightarrow$ 종료/정리]의 명확한 단계를 거쳐야 리소스 누수(Memory Leak)를 방지할 수 있습니다.
|
||||
|
||||
## 🚨 상태 머신 (State Machine) 도입
|
||||
시스템 복잡도가 임계치를 넘을 경우, `READY`, `RUNNING`, `PAUSED` 등 상태를 명시적으로 제어하는 **State Machine** 적용을 원칙으로 삼습니다.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[Project_Architecture_Guidelines]]
|
||||
- [[Single_Source_of_Truth]]
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: 프로젝트 회고: 고성능 테트리스 아키텍처
|
||||
category: Projects
|
||||
tags: [Retrospective, Tetris, Architecture, Performance]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 프로젝트 회고: 고성능 테트리스 아키텍처 (P-Reinforce)
|
||||
|
||||
## 🌊 프로젝트 아키텍처 요약
|
||||
본 프로젝트는 **Web Worker**를 활용한 완전한 연산-렌더링 분리를 실현하여, 실시간 게임 환경에서 극강의 부드러움을 확보하는 데 성공했습니다.
|
||||
|
||||
### 🧩 컴포넌트별 기술적 역할
|
||||
- **Game Engine**: 물리 계산 및 상태 전이 (`public/gameWorker.js`).
|
||||
- **State Manager**: UI의 유일한 진실 공급원 (`src/App.js`).
|
||||
- **Renderer**: Props 기반의 순수 매핑 렌더러 (`src/components/GameBoard.jsx`).
|
||||
|
||||
## ⚠️ 핵심 교훈 (Lessons Learned)
|
||||
> [!IMPORTANT]
|
||||
> **"논리가 완벽해도 실행 환경이 무너지면 아무 의미가 없다."**
|
||||
> 아키텍처 설계만큼이나 '파일 무결성 검증'과 '환경 재설정 루틴'이 개발 생산성에 지대한 영향을 미친다는 것을 확인했습니다.
|
||||
|
||||
## 🏆 성과
|
||||
- [x] Web Worker 기반 비동기 엔진 구축 완료.
|
||||
- [x] 표준 통신 프로토콜 기반의 Decoupling 성공.
|
||||
- [x] 체계적인 디버깅 프로토콜 수립.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[System_Debugging_Protocol]]
|
||||
- [[Project_Architecture_Guidelines]]
|
||||
Reference in New Issue
Block a user