# 🤝 API & Module Contract

이 문서는 모듈 간의 통신 규약과 데이터 규격을 정의한다. 모든 AI 에이전트는 코드를 생성하거나 수정하기 전 본 문서를 참조하여 인터페이스의 정합성을 유지해야 한다.

---

## 1. 모듈 간 데이터 규격 (Schemas)

모든 데이터 교환은 **Pydantic 모델**을 통해 이루어지며, 데이터의 오염을 방지하기 위해 입력 시점에 엄격한 검증을 수행한다.

- **저장 위치:** `app/schemas/` (또는 프로젝트 성격에 따라 `app/models/`)
- **모델 명명 규칙:** `[Domain][Action]Schema` (예: `UserLoginRequest`, `LogAnalysisResponse`)
- **정의 방식:**
    - `[ModelName]`: 모든 필드에 대해 **Type Hint**를 필수 적용한다.
    - 이 구조는 `Model`, `View`, `Controller` 등 모든 계층에서 공통으로 준수한다.

---

## 2. 핵심 인터페이스 (Internal Interface)



### 2.1 계층 간 상호작용 (Layer Interaction)

| 호출자 (Caller) | 수신자 (Callee) | 데이터 규격 (Schema) | 설명 |
| :--- | :--- | :--- | :--- |
| **Controller** | **Model** | `RequestSchema` | 사용자의 입력을 비즈니스 로직으로 전달 |
| **Model** | **View** | `ResponseSchema` | 처리된 결과를 UI에 전달하기 위한 규격 |

### 2.2 모듈별 입출력 명세 (Module Specification)

| 모듈명 | 입력 (Input) | 출력 (Output) | 비고 |
| :--- | :--- | :--- | :--- |
| `Services.Parser` | `RawData` | `ParsedResult` | 데이터 정규화 및 클리닝 담당 |
| `Services.Analyzer` | `ParsedResult` | `AnalysisReport` | 도메인 핵심 비즈니스 로직 수행 |
| `Services.Exporter` | `AnalysisReport` | `bool` / `FilePath` | 외부 시스템(파일, DB 등) 연동 |

---

## 3. 예외 및 에러 응답 (Error Handling)

에러를 침묵시키지 않으며(`pass` 금지), 발생한 모든 예외는 정의된 체계에 따라 명확히 전파한다.

### 3.1 에러 코드 체계
- **형식:** `[PREFIX]_[CODE]`
- **예시:** - `AUTH_401`: 인증 실패
    - `DATA_500`: 데이터 처리 오류
    - `SYSTEM_ERR`: 시스템 인프라 문제

### 3.2 응답 행동 및 전파 규칙
1. **커스텀 예외 사용:** 모든 에러는 `app/core/exceptions.py`에 정의된 예외 클래스를 사용한다.
2. **로그 기록:** 에러 발생 시점의 컨텍스트를 로그로 남긴 후 예외를 상위(Controller)로 던진다.
3. **사용자 인터페이스 연동:** **Controller**는 포착된 예외를 **View**가 이해할 수 있는 **한국어 메시지**로 변환하여 전달한다.
4. **일관성 유지:** AI는 새로운 기능을 추가할 때 기존 에러 코드 체계를 준수하며, 필요시 본 문서에 새로운 에러 코드를 추가한 뒤 코딩한다.