connectai/docs/refactoring_roadmap.md

# 🛠️ ConnectAI 아키텍처 리팩토링 로드맵

> [!IMPORTANT]
> 본 문서는 `Astra v2.80.18` 기준의 기술 부채 진단을 바탕으로 작성되었습니다. 모든 향후 기능 추가 시 아래 로드맵의 하위 과제를 병행하여 수행하는 것을 원칙으로 합니다.

## 1. 최우선 과제: Webview 계층 분리 (UI/UX 결합도 제거)
- **현상**: `sidebarProvider.ts` 내부에 3,000줄 이상의 HTML/JS/CSS 문자열 혼재.
- **해결**:
    - `webview-ui/` 디렉토리 신설.
    - React 또는 순수 TS/JS 기반의 프론트엔드 프로젝트로 분리.
    - 빌드 타임에 리소스를 로드하고 `postMessage` 통신 프로토콜을 타입화하여 정의.
- **기대효과**: 신택스 하이라이팅, 린팅 가능, UI 테스트 가능성 확보.

## 2. 엔진 추상화: `EngineClient` 추출
- **현상**: `agent.ts`와 `sidebarProvider.ts`에 중복된 엔진 선택 및 API 호출 로직.
- **해결**:
    - `src/core/engine/` 디렉토리에 `BaseEngineClient`, `OllamaClient`, `LMStudioClient` 구현.
    - 전략 패턴(Strategy Pattern)을 사용하여 엔진별 통신 규격 캡슐화.
    - `agent.ts`는 더 이상 `fetch`나 API URL 조립에 관여하지 않음.

## 3. 지식 데이터 분리: 프롬프트 관리 시스템
- **현상**: `utils.ts`에 하드코딩된 100줄 이상의 시스템 프롬프트.
- **해결**:
    - `prompts/` 디렉토리에 `.md` 파일 형식으로 프롬프트 관리.
    - `PromptLoader`를 통해 런타임에 지연 로딩.
    - 유저 피드백 기반의 프롬프트 버전 관리 체계 도입.

## 4. God Object 해체: `AgentExecutor` SRP 적용
- **현상**: 한 클래스가 프롬프트 조립, 액션 실행, 트랜잭션, 메모리 관리를 모두 수행.
- **해결**:
    - **`PromptOrchestrator`**: `PromptBuilder` 패턴을 사용하여 컨텍스트별 프롬프트 조립 및 로깅 담당.
    - **`ActionDispatcher`**: `CREATE/EDIT/READ` 등 에이전트 액션의 실제 실행 로직 분리.
    - **`ContextManager`**: 프로젝트 경로, 브레인 인벤토리 등 컨텍스트 추출 전담.

## 5. 단일 진실 원천 (SSoT) 확보
- **현상**: `globalState`, `localStorage`, `webview` 간의 상태 동기화 부재로 인한 Race Condition.
- **해결**:
    - 중앙 집중식 상태 관리자(`StateManager`) 도입.
    - VS Code `ConfigurationTarget`과 웹뷰 상태 간의 단방향 데이터 흐름(Unidirectional Data Flow) 강제.

## 6. 테스트 자동화 도입
- **현상**: 테스트 코드 전무, 회귀 버그 검출 불가.
- **해결**:
    - `security.ts` (보안 로직), `utils.ts` (유틸리티) 단위 테스트 작성.
    - 새로 추출할 `EngineClient` 및 `ActionDispatcher`에 대한 Mock 테스트 구현.

---

### 📊 현재 아키텍처 건전성 지표 (Self-Audit)
- **SRP (단일 책임 원칙)**: 🔴 2/10 (파일당 3,000줄 초과)
- **DIP (의존성 역전 원칙)**: 🟡 5/10 (Bridge에서 시도 중)
- **OCP (개방-폐쇄 원칙)**: 🔴 3/10 (엔진 추가 시 모든 파일 수정 필요)
- **테스트 커버리지**: 🔴 0%