Zoe-life/rest-shop
GitHub: Zoe-life/rest-shop
一个基于 MERN 技术栈的生产级电商平台，采用 Cloudflare Workers 边缘代理架构，集成多支付网关和企业级安全特性。
Stars: 1 | Forks: 0
# 具备 React 前端的 RESTful 电子商务平台
[](https://github.com/Zoe-life/rest-shop/actions/workflows/ci-cd.yml)
[](https://helmetjs.github.io/)
[](LICENSE)
一个现代化的全栈电子商务平台，采用双后端架构（Node.js + Cloudflare Workers）和 React TypeScript 前端。
## 前端演示
- **在线演示**: [Cloudflare Pages](https://rest-shop-frontend.pages.dev)
- **功能特性**:
- 日间/夜间模式切换
- 完全响应式设计
- 藏红花色与海军蓝主题
- 在 Cloudflare Pages 上拥有极速性能
## 仓库结构
```
rest-shop/
│
├─ frontend/ ← React + TypeScript + Tailwind CSS
│ ├─ src/
│ │ ├─ components/ # Reusable components
│ │ ├─ pages/ # Page components
│ │ ├─ contexts/ # React contexts (Auth, Theme)
│ │ ├─ api/ # API configuration
│ │ └─ App.tsx
│ ├─ public/
│ └─ package.json
│
├─ api/ ← Node + Express + Mongoose
│ ├─ models/
│ ├─ routes/
│ ├─ controllers/
│ ├─ middleware/
│ ├─ services/
│ ├─ config/
│ ├─ utils/
│ ├─ test/
│ ├─ server.js
│ └─ package.json
│
├─ worker/ ← Cloudflare Worker (Edge Proxy)
│ ├─ src/
│ │ └─ index.js
│ ├─ wrangler.toml
│ └─ package.json
│
├─ docs/ ← Comprehensive documentation
└─ README.md
```
## 目录
- [概述](#overview)
- [前端特性](#frontend-features)
- [架构](#architecture)
- [连接 Worker 到 Node.js 后端](#-connecting-the-worker-to-the-nodejs-backend)
- [功能特性](#features)
- [增强功能](#enhanced-features)
- [安全特性](#security-features)
- [性能特性](#performance-features)
- [技术栈](#technologies-used)
- [快速开始](#getting-started)
- [前置条件](#prerequisites)
- [安装](#installation)
- [配置](#configuration)
- [运行应用](#running-the-application)
- [API 端点](#api-endpoints)
- [文档](#documentation)
- [部署](#deployment)
- [CI/CD 流水线](#cicd-pipeline)
- [测试](#testing)
- [监控与可观测性](#monitoring-and-observability)
- [贡献](#contributing)
## 概述
这是一个全面的、**专业级全栈电子商务平台**，包含：
- **现代 React 前端**: TypeScript, Tailwind CSS, 响应式设计
- **RESTful API 后端**: Node.js, Express, Mongoose, MongoDB
- **边缘分发**: Cloudflare Workers 代理，实现全球性能优化
- **企业级功能**: 支付处理 (Stripe, PayPal, M-Pesa)，身份验证，订单管理
- **自动化 CI/CD**: GitHub Actions 实现持续部署
## 前端特性
### 现代 UI/UX
- **主题色**: 鲜艳的藏红花色 (#FF9933) 和海军蓝 (#002366)
- **深色/浅色模式**: 切换功能，通过 localStorage 持久化
- **响应式设计**: 移动优先，适配所有屏幕尺寸
- **简洁界面**: 专业、直观且用户友好
### 技术栈
- **React 19** 与 TypeScript
- **Tailwind CSS** 用于样式
- **React Router** 用于导航
- **Context API** 用于状态管理 (Auth, Theme, Cart)
- **Axios** 用于 API 通信
### 页面与功能
- **首页**: Hero 区域，包含特色产品和价值主张
- **产品浏览**: 网格布局，包含图片、价格和库存状态；支持添加到购物车
- **购物车与结账**: 持久化购物车，支持多种支付方式 (Card, Stripe, PayPal, M-Pesa)
- **身份验证**: 登录、注册和 OAuth 社交登录页面
- **订单管理**: 查看订单历史和状态
- **支付历史**: 认证用户的完整交易日志
- **关于与联系**: 带有联系表单的信息页面
- **管理后台**: 受保护的面板，用于管理产品、订单和用户
- **主题切换**: 无缝的日间/夜间模式切换
详细的前端文档请参阅 [Frontend README](./frontend/README.md)。
## 架构
### Cloudflare Workers 兼容的代理架构
应用采用 **三层代理架构**：
```
Frontend (Cloudflare Pages)
↓ HTTPS
Cloudflare Workers (Edge Proxy)
↓ HTTPS
Node.js Backend (Render)
↓
MongoDB Atlas
```
**组件:**
- **Frontend** (~100KB): React SPA 部署到 Cloudflare Pages
- **Cloudflare Workers** (~10KB): 轻量级边缘代理，用于全球分发
- **Node.js Backend**: 完整的 API，包含 Mongoose/MongoDB 操作
- **MongoDB Atlas**: 云数据库
**优势:**
- 前端的全球 CDN 分发
- 通过 Workers 实现快速边缘路由
- Node.js 中可靠的 Mongoose/MongoDB 操作
- 所有层的独立扩展
- 行业标准的架构模式
**部署:**
- Frontend: Cloudflare Pages (通过 GitHub Actions 自动部署)
- Workers: Cloudflare Workers (通过 GitHub Actions 自动部署)
- Backend: Render (推送时自动部署)
详细文档请参阅：
- [完整部署指南](docs/FULL_DEPLOYMENT_GUIDE.md)
- [GitHub CI/CD 设置](docs/GITHUB_SECRETS_CICD_GUIDE.md)
- [代理架构说明](docs/CLOUDFLARE_WORKERS_PROXY_ARCHITECTURE.md)
### 旧版微服务架构（已弃用）
以前的架构尝试使用 Durable Objects 在 Workers 中直接运行 Mongoose。这已被上面的代理架构取代，以解决运行时不兼容问题。
### 部署命令
```
# 部署所有服务
npm run deploy:all
# 部署单个服务
npm run deploy:base # Base service
npm run deploy:payments # Payment service
npm run deploy:gateway # Gateway (main entry point)
```
## 连接 Worker 到 Node.js 后端
**最重要的一步：** Cloudflare Worker 充当代理，需要知道你的 Node.js 后端运行在哪里。
### 快速设置
1. **部署你的 Node.js 后端** (Render 或 VPS):
# 使用 Render 示例
# 在 Render 控制面板连接你的 GitHub 仓库
# 获取你的 URL: https://your-app.onrender.com
2. **在你的 worker 中设置后端 URL**:
cd worker
wrangler secret put BACKEND_API_URL
# 输入: https://your-app.onrender.com
3. **部署 worker**:
wrangler deploy
4. **测试连接**:
curl https://your-worker.workers.dev/health
# 应该显示 worker 和 backend 都是 ok 的
### 本地开发
你可以完全跳过 worker，直接将前端连接到后端：
```
# 仅运行 Node.js 后端
npm start
# 后端运行在 http://localhost:3001
# 将前端指向：http://localhost:3001
```
### 详细指南
请参阅 **[连接指南](docs/CONNECTION_GUIDE.md)** 了解：
- 分步说明
- 多种部署选项 (Render, VPS)
- 常见问题排查
- 配置验证脚本
### 验证脚本
检查你的后端是否正确连接：
```
node api/scripts/validate-connection.js [worker-url]
# 示例：
node api/scripts/validate-connection.js https://your-app.onrender.com https://your-worker.workers.dev
```
## 功能特性
### 核心功能
- 使用 JWT 的用户身份验证和管理
- OAuth 2.0 集成 (Google, Microsoft, Apple)
- 多网关支付处理 (Stripe, PayPal, M-Pesa)
- 产品管理，支持搜索、过滤和分页
- 高级订单管理，包含状态跟踪
- 基于角色的访问控制 (Admin/User)
- 产品图片的文件上传
- 库存跟踪（库存水平, SKU）
- 支付历史和交易日志
- 用于支付回调的 Webhook 处理
- 全面的错误处理
- GitHub Actions CI/CD 流水线
- Cloudflare Workers 部署就绪
### 增强功能
#### 安全增强
- **邮箱验证**: 使用有时限的 Token 进行安全邮箱验证（24小时过期）
- **密码重置**: 带有邮件通知的安全密码重置功能（1小时过期）
- **双因素认证 (2FA)**: 基于验证器应用的 TOTP 2FA (Google Authenticator, Authy)
- 生成 QR 码以便轻松设置
- 10 个备用代码用于账户恢复
- 基于时间的一次性密码（符合 RFC 6238 标准）
- **API 版本控制**: `/api/v1` 端点，保持对旧版路由的向后兼容性
#### 性能特性
- **Redis 缓存**: 对 GET 请求进行自动响应缓存
- 每个端点可配置的 TTL
- 变更时自动使缓存失效
- 如果 Redis 不可用，则优雅降级
- **数据库索引**: 为常用查询字段优化索引
- **延迟加载**: 使用 Mongoose populate 进行选择性字段加载
- **CDN 集成**: 使用 Cloudinary 优化图片交付
#### 实时功能
- **WebSocket 通知**: 即时订单和支付状态更新
- 用户特定的通知通道
- 受 CORS 保护的 WebSocket 连接
- 自动重连处理
- **邮件通知**: 订单状态变更的自动邮件提醒
#### 测试与质量
- **自动化测试**: 使用 Mocha/Chai 的全面测试套件
- **负载测试**: 基于 Artillery 的性能测试场景
- **集成测试**: 完整的工作流测试
- **安全测试**: npm audit, Snyk, CodeQL 集成
**详细文档请参阅：**
- [增强功能指南](docs/ENHANCED_FEATURES.md) - 完整的设置和使用指南
- [监控与可观测性](docs/MONITORING_OBSERVABILITY.md) - APM, 指标和告警
- [测试指南](docs/TESTING_GUIDE.md) - 全面的测试文档
## 支付集成
### 支持的支付方式
- **Stripe**: 信用卡/借记卡支付（全球）
- **PayPal**: PayPal 账户支付（全球）
- **M-Pesa**: 肯尼亚用户的移动货币（肯尼亚特定）
### 支付功能
- **安全交易处理**: 符合 PCI 标准的支付处理
- **实时支付验证**: 即时支付状态更新
- **Webhook 集成**: 自动回调处理
- **多币种支持**: USD, EUR, GBP, KES
- **交易日志**: 完整的审计跟踪
- **支付状态跟踪**: 实时订单更新
- **退款支持**: 内置退款功能 (Stripe, PayPal)
详细集成说明请参阅 [Payment API Documentation](docs/PAYMENT_API_DOCUMENTATION.md) 和 [M-Pesa Setup Guide](docs/MPESA_SETUP_GUIDE.md)。
## 安全特性
### 生产级安全
- **Helmet.js**: 安全头 (CSP, HSTS, X-Frame-Options, XSS protection)
- **CORS**: 可配置的源限制
- **速率限制**:
- API 端点: 100 请求/15分钟
- 身份验证: 5 次尝试/15分钟
- 注册: 5 个账户/小时
- **输入验证**: 所有路由上的 express-validator
- **密码安全**: 带有强度要求的 Bcrypt 哈希
- **请求净化**: 使用 xss 库进行全面 XSS 防护
- **ObjectId 验证**: 防止注入攻击
- **JWT**: 1小时 Token 过期
- **OAuth 2.0**: 使用一次性交换码的安全第三方身份验证 — JWT 绝不会出现在重定向 URL 中（消除浏览器历史记录、服务器日志和 `Referer` 泄露）
- **HMAC State**: 用于 OAuth 流程的无状态 CSRF 保护 (RFC 6749 §10.12)
- **支付安全**: 加密支付数据，交易日志
- **PCI 合规就绪**: 服务器上不存储卡数据
### 支付安全
- **Tokenization**: 不存储卡详情 (Stripe tokens)
- **Webhook 验证**: 加密签名验证
- **IP 白名单**: 将支付回调限制为网关 IP
- **交易加密**: 敏感支付元数据已加密
- **审计日志**: 完整的交易历史
### 密码要求
- 至少 8 个字符
- 至少一个大写字母
- 至少一个小写字母
- 至少一个数字
- 至少一个特殊字符 (@$!%*?&)
## 技术栈
### 前端
- **React 19**: 现代 UI 库
- **TypeScript**: 类型安全的 JavaScript
- **Tailwind CSS**: 实用优先的 CSS 框架
- **React Router**: 客户端路由
- **Axios**: 用于 API 请求的 HTTP 客户端
- **Context API**: 状态管理
### 后端
- **运行时**: Node.js 18.x/20.x
- **框架**: Express.js 4.x
- **数据库**: MongoDB Atlas 与 Mongoose 8.x（带有用于可扩展性的索引）
- 详见 [Database Migration Analysis](docs/DATABASE_MIGRATION_ANALYSIS.md) 了解替代选项
- 详见 [Mongoose Troubleshooting Guide](docs/MONGOOSE_TROUBLESHOOTING.md) 了解常见问题
- **身份验证**: JWT (jsonwebtoken), Passport.js, OAuth 2.0
- **OAuth 提供商**: Google, Microsoft, Apple
- **支付网关**:
- Stripe (Credit/Debit cards)
- PayPal (PayPal accounts)
- M-Pesa Daraja API (Mobile money - Kenya)
- **HTTP 客户端**: Axios (用于支付网关 API)
- **安全**: Helmet, CORS, express-rate-limit, express-validator, xss
- **文件上传**: Multer, Cloudinary
- **测试**: Mocha, Chai, Sinon, Supertest
- **日志**: Morgan, 自定义交易日志
- **环境**: dotenv
### 部署
- **Frontend**: Cloudflare Pages
- **Edge Layer**: Cloudflare Workers
- **Backend**: Render/VPS
- **CI/CD**: GitHub Actions
- **Database**: MongoDB Atlas
## 快速开始
### 前置条件
- Node.js (v 或更高)
- MongoDB Atlas 账户
- npm 或 yarn 包管理器
- Git
### 安装
1. 克隆仓库：
git clone https://github.com/Zoe-life/rest-shop.git
cd rest-shop
2. 为所有组件安装依赖：
# 安装后端依赖
cd api && npm install
# 安装 worker 依赖
cd ../worker && npm install
# 安装前端依赖
cd ../frontend && npm install
### 配置
#### 1. 后端配置
在 `api/` 目录下创建 `.env` 文件（或从 `.env.example` 复制）：
```
cd api
cp ../env.example .env
```
根据你的配置编辑 `.env` 文件：
```
# 核心配置
MONGODB_URI=mongodb+srv://username:password@cluster0.lifak.mongodb.net/
MONGO_ATLAS_PW=your_mongo_password
JWT_KEY=your_jwt_secret_key
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:3001,http://localhost:5173
FRONTEND_URL=http://localhost:5173
PORT=3001
# 后端 API URL (用于 OAuth 回调)
# 用于本地开发：http://localhost:3001
# 用于生产环境：https://your-backend.onrender.com 或您部署的 URL
BACKEND_API_URL=http://localhost:3001
# 邮件服务 (用于验证和密码重置)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@example.com
SMTP_PASS=your-smtp-password
EMAIL_FROM=noreply@rest-shop.com
# Redis 缓存 (可选 - 用于性能优化)
REDIS_URL=redis://localhost:6379
# 或者使用单独的设置：
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
# OAuth (可选 - 用于社交登录)
# 从 https://console.cloud.google.com/apis/credentials 获取凭据
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3001/auth/google/callback
# 从 https://portal.azure.com 获取凭据
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_CALLBACK_URL=http://localhost:3001/auth/microsoft/callback
# 从 https://developer.apple.com 获取凭据
APPLE_CLIENT_ID=your-apple-client-id
APPLE_TEAM_ID=your-apple-team-id
APPLE_KEY_ID=your-apple-key-id
APPLE_CALLBACK_URL=http://localhost:3001/auth/apple/callback
# 支付网关 (可选 - 用于支付处理)
STRIPE_SECRET_KEY=your-stripe-secret-key
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
MPESA_CONSUMER_KEY=your-mpesa-consumer-key
MPESA_CONSUMER_SECRET=your-mpesa-consumer-secret
```
**重要说明：**
- 对于 **生产部署**，将 `BACKEND_API_URL` 设置为你部署的后端 URL（例如 `https://your-app.onrender.com`）
- OAuth 回调 URL 必须与你在 OAuth 提供商控制台中配置的完全一致
- 如果 `GOOGLE_CALLBACK_URL` 未设置，则默认为 `{BACKEND_API_URL}/auth/google/callback`
#### 2. 前端配置
在 `frontend/` 目录下创建 `.env` 文件（或从 `.env.example` 复制）：
```
cd frontend
cp .env.example .env
```
`.env` 文件应包含：
```
VITE_BACKEND_URL=http://localhost:3001
```
#### 3. MongoDB Atlas 设置
- 在 https://cloud.mongodb.com 创建集群
- 将你的 IP 添加到 IP 访问列表
- 创建数据库用户
- 获取你的连接字符串
**配置指南：**
- [OAuth Setup Guide](docs/OAUTH_SETUP.md) - 配置社交登录
- [Payment Setup](docs/PAYMENT_API_DOCUMENTATION.md) - 支付网关配置
- [M-Pesa Setup](docs/MPESA_SETUP_GUIDE.md) - M-Pesa 集成
- [Enhanced Features](docs/ENHANCED_FEATURES.md) - 邮箱、2FA、WebSocket、Redis 设置
**数据库连接故障排除：**
如果连接 MongoDB 时遇到问题，请参阅 [Mongoose Troubleshooting Guide](docs/MONGOOSE_TROUBLESHOOTING.md) 了解常见解决方案。
### 运行应用
#### 填充示例产品（可选）
要使用专业的示例产品填充你的数据库以获得逼真的电子商务体验：
```
cd api
# 查看将被填充的内容 (安全模式)
npm run seed
# 添加 12 个带有描述和图片的示例产品
npm run seed:force
# 清除现有产品并重新填充
npm run seed:clear
```
这将添加专业的示例产品，包括：
- 电子产品（耳机、智能手表、扬声器、键盘）
- 配件（包、太阳镜）
- 运动与健身（瑜伽垫、水瓶、跑鞋）
- 服装（有机棉 T 恤）
- 家居与厨房（咖啡杯、台灯）
所有产品都包含专业的描述、逼真的定价、高质量的图片和库存数量。
#### 开发模式 - 全栈
**终端 1 - 后端 API:**
```
cd api && npm start
# 服务器运行在 http://localhost:3001
```
**终端 2 - 前端:**
```
cd frontend && npm run dev
# 前端运行在 http://localhost:5173
```
访问 [http://localhost:5173](http://localhost:5173) 查看应用。
#### 开发模式 - 仅 API
```
cd api && npm start
# 服务器运行在 http://localhost:3001
```
#### 生产模式
```
cd api && NODE_ENV=production node server.js
```
#### 部署 Worker
```
npm run deploy:worker
# 或者
cd worker && npm run deploy
```
#### 运行测试
```
npm test
# 或者
cd api && npm test
```
## API 端点
### 健康检查
```
GET /health
```
返回系统健康状态和数据库连接状态。
### 用户端点
#### 注册新用户
```
POST /user/signup
Content-Type: application/json
{
"email": "user@example.com",
"password": "SecurePass123!"
}
```
#### 登录（本地认证）
```
POST /user/login
Content-Type: application/json
{
"email": "user@example.com",
"password": "SecurePass123!"
}
```
#### OAuth 2.0 认证
OAuth 流程使用 **一次性交换码** 模式，将真正的 JWT 保留在浏览器历史记录、服务器日志和 `Referer` 头之外。请参阅 [OAuth Exchange Code Guide](docs/OAUTH_EXCHANGE_CODE.md)。
**使用 Google 登录**
```
GET /auth/google
# 重定向到 Google 登录页面
# 成功后重定向到：FRONTEND_URL/auth/success?code=
```
**使用 Microsoft 登录**
```
GET /auth/microsoft
# 重定向到 Microsoft 登录页面
# 成功后重定向到：FRONTEND_URL/auth/success?code=
```
**用交换码换取 JWT** *(由前端自动调用)*
```
POST /auth/exchange
Content-Type: application/json
{ "code": "" }
# 返回：{ "token": "", "expiresAt": "..." }
# 代码在首次使用后删除，并在 30 秒后过期
```
详细配置说明请参阅 [OAuth Setup Guide](docs/OAUTH_SETUP.md)。
#### 邮箱验证
```
POST /user/request-verification
Content-Type: application/json
{
"email": "user@example.com"
}
GET /user/verify-email/:token
```
#### 密码重置
```
POST /user/request-password-reset
Content-Type: application/json
{
"email": "user@example.com"
}
POST /user/reset-password/:token
Content-Type: application/json
{
"password": "NewSecurePassword123!"
}
```
#### 双因素认证 (2FA)
```
# 设置 2FA
POST /user/2fa/setup
Authorization: Bearer
# 启用 2FA
POST /user/2fa/enable
Authorization: Bearer
Content-Type: application/json
{
"token": "123456"
}
# 验证 2FA
POST /user/2fa/verify
Content-Type: application/json
{
"userId": "user_id",
"token": "123456"
}
# 禁用 2FA
POST /user/2fa/disable
Authorization: Bearer
Content-Type: application/json
{
"password": "YourPassword123!"
}
```
完整详情请参阅 [Enhanced Features Documentation](docs/ENHANCED_FEATURES.md)。
#### 删除用户（仅限管理员）
```
DELETE /user/:userId
Authorization: Bearer
```
### 产品端点
#### 获取所有产品
```
GET /products
```
#### 创建产品（仅限管理员）
```
POST /products
Authorization: Bearer
Content-Type: multipart/form-data
name: "Product Name"
price: 99.99
productImage:
```
#### 获取单个产品
```
GET /products/:productId
```
#### 更新产品（仅限管理员）
```
PATCH /products/:productId
Authorization: Bearer
Content-Type: application/json
{
"name": "Updated Name",
"price": 149.99
}
```
#### 删除产品（仅限管理员）
```
DELETE /products/:productId
Authorization: Bearer
```
### 订单端点
#### 获取所有订单（已认证）
```
GET /orders
Authorization: Bearer
```
#### 获取单个订单（已认证）
```
GET /orders/:orderId
Authorization: Bearer
```
#### 创建订单（已认证）
```
POST /orders
Authorization: Bearer
Content-Type: application/json
{
"productId": "507f1f77bcf86cd799439011",
"quantity": 2
}
```
#### 删除订单（仅限管理员）
```
DELETE /orders/:orderId
Authorization: Bearer
```
#### 更新订单状态（仅限管理员）
```
PATCH /orders/:orderId/status
Authorization: Bearer
Content-Type: application/json
{
"status": "shipped"
}
```
### 支付端点
#### 发起支付
```
POST /payments/initiate
Authorization: Bearer
Content-Type: application/json
{
"orderId": "507f1f77bcf86cd799439011",
"paymentMethod": "mpesa",
"paymentData": {
"phoneNumber": "254712345678"
}
}
```
**支持的支付方式**: `stripe`, `card`, `paypal`, `mpesa`
#### 验证支付
```
GET /payments/verify/:paymentId
Authorization: Bearer
```
#### 获取支付详情
```
GET /payments/:paymentId
Authorization: Bearer
```
#### 获取支付历史
```
GET /payments/history?page=1&limit=10
Authorization: Bearer
```
#### M-Pesa 回调（Webhook）
```
POST /payments/mpesa/callback
Content-Type: application/json
(Called automatically by M-Pesa servers)
```
**完整的支付 API 文档请参阅：**
- [Payment API Documentation](docs/PAYMENT_API_DOCUMENTATION.md)
- [M-Pesa Setup Guide](docs/MPESA_SETUP_GUIDE.md)
## 文档
### 完整文档库
#### 快速开始
- [Installation & Configuration](#getting-started) - 设置和配置指南
- [OAuth Setup Guide](docs/OAUTH_SETUP.md) - 配置 Google, Microsoft, 和 Apple OAuth
- [OAuth Exchange Code Guide](docs/OAUTH_EXCHANGE_CODE.md) - 一次性交换码安全模式
#### 架构与部署
- **[Complete Deployment Guide](docs/FULL_DEPLOYMENT_GUIDE.md)** - 全栈部署演示
- **[GitHub CI/CD Setup](docs/GITHUB_SECRETS_CICD_GUIDE.md)** - 使用 GitHub Actions 自动化部署
- [Microservices Architecture](docs/MICROSERVICES_ARCHITECTURE.md) - 详细架构概述
- [Microservices Quickstart](docs/MICROSERVICES_QUICKSTART.md) - 快速部署指南
- [Cloudflare Deployment](docs/CLOUDFLARE_DEPLOYMENT.md) - 部署到 Cloudflare Workers
- [Cloudflare Secrets Setup](docs/CLOUDFLARE_SECRETS_SETUP.md) - 配置 secrets
- [Frontend README](frontend/README.md) - 前端专用文档
#### 增强功能
- **[Enhanced Features Guide](docs/ENHANCED_FEATURES.md)** - 完整指南，包括：
- 邮箱验证和密码重置
- 双因素认证 (2FA) 设置
- 实时 WebSocket 通知
- Redis 缓存配置
- API 版本控制使用
#### 支付集成
- [Payment API Documentation](docs/PAYMENT_API_DOCUMENTATION.md) - 完整的支付 API 参考
- [M-Pesa Setup Guide](docs/MPESA_SETUP_GUIDE.md) - M-Pesa 集成指南
#### 监控与运维
- **[Monitoring & Observability](docs/MONITORING_OBSERVABILITY.md)** - 综合指南，包括：
- 应用性能监控 (APM) 集成
- 分布式追踪设置
- 自定义指标和仪表盘
- 告警配置
- 健康检查和探针
#### 测试
- **[Testing Guide](docs/TESTING_GUIDE.md)** - 完整的测试文档：
- 单元和集成测试
- 使用 Artillery 进行负载测试
- 使用 Cypress 进行端到端测试
- 契约测试
- 测试覆盖率策略
#### 数据库
- [Database Migration Analysis](docs/DATABASE_MIGRATION_ANALYSIS.md) - 数据库选项
- [MongoDB Cloudflare Strategy](docs/MONGODB_CLOUDFLARE_STRATEGY.md) - Cloudflare 上的 MongoDB
- [Mongoose Troubleshooting](docs/MONGOOSE_TROUBLESHOOTING.md) - 常见问题和解决方案
#### 故障排除
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - 常见问题和解决方案
- [Implementation Summary](docs/IMPLEMENTATION_SUMMARY.md) - 技术实现细节
- [Before/After Comparison](docs/BEFORE_AFTER_COMPARISON.md) - 功能演进
## 部署
### 使用 GitHub Actions 自动部署
项目包含通过 GitHub Actions 实现的完整 CI/CD 自动化，用于：
- Cloudflare Workers (Edge proxy)
- Cloudflare Pages (Frontend)
- 自动化测试和安全扫描
**快速设置：**
1. 配置 [GitHub Secrets](docs/GITHUB_SECRETS_CICD_GUIDE.md)
2. 推送到 `main` 分支
3. GitHub Actions 处理剩下的工作！
**详细指南请参阅：**
- **[GitHub CI/CD Setup Guide](docs/GITHUB_SECRETS_CICD_GUIDE.md)** - 完整的自动化设置
- **[Full Deployment Guide](docs/FULL_DEPLOYMENT_GUIDE.md)** - 手动部署演示
### 部署后端（Render）
后端通过 Render 内置的 CI/CD 自动部署：
**Render:**
```
# 连接 GitHub 仓库
# Render 在推送到 main 分支时自动部署
# 在 Render 仪表板中配置环境变量
```
### 手动部署
#### 手动部署 Worker
```
cd worker
wrangler secret put BACKEND_API_URL # One-time setup
wrangler deploy
```
#### 手动部署 Frontend
```
cd frontend
npm run build
wrangler pages deploy build --project-name=rest-shop-frontend
```
## CI/CD 流水线
项目使用 GitHub Actions 进行自动化持续集成和部署。
### 流水线阶段
1. **代码质量与 Linting** - ESLint, 代码风格检查
2. **安全扫描** - npm audit, Snyk, CodeQL
3. **测试** - 使用 MongoDB Memory Server 的完整测试套件
4. **构建验证** - 构建 worker 和 frontend
5. **部署 Worker** - 自动部署到 Cloudflare Workers（仅限 main 分支）
6. **部署 Frontend** - 自动部署到 Cloudflare Pages（仅限 main 分支）
### 必需的 GitHub Secrets
在 GitHub 仓库设置 → Secrets and variables → Actions 中配置：
```
CLOUDFLARE_API_TOKEN - Cloudflare API token for deployments
CLOUDFLARE_ACCOUNT_ID - Your Cloudflare account ID
REACT_APP_API_URL - Worker URL for frontend (e.g., https://rest-shop-worker.workers.dev)
```
可选：
```
JWT_KEY - For CI tests only (not production)
SNYK_TOKEN - For Snyk security scanning
```
### 触发部署
**自动：**
- 推送到 `main` 分支会触发完整部署
- Pull 请求仅触发测试（不部署）
**手动：**
- 进入 Actions 标签页 → CI/CD Pipeline → Run workflow
**详细指南请参阅：** [GitHub Secrets & CI/CD Setup](docs/GITHUB_SECRETS_CICD_GUIDE.md)
## 测试
### 测试套件概述
项目包含多个级别的全面测试：
#### 单元与集成测试
```
# 运行所有测试
npm test
# 在监视模式下运行测试
npm run test:watch
```
#### 使用 Artillery 进行负载测试
```
# 产品端点负载测试
npm run test:load
# 已认证用户旅程
npm run test:load:auth
# Spike 测试 (突发负载增加)
npm run test:load:spike
```
### 测试结构
```
test/
├── setup.js # MongoDB Memory Server setup
├── controllers/
│ ├── user.test.js # User authentication tests
│ ├── products.test.js # Product CRUD tests
│ ├── orders.test.js # Order management tests
│ ├── payments.test.js # Payment processing tests
│ ├── auth.test.js # Email verification & password reset
│ └── twoFactor.test.js # 2FA functionality tests
└── middleware/
└── check-auth.test.js # Authentication middleware tests
tests/load/
├── products-load-test.yml # Product browsing scenarios
├── auth-load-test.yml # Authenticated user flows
└── spike-test.yml # Sudden traffic spike test
```
### 测试前置条件
- **MongoDB Memory Server**: 测试使用内存中的 MongoDB 实例
- **Node.js**: v20.x 或更高
- **Ubuntu 22.04+**: 配置为 OpenSSL 3.x 兼容 (MongoDB 7.0.14)
### 测试覆盖范围
- 用户身份验证（注册、登录、删除、邮箱验证、密码重置）
- 双因素认证（设置、启用、验证、禁用）
- 带有缓存的产品 CRUD 操作
- 带有实时通知的订单管理
- 支付处理 (Stripe, PayPal, M-Pesa)
- JWT 中间件和授权
- WebSocket 连接和通知
- 错误处理和安全
- 负载测试场景
- **目标覆盖率**: > 90%
**完整的测试文档请参阅 [Testing Guide](docs/TESTING_GUIDE.md)**
## 监控与可观测性
### 可用的监控功能
#### 应用监控
- **健康检查端点**: `/health` - 系统健康和数据库状态
- **结构化日志**: 带有 trace ID 的 JSON 格式日志
- **审计日志**: 安全事件跟踪（登录、注册、失败）
#### 性能指标
- 响应时间跟踪
- 请求吞吐量
- 错误率监控
- 缓存命中/未命中率
- WebSocket 连接数
#### APM 集成支持
- New Relic
- Datadog APM
- Elastic APM
- Prometheus/Grafana
#### 分布式追踪
- 跨服务的 Trace ID 传播
- 请求关联
- 性能瓶颈识别
#### 告警
- 高错误率告警
- 慢响应时间通知
- 数据库连接失败
- 支付网关问题
- 内存和 CPU 使用率警告
**完整的监控设置请参阅 [Monitoring & Observability Guide](docs/MONITORING_OBSERVABILITY.md)**
## 中间件
### 安全中间件
- **Helmet**: 安全头
- **CORS**: 跨源资源共享
- **Rate Limiting**: 请求节流
- **Input Validation**: express-validator
- **Sanitization**: XSS 防护
### 认证中间件
- **checkAuth**: 验证 JWT Token
- **checkRole**: 基于角色的访问控制
### 自定义中间件
- **Error Handler**: 集中错误处理
- **Morgan Logger**: HTTP 请求日志
## 错误处理
所有错误返回一致的 JSON 格式：
```
{
"error": {
"message": "Error description"
}
}
```
### HTTP 状态码
- `200` - 成功
- `201` - 已创建
- `400` - 错误请求（验证错误）
- `401` - 未授权（认证失败）
- `403` - 禁止访问（权限不足）
- `404` - 未找到
- `409` - 冲突（资源重复）
- `429` -请求过多（速率限制）
- `500` - 内部服务器错误
## 贡献
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request
### 开发指南
- 为新功能编写测试
- 遵循现有的代码风格
- 更新文档
- 确保所有测试通过
- 保持提交原子化且描述清晰
## 许可证
本项目基于 ISC 许可证授权。
## 作者
**Merlyn Zawadi**
## 支持
如有问题或疑问：
- 在 GitHub 上提出 issue
- 查看现有文档
- 在 Postman 集合中查看 API 端点
## 致谢
- Express.js 社区
- MongoDB Atlas
- Cloudflare Workers
- 所有贡献者
标签：API网关, CISA项目, Express, GNU通用公共许可证, Helmet, MERN架构, MITM代理, MongoDB, Node.js, React, RESTful API, Syscall, Syscalls, Tailwind CSS, TypeScript, Web开发, 前后端分离, 双后端架构, 响应式设计, 安全插件, 提示词优化, 搜索引擎查询, 电商系统, 电商网站建设, 程序员工具, 系统可扩展性, 网络安全, 自定义脚本, 自定义脚本, 自定义脚本, 边缘计算, 隐私保护, 高并发