fithia2/dev/finished/phase1_deliverables/coding_rules.md

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. 코드 리뷰 기준

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