Merge branch 'main' of https://git.ro-being.com/ivada_Ro-being/DOCS

book/300_architecture/311_FastAPI_구조_원칙.md

@@ -363,6 +363,61 @@ utils
 ## 18. 테스트 원칙
 
 - **실제 테스트 필수**: 코드 수정 후 추측하지 말고 실제로 테스트 (curl, Slack 직접 사용, DB 조회)
+
+## 19. 리팩토링 시 로직 상실 방지 원칙
+
+### 필수 체크리스트 (코드 이동/리팩토링 전)
+
+**1. 의존성 추적**
+- [ ] 이동할 함수/메서드의 모든 호출부 찾기 (`grep -r "함수명"`)
+- [ ] 이동할 함수 내부의 모든 함수 호출/DB 저장/로깅 등 부수 효과(side effect) 목록화
+- [ ] 이동 전 코드의 전체 실행 흐름 문서화 (호출 → 처리 → 저장 → 응답)
+
+**2. 기능 동일성 검증**
+- [ ] 이동 전 코드의 모든 기능을 테스트로 검증 (DB 저장, 로깅, 에러 처리 등)
+- [ ] 이동 후 동일한 테스트로 재검증 (기능 누락 확인)
+- [ ] 실제 환경에서 E2E 테스트 수행 (단위 테스트만으로는 부족)
+
+**3. 코드 이동 절차**
+- [ ] 이동할 코드 블록 전체 복사 (주석, 로깅, 에러 처리 포함)
+- [ ] 새 위치에 붙여넣기 후 import 경로 수정
+- [ ] 모든 호출부를 새 위치로 변경
+- [ ] 기존 코드 제거 전 테스트 통과 확인
+- [ ] 기존 코드 제거 후 재테스트
+
+**4. 부수 효과(side effect) 확인**
+- [ ] DB 저장 로직 (`save_*`, `insert`, `update` 등)
+- [ ] 로깅 (`logger.info`, `logger.error` 등)
+- [ ] 캐시 업데이트
+- [ ] 외부 API 호출
+- [ ] 이벤트 발행/구독
+- [ ] 상태 변경
+
+### 금지 사항
+
+- ❌ **기능만 이동하고 부수 효과 제거**: 감정 분석만 이동하고 DB 저장 로직 누락
+- ❌ **호출부 일부만 수정**: 일부 호출부는 새 위치, 일부는 기존 위치 혼재
+- ❌ **테스트 없이 리팩토링**: "동작할 것 같다"는 추측으로 진행
+- ❌ **점진적 이동**: 일부만 이동하고 나머지는 나중에 → 누락 위험
+
+### 권장 사항
+
+- ✅ **전체 이동 후 테스트**: 코드를 한 번에 모두 이동하고 테스트
+- ✅ **리팩토링 전후 비교 문서화**: 이동 전 코드와 이동 후 코드를 문서에 기록
+- ✅ **의존성 그래프 작성**: 이동할 함수가 호출하는 모든 함수와 호출하는 모든 함수를 시각화
+- ✅ **E2E 테스트 필수**: 단위 테스트뿐만 아니라 실제 사용 시나리오 테스트
+
+### 교훈 (실제 사례)
+
+**사례 1: emotion_readings 저장 로직 누락 (2025-12-23)**
+- 문제: `router._call_internal_llm`을 `internal_llm_service.py`로 이동 시 `save_emotion_reading()` 호출 누락
+- 원인: 감정 분석 로직만 이동하고 DB 저장 부수 효과 미이동
+- 해결: 리팩토링 체크리스트 적용하여 부수 효과 확인 후 이동
+
+**사례 2: 동일 문제 재발 (2025-10-02)**
+- 문제: 동일한 `save_emotion_reading()` 누락 문제 재발
+- 원인: 리팩토링 체크리스트 없이 진행
+- 교훈: 체크리스트 문서화 및 필수 준수 필요
 - **Git 커밋 확인**: 각 프로젝트 폴더에서 개별 확인 (루트에서 확인 금지)
 
 ## 19. 모범 사례 참고