freepasserp4

프리패스 ERP v4는 저신용·무심사 니치 렌터카 중개(brokerage) 업무를 위한 ERP로, v3(바닐라 SPA)의 손롤 라우터와 페이지 파편화를 걷어내고 jpkerp6에서 검증한 원자화 아키텍처를 프리패스 도메인에 맞게 재건축한 버전이다. v3는 라이브(Vercel)에서 무중단 유지하고, v4는 로컬 우선으로 구축한 뒤 안정화 후 원격/마이그레이션하는 전략을 취한다. 실행은 npm install 후 npm run dev로 http://localhost:4004 에서 확인한다. Firebase가 설정되지 않으면 lib/store.ts가 자동으로 LocalAdapter(localStorage)로 폴백해 바로 동작하며, 첫 실행 시 lib/seed.ts의 샘플 계약이 주입된다. 아키텍처는 5층 원자화로 구성되어 페이지에 JSX나 계산 로직을 직접 작성하지 않는다. ① 엔티티 SSOT(lib/intake/entities.ts)는 ENTITIES 하나로 직접입력·엑셀·OCR 3방식 폼을 동시에 생성하며 ocrFrom/manual/idFrom을 포함한다. ② 저장 원자(lib/store.ts)는 단일 StoreAdapter(Local/Firestore/Dispatch)로 자연키 dedup, soft-delete, 회사격리(companyId)를 처리한다. ③ UI 원자(components/ui/index.tsx)는 ObjCard(목록 단일원자 56px), Sec, Cards, Metric, Badge, DataTable(모바일=카드), Modal, FormGrid를 제공한다. ④ 섹션(콕핏, app/page.tsx)은 상태가 던지는 질문으로 분류해 심사대기·발송대기·운행중·환수구간·채권을 다룬다. ⑤ 도메인 엔진(lib/domain/*)은 순수함수로 marginFee(공급사수수료−영업자수수료)와 clawbackWatch(무보증 3·6개월 환수)를 계산한다. jpkerp(직영)과 다른 축으로, 차량은 매입/감가/매각이 아니라 공급사·공급가·마진을 중심으로 하고 계약은 미수 중심이 아니라 상품유형·심사·영업자·커미션·환수를 중심으로 한다. partner(영업자)와 supplier(공급사)는 직영에 없는 2-sided 엔티티다. 설계 철칙으로 원자·카드로만 구성(새 목록/상세는 ObjCard+Sec 재사용, 손롤 카드/인라인 금지), 웹·모바일 통일(원자가 useIsMobile로 반응형 내장, 한쪽 전용은 명시 합의 시만), 오류 구조적 방지(라우트 파일 named export 금지, dev/build 격리, 문자열 날짜비교 지양, silent truncation 시 잔여 표기)를 둔다. 현재 골격·인프라·엔티티 SSOT·홈 콕핏(계약 슬라이스)은 완료되었고, 계약 상세(Drawer)·심사/발송/서명 액션·커미션 정산·환수 트래킹, 차량(매물)·영업자·공급사 슬라이스, OCR intake(계약서·면허·등록증)·엑셀 임포트, v3→v4 마이그레이션 어댑터, 프리패스 전용 Firebase 연결(원격)은 미완료 상태다. 모든 AI·작업자는 작업 시작 전 AGENTS.md의 역할 분담(Claude=설계·게이트 / Cursor=노가다 / Codex=전수검증)과 불변 규칙·게이트를 확인해야 한다.