parkcore

ParkCore는 독립 주차 시설 소유자를 대상으로 하는 풀스택 주차 운영 애플리케이션입니다. 이 시스템의 범위는 의도적으로 좁게 설정되어, 예약 중개나 금전 처리가 아닌 주차장의 일상적인 상태 운영에 집중합니다. README에는 예약 마켓플레이스나 결제 플랫폼이 아님을 명확히 명시하고 있습니다. 주요 기능 - 공개 검색: 누구나 읽기 전용 카탈로그를 통해 주소와 시간당 요금으로 활성 주차 시설을 검색하고 필터링할 수 있습니다. - 주차 라이프사이클: 소유자는 시설을 관리하며, 각 시설의 활성화 여부, 공개 여부 및 신규 체크인 허용 여부를 제어합니다. - 세션 운영: 차량 체크인, 활성 세션 모니터링, 숙박 완료 또는 취소, 세션 내역 검토가 가능합니다. - 차량 인식: 번호판을 정규화하여 특정 주차장 내에서 재방문 시 차량 식별 정보를 재사용할 수 있습니다. - 가격 스냅샷: 체크인 시 시간당 요금과 통화가 저장되므로, 이후 시설 설정이 변경되더라도 완료된 총 금액은 정확하게 유지됩니다. 엔지니어링 접근 방식 도메인 규칙은 API 경계에 위치합니다. 체크인을 수락하려면 주차장이 활성 상태여야 하며, 소유자만이 주차장 및 세션을 운영할 수 있습니다. 수용 인원은 직렬화된 지속성 작업과 데이터베이스 제약 조건을 통해 동시 체크인으로부터 보호되며, 이는 동일 주차장 내 중복 활성 차량 진입도 방지합니다. 웹 클라이언트는 계약 기반(contract-driven)으로 작동합니다. TypeScript 패키지인 @parkcore/api-client는 API의 OpenAPI 아티팩트에서 생성되며, pnpm contract:check를 통해 API와 클라이언트 간의 불일치를 감지합니다. 브라우저 앱은 API 내부 구조나 Prisma 타입을 임포트하지 않고, 오직 생성된 클라이언트를 통해서만 API와 통신합니다. 검증은 README에 언급된 시스템 경계에 따라 분리되어 있습니다. 도메인 및 지속성 동작을 위한 PostgreSQL 기반 API 테스트, 컴포넌트 및 라우트를 위한 웹 테스트, 소유자 워크플로우를 위한 Playwright, 그리고 배포된 시스템을 실행할 수 있는 별도의 리얼 스택 체크가 포함됩니다. 아키텍처 및 스택 흐름은 브라우저에서 Vercel 호스팅 웹 앱(React/Vite 및 생성된 API 클라이언트)을 거쳐 Render API, 그리고 Neon PostgreSQL로 이어집니다. API 앱은 인증, 도메인 규칙, 권한 부여 및 Prisma 지속성을 담당합니다. 웹 앱은 공개 검색 및 소유자 운영을 담당하며, 내비게이션에는 React Router를, 서버 상태 관리에는 TanStack Query를 사용합니다. 툴링으로는 pnpm workspaces, Vitest, Playwright, ESLint, Prettier 및 Docker Compose가 포함되며, API 측은 Node.js, Express 5, Prisma, PostgreSQL, Zod 및 OpenAPI를 사용합니다. 시작하기 사전 요구 사항은 Node.js 24, pnpm 10 및 Docker Desktop입니다. API와 웹 앱을 위해 제공된 .env.example 파일을 복사한 후, pnpm install, pnpm docker:up, pnpm db:setup, pnpm dev 순으로 실행합니다. API는 3000번 포트에서, 웹 앱은 보통 5173번 포트에서 실행됩니다. 품질 스크립트는 포맷팅, 린팅, 타입 체크, 커버리지가 포함된 테스트, Playwright E2E 실행, 계약 확인 및 빌드(VITE_API_URL 필요)를 지원합니다. 저장소의 문서는 프로젝트 범위, 아키텍처, 개발 워크플로우, 테스트 및 배포 내용을 다룹니다. 웹 앱의 라이브 데모와 API 상태 확인 엔드포인트는 README에 링크되어 있습니다.