rashid-mamun/bdshop-server

# BDShop Server BDShop Server 是一个全栈电商平台的后端 API，使用 Express、TypeScript、MongoDB 和 Stripe 构建。它通过产品目录 API、身份验证、结账、支付、订单追踪、后台管理操作、文件上传、邮件工作流以及安全中间件为 BDShop 前端提供支持。 本仓库仅包含后端 API。前端应用位于单独的 `bdshop-client` 仓库中。 ## 项目概述 BDShop 是一个用于销售电子产品、车辆和配件等商品的生产级电商项目。服务器负责核心可信的业务逻辑：产品数据、用户账户、结账总额、优惠券、库存预留、订单创建、支付集成、订单追踪和后台管理。 后端支持游客结账以及登录用户结账。每个订单都会获得一个公开的 `BDS-...` 订单号，以便客户无需登录即可追踪订单。 ## 主要功能 ### 电商 API - 产品目录支持搜索、分类筛选、价格筛选、排序和分页。 - 后台产品 CRUD。 - 库存字段和库存更新支持。 - 购物车 API。 - 评论 API 和评论统计。 - 地址簿 API。 - 订单创建、列表、状态更新、删除和统计。 - 通过 `BDS-...` 订单号或 Mongo 订单 ID 进行公开订单追踪。 ### 结账与支付 - 服务器端结账报价计算。 - 可靠的小计、运费、税费、折扣和最终总额。 - 优惠券支持。 - 使用邮箱的游客结账。 - 使用登录用户邮箱的授权结账。 - 订单创建期间的库存预留。 - 支持 Stripe PaymentIntent。 - 用于更新支付状态的 Stripe webhook endpoint。 - 支持货到付款（Cash on Delivery）。 ### 身份验证与用户管理 - 邮箱/密码注册和登录。 - 支持 JWT access token 和 refresh token。 - 支持 HttpOnly cookie。 - Google 和 Facebook OAuth 路由。 - 密码重置请求和重置流程。 - 用户个人资料和密码修改。 - 后台角色管理。 - 用户激活和停用。 ### 公开工作流 - 时事通讯订阅。 - 退货申请提交。 - 公开内容路由。 - 面向客户的安全错误消息。 - 用于密码重置、订单确认和退货通知的邮件服务。 ### 上传与库存通知 - 后台图片上传路由。 - 支持 Cloudinary 上传。 - 本地上传兜底方案。 - 待处理上传追踪和清理。 - 待处理上传配额限制。 - 到货通知服务。 ### 安全与可靠性 - Helmet 安全标头。 - CORS 配置。 - Rate limiting。 - 针对不安全 API 方法的 CSRF 防护。 - 请求日志记录。 - 集中式错误处理。 - 适用于生产环境的公开错误响应。 - 生产环境变量验证。 - 支持 Docker 的构建设置。 ## 技术栈 - Node.js - Express - TypeScript - MongoDB - Mongoose - Stripe - Nodemailer - Cloudinary - JWT - Jest - Supertest - MongoDB Memory Server ## 仓库结构 ``` bdshop-server/ src/ config/ # Database, environment, logger, Cloudinary constants/ # App constants, messages, status codes controllers/ # HTTP request handlers middleware/ # Auth, validation, CSRF, rate limiting, errors models/ # Mongoose schemas routes/ # Express routes services/ # Business logic types/ # TypeScript interfaces utils/ # Response, JWT, logging, async helpers app.ts # Express app seed.ts # Seed script tests/ integration/ # API integration tests unit/ # Unit tests setup.js # Test database setup server.ts # Server entry point Dockerfile docker-compose.yml env.example package.json ``` ## 环境要求 - 推荐使用 Node.js 20 或更高版本。 - npm。 - 用于本地开发的 MongoDB。 - 用于银行卡支付的 Stripe 账户。 - 用于发送真实邮件的 SMTP 提供商。 - 用于持久化图片托管的 Cloudinary 账户。 测试使用 MongoDB Memory Server，因此 Jest 测试套件不需要本地 MongoDB 实例。 ## 环境变量 从 `env.example` 创建 `.env`： ``` cp env.example .env ``` 核心本地示例： ``` NODE_ENV=development PORT=5000 API_PREFIX=/api MONGODB_URI=mongodb://localhost:27017/bdshop JWT_SECRET=replace-with-a-long-random-secret JWT_REFRESH_SECRET=replace-with-another-long-random-secret CORS_ORIGIN=http://localhost:5173 FRONTEND_URL=http://localhost:5173 STRIPE_SECRET_KEY=sk_test_replace_me STRIPE_WEBHOOK_SECRET=whsec_replace_me CLOUDINARY_CLOUD_NAME=replace_me CLOUDINARY_API_KEY=replace_me CLOUDINARY_API_SECRET=replace_me SMTP_HOST=smtp.gmail.com SMTP_PORT=465 SMTP_USER=replace_me SMTP_PASS=replace_me EMAIL_FROM="BDShop " ``` ### 环境说明 - 切勿提交真实的密钥。 - 生产环境需要高强度的 JWT 密钥。 - Stripe 银行卡支付需要真实的 Stripe 密钥以及匹配的前端 publishable key。 - Stripe webhook 处理需要 `STRIPE_WEBHOOK_SECRET`。 - Gmail SMTP 通常需要应用密码，而不是常规的账户密码。 - 如果 SMTP 发送失败，服务器会记录失败日志，并尽可能保证关键流程可用。 ## 安装 ``` npm install ``` ## 本地运行 ``` npm run dev ``` 默认 API： ``` http://localhost:5000/api ``` 健康检查： ``` http://localhost:5000/health ``` 根 endpoint： ``` http://localhost:5000/ ``` ## 构建与启动 构建 TypeScript： ``` npm run build ``` 启动编译后的服务器： ``` npm start ``` 直接使用 TypeScript 运行： ``` npm run start:ts ``` ## 种子数据 ``` npm run seed ``` 全新种子数据： ``` npm run seed:fresh ``` ## 可用脚本 ``` npm run dev # Start development server with nodemon npm run start:ts # Start using ts-node npm run build # Compile TypeScript npm start # Start compiled dist/server.js npm test # Run all Jest tests npm run test:watch # Run tests in watch mode npm run test:coverage # Run tests with coverage npm run test:integration # Run integration tests npm run seed # Seed database npm run seed:fresh # Clear and seed database npm run lint # Run ESLint npm run format # Format files ``` ## 重要 API 领域 ### 产品 ``` GET /api/services GET /api/services/:id POST /api/services PUT /api/services/:id DELETE /api/services/:id ``` 创建、更新和删除需要后台管理员身份验证。 ### 结账与订单 ``` POST /api/orders/quote POST /api/orders GET /api/orders/my-orders GET /api/orders/my-stats GET /api/orders/track/:id?email=customer@example.com GET /api/orders PUT /api/orders/:id ``` 游客结账使用请求正文中提供的邮箱。授权结账使用登录用户的邮箱。 ### Stripe Webhook ``` POST /api/orders/stripe/webhook ``` webhook 路由在 JSON body 解析之前注册，以便 Stripe 签名验证可以使用原始请求正文。 处理的事件： - `payment_intent.succeeded` - `payment_intent.payment_failed` ### 公开订单追踪 每个新订单都会获得一个公开的订单号： ``` BDS-MPXWIHDH-QHUJ ``` 追踪订单方式： ``` GET /api/orders/track/BDS-MPXWIHDH-QHUJ?email=customer@example.com ``` `:id` 参数也可以是 Mongo 订单 ID。无效的公开 ID 会返回友好的“未找到”响应，而不是数据库 cast 错误。 ### 公开路由 ``` POST /api/public/newsletter POST /api/public/returns ``` ### 上传 ``` POST /api/upload DELETE /api/upload/pending/expired ``` 上传路由需要管理员权限。 ## 结账规则 服务器是结账总额的唯一可信源。 前端发送商品 ID、数量、地址、优惠券代码和支付方式信息。后端会： 1. 从数据库加载产品价格。 2. 验证库存。 3. 计算小计。 4. 应用优惠券折扣。 5. 添加运费和税费。 6. 在订单创建期间预留库存。 7. 创建订单。 8. 如果配置了 SMTP，则发送确认邮件。 永远不能信任前端的最终总额。 ## 错误处理策略 API 避免在面向客户的响应中暴露原始内部错误。 隐藏的详细信息示例： - 数据库 cast 错误。 - 堆栈追踪。 - SMTP 凭证失败。 - Stripe 密钥/提供商错误。 - 内部服务器消息。 对于服务器错误，公开响应是通用的： ``` { "success": false, "error": "Something went wrong. Please try again." } ``` 在确保安全的前提下，验证错误仍会提供可操作的提示。 ## 测试 运行所有测试： ``` npm test ``` 运行针对性测试套件： ``` npm run test:integration:orders npm run test:integration:users npm run test:integration:services npm run test:integration:carts npm run test:integration:reviews npm run test:integration:addresses npm run test:integration:auth npm run test:integration:upload ``` 测试覆盖率： ``` npm run test:coverage ``` 测试技术栈： - Jest - Supertest - MongoDB Memory Server - ts-jest 重要的已测流程包括： - 身份验证与授权。 - 产品目录。 - 购物车。 - 订单与游客结账。 - 通过 `BDS-...` 订单号进行公开订单追踪。 - 评论。 - 地址。 - 上传权限。 - 安全的公开错误响应。 ## Docker 构建并运行： ``` docker compose up --build ``` Dockerfile 使用构建阶段，并从 `dist/server.js` 启动编译后的服务器。 在运行类生产环境的容器之前，请确保提供了所需的环境变量。 ## 生产环境检查清单 - 设置 `NODE_ENV=production`。 - 使用高强度的 `JWT_SECRET` 和 `JWT_REFRESH_SECRET`。 - 设置精确的 `CORS_ORIGIN` 和 `FRONTEND_URL`。 - 配置 MongoDB 连接字符串。 - 配置 Stripe 密钥和 webhook 密钥。 - 在客户端仓库中配置前端的 Stripe publishable key。 - 配置 SMTP 凭证。 - 配置 Cloudinary 凭证。 - 运行 `npm run build`。 - 运行 `npm test`。 - 运行 `npm audit --omit=dev`。 - 验证游客结账、银行卡支付、货到付款（Cash on Delivery）、订单追踪和后台订单更新。 ## 相关仓库 前端客户端： ``` bdshop-client ``` 前端应将此服务器的 `/api` URL 用作 `VITE_API_BASE_URL`。 ## 当前限制 - 完整的支付可靠性取决于生产环境的 Stripe webhook 配置。 - 真实的邮件投递取决于有效的 SMTP 凭证。 - 尚未包含完整的 E2E 浏览器测试。 - 高级库存报表功能有待进一步扩展。 ## 路线图 - 服务器同步的愿望清单和购物车合并。 - 更详细的后台库存分析。 - 更多的邮件模板和通知事件。 - 针对结账、支付和身份验证的端到端测试。 - 结合前后端的请求关联结构化日志记录。

标签：GNU通用公共许可证, MITM代理, MongoDB, Node.js, RESTful API, Stripe支付, 后端API, 提示词优化, 电子商务, 自动化攻击, 请求拦截