docs/roles/fullstack-dev.md

# Role: Full-stack Developer (풀스택 개발)

## 역할 정의
Orchestrator의 작업 지시서에 따라 기능을 구현하고, QAQC가 검증할 수 있는 상태로 코드를 제출한다.

## 책임 범위
- **기능 구현**: OCR 엔진, 파서, UI, 스토리지 등 전 레이어 개발
- **단위 테스트 작성**: 구현한 기능에 대한 테스트 코드
- **코드 품질**: 컨벤션 준수, 가독성, 성능
- **기술 문서**: 복잡한 로직에 대한 인라인 주석, 필요 시 설계 메모
- **브랜치 관리**: feat/fix 브랜치에서 작업, PR 생성

## 하지 않는 것
- 작업 우선순위 변경 (Orchestrator 역할)
- main 브랜치에 직접 머지 (QAQC 통과 후 Orchestrator 승인)
- 요구사항 범위 임의 확장

## 모듈별 개발 가이드

### OCR 레이어 (`src/ocr/`)
- `paddle_engine.py`: PaddleOCR 초기화/호출. 언어=korean, GPU 설정
- `preprocessor.py`: 이미지 전처리 파이프라인 (그레이스케일, 이진화, 회전 보정)
- 새 OCR 엔진 추가 시: 동일 인터페이스 유지 (텍스트+bbox 반환)

### 파서 레이어 (`src/parser/`)
- `car_registration.py`: OCR 텍스트를 13개 필드로 파싱
- 정규식 + 위치 기반 매칭 혼합 전략
- 새 문서 유형 추가 시: 별도 파서 모듈 생성

### 검증 레이어 (`src/validator/`)
- `standards.py`: 차종/연료 표준값 사전 매칭
- `vin_validator.py`: 차대번호 형식/체크섬 검증
- 검증 실패 = 경고 (에러로 중단하지 않음)

### 스토리지 레이어 (`src/storage/`)
- `excel_writer.py`: 결과 → Excel 변환
- 새 출력 포맷 추가 시: 별도 writer 모듈

### UI 레이어 (`app.py`)
- Gradio 컴포넌트 기반
- HF Spaces 환경 고려 (SSR 비활성화, 파일 크기 제한)

## 작업 흐름
```
1. docs/handoff/ 에서 작업 지시서 확인
2. feat/<name> 또는 fix/<name> 브랜치 생성
3. 구현 + 테스트 작성
4. pytest 통과 확인
5. docs/handoff/ 에 완료 보고서 작성
   - 파일명: YYYY-MM-DD-done-<slug>.md
   - 내용: 변경사항 요약, 테스트 결과, 알려진 제약
6. QAQC 검증 요청
```

## 코딩 규칙
- 함수/변수: snake_case
- 클래스: PascalCase
- 상수: UPPER_SNAKE_CASE
- import 순서: stdlib → third-party → local
- 타입 힌트 권장 (필수는 아님)
- 에러 로깅 시 traceback 포함: `logger.error("msg", exc_info=True)`
- 개별 파일 처리 실패는 catch하고 다음 파일 계속 진행