# rb8001 계층 분리 리팩토링 계획

**날짜**: 2025-11-23
**작성자**: admin
**관련 파일**: `rb8001/main.py`, `rb8001/app/router/router.py`
**참고**: `DOCS/book/300_architecture/311_FastAPI_구조_원칙.md`

---

## 목적

rb8001의 중복 대화 저장 문제를 해결하고, FastAPI 구조 원칙(311_FastAPI_구조_원칙.md)을 준수하는 계층 분리 구조로 리팩토링

### 즉시 해결 필요 문제
- 대화가 DB에 2번 저장되는 중복 저장 버그 (1회 요청 → 2회 DB INSERT)

### 장기 개선 목표
- 계층 분리 원칙 위반 15건 해결
- 유지보수성 및 확장성 향상
- Conversation/Message 온톨로지 기반 통합 로그(actor, source_channel, channel_id, context_node 등)로 전환 + Celery/Redis 비동기 큐 도입 검토 (ChromaDB, intent_review_queue 백그라운드 처리)

---

## 현재 문제

### 1. 중복 저장 (긴급)

**문제 상황:**
- router.py:876 - `_call_internal_llm`에서 1차 저장 (router → state 직접 호출)
- main.py:110 - `save_message_conversation`에서 2차 저장 (이미 제거됨)
- 결과: conversation_log 테이블에 동일 대화 2번 삽입

**원칙 위반:**
- 311_FastAPI_구조_원칙.md:92 - 계층 건너뛰기 (router → state 직접 호출)
- DRY 원칙 위반 (같은 로직 2곳 실행)

### 2. 계층 구조 위반 (15건)

#### 계층 건너뛰기
1. router.py:876 - router → state 직접 호출 (원칙:92)
2. router/feedback_handler.py:58 - SessionLocal() 직접 사용 (원칙:21, 164)
3. router/intent_review_endpoint.py:21 - SessionLocal() 직접 사용
4. router/slack_handler.py:77,202,361 - SessionLocal() 직접 사용
5. services/startup_valuation.py:475 - asyncpg.connect() 직접 사용 (원칙:164)
6. services/intent_bayes.py:57,117,160 - psycopg2.connect() 직접 사용
7. services/coldmail_filter.py:182,208,255 - asyncpg.connect() 직접 사용
8. main.py:694,711 - state/database 직접 호출 (원칙:92)

#### main.py 원칙 위반
9. main.py:84-176 - 엔드포인트 직접 정의 (원칙:30 - "앱 실행, 라우터 등록만")
10. main.py:118-137 - 비즈니스 로직 포함 (원칙:21)
11. main.py:211,620 - router 내부 메서드(_call_internal_llm) 직접 호출

#### 비즈니스 로직 배치 오류
12. router.py:128-682 - route_message()는 비즈니스 로직, services/에 있어야 함 (원칙:21)
13. app/brain/, app/llm/, app/memory/ - services/brain/, services/llm/로 이동 필요 (원칙:28-42)

#### 구조 누락
14. schemas/ 폴더 없음 (원칙:49)
15. models와 state 미분리 - state/database.py에 ORM 모델 + DB 접근 혼재 (원칙:36,47)

#### 파일 크기 초과
- 24개 파일이 300줄 초과 (router.py 915줄, main.py 747줄 등)

---

## 해결 방안

### Phase 1: 중복 저장 해결 (긴급, 완료)

**수정 완료:**
- router.py:873-884 - `_save_conversation` 호출 제거
- router.py:628-638, 670-680 - services 호출 추가
- main.py:108-115 - `save_message_conversation` 호출 제거

**결과:**
- 대화 저장 1회로 축소
- 하지만 router에서 services 호출 (임시)

### Phase 2 Step 1-2: 엔드포인트 및 비즈니스 로직 분리 (완료)

**수정 완료:**
- app/router/message_endpoint.py 생성 - 엔드포인트 분리
- main.py:84-176 제거 → message_endpoint.py로 이동
- main.py에 include_router 추가
- app/services/message_service.py 생성 - route_message 이동
- router.py:128-682 (route_message) → message_service.py로 이동
- router.py는 message_service 호출만 (~10줄)

**결과:**
- 계층 분리 원칙 준수 (router → services → state)
- 중복 저장 문제 해결 (services 레이어에서 한 번만 저장)
- router.py 크기 927줄 → 366줄로 축소

### Phase 2 Step 3: 폴더 구조 정리 (완료)

**수정 완료:**
- app/brain/ → app/services/brain/ 이동
- app/llm/ → app/services/llm/ 이동
- app/memory/ → app/services/memory/ 이동
- app/skills/ → app/services/skills/ 이동
- 모든 import 경로 수정 (28개 파일)
- main.py의 skills import 경로 수정

**결과:**
- 서비스 레이어 통합 완료
- import 경로 일관성 확보

### Phase 2 Step 4: DB 접근 정리 (완료)

**수정 완료:**
- feedback_handler.py: SessionLocal 제거, repository 사용
  - handle_chat_feedback를 async로 변경
  - update_or_create_feedback를 async로 변경 (내부 Session 관리)
  - get_conversation_by_id 추가
- slack_handler.py: SessionLocal 제거, slack_repository 사용
  - get_team_uuid_by_slack_team_id 추가
  - 3곳의 SessionLocal 직접 호출 제거
- intent_review_endpoint.py: FastAPI Depends 패턴 유지 (허용)

**결과:**
- router/services에서 SessionLocal 직접 사용 제거
- repository 패턴으로 통일
- TDD 테스트 작성 및 통과 확인

### Phase 2: 계층 분리 리팩토링 (대규모)

#### Step 1: 엔드포인트 분리
**생성:**
- app/router/message_endpoint.py (~100줄)

**수정:**
- main.py:84-176 제거 → message_endpoint.py로 이동
- main.py에 include_router 추가

#### Step 2: 비즈니스 로직 분리
**생성:**
- app/services/message_service.py (~550줄)

**수정:**
- router.py:128-682 (route_message) → message_service.py로 이동
- router.py는 message_service 호출만 (~10줄)
- slack_handler.py:424,437,448,893 - message_service 호출로 변경

#### Step 3: 폴더 구조 정리
**이동:**
- app/brain/ → app/services/brain/
- app/llm/ → app/services/llm/
- app/memory/ → app/services/memory/
- app/skills/ → app/services/skills/
- app/notifications/ → app/services/notifications/
- app/pipelines/ → app/services/pipelines/

**생성:**
- app/schemas/ - API 요청/응답 스키마 분리

#### Step 4: DB 접근 정리
**생성:**
- app/models/{domain}_model.py - ORM 모델 분리

**수정:**
- state/database.py - models 제거, Repository만 남김
- router/feedback_handler.py, intent_review_endpoint.py, slack_handler.py - state 통해서만 DB 접근
- services 파일들 - asyncpg.connect() 제거, state 호출로 변경

---

## 기대효과

### 즉시 효과
- 중복 저장 버그 해결 → DB 용량 절약, 데이터 정합성 확보

### 장기 효과
1. **유지보수성**: 계층별 책임 명확 → 수정 영향 범위 최소화
2. **확장성**: 새 기능 추가 시 어느 계층에 넣을지 명확
3. **테스트**: 계층별 단위 테스트 작성 용이
4. **협업**: 원칙 준수로 코드 가독성 향상
5. **기술부채 감소**: 15개 위반 사항 해결

---

## 구현 규모

### 최소 수정 (Phase 1만)
- 영향 파일: 2개 (router.py, main.py)
- 수정 라인: ~50줄
- 소요 시간: 완료

### 전체 리팩토링 (Phase 2)
- 영향 파일: 최소 30개
- 신규 생성: ~650줄
- 수정/제거: ~1,300줄
- 총 변경: ~2,000줄
- 예상 소요: 1-2일

---

## 우선순위

1. **긴급 (완료)**: 중복 저장 버그 해결
2. **높음**: 엔드포인트 분리 (main.py 원칙 준수)
3. **중간**: 비즈니스 로직 분리 (route_message → service)
4. **낮음**: 폴더 구조 정리, 파일 크기 축소

---

## 참고

- 311_FastAPI_구조_원칙.md - 계층 분리 원칙
- 312_문서_작성_원칙.md - 문서 작성 규칙