DOCS/journey/plans/251123_rb8001_계층_분리_리팩토링_계획.md

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건 해결
• 유지보수성 및 확장성 향상

---

현재 문제

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 - 문서 작성 규칙