parkcore

ParkCore 是一款面向独立停车场所有者的全栈停车场运营应用程序。其范围被刻意限定在狭窄领域：负责停车场的日常状态运行，而非代理预订或处理资金。README 中明确指出，它不是一个预约市场或支付平台。 核心功能 - 公共发现：任何人都可以通过只读目录，按地址和每小时费率搜索并筛选活跃的停车场。 - 停车生命周期：所有者可以管理其设施，并控制每个设施是否处于活跃状态、是否公开可见以及是否允许新车辆办理入住。 - 会话操作：办理车辆入住、监控活跃会话、完成或取消停留，以及查看会话历史记录。 - 车辆识别：车牌号经过标准化处理，以便在特定停车场内为重复访问的车辆复用身份标识。 - 价格快照：入住时的每小时费率和币种会被存储，因此即使设施的当前配置随后发生变化，已完成的总额依然正确。 工程方法 领域规则位于 API 边界：停车场必须处于活跃状态才能接受入住，且只有所有者可以操作该停车场及其会话。通过可序列化的持久化工作加上数据库约束，容量在并发入住时受到保护，该约束同时防止同一停车场内出现重复的活跃车辆。 Web 客户端采用契约驱动：TypeScript 包 @parkcore/api-client 是由 API 的 OpenAPI 产物生成的，pnpm contract:check 用于检测 API 与客户端之间的偏差。浏览器应用不导入 API 内部实现或 Prisma 类型，仅通过该生成的客户端与 API 通信。 验证工作分布在 README 中提到的系统边界：基于 PostgreSQL 的 API 测试用于验证领域和持久化行为，Web 测试用于组件和路由，Playwright 用于所有者工作流，以及独立的真实堆栈检查用于测试部署后的系统。 架构与技术栈 数据流向为：浏览器 $\rightarrow$ Vercel 托管的 Web 应用（React/Vite 加上生成的 API 客户端） $\rightarrow$ Render API $\rightarrow$ Neon PostgreSQL。API 应用负责身份验证、领域规则、授权和 Prisma 持久化。Web 应用负责公共发现和所有者操作，使用 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 和 Web 应用提供的 .env.example 文件后，文档规定的操作顺序为 pnpm install, pnpm docker:up, pnpm db:setup 和 pnpm dev。API 运行在 3000 端口，Web 应用通常运行在 5173 端口。质量保证脚本涵盖了格式化、Lint 检查、类型检查、带覆盖率的测试、Playwright 端到端运行、契约检查和构建（构建需要 VITE_API_URL）。 仓库中的文档涵盖了项目范围、架构、开发工作流、测试和部署。README 中提供了 Web 应用的实时演示链接和 API 健康检查端点。