2.7 KiB

Raw Permalink Blame History

🤝 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 응답 행동 및 전파 규칙

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