From d083177d9526f00739e31cd1890401576684e8cd Mon Sep 17 00:00:00 2001 From: g1nation Date: Fri, 8 May 2026 01:29:03 +0900 Subject: [PATCH] docs: add architectural refactoring roadmap based on technical debt audit --- docs/refactoring_roadmap.md | 53 +++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/refactoring_roadmap.md diff --git a/docs/refactoring_roadmap.md b/docs/refactoring_roadmap.md new file mode 100644 index 0000000..54d62c9 --- /dev/null +++ b/docs/refactoring_roadmap.md @@ -0,0 +1,53 @@ +# πŸ› οΈ 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%