# Phase 1 코딩 규칙

## 1. 기본 원칙

- 함수는 가능하면 작은 단위로 분리합니다.
- adapter / parser / db / feature builder 책임을 섞지 않습니다.
- side effect는 application layer에 모읍니다.
- 표준 라이브러리와 검증된 범용 라이브러리를 우선 사용합니다.
- 예외를 삼키지 않습니다.

## 2. 타입과 검증

- Python type hint를 필수로 사용합니다.
- 외부 입력은 Pydantic 또는 동등한 검증 계층을 거칩니다.
- 내부 DTO와 DB model을 혼용하지 않습니다.

## 3. idempotency 규칙

- 동일 입력을 두 번 처리해도 결과가 달라지지 않아야 합니다.
- source key + checksum + unique constraint를 적극 사용합니다.
- raw 수집과 structured 적재는 분리합니다.

## 4. 예외 처리

반드시 아래 중 하나로 분류합니다.
- retryable
- non-retryable
- validation
- dependency

예외 객체에는 source/entity/context가 있어야 합니다.

## 5. retry / timeout

- 외부 HTTP 호출은 timeout 필수
- 무한 retry 금지
- 지수 백오프 + 상한 적용
- validation 실패는 retry 금지

## 6. 파일 저장 규칙

- 파일명은 deterministic 해야 합니다.
- 원문 overwrite 금지
- sidecar metadata JSON 함께 저장
- 상대경로 대신 data root 기준 canonical path 사용

## 7. DB write 규칙

- 가능하면 upsert 사용
- bulk insert 전 unique key 명확화
- transaction scope를 짧게 유지
- parser core에서 DB 세션 직접 접근 금지

## 8. 로깅 규칙

- INFO: 정상 단계
- WARNING: 데이터 이상, fallback 사용
- ERROR: 처리 실패
- DEBUG: 로컬 개발 전용

민감정보 로그 출력 금지:
- API key
- secret
- full auth header

## 9. 테스트 규칙

- fixture 없는 adapter 구현 금지
- parser는 최소 10개 이상의 샘플 문서 fixture 확보 권장
- 회귀 버그는 반드시 fixture 추가 후 수정

## 10. 문서화 규칙

- 모든 adapter에 README 또는 docstring 필요
- config key는 설명과 기본값 포함
- migration은 목적 설명 포함

## 11. 코드 리뷰 기준

- 책임 분리가 되어 있는가
- 재실행 안전한가
- 실패 시 상태가 명확한가
- 테스트가 충분한가
- 로그로 추적 가능한가