# Dashboard & Bot Stability Infrastructure Fix (2026-04-21)

## 개요
사용자가 대시보드 URL 접속 시 `Turbopack Panic` 에러를 겪는 문제를 해결하고, 봇 프로세스의 불안정성(IPC 채널 종료)을 개선했습니다.

## 원인 분석
1. **gRPC Contract 초기화 이슈**: 
   - `grpc-contracts` 패키지 로드 시점에 동적으로 파일 시스템을 조회하여 `proto` 파일을 로드함.
   - Next.js의 빌드/분석 단계에서 파일 시스템 접근 권한이나 경로 문제로 인해 crash 유발.
2. **Turbopack 환경 호환성 이슈**:
   - Turbopack이 내부 worker 프로세스를 스폰할 때 시스템 `$PATH`에서 `node` 바이너리를 찾지 못함 (`os error 2`).
   - 이는 Turborepo의 환경 변수 제한 정책과 겹쳐 발생함.

## 해결 방법
1. **gRPC Lazy Loading 적용**:
   - `packages/grpc-contracts/src/index.js`를 수정하여 실제 모듈 접근 시점에만 proto를 로드하도록 `getter` 패턴 적용.
2. **gRPC 서버 개발 모드 통합**:
   - `apps/bot/src/utils/grpcServer.ts`를 신설하여 공통 gRPC 서버 로직을 추출.
   - 단일 실행 모드(`index.ts`)와 Sharding 모드(`shard.ts`) 모두에서 대시보드 통신을 위한 gRPC 서버가 기동되도록 수정.
3. **Webpack Fallback 및 PATH 주입**:
   - Turbopack의 하위 프로세스 스폰 이슈(`os error 2`)를 회피하기 위해 대시보드를 Webpack 모드(`next dev --webpack`)로 구동.
   - `apps/dashboard/package.json`에서 명시적으로 Node.js 실행 경로를 `PATH`에 주입.
4. **인프라 자동 복구**:
   - `docker-compose`를 통해 PostgreSQL 컨테이너를 정상화하고 `Prisma` 스키마를 동기화.
5. **좀비 프로세스 정리**:
   - 포트 점유 이슈를 유발하던 구형 Node 프로세스들을 원천 정리.

## 결과 확인
- `scripts/verify-recovery.ts`를 통해 DB, gRPC, Bot 연동 전수 검토 완료 (ALL PASS).
- `curl -I http://localhost:3000/`를 통해 대시보드 응답 확인.
- 브라우저를 통한 대시보드 UI 정상 렌더링 확인.

## 참고 사항
- 현재 대시보드는 안정성을 위해 임시로 `3005` 포트에서 구동 확인을 마쳤으나, `3000`번 포트 점유가 해제되면 다시 `3000`번으로 서비스될 수 있도록 설정되어 있습니다.