jiebanke/docs/系统架构文档.md

# 🏗️ 结伴客系统架构文档

## 📋 项目概述

结伴客是一个综合性的社交旅行平台，采用现代化的微服务架构设计，包含后台管理系统、微信小程序和官方网站三个主要模块。系统支持结伴旅行、动物认领、商家服务等核心业务功能。

## 🎯 技术选型

### 前端技术栈

#### 微信小程序
- **开发框架**：原生微信小程序
- **UI组件库**：Vant Weapp
- **状态管理**：原生状态管理
- **网络请求**：wx.request封装
- **构建工具**：微信开发者工具

#### 后台管理系统
- **开发框架**：Vue 3 + TypeScript
- **UI组件库**：Element Plus
- **状态管理**：Pinia
- **路由管理**：Vue Router 4
- **HTTP客户端**：Axios
- **构建工具**：Vite

#### 官方网站
- **开发框架**：Vue 3 + JavaScript
- **UI框架**：自定义CSS + 响应式设计
- **路由管理**：Vue Router
- **构建工具**：Vite
- **SEO优化**：Vue Meta

### 后端技术栈

#### Node.js版本（主要）
- **运行环境**：Node.js 16.x+
- **Web框架**：Express.js
- **数据库ORM**：Sequelize
- **认证授权**：JWT + bcrypt
- **参数验证**：Joi
- **日志管理**：Winston
- **进程管理**：PM2

#### Java微服务版本（备选）
- **开发框架**：Spring Boot 2.7+
- **微服务框架**：Spring Cloud
- **数据库ORM**：MyBatis Plus
- **服务注册**：Eureka Server
- **API网关**：Spring Cloud Gateway
- **配置中心**：Spring Cloud Config

### 数据存储

#### 关系型数据库
- **主数据库**：MySQL 8.0
- **连接池**：HikariCP
- **数据迁移**：Sequelize Migrations
- **备份策略**：定时全量备份 + 增量备份

#### 缓存系统
- **内存缓存**：Redis 6.0+
- **缓存策略**：LRU淘汰策略
- **数据类型**：String、Hash、List、Set
- **持久化**：RDB + AOF

#### 文件存储
- **对象存储**：MinIO / 阿里云OSS
- **CDN加速**：阿里云CDN
- **图片处理**：ImageMagick
- **文件类型**：图片、文档、视频

### 开发工具

#### 版本控制
- **代码仓库**：Git
- **分支策略**：Git Flow
- **代码审查**：Pull Request

#### 代码质量
- **代码规范**：ESLint + Prettier
- **类型检查**：TypeScript
- **单元测试**：Jest + Supertest
- **集成测试**：Postman + Newman

#### 容器化部署
- **容器技术**：Docker
- **编排工具**：Docker Compose
- **镜像仓库**：Docker Hub / 阿里云容器镜像服务

## 🏢 系统架构设计

### 整体架构图

```mermaid
graph TB
    subgraph "客户端层"
        A[微信小程序]
        B[后台管理系统]
        C[官方网站]
    end
    
    subgraph "网关层"
        D[Nginx负载均衡]
        E[API网关]
    end
    
    subgraph "应用服务层"
        F[用户服务]
        G[旅行服务]
        H[动物服务]
        I[商家服务]
        J[订单服务]
        K[消息服务]
    end
    
    subgraph "数据存储层"
        L[MySQL主库]
        M[MySQL从库]
        N[Redis缓存]
        O[MinIO对象存储]
    end
    
    subgraph "基础设施层"
        P[监控系统]
        Q[日志系统]
        R[配置中心]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M
    F --> N
    G --> N
    H --> N
    I --> O
    F --> P
    G --> Q
    H --> R
```

### 微服务架构（Java版本）

```mermaid
graph TB
    subgraph "服务注册中心"
        A[Eureka Server]
    end
    
    subgraph "API网关"
        B[Gateway Service]
    end
    
    subgraph "业务服务"
        C[用户服务 User Service]
        D[认证服务 Auth Service]
        E[旅行服务 Travel Service]
        F[动物服务 Animal Service]
        G[订单服务 Order Service]
        H[推广服务 Promotion Service]
    end
    
    subgraph "数据层"
        I[MySQL集群]
        J[Redis集群]
        K[消息队列 RabbitMQ]
    end
    
    B --> A
    C --> A
    D --> A
    E --> A
    F --> A
    G --> A
    H --> A
    
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    
    C --> I
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    
    C --> J
    E --> J
    F --> J
    
    G --> K
    H --> K
```

## 🗄️ 数据库设计

### 数据库架构

#### 主从复制架构
```mermaid
graph LR
    A[应用服务器] --> B[MySQL主库]
    B --> C[MySQL从库1]
    B --> D[MySQL从库2]
    A --> C
    A --> D
```

#### 分库分表策略
- **用户表**：按用户ID取模分表
- **订单表**：按时间分表（月表）
- **日志表**：按日期分表（日表）

### 核心表结构

#### 用户相关表
```sql
-- 用户基础信息表
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    openid VARCHAR(100) UNIQUE NOT NULL COMMENT '微信openid',
    nickname VARCHAR(50) NOT NULL COMMENT '用户昵称',
    avatar VARCHAR(255) COMMENT '头像URL',
    gender ENUM('male', 'female', 'unknown') DEFAULT 'unknown',
    birthday DATE COMMENT '生日',
    phone VARCHAR(20) COMMENT '手机号',
    email VARCHAR(100) COMMENT '邮箱',
    travel_count INT DEFAULT 0 COMMENT '旅行次数',
    animal_claim_count INT DEFAULT 0 COMMENT '认领动物数量',
    status ENUM('active', 'inactive', 'banned') DEFAULT 'active',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_openid (openid),
    INDEX idx_phone (phone),
    INDEX idx_status (status)
);
```

#### 旅行相关表
```sql
-- 旅行计划表
CREATE TABLE travel_plans (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT NOT NULL,
    destination VARCHAR(100) NOT NULL COMMENT '目的地',
    start_date DATE NOT NULL COMMENT '开始日期',
    end_date DATE NOT NULL COMMENT '结束日期',
    budget DECIMAL(10,2) COMMENT '预算',
    interests TEXT COMMENT '兴趣偏好',
    description TEXT COMMENT '行程描述',
    visibility ENUM('public', 'friends', 'private') DEFAULT 'public',
    max_participants INT DEFAULT 4 COMMENT '最大参与人数',
    current_participants INT DEFAULT 1 COMMENT '当前参与人数',
    status ENUM('active', 'completed', 'cancelled') DEFAULT 'active',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id),
    INDEX idx_destination (destination),
    INDEX idx_date_range (start_date, end_date),
    INDEX idx_status (status)
);
```

#### 动物认领表
```sql
-- 动物信息表
CREATE TABLE animals (
    id INT PRIMARY KEY AUTO_INCREMENT,
    merchant_id INT NOT NULL,
    name VARCHAR(50) NOT NULL COMMENT '动物名称',
    type ENUM('cow', 'sheep', 'pig', 'chicken') NOT NULL COMMENT '动物类型',
    breed VARCHAR(50) COMMENT '品种',
    age INT COMMENT '年龄（月）',
    gender ENUM('male', 'female') COMMENT '性别',
    description TEXT COMMENT '动物描述',
    images JSON COMMENT '动物图片',
    price DECIMAL(10,2) NOT NULL COMMENT '认领价格',
    farm_location VARCHAR(100) COMMENT '农场位置',
    status ENUM('available', 'claimed', 'unavailable') DEFAULT 'available',
    claim_count INT DEFAULT 0 COMMENT '被认领次数',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (merchant_id) REFERENCES merchants(id),
    INDEX idx_type (type),
    INDEX idx_status (status),
    INDEX idx_price (price)
);
```

## 🔐 安全架构

### 认证授权机制

#### JWT Token认证
```mermaid
sequenceDiagram
    participant C as 客户端
    participant A as 认证服务
    participant S as 业务服务
    participant D as 数据库
    
    C->>A: 微信登录请求
    A->>D: 验证用户信息
    D-->>A: 返回用户数据
    A-->>C: 返回JWT Token
    C->>S: 携带Token请求业务接口
    S->>S: 验证Token有效性
    S->>D: 查询业务数据
    D-->>S: 返回业务数据
    S-->>C: 返回业务响应
```

#### 权限控制
- **角色定义**：普通用户、商家用户、管理员
- **权限粒度**：接口级权限控制
- **权限验证**：中间件统一验证

### 数据安全

#### 数据加密
- **传输加密**：HTTPS/TLS 1.3
- **存储加密**：敏感数据AES-256加密
- **密码加密**：bcrypt哈希算法

#### 数据脱敏
- **手机号脱敏**：中间4位显示为*
- **身份证脱敏**：中间部分显示为*
- **银行卡脱敏**：只显示后4位

## 🚀 性能优化

### 缓存策略

#### Redis缓存设计
```mermaid
graph TB
    A[客户端请求] --> B{缓存命中?}
    B -->|是| C[返回缓存数据]
    B -->|否| D[查询数据库]
    D --> E[更新缓存]
    E --> F[返回数据]
```

#### 缓存层级
- **L1缓存**：应用内存缓存（Node.js内存）
- **L2缓存**：Redis分布式缓存
- **L3缓存**：CDN边缘缓存

### 数据库优化

#### 索引策略
- **主键索引**：所有表必须有主键
- **唯一索引**：唯一字段建立唯一索引
- **复合索引**：多字段查询建立复合索引
- **覆盖索引**：高频查询建立覆盖索引

#### 查询优化
- **分页查询**：使用LIMIT + OFFSET
- **批量操作**：使用批量插入/更新
- **读写分离**：读操作走从库，写操作走主库

## 📊 监控运维

### 系统监控

#### 监控指标
- **系统指标**：CPU、内存、磁盘、网络
- **应用指标**：QPS、响应时间、错误率
- **业务指标**：用户活跃度、订单量、收入

#### 监控工具
- **系统监控**：Prometheus + Grafana
- **应用监控**：APM工具
- **日志监控**：ELK Stack

### 日志管理

#### 日志分类
- **访问日志**：记录所有API请求
- **错误日志**：记录系统异常和错误
- **业务日志**：记录关键业务操作
- **审计日志**：记录敏感操作

#### 日志格式
```json
{
  "timestamp": "2025-01-01T12:00:00.000Z",
  "level": "info",
  "service": "user-service",
  "traceId": "abc123",
  "userId": 1001,
  "action": "login",
  "message": "用户登录成功",
  "duration": 150,
  "ip": "192.168.1.100"
}
```

## 🔄 部署架构

### 容器化部署

#### Docker容器设计
```dockerfile
# Node.js应用容器
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
```

#### Docker Compose编排
```yaml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - mysql
      - redis
    environment:
      - NODE_ENV=production
  
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - mysql_data:/var/lib/mysql
  
  redis:
    image: redis:6-alpine
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:
```

### 负载均衡

#### Nginx配置
```nginx
upstream backend {
    server app1:3000 weight=1;
    server app2:3000 weight=1;
    server app3:3000 weight=1;
}

server {
    listen 80;
    server_name api.jiebanke.com;
    
    location / {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

## 📈 扩展性设计

### 水平扩展

#### 应用层扩展
- **无状态设计**：应用服务无状态，支持水平扩展
- **负载均衡**：通过负载均衡器分发请求
- **自动扩缩容**：基于CPU/内存使用率自动扩缩容

#### 数据层扩展
- **读写分离**：主库写入，从库读取
- **分库分表**：按业务或数据量分库分表
- **缓存集群**：Redis集群模式

### 垂直扩展

#### 服务拆分
- **按业务拆分**：用户服务、订单服务、支付服务
- **按功能拆分**：认证服务、通知服务、文件服务
- **按数据拆分**：用户数据、业务数据、日志数据

## 🔮 技术演进规划

### 短期规划（3-6个月）
- 完善监控告警系统
- 优化数据库性能
- 增强安全防护机制

### 中期规划（6-12个月）
- 微服务架构改造
- 引入消息队列
- 实现服务治理

### 长期规划（1-2年）
- 云原生架构转型
- 大数据分析平台
- AI智能推荐系统

---

*文档版本：v1.0*  
*最后更新：2025年1月*