[P-Reinforce] Document G1nation build fix & engine rebuilding

2026-04-24 18:10:16 +09:00
parent 6661b1bcb8
commit 692f936303
2 changed files with 102 additions and 0 deletions
@@ -0,0 +1,33 @@
+# [Report] G1nation Extension Encoding & Engine Rebuilding
+**Date**: 2026-04-24
+**Author**: PD Kodari (AI)
+**Status**: COMPLETED & PACKAGED (v2.2.15)
+
+## 1. 개요 (Overview)
+ConnectAI에서 G1nation으로의 브랜딩 전환 이후 발생한 심각한 빌드 오류 및 런타임 불안정성을 해결하기 위한 긴급 수술을 집행함. 소스 코드 내 인코딩 오염과 코드 복제(Duplication)로 인해 `npm run compile`이 불가능한 상태였음.
+
+## 2. 주요 결함 (Critical Issues)
+- **인코딩 지뢰 (Encoding Corruption)**: `extension.ts` 내 한글 주석 및 UI 문자열이 UTF-8 형식을 벗어나 깨지면서 따옴표(`'`) 인식을 방해함 -> `Unterminated string literal` 에러 발생.
+- **좀비 코드 (Ghost Blocks)**: 함수 외부에 버려진 실행 코드와 닫는 중괄호(`}`)들이 산재하여 문법 파괴.
+- **엔진 중복 (Engine Duplication)**: `_executeActions` 함수가 두 군데 이상 중복 정의되어 로직 충돌 및 용량 비대화 초래.
+- **문법 오용**: `execSync`에 `.catch()`를 사용하는 등 동기/비동기 혼선 발견.
+
+## 3. 수술 과정 (Surgical Process)
+총 20단계에 걸친 **PowerShell 레이저 수술(Line-by-line Patch)**을 통해 표준 `replace` 도구의 인코딩 한계를 극복함.
+
+- **v1~v10**: 설정 메뉴(`_handleSettingsMenu`) 및 브레인 메뉴(`_handleBrainMenu`)의 깨진 텍스트를 영문/표준 UTF-8로 전면 교체.
+- **v11~v18**: 중복된 코드 블록들을 찾아내어 삭제하고, 흩어진 액션 핸들러들을 하나로 통합.
+- **v19**: 메인 엔진(`_executeActions`)을 중복 없는 최신 구조로 리빌딩.
+- **v20**: 함수 외부에 잔존하던 '유령 코드'와 깨진 문자열 최종 소거.
+
+## 4. 최종 결과 (Final Result)
+- **빌드 성공**: `esbuild` 컴파일 정상 통과 (30ms 내외).
+- **패키징 완료**: `g1nation-2.2.15.vsix` 생성 완료.
+- **안정성 확보**: UI 텍스트 영문화 및 표준화를 통해 향후 인코딩 문제 재발 가능성 차단.
+
+## 5. 향후 과제 (Next Steps)
+- **모듈화**: 2,500라인이 넘는 `extension.ts`를 `ActionHandlers.ts`, `UIProvider.ts` 등으로 분리하여 유지보수성 향상 필요.
+- **i18n 도입**: 한글 UI 재도입 시 직접 하드코딩 대신 별도의 JSON 언어팩 사용 권장.
+
+---
+**PD 코다리의 한마디**: "조직이 시스템이다. 엔진이 깨끗해야 비행기가 뜬다!" 😎🐟