# PRD — 고객사 매출·원가 장부

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

## 1. 한 줄 정의
계산서를 발행할 때마다 엑셀에 손으로 옮겨 적던 매출·원가를, **계산서·원가 CSV를 불러오기만 하면 고객사별 연간 매출·원가·이익률이 자동으로 다시 계산**되고, 매월 리포트는 Claude Code가 써 주는 고객 관리 앱.

## 2. 누가 쓰나
| 역할 | 하는 일 |
|---|---|
| 담당자(본인) | 매월 계산서·원가 CSV 불러오기, 대시보드 확인, 월간 리포트 요청 |
| 팀원 | 고객사 DB 검색·상세 확인, 엑셀용 CSV 내려받아 공유 양식에 붙이기 |

## 3. 오늘 만들 기능 (필수)
- [ ] **계산서 CSV 불러오기**: `invoices.csv`·`costs.csv` 를 골라 계산서번호로 원가를 붙이고 고객ID로 고객사와 짝짓기(매칭 진행 막대, 안 맞는 건 표시)
- [ ] **연간 대시보드**: KPI 4개(매출·원가·이익·이익률, 작은 추이선), 월별 매출·원가 선 그래프, 고객사별 매출 TOP 막대, 업종별 매출 도넛, 품목·원가 구성 막대
- [ ] **고객사 DB**: 30곳 표(검색·등급 필터·매출순 정렬), 행을 누르면 상세(이익률 게이지·월별 매출 막대·담당자 정보)
- [ ] **엑셀용 CSV 내보내기**: 고객사별 연 매출·원가·이익률 표
- [ ] **Claude Code 월간 리포트 카드**: `report_10.md` 를 대시보드에 표시

## 4. 화면 구성
1. **상단**: 앱 이름 · [연간 매출·원가 대시보드 / 고객사 DB · 계산서 불러오기] 탭 · 기간(2026년 1~10월)
2. **대시보드 탭**: KPI 4개 → 월별 선 그래프 + 고객사 TOP → 업종 도넛 · 구성 막대 · Claude Code 리포트 카드
3. **고객사 DB 탭**: 계산서 불러오기 줄(파일 선택·매칭 진행) → 고객사 표(왼쪽) + 선택한 고객사 상세(오른쪽)
4. 그래프에 **마우스를 올리면 금액이 말풍선으로**, 카드에 올리면 그래프가 다시 채워짐

## 5. 데이터 — 파일과 항목 (모두 가상 데이터)
| 파일 | 항목 |
|---|---|
| `data/clients.csv` | 고객ID, 고객사명, 업종, 등급(A/B/C), 담당자, 직책, 이메일, 지역, 첫거래일 |
| `data/invoices.csv` | 계산서번호, 발행일, 고객ID, 고객사명, 품목, 공급가액, 세액, 합계금액 |
| `data/costs.csv` | 원가ID, 계산서번호, 원가항목(강사료/외주용역/교재·인쇄/장소·식음/기타), 금액 |

- 매출 = 공급가액 합계(세액 제외) · 이익 = 매출 − 원가 · 이익률 = 이익 ÷ 매출 × 100
- 등급: 연 매출 5천만 원 이상 A, 1천만 원 이상 B, 그 밖 C
- 저장 위치: 브라우저 저장공간(localStorage) + CSV 파일. **외부 서버·데이터베이스를 쓰지 않습니다.**

## 6. AI 일은 Claude Code가 합니다
앱 안에서 AI를 부르지 않습니다(사내 기준: 별도 API 키 없음). 대신:
1. 매월 초 Claude Code에게 «월간 리포트를 써줘»라고 요청(요청문은 앱의 [리포트 요청문 복사] 버튼)
2. Claude Code가 세 CSV를 읽어 **누적·당월 실적, 이익률 낮은 고객, 매출 쏠림, 다음 달 확인할 일**을 `report_MM.md` 로 저장
3. 앱이 리포트를 읽어 «Claude Code 월간 리포트» 카드에 표시 — 숫자는 앱 대시보드와 서로 맞춰 봅니다

## 7. 기술 원칙 (로컬 실행)
- 폴더 하나: `Test/client-ledger/` 안에 `index.html`, `style.css`, `app.js`, `data/`
- 순수 HTML·CSS·JavaScript. 외부 인터넷 주소(CDN·글꼴)를 불러오지 않음 — 그래프는 직접 그림
- 금액은 원 단위로 계산하고, 화면에는 만 원·백만 원·억 원으로 보기 좋게 표시
- 실행: `python -m http.server 8765` → 브라우저에서 `http://localhost:8765`
- 결과물은 폴더째 zip으로 묶어 가져감. 인터넷에 올리지(배포하지) 않음

## 8. 원래 요청에서 조정한 부분
| 원래 요청 | 오늘은 이렇게 | 이유 |
|---|---|---|
| 계산서 발행 후 매출이 자동 업데이트 | 계산서 시스템에서 내보낸 CSV를 불러오면 자동 재계산 | 사내 계산서·회계 시스템 직접 연결 불가(외부 연결 금지) |
| 별도 CRM의 고객사 DB | CRM에서 내보냈다고 가정한 `clients.csv` 사용 | 실제 고객 정보 사용 금지 — 가상 고객사 30곳 |
| 공유 엑셀 양식 | 앱에서 엑셀용 CSV 내보내기 → 공유 폴더에 두기 | 외부 배포·서버 금지 |

## 9. 완료 기준 (테스트)
- [ ] 세 CSV를 불러오면 1~10월 매출 **12억 4,610만 원**, 원가 **5억 7,224만 원**, 이익률 **54.1%** 로 표시된다
- [ ] 계산서 **120건**이 모두 고객사와 짝지어지고(매칭 120/120), 거래 고객은 **29곳**으로 나온다
- [ ] 매출 1위 고객사는 **한결건설(2억 6,050만 원, 이익률 52.3%)** 이고, 표에서 누르면 월별 매출 막대 10개가 보인다
- [ ] 10월 이익률이 **46.5%** 로 연중 가장 낮게 표시되고, Claude Code의 `report_10.md` 가 카드에 보인다
- [ ] 새로고침(F5)해도 데이터가 남아 있고, 폴더를 zip으로 풀어도 똑같이 실행된다

## 10. 다음 단계 (집에서 더 키울 것)
- 전년 대비·목표 대비 비교 그래프
- 팀원별 담당 고객 화면, 미수금(입금 확인) 관리
- 계산서 시스템·CRM 자동 연동은 사내 IT 검토 후

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

매월 혼자 확인하는 데는 로컬판으로 충분합니다. 팀원들이 같은 주소에서 대시보드와 고객사 상세를 보게 할 때만 웹앱으로 옮깁니다. **실제 고객·매출 정보는 사내 IT 승인 전에는 넣지 않습니다.**

| 구분 | 로컬판 | 웹앱판 |
|---|---|---|
| 입력 | 담당자가 CSV 불러오기 | 담당자가 올리면 팀 전체에 반영 |
| 저장 | 브라우저 저장공간 + CSV | Supabase 표 3개(고객사·계산서·원가) |
| 화면 주소 | localhost (내 PC) | Vercel 주소 (모두 같은 주소) |
| 권한 | 없음 | 담당자만 불러오기, 팀원은 보기만 |

- 로그인: Supabase 이메일 로그인. 담당자 계정은 «담당자» 역할 표시
- 잠금 설정: 로그인한 사람만 보기, 계산서·원가 불러오기와 고치기는 담당자만
- 매출·이익률 계산법, 등급 기준(A 5천만 원·B 1천만 원), 월간 리포트 카드는 로컬판과 같게 유지
- 계산서 시스템·CRM 자동 연동은 사내 IT 검토 후. 가상 데이터(data 폴더 CSV)로 먼저 시험

### 웹앱판 완료 기준
- [ ] 담당자 계정으로 세 CSV를 올리면 매출 12억 4,610만 원, 이익률 54.1%가 나온다
- [ ] 팀원 계정으로 로그인하면 고객사 29곳의 대시보드는 보이지만 불러오기 버튼은 없다
- [ ] 다른 PC(또는 휴대폰)에서 같은 주소로 들어가도 매출 1위 한결건설(2억 6,050만 원)이 같게 보인다
- [ ] 로그인하지 않으면 고객사·매출 정보가 보이지 않는다