English Version | 项目规范 | 原型说明
Veloform 是一款基于 Next.js、Tailwind CSS 并由 Firebase 驱动的高级自行车配置器应用。它允许用户浏览和定制不同类别自行车的配置清单，包括公路车 (Road)、山地车 (MTB) 和折叠车 (Fold)。
生产地址: https://veloform.app
代码仓库: https://github.com/sutchan/Veloform
- Apple 风格设计: 采用极简主义设计理念，充足留白、清晰视觉层次、大图展示、SF Pro 字体、Apple Blue 主色调
- 双主题支持: 支持深色/浅色双主题模式，风格统一
- 实时价格与重量计算: 动态计算并展示整车造价及预计重量
- 配置云同步: 深度集成 Firebase Firestore 和 Auth，安全留存用户的独家配置方案
- 自动同步机制: 用户登录后自动加载云端配置，实现多设备间数据同步
- 车型分类: 在公路车、山地车和折叠车间无缝瞬间切换
- 完美响应式: 贯彻移动端优先范式，但保留毫不妥协的桌面端设计美学体验
- 双语支持: 内置 EN/ZH-CN 国际化系统，一键切换语言
- 配置库管理: 保存、加载、分享个人配置方案
- 流畅动画: 基于 Framer Motion 的微交互动画，提供自然流畅的用户体验
- 性能优化: 选择性状态订阅，避免不必要的组件重渲染
完整技术栈说明见 架构概览。
| 技术 | 版本 | 用途 |
|---|---|---|
| Next.js | v14.1.0 | App Router 架构，React Server Components |
| React | v18.2.0 | UI 组件库 |
| Zustand | v4.5.0 | 轻量级状态管理 |
| Tailwind CSS | v3.4.0 | 样式框架 |
| Firebase | v10.0.0 | Firestore 数据库与 Auth 身份验证 |
| Framer Motion | v10.16.4 | 动画效果 |
| Lucide React | v0.294.0 | 图标库 |
src/
├── app/ # App Router 路由文件
│ ├── layout.tsx # 根布局（含 SyncProvider）
│ ├── page.tsx # 首页/配置器
│ ├── providers.tsx # 全局提供者
│ ├── globals.css # 全局样式
│ └── library/
│ └── page.tsx # 配置库页面
├── components/ # UI 组件
│ ├── configurator/ # 配置器组件
│ │ ├── BikeTypeSelector.tsx # 车型选择器
│ │ ├── BuildList.tsx # 组件清单
│ │ ├── ComponentDetailModal.tsx # 组件详情模态框
│ │ ├── ComponentSelector.tsx # 组件选择器
│ │ ├── CostBreakdownChart.tsx # 成本分解图表
│ │ ├── RecommendedConfigs.tsx # 推荐配置
│ │ ├── ShareModal.tsx # 分享模态框
│ │ └── SummaryPanel.tsx # 汇总面板
│ ├── layout/ # 布局组件
│ │ └── Navbar.tsx # 导航栏
│ ├── ui/ # 通用 UI 组件
│ │ ├── Button.tsx # 按钮
│ │ ├── Card.tsx # 卡片
│ │ ├── ErrorBoundary.tsx # 错误边界
│ │ ├── Modal.tsx # 模态框
│ │ ├── OnboardingGuide.tsx # 新手引导
│ │ ├── SupportModal.tsx # 支持模态框
│ │ ├── ThemeToggle.tsx # 主题切换
│ │ └── Toast.tsx # Toast 通知
│ └── SyncProvider.tsx # 云同步提供者（Auth + Firestore）
├── lib/ # 工具库
│ ├── auth.ts # Firebase 认证服务
│ ├── constants.ts # 应用常量
│ ├── env.ts # 环境变量验证
│ ├── firebase-service.ts # Firebase Firestore 服务
│ ├── firebase.ts # Firebase 配置
│ ├── store.ts # Zustand 状态管理（含选择性 hooks）
│ ├── utils.ts # 工具函数
│ ├── toast.ts # Toast 通知
│ ├── recommended-configs.ts # 推荐配置
│ ├── data/ # 模块化数据
│ │ ├── index.ts
│ │ ├── component-details.ts
│ │ └── component-alternatives.ts
│ └── i18n/ # 国际化
│ ├── index.ts
│ ├── en.ts
│ └── zh-CN.ts
└── types/ # TypeScript 类型定义
└── index.ts # 强化类型定义（含组件规格接口）
详细开发规范请参阅 openspec/PROJECT_GUIDELINES.md。
- Node.js >= 18.x
- npm 或 pnpm
- Firebase 项目（用于后端服务）
-
克隆仓库：
git clone https://github.com/sutchan/Veloform.git cd Veloform -
安装依赖：
npm install # 或使用 pnpm pnpm install -
配置环境变量：
cp .env.example .env # 编辑 .env 填入 Firebase 配置 -
启动开发服务器：
npm run dev
-
访问应用： 浏览器打开
http://localhost:3000
- 访问 Firebase Console
- 创建新项目或选择现有项目
- 启用 Authentication（Email/Password）
- 启用 Firestore Database
- 在项目设置中获取 Web App 配置
- 将配置值填入
.env文件
| 命令 | 说明 |
|---|---|
npm run dev |
启动开发服务器（端口 3000） |
npm run build |
构建生产版本 |
npm run start |
启动生产服务器 |
npm run lint |
运行 ESLint 检查 |
npm run test |
运行单元测试 |
npm run test:coverage |
运行测试并生成覆盖率报告 |
完整的开发约定、分支与提交规则、测试要求和文档维护指南，请参阅：
- openspec/README.md - 规范文档索引（推荐从这里开始）
- openspec/PROJECT_GUIDELINES.md - 项目开发指南
- openspec/design/ui-design-system.md - UI 设计系统
- openspec/prototype-guide.md - 原型图说明
- openspec/design/design-review.md - 设计审查与优化建议
本项目支持以下部署平台：
- Vercel: 推荐部署平台，零配置自动部署
- EdgeOne Pages: 腾讯云边缘部署方案
部署指南见 环境配置。
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'feat: add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
提交前请确保：
- 所有测试通过 (
npm run test) - Lint 检查通过 (
npm run lint) - 遵循 编码规范
MIT License
当前版本：v3.7.0
最后更新：2026-06-08
详细变更记录见 CHANGELOG.md。