pdutta25/devex-bike-shop

# DevEx Bike Shop 一个全栈演示电商应用，专为高端自行车店打造 —— 使用 Next.js 14+、Drizzle ORM、SQLite 和 Tailwind CSS 构建。功能包括深色主题商店前台、购物车、模拟结账、带有销售分析的管理后台以及一键数据填充。 ## 技术栈 | 层级 | 技术 | |---|---| | **Framework** | Next.js 14+ (App Router, Server Components) | | **Language** | TypeScript | | **Database** | SQLite via better-sqlite3 | | **ORM** | Drizzle ORM | | **Styling** | Tailwind CSS | | **Charts** | Recharts | | **Validation** | Zod | | **Font** | Inter (Google Fonts) | | **Testing** | Vitest | | **Linting** | ESLint | | **Security Scanning** | Trivy + npm audit | | **Code Quality** | SonarCloud | | **CI** | GitHub Actions | | **CD** | Harness | ## 功能 ### 商店前台 - **Homepage** — Hero 区域、精选自行车、分类网格、促销横幅 - **Catalog** — 浏览 8 个类别共 48 款自行车，支持排序和筛选 - **Product Detail** — SVG 自行车插图、规格表、客户评论、相关产品 - **Shopping Cart** — 服务端持久化购物车，支持尺寸/颜色选择 - **Checkout** — 配送/自提切换、收货地址、模拟支付表单 - **Order Tracking** — 订单历史及可视化状态时间线 - **Wishlist** — 稍后保存自行车 - **Search** — 全文产品搜索 - **Account** — 基于 Cookie 的客户识别（无密码） ### 管理后台 - **KPI Cards** — 总收入、订单数、平均订单金额、产品数量 - **Revenue Chart** — 30 天收入趋势 - **Order Management** — 查看所有订单、更新状态、取消订单 - **Product CRUD** — 创建、编辑、删除产品及完整规格管理 - **Inventory** — 库存水平、低库存预警、行内库存更新 - **Reports** — 收入趋势、热销产品、按状态统计订单、分类表现 - **Data Seeding** — 带进度指示器的一键填充/重置 ### 设计 - **Dark Theme** — 深炭色 (`#0f0f1a`) 配琥珀色点缀 (`#f59e0b`) - **Glassmorphism** — 毛玻璃效果的顶部导航栏，带滚动检测 - **SVG Illustrations** — 分类主题自行车插图（无外部图片） - **Responsive** — 手机、平板和桌面布局 - **Animations** — 淡入、悬停效果、渐变移动、发光阴影 ## 入门指南 ### 前置条件 - Node.js 18+ - npm ### 安装 ``` git clone https://github.com/pdutta25/devex-bike-shop.git cd devex-bike-shop npm install ``` ### 运行开发服务器 ``` npm run dev ``` 在浏览器中打开 [http://localhost:3000](http://localhost:3000)。 ### 填充演示数据 1. 访问 [http://localhost:3000/admin/seed](http://localhost:3000/admin/seed) 2. 点击 **"Seed Everything"** 以向数据库填充： - 8 个类别共 48 款产品 - 60 位客户 - 200 个订单（跨度 90 天） - 280+ 条评论 SQLite 数据库会在首次运行时自动创建于 `data/bikeshop.db`。 ## 项目结构 ``` src/ ├── app/ │ ├── (storefront)/ # Customer-facing pages │ │ ├── bikes/ # Catalog + product detail │ │ ├── category/ # Category filtered views │ │ ├── cart/ # Shopping cart │ │ ├── checkout/ # Checkout + confirmation │ │ ├── orders/ # Order history + detail │ │ ├── wishlist/ # Saved items │ │ ├── search/ # Search results │ │ └── account/ # Customer account │ ├── (admin)/admin/ # Admin dashboard │ │ ├── orders/ # Order management │ │ ├── products/ # Product CRUD │ │ ├── inventory/ # Stock management │ │ ├── reports/ # Analytics charts │ │ ├── customers/ # Customer list │ │ └── seed/ # Data seeding controls │ └── api/ # REST API routes ├── components/ │ ├── ui/ # Reusable UI primitives │ ├── layout/ # Header, footer, admin sidebar │ ├── cart/ # Cart icon │ └── providers/ # Context providers ├── lib/ │ ├── db/ # Schema, connection, migrations │ ├── queries/ # Database query functions │ ├── seed/ # Data generation modules │ ├── utils.ts # Helpers (formatPrice, cn, etc.) │ ├── constants.ts # Enums, categories, config │ └── validations.ts # Zod schemas └── hooks/ # Custom React hooks ``` ## 数据库 Schema | 表 | 描述 | |---|---| | `categories` | 8 个自行车类别 (公路车、山地车、混合动力车、电动自行车、童车、巡航车、砾石车、小轮车) | | `products` | 自行车及其定价、规格、库存水平、评分 | | `customers` | 客户资料（基于邮箱识别） | | `orders` | 订单及状态跟踪、履约类型、支付信息 | | `order_items` | 订单行项目及产品快照 | | `reviews` | 星级评分和文字评论 | | `wishlists` | 每位客户保存的产品 | | `cart_items` | 基于会话的购物车 | ## 关键页面 | 路由 | 描述 | |---|---| | `/` | 包含 Hero、精选自行车、分类的首页 | | `/bikes` | 带筛选和排序的完整目录 | | `/bikes/[slug]` | 产品详情及规格和评论 | | `/category/[slug]` | 分类筛选视图 | | `/cart` | 购物车 | | `/checkout` | 结账表单 | | `/orders` | 订单历史 | | `/admin` | 仪表板及 KPI 和图表 | | `/admin/products` | 产品管理 | | `/admin/inventory` | 库存水平和预警 | | `/admin/reports` | 销售分析 | | `/admin/seed` | 数据填充控制 | ## 测试 单元测试使用 [Vitest](https://vitest.dev/) 编写 —— 共 67 个测试，分布在 3 个套件中，覆盖工具函数、验证 schema 和应用程序常量。 ``` npm test # Run all tests once npm run test:watch # Run in watch mode during development ``` | 套件 | 测试数 | 覆盖范围 | |---|---|---| | `utils.test.ts` | 29 | `formatPrice`, `generateOrderNumber`, `slugify`, `generateSku`, `cn`, `randomBetween`, `pickRandom`, `shuffleArray` | | `validations.test.ts` | 24 | `customerSchema`, `checkoutSchema`, `productSchema`, `reviewSchema` — 有效数据、无效数据、边缘情况 | | `constants.test.ts` | 14 | 订单状态、支付状态、履约类型、税率、运费、分类、产品规格 | ## CI/CD 流水线 ### GitHub Actions (CI) 每次向 `main` 分支的推送和 PR 都会触发一个多阶段 CI 流水线，使用真实工具： ``` build ──┐ lint ──┤──→ security-scan ──┐ test ──┤──→ code-quality ──┤──→ deploy-gate └────────────────────┘ ``` | 阶段 | 工具 | 描述 | |---|---|---| | 🔨 **Build** | Next.js | 生产构建及构件上传 | | 📋 **Lint** | ESLint | 代码检查（非阻塞） | | 🧪 **Test** | Vitest | 覆盖工具函数、验证和常量的 67 个单元测试 | | 🛡️ **Security Scan** | Trivy + npm audit | 文件系统漏洞扫描 (CRITICAL/HIGH) 及依赖审计 | | 📊 **Code Quality** | SonarCloud | 静态分析、代码异味、可维护性（非阻塞） | | 🚀 **Deploy Gate** | Harness webhook | 成功构建 main 分支后触发 CD 流水线 | 其他 CI 工作流： - **AI PR Review** — 使用 GitHub Copilot 对 PR 进行自动代码审查 - **AI Release Notes** — 标签推送时自动生成发布说明 - **Auto Docs** — 生成 API 和 schema 文档，发布到 GitHub Wiki（仅限 main 分支） 流水线特性： - **Path filtering** — 跳过仅更改 markdown/文档的 CI - **Concurrency groups** — 快速推送时取消正在进行的运行 - **Dependabot grouping** — 次要/补丁 npm 更新和 GitHub Actions 更新被分组到单个 PR 中 ### Harness (CD) 通过 [Harness](https://harness.io/) 进行持续部署，采用三阶段流水线： | 阶段 | 环境 | 审批 | |---|---|---| | **DEV** | Development | 自动审批 | | **SIT** | System Integration Testing | 自动审批 | | **PROD** | Production | 需人工审批 | ## 脚本 ``` npm run dev # Start development server npm run build # Production build npm run start # Start production server npm run lint # Run ESLint npm test # Run unit tests (Vitest) npm run test:watch # Run tests in watch mode npm run db:push # Push schema changes to SQLite npm run db:studio # Open Drizzle Studio (DB browser) npm run docs # Generate API & schema docs npm run docs:ai # Generate AI-powered UX docs ``` ## 许可证 [MIT](LICENSE)

标签：API集成, CISA项目, DNS 反向解析, Drizzle ORM, GitHub Actions, Harness, PoC框架, React, Recharts, SEO, SonarCloud, SQLite, Syscalls, Tailwind CSS, TypeScript, Vitest, Zod, 代码示例, 仪表盘, 可观测性, 后端开发, 在线支付, 安全扫描, 安全插件, 库存管理, 数据分析, 时序注入, 演示项目, 电商平台, 管理系统, 网店系统, 自动笔记, 自行车店, 购物车