# PRD — 차량 운행일지·주유 정산 자동화

> **실습 방식**: 내 PC 안(로컬) · Claude 데스크톱 앱 **Code** 탭 · 다운로드 › **Test** 폴더 · 가상 데이터만 사용
> 이 문서를 Claude Code가 그대로 읽고 앱을 만듭니다. 고치고 싶은 곳은 직접 고쳐도 됩니다.

## 1. 한 줄 정의
운전한 직원은 **배차 건을 고르고 계기판·주유 영수증 사진만 올리고**, 총무 담당자는 **Claude Code가 사진에서 읽어 준 주행거리·리터·금액**으로 빈칸 없는 **국세청 업무용승용차 운행기록부 엑셀**을 내려받고 차량별 누적거리·유류비·실연비를 한 화면에서 보는 앱.

## 2. 누가 쓰나
| 역할 | 하는 일 |
|---|---|
| 운행 직원(운전자) | 내 배차 승인 건 선택 → 운행 종료 계기판 사진 올리기 → 주유했으면 영수증 사진 올리기 → 제출 |
| 총무·회계 담당자(관리자) | ERP 배차 CSV 불러오기, 주행거리·유류비 검증과 누락 보정, 운행기록부 엑셀 내려받기, 차량별 연비·누적거리 확인 |

## 3. 오늘 만들 기능 (필수)
- [ ] **배차 불러오기 + 운전자 입력 화면**: ERP에서 내보낸 `dispatch_erp.csv` 의 «승인» 건만 목록으로, 휴대폰 모양 화면에서 배차 건 선택 → 계기판 사진 → 주유 여부·영수증 사진 → 제출
- [ ] **사진 인식 결과 반영**: Claude Code가 `images/` 사진을 읽어 만든 `photo_read.csv` 를 불러와 운행일지·주유 내역의 빈칸을 채움
- [ ] **주행거리 대조·누락 보정**: 같은 차량의 «직전 주행 후 km = 이번 주행 전 km» 인지 검사, 빈칸은 «확인 필요»로 표시하고 다음 운행의 주행 전 km로 채우는 [보정] 버튼
- [ ] **국세청 운행기록부 엑셀**: 차량을 고르고 버튼 하나로 업무용승용차 운행기록부 서식의 `.xlsx` 내려받기
- [ ] **관리자 대시보드**: 분기 총 주행거리·유류비·평균 실연비·확인 필요 건수 카드, 차량별 주행거리 막대, 월별 유류비, 입력 상태 도넛, 차량별 현황 표(실연비 vs 공인연비)

## 4. 화면 구성
1. **상단**: 앱 이름 · [총무 대시보드 / 운전자 모바일 입력 / 국세청 운행기록부] 탭 · 분기 표시
2. **총무 대시보드**: KPI 카드 4개 → 차량별 주행거리 · 월별 유류비 · 입력 상태 도넛 → 차량별 현황 표 + Claude Code 사진 인식 카드
3. **운전자 모바일 입력**: 왼쪽 휴대폰 모양 틀(배차 선택 → 계기판 사진 → 주유 여부 → 제출 전 확인), 오른쪽 올라온 사진 4장과 읽은 값, 자동 검증 목록, 입력 현황 막대
4. **국세청 운행기록부**: 서식 미리보기(사진 인식 칸은 파랑, 누락 보정 칸은 노랑), 아래에 총 주행거리·업무용 사용거리·업무사용비율, 오른쪽 차량 선택과 완성도
5. 그래프에 **마우스를 올리면 수치가 말풍선으로** 보이게

## 5. 데이터 — 파일과 항목 (모두 가상 데이터, 2026년 3분기)
| 파일 | 항목 |
|---|---|
| `data/vehicles.csv` (5행) | 차량번호, 차종, 연료, 공인연비(km/L), 관리부서, 분기초누적km(7/1) |
| `data/dispatch_erp.csv` (103행) | 배차번호, 신청일, 운행일, 차량번호, 부서, 운전자, 목적지, 업무목적, 승인상태(승인 97·반려 6) |
| `data/trip_log.csv` (97행) | 배차번호, 차량번호, 운행일, 부서, 운전자, 주행전km, 주행후km, 주행거리km, 출퇴근용km, 일반업무용km, 계기판사진, 입력상태 |
| `data/fuel.csv` (22행) | 주유번호, 주유일, 차량번호, 운전자, 주유소, 유종, 리터, 단가, 금액, 결제, 영수증사진, 입력상태 |
| `data/images/` (4장) | `dash_01.png`·`dash_02.png`(계기판), `receipt_01.png`·`receipt_02.png`(주유 영수증) |

- 운행일지 중 **사진만 올린 2건**(주행후km 빈칸)과 **계기판 누락 3건**, 주유 중 **영수증 사진만 올린 2건**(리터·금액 빈칸)이 일부러 들어 있습니다.
- 실연비 = 분기 주행거리 ÷ 분기 주유 리터. 업무사용비율 = 업무용 사용거리(출퇴근용 + 일반업무용) ÷ 총 주행거리.
- 저장 위치: 브라우저 저장공간(localStorage) + CSV 파일. **외부 서버·데이터베이스를 쓰지 않습니다.**

## 6. AI 사진 인식은 Claude Code가 합니다
앱 안에서 AI를 부르지 않습니다(사내 기준: 별도 API 키 없음). 대신:
1. 운전자가 올린 사진이 `data/images/` 폴더에 모임(오늘은 가상 사진 4장)
2. Claude Code가 사진을 하나씩 열어 **계기판 ODO·TRIP 값, 영수증의 주유소·날짜·단가·리터·금액**을 읽고, `trip_log.csv`·`fuel.csv` 의 같은 사진 이름 행과 짝지어 `data/photo_read.csv` 로 저장(앞뒤 주행거리 검증 포함)
3. 앱이 `photo_read.csv` 를 불러와 빈칸을 채우고, 대시보드의 «Claude Code 사진 인식» 카드에 요약 표시

## 7. 기술 원칙 (로컬 실행)
- 폴더 하나: `Test/vehicle-log/` 안에 `index.html`, `style.css`, `app.js`, `data/`(CSV 4개 + `images/`)
- 순수 HTML·CSS·JavaScript. 외부 인터넷 주소(CDN·글꼴)를 불러오지 않음 — 엑셀 라이브러리(SheetJS 등)가 필요하면 파일을 폴더 안 `lib/` 에 내려받아 사용
- 실행: `python -m http.server 8765` → 브라우저에서 `http://localhost:8765`
- 결과물은 폴더째 zip으로 묶어 가져감. 인터넷에 올리지(배포하지) 않음

## 8. 원래 요청에서 조정한 부분
| 원래 요청 | 오늘은 이렇게 | 이유 |
|---|---|---|
| 앱에서 본인 배차 승인 건을 바로 조회 | ERP에서 내보냈다고 가정한 `dispatch_erp.csv` 불러오기 | 배차 신청·승인은 기존 ERP 그대로 — 사내 시스템 연동은 실습 범위 밖 |
| 사진 속 숫자를 앱이 AI로 자동 인식·검증 | Claude Code가 `images/` 사진을 읽어 `photo_read.csv` 작성 → 앱이 불러오기 | 앱 안 AI 호출에는 별도 API 키가 필요 |
| 직원이 각자 휴대폰 웹으로 입력 | PC 화면 안 휴대폰 모양 화면으로 입력 흐름 시연 | 외부 배포 금지 — 휴대폰 접속은 인터넷 공개가 필요 |

## 9. 완료 기준 (테스트)
- [ ] CSV 4개를 불러오면 대시보드에 **분기 총 주행거리 8,118 km · 유류비 1,200,500원 · 평균 실연비 11.3 km/L** 가 보인다
- [ ] 운행일지 97회 중 **확인 필요 5건**(사진만 2 · 계기판 누락 3)이 표시되고, [보정]을 누르면 234나5678의 7/22 운행이 **77 km**(32,103 → 32,180)로 채워진다
- [ ] Claude Code가 만든 `photo_read.csv` 에 **dash_01 = 31,913 km, receipt_01 = 41.8 L · 71,440원** 이 들어 있고, 불러오면 빈칸이 사라진다
- [ ] 운행기록부에서 234나5678을 고르면 총 주행거리 **1,845 km**, 출퇴근 **117 km**, 업무사용비율 **100%** 로 엑셀이 내려받아지고, 엑셀에 빈칸이 없다
- [ ] 차량별 실연비가 싼타페 **8.8 km/L**(공인 10.8의 81%)처럼 공인연비와 나란히 보인다
- [ ] 새로고침(F5)해도 입력이 남아 있고, 폴더를 zip으로 묶어 다른 폴더에 풀어도 똑같이 실행된다

## 10. 다음 단계 (집에서 더 키울 것)
- 차량 5대를 한 엑셀 파일(시트 5장)로, 연간 합계 시트 추가
- 정비·타이어 교체 이력을 붙여 연비 떨어진 차량 알림
- 사내 ERP·법인카드 내역 연동은 사내 IT 검토 후