From fcb5fe0706867ffb27d2713d217d34d0b0e9a8dc Mon Sep 17 00:00:00 2001 From: happybell80 Date: Sun, 4 Jan 2026 15:23:59 +0900 Subject: [PATCH] =?UTF-8?q?add:=20=EB=A6=AC=ED=8C=A9=ED=86=A0=EB=A7=81=20?= =?UTF-8?q?=EC=8B=9C=20=EB=A1=9C=EC=A7=81=20=EC=83=81=EC=8B=A4=20=EB=B0=A9?= =?UTF-8?q?=EC=A7=80=20=EC=9B=90=EC=B9=99=20=EC=B6=94=EA=B0=80=20-=20?= =?UTF-8?q?=EC=9D=98=EC=A1=B4=EC=84=B1=20=EC=B6=94=EC=A0=81,=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=20=EB=8F=99=EC=9D=BC=EC=84=B1=20=EA=B2=80=EC=A6=9D,?= =?UTF-8?q?=20=EB=B6=80=EC=88=98=20=ED=9A=A8=EA=B3=BC=20=ED=99=95=EC=9D=B8?= =?UTF-8?q?=20=EC=B2=B4=ED=81=AC=EB=A6=AC=EC=8A=A4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../311_FastAPI_구조_원칙.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md index 76369ee..4dfee4e 100644 --- a/book/300_architecture/311_FastAPI_구조_원칙.md +++ b/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. 모범 사례 참고