VANTAGE VIN · AI-Powered High-End Vehicle Appraisal

Used-car dealer workbench: VIN/search, expert faults (local or Sheet), photo→VIN (AI), Trim recognition, market reference prices, haggling tips, depreciation chart.

Overview

• Search: 17-char VIN or upload car photo → AI identifies make/model and VIN if visible, then fills the box and can auto-run search.
• Backend (server/): GET /api/faults (faults and tips from local expertData or Google Sheet); POST /api/identify-car (image → OpenAI); GET /api/price-radar (local price_ranges or Firecrawl).
• Dealer workbench (after search): Trim + reasoning, market reference (VANTAGE 市场参考价), Expert faults, Haggling Pro, Premium History CTA.

Run locally

1. Frontend

npm install
npm run dev

2. Backend（依赖外部 API 时需配置 .env）

cd server
cp .env.example .env
# 编辑 .env：至少填写 OPENAI_API_KEY；可选 GOOGLE_SHEET_CSV_URL、FIRECRAWL_API_KEY（详见 server/README.md）
npm install
npm run dev

• Vite 将 /api 代理到 http://localhost:3002，前端访问 http://localhost:5173。
• 外部 API：OPENAI_API_KEY（必填）；GOOGLE_SHEET_CSV_URL、FIRECRAWL_API_KEY 可选（通病/价格当前用本地 expertData.json，Firecrawl 建议先不配）。详见 server/README.md。

通病与砍价数据（本地）

通病与砍价话术来自 src/data/expertData.json，与前端同源。需要修改时在 Cursor 里直接编辑该文件即可，无需配置 Google Sheet 或其它外部 API。详见 server/README.md。

Build

npm run build
npm run preview

测试与 Git 自动跑测

• 本地一条命令跑全量测试：在项目根目录执行 npm run test:all（前端 Vitest + 后端 Node test）。
• Git 提交前自动跑测试（可选）：在项目根目录执行一次 npm run install-hooks，之后每次 git commit 前会自动跑测试，失败则无法提交。
• GitHub 上自动跑测试：代码推送到 main / master 或发起 PR 时，会在 GitHub Actions 里自动跑 npm run test:all，可在仓库的 Actions 页查看结果。

Stack

• React 18, Vite 6, Tailwind CSS 3, Lucide React, Chart.js
• Node (Express), OpenAI API (gpt-4o-mini), local expertData / optional Google Sheet & Firecrawl