# 结伴客系统架构文档 ## 1. 系统架构概览 ### 1.1 架构图 ```mermaid graph TB subgraph "客户端层" A[微信小程序 uni-app] B[后台管理系统 Vue 3 + Ant Design] C[官网系统 HTML5 + Bootstrap] end subgraph "接入层" D[Express API Gateway] end subgraph "应用服务层" E[认证服务] F[用户服务] G[旅行服务] H[动物服务] I[订单服务] J[管理员服务] end subgraph "基础设施层" K[MySQL 数据库] L[Redis 缓存] M[RabbitMQ 消息队列] N[文件存储] end subgraph "监控运维层" O[Swagger API 文档] P[Winston 日志系统] Q[健康检查监控] end A --> D B --> D C --> D D --> E D --> F D --> G D --> H D --> I D --> J E --> K F --> K G --> K H --> K I --> K J --> K E --> L F --> L G --> L I --> M E --> N F --> N H --> N D --> O D --> P D --> Q ``` **系统架构层次说明：** **1. 客户端层** - **微信小程序**: 基于uni-app开发，提供用户端功能 - **后台管理系统**: 基于Vue.js 3 + TypeScript + Ant Design Vue + Pinia开发，提供管理功能 - **官网系统**: 基于HTML5 + Bootstrap开发，提供企业宣传功能 **2. 接入层** - **API网关**: 基于Express.js框架，提供统一的API接入、路由分发、安全防护和请求处理，所有API路径前缀为`/api/v1` **3. 应用服务层** - **认证服务**: 用户身份认证、JWT令牌管理和权限控制 - **用户服务**: 用户信息管理、个人中心功能和用户统计 - **旅行服务**: 旅行计划创建、查询、匹配和管理功能 - **动物服务**: 动物信息管理、认领流程和动物统计 - **订单服务**: 订单创建、支付处理和交易管理 - **管理员服务**: 管理员权限管理和系统配置 **4. 基础设施层** - **MySQL数据库**: 单实例架构，存储核心业务数据，使用连接池优化性能（测试环境: 192.168.0.240:3306，生产环境: 129.211.213.226:9527） - **Redis缓存**: 单实例模式，提供会话管理和数据缓存服务 - **RabbitMQ消息队列**: 异步消息处理和解耦（待实现） - **文件存储**: 本地文件系统，存储用户上传的图片和文件资源 **5. 监控运维层** - **Swagger API文档**: 自动生成的API接口文档 - **Winston日志系统**: 结构化日志记录和分析 - **健康检查监控**: 系统状态监控和性能统计 **架构连接关系：** - 所有客户端通过API网关访问后端服务 - 应用服务层各服务独立部署，通过API网关统一暴露接口 - 认证服务、用户服务、旅行服务、动物服务、商家服务连接MySQL数据库和Redis缓存 - 支付服务和推广服务连接MySQL数据库和RabbitMQ消息队列 - 认证服务、用户服务、动物服务、商家服务连接对象存储 - 监控系统、日志系统、CI/CD系统监控所有应用服务 ## 2. 项目结构 ``` 结伴客项目 (根目录) ├── mini-program // 微信小程序 (uni-app) │ ├── pages │ │ ├── user // 用户相关页面 │ │ │ ├── login // 登录页面 │ │ │ ├── register // 注册页面 │ │ │ ├── profile // 个人主页 │ │ │ └── settings // 设置页面 │ │ ├── merchant // 商家相关页面 │ │ │ ├── register // 商家注册 │ │ │ ├── profile // 商家主页 │ │ │ └── dashboard // 商家控制台 │ │ ├── travel // 旅行结伴页面 │ │ │ ├── plan // 旅行计划 │ │ │ ├── search // 搜索结伴 │ │ │ └── activities // 其他活动 │ │ ├── animal // 动物认领页面 │ │ │ ├── list // 动物列表 │ │ │ ├── detail // 动物详情 │ │ │ └── claim // 认领流程 │ │ ├── social // 社交互动页面 │ │ │ ├── messages // 消息聊天 │ │ │ └── feed // 动态分享 │ │ ├── flower // 送花服务页面 │ │ │ ├── products // 鲜花产品 │ │ │ └── orders // 订单管理 │ │ └── promotion // 推广奖励页面 │ │ ├── invite // 邀请推广 │ │ └── rewards // 奖励中心 │ ├── components // 可复用组件 │ │ ├── common // 通用组件 │ │ ├── user // 用户相关组件 │ │ ├── travel // 旅行相关组件 │ │ ├── animal // 动物相关组件 │ │ ├── social // 社交相关组件 │ │ ├── merchant // 商家相关组件 │ │ └── flower // 鲜花相关组件 │ ├── utils // 工具函数 │ │ ├── request // 网络请求封装 │ │ ├── auth // 认证相关工具 │ │ ├── storage // 存储相关工具 │ │ └── helpers // 辅助函数 │ ├── static // 静态资源 │ │ ├── images // 图片资源 │ │ └── styles // 样式文件 │ └── store // 状态管理 │ ├── modules // 模块化状态 │ │ ├── user // 用户状态 │ │ ├── travel // 旅行状态 │ │ ├── animal // 动物状态 │ │ ├── social // 社交状态 │ │ ├── merchant // 商家状态 │ │ ├── flower // 鲜花状态 │ │ └── promotion // 推广状态 │ └── index.js // 状态管理入口 ├── admin-system // 后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia) │ ├── public // 静态资源 │ ├── src │ │ ├── api // API接口 (TypeScript类型定义) │ │ │ ├── user // 用户相关接口 │ │ │ ├── merchant // 商家相关接口 │ │ │ ├── travel // 旅行相关接口 │ │ │ ├── animal // 动物相关接口 │ │ │ ├── order // 订单相关接口 │ │ │ ├── promotion // 推广相关接口 │ │ │ └── system // 系统管理接口 │ │ ├── assets // 静态资源 │ │ ├── components // 公共组件 (Vue 3 Composition API) │ │ │ ├── layout // 布局组件 │ │ │ ├── common // 通用组件 │ │ │ ├── user // 用户相关组件 │ │ │ ├── merchant // 商家相关组件 │ │ │ ├── travel // 旅行相关组件 │ │ │ ├── animal // 动物相关组件 │ │ │ ├── order // 订单相关组件 │ │ │ ├── promotion // 推广相关组件 │ │ │ └── dashboard // 仪表板组件 │ │ ├── composables // 组合式函数 (Vue 3 Composition API) │ │ ├── directives // 自定义指令 │ │ ├── layouts // 页面布局 │ │ │ ├── default.vue // 默认布局 │ │ │ ├── auth.vue // 认证布局 │ │ │ └── empty.vue // 空白布局 │ │ ├── locales // 国际化资源 │ │ │ ├── zh-CN.json // 中文语言包 │ │ │ └── en-US.json // 英文语言包 │ │ ├── pages // 页面视图 (Vue 3 + TypeScript) │ │ │ ├── dashboard // 仪表板页面 │ │ │ ├── user // 用户管理页面 │ │ │ ├── merchant // 商家管理页面 │ │ │ ├── travel // 旅行管理页面 │ │ │ ├── animal // 动物管理页面 │ │ │ ├── order // 订单管理页面 │ │ │ ├── promotion // 推广管理页面 │ │ │ ├── system // 系统管理页面 │ │ │ ├── login.vue // 登录页面 │ │ │ └── register.vue // 注册页面 │ │ ├── plugins // 插件 │ │ ├── router // 路由配置 (Vue Router 4 + TypeScript) │ │ │ ├── modules // 模块路由 │ │ │ │ ├── user.ts // 用户路由 │ │ │ │ ├── merchant.ts // 商家路由 │ │ │ │ ├── travel.ts // 旅行路由 │ │ │ │ ├── animal.ts // 动物路由 │ │ │ │ ├── order.ts // 订单路由 │ │ │ │ ├── promotion.ts // 推广路由 │ │ │ │ └── system.ts // 系统路由 │ │ │ └── index.ts // 路由入口 │ │ ├── stores // 状态管理 (Pinia 2 + TypeScript) │ │ │ ├── modules // 模块状态 │ │ │ │ ├── user.ts // 用户状态 │ │ │ │ ├── merchant.ts // 商家状态 │ │ │ │ ├── travel.ts // 旅行状态 │ │ │ │ ├── animal.ts // 动物状态 │ │ │ │ ├── order.ts // 订单状态 │ │ │ │ ├── promotion.ts // 推广状态 │ │ │ │ └── system.ts // 系统状态 │ │ │ └── index.ts // 状态管理入口 │ │ ├── styles // 样式文件 │ │ ├── types // TypeScript类型定义 │ │ ├── utils // 工具函数 (TypeScript) │ │ │ ├── request.ts // 请求封装 (Axios + TypeScript) │ │ │ ├── auth.ts // 认证工具 │ │ │ ├── storage.ts // 存储工具 │ │ │ ├── format.ts // 格式化工具 │ │ │ └── validate.ts // 验证工具 │ │ └── App.vue // 根组件 (Vue 3 + TypeScript) │ │ └── main.ts // 入口文件 (Vue 3 + TypeScript + Pinia + Ant Design Vue) │ ├── tests // 测试目录 (Vitest + Vue Test Utils) │ ├── .env // 环境配置 │ ├── .env.development // 开发环境配置 │ ├── .env.production // 生产环境配置 │ ├── index.html // HTML模板 │ ├── tsconfig.json // TypeScript配置 (严格模式) │ ├── vite.config.ts // 构建配置 (Vite 4 + TypeScript) │ └── package.json // 依赖配置 (Vue 3 + TypeScript + Ant Design Vue + Pinia) ├── website // 官网系统 (HTML5 + Bootstrap) │ ├── index.html // 首页 │ ├── about.html // 关于我们 │ ├── contact.html // 联系我们 │ ├── merchant // 商家合作页面 │ │ ├── index.html // 商家合作首页 │ │ ├── policy.html // 合作政策 │ │ └── apply.html // 入驻申请 │ ├── case.html // 案例展示 │ ├── css // 样式文件 │ │ ├── bootstrap.min.css // Bootstrap样式 │ │ └── custom.css // 自定义样式 │ ├── js // JavaScript文件 │ │ ├── bootstrap.min.js // Bootstrap脚本 │ │ └── custom.js // 自定义脚本 │ ├── images // 图片资源 │ └── vendor // 第三方库 ├── backend // 后端接口服务 (Node.js + Express) │ ├── src │ │ ├── controllers // 控制器层 │ │ │ ├── user // 用户控制器 │ │ │ ├── merchant // 商家控制器 │ │ │ ├── travel // 旅行控制器 │ │ │ ├── animal // 动物控制器 │ │ │ ├── social // 社交控制器 │ │ │ ├── flower // 鲜花控制器 │ │ │ ├── promotion // 推广控制器 │ │ │ └── auth // 认证控制器 │ │ ├── services // 业务逻辑层 │ │ │ ├── user // 用户服务 │ │ │ ├── merchant // 商家服务 │ │ │ ├── travel // 旅行服务 │ │ │ ├── animal // 动物服务 │ │ │ ├── social // 社交服务 │ │ │ ├── flower // 鲜花服务 │ │ │ ├── promotion // 推广服务 │ │ │ └── auth // 认证服务 │ │ ├── models // 数据模型层 │ │ │ ├── user.js // 用户模型 │ │ │ ├── merchant.js // 商家模型 │ │ │ ├── travelPlan.js // 旅行计划模型 │ │ │ ├── animal.js // 动物模型 │ │ │ ├── claim.js // 认领模型 │ │ │ ├── message.js // 消息模型 │ │ │ ├── activity.js // 活动模型 │ │ │ ├── product.js // 商品模型 │ │ │ ├── order.js // 订单模型 │ │ │ ├── review.js // 评价模型 │ │ │ └── reward.js // 奖励模型 │ │ ├── routes // 路由定义 │ │ │ ├── api // API路由 │ │ │ │ ├── v1 // v1版本API │ │ │ │ │ ├── user.js // 用户相关API │ │ │ │ │ ├── merchant.js // 商家相关API │ │ │ │ │ ├── travel.js // 旅行相关API │ │ │ │ │ ├── animal.js // 动物相关API │ │ │ │ │ ├── social.js // 社交相关API │ │ │ │ │ ├── flower.js // 鲜花相关API │ │ │ │ │ └── promotion.js // 推广相关API │ │ │ │ └── index.js // API路由入口 │ │ │ └── web // Web路由(管理后台) │ │ ├── middleware // 中间件 │ │ │ ├── auth // 认证中间件 │ │ │ ├── validation // 验证中间件 │ │ │ ├── rateLimit // 限流中间件 │ │ │ └── error // 错误处理中间件 │ │ ├── utils // 工具函数 │ │ │ ├── database // 数据库工具 │ │ │ ├── logger // 日志工具 │ │ │ ├── helpers // 辅助函数 │ │ │ └── constants // 常量定义 │ │ ├── config // 配置文件 │ │ │ ├── database.js // 数据库配置 │ │ │ ├── redis.js // Redis配置 │ │ │ ├── rabbitmq.js // RabbitMQ配置 │ │ │ └── app.js // 应用配置 │ │ └── app.js // 应用入口 │ ├── tests // 测试目录 │ │ ├── unit // 单元测试 │ │ └── integration // 集成测试 │ ├── docs // 文档目录 │ └── package.json // 依赖配置 └── docs // 项目文档 ├── requirements.md // 需求文档 ├── architecture.md // 架构文档 ├── detailed_design.md // 详细设计文档 └── development_plan.md // 开发计划文档 ``` ## 2. 技术栈选型 ### 2.1 后端技术栈 | 技术组件 | 版本 | 用途 | 选型理由 | |---------|------|------|----------| | Node.js | >=16.0.0 | 运行时环境 | 高性能、异步I/O、丰富的生态系统 | | Express.js | ^4.18.2 | Web框架 | 轻量级、灵活、中间件生态丰富 | | MySQL2 | ^3.14.3 | 数据库驱动 | 支持Promise、连接池、性能优化 | | JWT | ^9.0.2 | 身份认证 | 无状态、安全、易于分布式部署 | | bcryptjs | ^2.4.3 | 密码加密 | 安全性高、性能适中 | | Redis | ^5.8.2 | 缓存/会话 | 内存存储、高性能、支持数据结构 | | RabbitMQ | ^0.10.9 | 消息队列 | 异步处理、系统解耦（待实现） | | Swagger | ^6.2.8 | API文档 | 自动化文档、接口测试 | | Winston | ^3.11.0 | 日志系统 | 结构化日志、多传输方式 | ### 2.2 安全防护 | 安全组件 | 版本 | 防护类型 | |----------|------|----------| | Helmet | ^7.1.0 | 安全头部 | | express-rate-limit | ^7.1.5 | 请求限流 | | xss-clean | ^0.1.4 | XSS防护 | | hpp | ^0.2.3 | 参数污染防护 | | express-mongo-sanitize | ^2.2.0 | NoSQL注入防护 | ### 2.3 前端技术栈 | 项目 | 技术栈 | 状态 | |------|--------|------| | 微信小程序 | uni-app + Vue 2 | 开发中 | | 后台管理系统 | Vue 3 + TypeScript + Ant Design Vue + Pinia | 开发中 | | 官网系统 | HTML5 + Bootstrap + JavaScript | 待开发 | ### 2.6 选型理由与对比分析 #### 后端技术栈选型理由 **Node.js (TypeScript) + Express.js** - **优势**： - 高性能：Node.js基于事件驱动和非阻塞I/O模型，适合高并发场景 - 生态丰富：npm生态系统庞大，可快速集成各种第三方库 - 全栈统一：前后端均可使用JavaScript/TypeScript，降低开发成本 - 轻量级：Express.js是一个轻量级的Web框架，灵活性高 - RBAC支持：完善的权限管理中间件生态，支持JWT和RBAC权限控制 - **劣势**： - CPU密集型任务处理能力较弱 - 回调地狱问题（TypeScript可有效缓解） #### 前端技术栈选型理由 **uni-app** - **优势**： - 一套代码多端运行：可同时发布到iOS、Android、H5、以及各种小程序平台 - 开发生态：基于Vue.js，学习成本低，社区活跃 - 性能优化：接近原生应用的性能体验 - **劣势**： - 平台限制：某些平台特定功能需要特殊处理 - 复杂度：多端兼容可能带来额外的复杂性 **后台管理系统 (Vue.js 3 + TypeScript + Ant Design Vue + Pinia)** - **优势**： - **类型安全**: TypeScript提供编译时类型检查，减少运行时错误 - **开发体验**: Vue 3 Composition API + `