원 레포랑 완전 분리

docs/ADR-3.md

@@ -0,0 +1,82 @@
+# **ADR-003**
+
+* 제목: **서비스 간 공통 모듈 연동 방식 결정**
+* 날짜: **2025-06-12**
+* 상태: 제안됨 (Proposed)
+* 작성자: **\[김용연 연구원]**
+
+---
+
+## 1. 컨텍스트 (Context)
+
+ADR-002를 통해 **멀티레포 아키텍처**로 결정되었으며, 이에 따라 각 서비스 간 **공통 모듈을 어떤 방식으로 연동할 것인지**에 대한 결정을 내려야 한다. 이번 논의는 다음 피드백을 기반으로 진행된다.
+
+> 1. 공통모듈이 많고 복잡한가?
+> 2. 관리포인트가 늘어날 여지가 많은가?
+
+또한, Git 연동 방식 외에도 **Gitea Action 기반 자동 동기화 방식**을 함께 검토한다. 고려 요소는 다음과 같다.
+
+* 공통 모듈의 복잡도 및 변경 빈도
+* 유지보수 및 형상관리 난이도
+* 개발자 사용성
+* 자동화 가능성과 CI/CD 연계
+* 로컬/원격 환경 간의 충돌 여부
+
+---
+
+## 2. 결정 (Decision)
+
+현재 고려 중인 연동 방식은 다음과 같다.
+
+| 방법                          | 장점                           | 단점                           |
+| --------------------------- | ---------------------------- | ---------------------------- |
+| **git-submodule**           | 참조만으로 관리되어 가볍고 명확한 버전 고정 가능  | 초기 사용 복잡, 동기화 어려움, 실수 발생 가능성 |
+| **git-subtree** ✅ | 병합, 업데이트 용이, 독립적인 서비스 유지 가능  | 충돌 시 수동 병합 필요, 코드 중복 위험      |
+| **Gitea Action(강제 동기화)**   | CI로 일관된 코드 유지 가능, 자동화 쉬움     | 설정 복잡, 브랜치 충돌 발생 가능성 있음      |
+---
+
+## ✅ 공통모듈
+
+현재 공통적으로 사용되거나 예정된 모듈은 다음과 같다:
+
+| 영역            | 모듈 예시                              | 설명                                         |
+| ------------- | ---------------------------------- | ------------------------------------------ |
+| 로깅            | `logger.py`                        | 공통 포맷의 로그 기록, Loki 기반 모니터링 대응              |
+| 요청 로깅 추적            | `request_logger.py`                        | 클라이언트 IP, 요청 시간, API 경로 등을 기록, Loki/Grafana 연동         |
+| 설정 관리         | `config_loader.py`                 | 환경 변수 및 설정 파일 통합 로딩                        |
+| 응답 구조         | `response.py`                      | API 응답 형식 표준화 |
+| 예외 처리         | `exceptions.py`                    | 공통 예외 클래스로 서비스간 처리 로직 통일                   |
+| Celery 태스크 래퍼 | `celery_base.py`                   | 공통 Task 기반 클래스, 재시도/타임아웃/로깅 통일             |
+| 작업 상태 추적      | `redis_job_tracker.py`             | Redis 기반 작업 상태 추적 기능                       |
+| 모델 어댑터        | `llm_adapter.py`, `ocr_adapter.py` | 다양한 추론 서비스에 대한 공통 인터페이스          |
+| 라우터 템플릿       | `base_router.py`                   | FastAPI 기반 라우터 템플릿 및 공통 설정                 |
+| 파일 유틸리티      | `file_utils.py`                   | 확장자 검사, 디렉토리 생성 등 파일 처리 로직                 |
+---
+
+## 3. 고려된 대안
+
+### 1. **git-submodule**
+
+* 경량화 및 버전 고정 측면에서 유리
+* 그러나 초기 진입장벽이 높고, 실수(예: 서브모듈 커밋 누락 등) 발생 가능
+
+### 2. **git-subtree**
+
+* 현재 가장 유력한 방식
+* 외부 저장소의 디렉터리를 내부로 복사하여 통합된 이력 관리 가능
+* CI/CD 파이프라인 내에서도 동기화 명령 (`pull`, `push`, `split`)이 명확
+
+### 3. **Gitea Action 통한 자동 동기화**
+
+* push 이벤트 발생 시 `main` 브랜치의 `common/` 디렉토리를 각 서비스의 `utils/`로 복사
+* 자동화는 강력하나, 충돌이나 병합 충돌 발생 시 수동 대응 필요
+
+---
+
+## 4. 향후 계획
+
+* 실제 운영 중인 공통 모듈을 기준으로 **변경 빈도, 영향 범위 분석**
+* `subtree` 및 `Gitea Action` 기반 연동 테스트 진행
+* 두 방식을 병행 테스트하여 장단점 비교
+
+---