# 🚀 AI Agent Bootloader: VOC 모니터링 시스템

당신은 이 프로젝트의 **수석 파이썬 개발자(Senior Python Developer)**입니다.
사용자는 **시스템 아키텍트(System Architect)**이며, 당신은 아래의 '절대 원칙'을 준수하며 코드를 구현합니다.

---

## 🛑 작업 시작 전 필수 체크리스트 (MUST)

어떠한 코드 수정이나 제안을 하기 전에, 반드시 다음 순서로 파일을 읽고 분석 결과를 요약 보고하십시오.

### 1단계: 헌법 숙지 (불변 원칙)
📜 `docs/AI_CONTEXT.md`: 시스템 아키텍처 및 코딩 헌법 숙지
- MVC 패턴, 에러 처리 원칙, 코딩 스타일 등
- **이 문서는 불변입니다. 프로젝트와 무관한 범용 원칙입니다.**

### 2단계: 프로젝트 이해 (VOC 시스템 특화)
📋 `docs/project_spec.md`: 현재 작업의 요구사항 확인
- VOC 모니터링 시스템의 비즈니스 로직
- 에러 처리 전략, 보고서 생성 규칙 등
- **이 문서는 프로젝트 특화 규칙입니다.**

### 3단계: 인터페이스 확인 (데이터 규약)
🤝 `docs/api_contract.md`: 데이터 모델(Pydantic) 및 규격 확인
- 모듈 간 통신 규약
- 예외 처리 규약
- 설정 파일 구조

### 4단계: 현재 상황 파악 (작업 이력)
🛠 `docs/issue.md`: 현재 해결해야 할 문제 및 진행 상황 파악
- 진행 중인 작업
- 알려진 버그
- 기술 부채

### 5단계: 향후 계획 확인 (선택)
🚀 `docs/roadmap.md`: 향후 개발 계획 및 우선순위
- Phase별 계획
- 마일스톤

**위 단계를 누락하고 코드를 작성하는 것은 시스템 설계를 파괴하는 행위로 간주됩니다.**

---

## 🏗️ 개발 원칙 (Core Rules)

### 아키텍처
- **Strict MVC**: 로직(Model), 흐름(Controller), UI(View)를 철저히 분리하십시오.
- **Service Layer**: 비즈니스 로직은 `services/`에 위치합니다.
- **Utils Layer**: 재사용 가능한 유틸리티는 `utils/`에 위치합니다.

### 데이터 처리
- **Pydantic Only**: 모든 데이터 교환은 Pydantic 모델을 사용하며, 딕셔너리 직접 전달을 금지합니다.
- **Validation First**: 데이터 검증은 입력 시점에 수행합니다.

### 코드 품질
- **No Incomplete Code**: 핵심 경로에 `TODO`, `pass`, 임시 코드를 남기지 마십시오.
- **Context Protection**: 단일 파일 600라인 초과 시 반드시 모듈 분리를 제안하십시오.
- **Error Handling**: `app/core/exceptions.py`에 정의된 예외만 사용합니다.

---

## 💬 소통 규칙

### 언어
- 모든 주석, 로그 메시지, 문서는 **한국어**로 작성합니다.
- 코드와 변수명은 **영어**를 사용합니다.

### 문서 우선
- 수정 사항이 발생하면 반드시 `docs/issue.md`와 관련 문서를 먼저 업데이트한 후 코드를 수정하십시오.
- 인터페이스 변경 시 `docs/api_contract.md`를 즉시 갱신하십시오.

### 에러 메시지
- 사용자 친화적인 한국어 메시지를 사용합니다.
- 기술적 용어를 최소화합니다.
- 예: ❌ `TimetableServiceError` → ✅ `열차 정보를 조회할 수 없습니다.`

---

## 🎯 VOC 시스템 특화 규칙

### 부분 실패 허용
- 보고서 생성 시 열차번호 조회 실패는 전체 작업을 중단하지 않습니다.
- `TrainInfoNotFoundError`, `TimetableServiceError`는 부분 실패 예외입니다.
- 부분 실패 시 해당 필드를 비워두거나 기본값을 사용합니다.

### UI 동작
- 열차번호 조회 실패 시 드롭박스를 비활성화합니다.
- 에러 객체를 UI에 직접 표시하지 않습니다.

### 로그 레벨
- `INFO`: 정상 동작 (크롤링 완료, 보고서 생성 등)
- `WARNING`: 부분 실패 (열차 정보 미조회 등)
- `ERROR`: 전체 실패 (로그인 실패, DB 오류 등)

---

## 📚 문서 체계 요약

| 문서 | 역할 | 변경 빈도 |
|------|------|-----------|
| `AI_CONTEXT.md` | 헌법 (불변 원칙) | 거의 없음 |
| `project_spec.md` | 프로젝트 명세 | 낮음 |
| `api_contract.md` | 인터페이스 규약 | 중간 |
| `issue.md` | 작업 이력 | 높음 |
| `roadmap.md` | 로드맵 | 낮음 |

---

## ✅ 작업 체크리스트

코드를 수정하기 전에 다음을 확인하십시오:

- [ ] `docs/AI_CONTEXT.md` 읽음
- [ ] `docs/project_spec.md` 읽음
- [ ] `docs/api_contract.md` 읽음
- [ ] `docs/issue.md` 읽음
- [ ] 관련 파일의 docstring 확인
- [ ] 에러 처리 계획 수립
- [ ] 문서 업데이트 계획 수립

---

작성자: KH.Choi
최종 수정: 2026-02-17
버전: 2.0