# xlcigbackend **Repository Path**: leheya/xlcigbackend ## Basic Information - **Project Name**: xlcigbackend - **Description**: 一个现代化的电商后端API系统，帮助用户选择合适的硬件配置，提供完整的装机解决方案 - **Primary Language**: JavaScript - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-07-04 - **Last Updated**: 2025-07-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: Nodejs, Koa ## README # 装机指南 API > 一个现代化的电脑装机指导后端API系统，帮助用户选择合适的硬件配置，提供完整的装机解决方案。 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![Koa.js](https://img.shields.io/badge/Koa.js-2.14+-orange.svg)](https://koajs.com/) [![MySQL](https://img.shields.io/badge/MySQL-8.0+-blue.svg)](https://www.mysql.com/) [![Docker](https://img.shields.io/badge/Docker-ready-blue.svg)](https://www.docker.com/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) ## 📋 目录 - [前端直达](https://gitee.com/leheya/xlweb) - [接口说明](https://gitee.com/leheya/xlcigbackend/blob/master/API.md) - [部署指南](https://gitee.com/leheya/xlcigbackend/blob/master/DEPLOYMENT.md) - [项目简介](#-项目简介) - [功能特性](#-功能特性) - [技术栈](#-技术栈) - [快速开始](#-快速开始) - [API文档](#-api文档) - [开发计划](#-开发计划) - [贡献指南](#-贡献指南) ## 更新日志 - [点击查看](https://gitee.com/leheya/xlcigbackend/blob/master/CHANGELOG.md) ## ❓ 常见问题 ### 🏗️ 技术选型
为什么选择 Koa.js 作为后端框架？ **选择理由：** - ⚡ **轻量级**：相比 Express，Koa 更精简，性能更优 - 🚀 **开发效率**：简洁的 API 设计，快速上手，开发周期短 - 📦 **模块化**：插件生态丰富，按需引入，灵活组合 - 🎯 **现代化**：原生支持 async/await，错误处理更优雅
### 🔄 项目发展规划
项目后期优化计划 **短期计划：** - 🎨 **前端优化**：简化用户角色，从三种身份（用户-商家-管理员）精简为两种，采用 A to C 直连模式 - 📧 **性能优化**：解决邮箱验证码发送延迟问题，优化用户体验 - 🏪 **功能调整**：考虑暂时简化商家功能，专注核心装机指导功能 **长期规划：** - ☕ **技术栈升级**：前端功能稳定后，考虑后端迁移至 Java 以支持更高并发 - 🖥️ **服务器升级**：配合技术栈升级，提升硬件配置 - 🔧 **功能完善**：预算充足后，重新完善商家系统，实现完整的 A to B to C 模式 > 💡 **设计理念**：功能优先，快速迭代，逐步优化
### 🚀 部署架构
当前部署方案 **生产环境状态：** ``` ┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐ │ id │ name │ mode │ ↺ │ status │ cpu │ memory │ ├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤ │ 2 │ xlcig-api │ cluster │ 0 │ online │ 0% │ 62.8mb │ │ 3 │ xlcig-web │ fork │ 3 │ online │ 0% │ 68.9mb │ └────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘ ``` **部署方案选择：** - 🎯 **当前方案**：PM2 进程管理器 - ✅ 部署速度快，配置简单 - ✅ 支持集群模式，自动重启 - ✅ 内置负载均衡，实时监控 - 🐳 **备选方案**：Docker + Nginx - 📦 配置文件已完成（docker-compose.yml） - 🔧 考虑到快速开发需求，暂时搁置 - 🚀 后期将采用 Docker + PM2 混合部署 **部署优势：** - 🚀 **快速部署**：从代码提交到服务上线 < 5分钟 - 🔄 **零停机**：滚动更新，用户无感知 - 📊 **实时监控**：CPU、内存、响应时间全面监控
### 🎯 性能与并发
性能测试与优化 **当前性能指标：** - 🖥️ **服务器配置**：2核2G - 👥 **并发支持**：~1000 并发连接 - ⚡ **响应时间**：平均 < 100ms - 📊 **可用性**：99.9% 运行时间 **性能优化策略：** - 📈 **水平扩展**：PM2 集群模式 + 服务器升级 - 🔄 **负载均衡**：支持 10,000+ 并发（理论值） - 💾 **缓存策略**：Redis 缓存 + CDN 加速 - 🎯 **数据库优化**：索引优化 + 连接池管理 **使用建议：** - ✅ **适合场景**：中小型项目，快速原型开发 - ✅ **前端部署**：支持无上限扩展 - ⚠️ **高并发需求**：建议评估业务需求，必要时进行架构升级 > 💡 **性能提示**：当前架构可满足大部分中小型项目需求，如需支持更高并发，建议联系进行架构咨询。
## 📖 项目简介 装机指南API是一个专业的电脑装机指导后端服务，旨在帮助用户： - 🎯 **智能推荐**：根据用户需求和预算推荐最佳硬件配置 - 🔍 **产品比较**：提供详细的硬件产品信息和性能对比 - 💰 **价格追踪**：实时监控硬件价格变化，找到最优购买时机 - 🛠️ **兼容性检查**：自动检测硬件间的兼容性问题 - 📚 **装机指导**：提供详细的装机教程和故障排除指南 ## ✨ 功能特性 ### 🎉 已完成功能 #### 🔐 用户系统 - ✅ 用户注册、登录、登出 - ✅ JWT身份认证和授权 - ✅ 密码加密存储（bcrypt） - ✅ 用户资料管理 - ✅ 权限控制和角色管理 #### 📦 产品管理 - ✅ 硬件产品信息管理（CPU、GPU、主板、内存等） - ✅ 产品分类和标签系统 - ✅ 热门产品推荐 - ✅ 最新产品展示 - ✅ 精选产品管理 - ✅ 产品规格详情 #### 🏪 商家系统 - ✅ 商家入驻和认证 - ✅ 商家产品管理 - ✅ 商家信息维护 #### 📋 订单系统 - ✅ 订单创建和管理 - ✅ 订单状态跟踪 - ✅ 订单历史记录 #### 📂 文件管理 - ✅ 阿里云OSS文件上传 - ✅ 图片上传和管理 - ✅ 文件类型验证 #### 🌍 地理服务 - ✅ IP地址定位 - ✅ 用户地址管理 - ✅ 高德地图集成 #### 🔧 系统功能 - ✅ 自动路由生成系统 - ✅ 健康检查接口 - ✅ 统一错误处理 - ✅ 日志记录 - ✅ 数据库连接池 - ✅ 跨域支持 ### 🚀 开发中功能 #### 💡 智能推荐引擎 - 🔄 基于用户需求的配置推荐算法 - 🔄 机器学习驱动的个性化推荐 - 🔄 用户行为分析和偏好学习 - 🔄 配置兼容性智能检测 #### 💰 价格监控系统 - 🔄 多平台价格爬取和对比 - 🔄 价格趋势分析和预测 - 🔄 降价提醒和通知 - 🔄 历史价格图表展示 #### 🎮 性能评测系统 - 🔄 硬件性能基准测试数据库 - 🔄 游戏性能预测 - 🔄 配置方案性能评分 - 🔄 瓶颈分析和优化建议 ### 📅 未来规划 #### 🤖 AI助手 - 📝 智能装机顾问聊天机器人 - 📝 自然语言处理配置需求 - 📝 图像识别硬件型号 - 📝 语音助手支持 #### 📊 数据分析 - 📝 用户行为数据分析 - 📝 市场趋势分析报告 - 📝 硬件流行度统计 - 📝 配置方案成功率追踪 #### 🎥 内容系统 - 📝 装机教学视频管理 - 📝 硬件评测文章系统 - 📝 用户评价和晒单 - 📝 社区问答功能 #### 🔗 第三方集成 - 📝 电商平台API集成 - 📝 支付系统集成 - 📝 物流跟踪集成 - 📝 客服系统集成 #### 📱 移动端支持 - 📝 移动端API优化 - 📝 微信小程序后端 - 📝 APP推送通知 - 📝 离线模式支持 ## 🛠 技术栈 ### 后端框架 - **Node.js** - JavaScript运行时环境 - **TypeScript** - 类型安全的JavaScript超集 - **Koa.js** - 现代化的Node.js Web框架 - **Koa Router** - 路由中间件 ### 数据库 - **MySQL** - 关系型数据库 - **mysql2** - MySQL连接驱动 ### 认证 & 安全 - **JWT** - JSON Web Token认证 - **bcryptjs** - 密码加密 - **Joi** - 数据验证 ### 云服务 - **阿里云OSS** - 对象存储服务 - **高德地图** - 地理位置服务 ### 开发工具 - **nodemon** - 开发环境热重载 - **ts-node** - TypeScript直接执行 ## ⚠️ 重要提示 **首次部署必读：** 本项目包含敏感配置信息，为了安全考虑，配置文件 `src/config/env.ts` 已被添加到 `.gitignore` 中。 📖 **请在开始前阅读：** - [📋 环境变量配置指南 (CONFIG.md)](./CONFIG.md) - **必读** - [🚀 部署配置指南 (DEPLOYMENT.md)](./DEPLOYMENT.md) - [📚 API 接口文档 (API.md)](./API.md) ## 🚀 快速开始 ### 环境要求 - Node.js >= 18.0.0 - MySQL >= 8.0 - npm >= 8.0.0 ### 安装步骤 1. **克隆项目** ```bash git clone https://github.com/your-username/xlcig-api.git cd xlcig-api ``` 2. **安装依赖** ```bash npm install ``` 3. **环境配置** ```bash # 请参照 CONFIG.md 配置指南创建环境变量文件 # 根据您的环境创建对应的配置文件： cp .env.example .env.development # 开发环境 cp .env.example .env.production # 生产环境 # 编辑配置文件，设置数据库连接等信息 # 详细配置说明请查看 CONFIG.md nano .env.development ``` 4. **数据库初始化** ```bash # 创建数据库 mysql -u root -p -e "CREATE DATABASE cig CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" # 运行数据库迁移 npm run init-db ``` 5. **启动服务** ```bash # 开发模式 npm run dev # 生产模式 npm run build npm start ``` 访问 `http://localhost:9999/health` 检查服务状态。 ## 📚 API文档 ### 基础信息 - **Base URL**: `http://localhost:9999` (开发) / `https://api.xlcig.cn` (生产) - **认证方式**: Bearer Token (JWT) - **数据格式**: JSON ### 响应格式 ```json { "success": true, "data": {}, "message": "操作成功", "code": 200 } ``` ### 主要接口 #### 用户认证 ```bash POST /api/auth/register # 用户注册 POST /api/auth/login # 用户登录 GET /api/user/profile # 获取用户信息 ``` #### 产品管理 ```bash GET /api/product/hot # 热门产品 GET /api/product/featured # 精选产品 GET /api/product/latest # 最新产品 GET /api/product/list # 产品列表 GET /api/product/detail/:id # 产品详情 ``` #### 配置推荐 ```bash GET /api/config/hot # 热门配置 GET /api/config/featured # 精选配置 POST /api/config/recommend # 智能推荐 ``` #### 系统接口 ```bash GET /health # 健康检查 GET /api/system/config # 系统配置 ``` ### 完整API文档 详细的API文档请参考：[API Documentation](docs/api.md) ## 🗂 项目结构 ``` xlcig-api/ ├── src/ # 源代码目录 │ ├── app.ts # 应用入口 │ ├── types.ts # 类型定义 │ ├── config/ # 配置文件 │ │ ├── database.ts # 数据库配置 │ │ └── env.ts # 环境变量 │ ├── middleware/ # 中间件 │ │ ├── auth.ts # 认证中间件 │ │ └── error.ts # 错误处理 │ ├── routes/ # 路由定义 │ │ ├── auth/ # 认证路由 │ │ ├── user/ # 用户路由 │ │ ├── product/ # 产品路由 │ │ └── config/ # 配置路由 │ ├── services/ # 业务逻辑 │ └── utils/ # 工具函数 ├── database/ # 数据库文件 ├── docs/ # 文档目录 ├── scripts/ # 脚本文件 └── README.md # 项目说明 ``` ## 🤝 贡献指南 我们欢迎所有形式的贡献！ ### 如何贡献 1. **Fork** 本项目 2. 创建特性分支：`git checkout -b feature/AmazingFeature` 3. 提交更改：`git commit -m 'Add some AmazingFeature'` 4. 推送分支：`git push origin feature/AmazingFeature` 5. 创建 **Pull Request** ### 开发规范 - 使用 TypeScript 编写代码 - 遵循现有的代码风格 - 添加必要的注释和文档 - 编写测试用例（如适用） ### 提交规范 使用 [Conventional Commits](https://conventionalcommits.org/) 规范： ``` feat: 添加新功能 fix: 修复bug docs: 更新文档 style: 代码格式化 refactor: 重构代码 test: 添加测试 chore: 构建工具变动 ``` ## 📄 许可证 本项目基于 [MIT License](LICENSE) 开源。 ## 🙏 致谢 感谢以下开源项目： - [Koa.js](https://koajs.com/) - Web框架 - [TypeScript](https://www.typescriptlang.org/) - 类型系统 - [MySQL](https://www.mysql.com/) - 数据库 - [Docker](https://www.docker.com/) - 容器化 如果这个项目对你有帮助，请给我们一个 ⭐ Star！