# 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 검토 후

## 11. 웹앱·서버 버전 (교육 후, 사내 기준 확인 뒤)

로컬판이 완성된 뒤, 운전자가 각자 휴대폰으로 사진을 올리는 웹앱으로 옮길 때의 설계입니다. 총무 담당자의 집계·엑셀 내보내기만이라면 로컬판으로 충분합니다. **실제 운행·운전자 데이터는 사내 IT 승인 전에는 넣지 않습니다.**

| 구분 | 로컬판 | 웹앱판 |
|---|---|---|
| 입력 | Claude Code가 사진 폴더를 읽어 CSV로 | 운전자가 휴대폰으로 사진을 바로 올림 |
| 저장 | 브라우저 저장공간 + CSV | Supabase 표 4개(차량·운행일지·주유·사진) + 사진 보관함 |
| 화면 주소 | localhost (내 PC) | Vercel 주소 (모두 같은 주소, 휴대폰 가능) |
| 권한 | 없음 | 운전자는 내 배차만, 총무는 전체 관리 |

- 로그인: Supabase 이메일 로그인. 총무 계정은 «총무» 역할 표시
- 잠금 설정: 로그인한 사람만 보기, 운전자는 자기 배차·사진만 올리고 보기
- 사진 속 숫자 읽기는 당분간 총무가 모인 사진을 Claude Code로 읽어 채움 (앱 안에서 AI를 부르는 건 IT 확인 후)
- 주행거리 대조·누락 보정·국세청 운행기록부 서식은 로컬판과 같게 유지
- 가상 데이터(data 폴더 CSV·사진)로 먼저 채워 시험한 뒤 실제 사용은 IT 확인 후

### 웹앱판 완료 기준
- [ ] 운전자 계정으로 휴대폰에서 계기판 사진을 올리면 총무 화면 «확인 필요» 목록에 바로 뜬다
- [ ] 총무 계정에서 분기 총 주행거리 8,118 km · 유류비 1,200,500원 · 평균 실연비 11.3 km/L 가 보인다
- [ ] 다른 PC에서 같은 주소로 들어가도 234나5678 운행기록부가 총 1,845 km · 업무사용비율 100% 로 내려받아진다
- [ ] 운전자 계정에는 내 배차만 보이고, 로그인하지 않으면 데이터가 보이지 않는다