# **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` 기반 연동 테스트 진행
* 두 방식을 병행 테스트하여 장단점 비교

---