jiebanke/docs/architecture-java.md

# 🏗️ 结伴客Java微服务架构文档

## 📋 项目概述
结伴客项目是一个综合性的管理系统，包含后台管理、微信小程序和官网三个主要模块。本项目采用Java微服务架构，基于Spring Boot和Spring Cloud实现。

## 🎯 技术栈

### 后端技术栈
- **运行时**: Java 17
- **框架**: Spring Boot 3.1.0 + Spring Cloud 2022.0.3
- **服务注册与发现**: Eureka Server
- **API网关**: Spring Cloud Gateway
- **数据库**: MySQL 8.0
- **ORM**: MyBatis-Plus 3.5.3.1
- **认证**: JWT + Spring Security
- **缓存**: Redis 6.0+
- **消息队列**: RabbitMQ 3.8+
- **构建工具**: Maven 3.6+

### 前端技术栈
- **后台管理系统**: Vue 3 + Element Plus
- **微信小程序**: 原生小程序 + Vant Weapp
- **官方网站**: Vue 3 + Vue Router

### 开发工具
- **包管理**: npm
- **容器化**: Docker + Docker Compose
- **代码质量**: Checkstyle + PMD
- **测试**: JUnit 5 + Mockito

## 🏢 系统架构

```mermaid
graph TB
    subgraph "前端应用"
        A[后台管理系统]
        B[微信小程序]
        C[官方网站]
    end
    
    subgraph "API网关层"
        D[Spring Cloud Gateway]
    end
    
    subgraph "微服务层"
        E[Eureka Server]
        F[Auth Service]
        G[User Service]
        H[Travel Service]
        I[Animal Service]
        J[Order Service]
        K[Promotion Service]
    end
    
    subgraph "数据层"
        L[MySQL]
        M[Redis]
        N[RabbitMQ]
    end
    
    A --> D
    B --> D
    C --> D
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    D --> K
    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    F --> N
    G --> N
    H --> N
    I --> N
    J --> N
    K --> N
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
```

## 🗄️ 数据库设计

### 核心表结构设计

```mermaid
erDiagram
    USERS ||--o{ TRAVEL_PLANS : creates
    USERS ||--o{ ANIMAL_CLAIMS : claims
    USERS ||--o{ FLOWER_ORDERS : places
    MERCHANTS ||--o{ ANIMALS : owns
    MERCHANTS ||--o{ FLOWER_PRODUCTS : sells
    ANIMALS ||--o{ ANIMAL_CLAIMS : claimed_by
    FLOWER_PRODUCTS ||--o{ FLOWER_ORDERS : ordered
    TRAVEL_PLANS ||--o{ TRAVEL_INVITATIONS : has
    ADMINS ||--o{ ADMIN_LOGS : manages
    
    USERS {
        bigint id PK
        varchar username
        varchar password
        varchar email
        varchar phone
        varchar real_name
        varchar id_card
        varchar status
        decimal balance
        int credit_score
        timestamp last_login
        timestamp created_at
        timestamp updated_at
    }
    
    ADMINS {
        bigint id PK
        varchar username
        varchar password
        varchar email
        varchar role
        varchar status
        timestamp last_login
        timestamp created_at
        timestamp updated_at
    }
    
    MERCHANTS {
        bigint id PK
        bigint user_id FK
        varchar merchant_type
        varchar business_name
        varchar business_license
        varchar contact_person
        varchar contact_phone
        varchar address
        varchar description
        varchar status
        timestamp created_at
        timestamp updated_at
    }
    
    TRAVEL_PLANS {
        bigint id PK
        bigint user_id FK
        varchar destination
        date start_date
        date end_date
        decimal budget
        text interests
        text description
        varchar visibility
        varchar status
        timestamp created_at
        timestamp updated_at
    }
    
    ANIMALS {
        bigint id PK
        bigint merchant_id FK
        varchar name
        varchar species
        varchar breed
        date birth_date
        text personality
        varchar farm_location
        decimal price
        int claim_count
        varchar status
        timestamp created_at
        timestamp updated_at
    }
    
    ANIMAL_CLAIMS {
        bigint id PK
        bigint user_id FK
        bigint animal_id FK
        int duration
        decimal total_amount
        varchar status
        date start_date
        date end_date
        timestamp created_at
        timestamp updated_at
    }
    
    FLOWER_PRODUCTS {
        bigint id PK
        bigint merchant_id FK
        varchar name
        text description
        decimal price
        decimal original_price
        json images
        varchar category
        int sales_count
        decimal rating
        varchar status
        timestamp created_at
        timestamp updated_at
    }
    
    FLOWER_ORDERS {
        bigint id PK
        bigint user_id FK
        bigint product_id FK
        varchar order_number
        int quantity
        decimal total_amount
        json recipient_info
        date delivery_date
        varchar message
        varchar status
        timestamp created_at
        timestamp updated_at
    }
    
    PROMOTION_ACTIVITIES {
        bigint id PK
        varchar name
        text description
        varchar reward_type
        decimal reward_amount
        varchar status
        timestamp start_time
        timestamp end_time
        int max_participants
        int current_participants
        timestamp created_at
        timestamp updated_at
    }
    
    REWARD_RECORDS {
        bigint id PK
        bigint user_id
        varchar user_name
        varchar user_phone
        bigint activity_id
        varchar activity_name
        varchar reward_type
        decimal reward_amount
        varchar status
        timestamp issued_at
        timestamp created_at
    }
```

## 🌐 环境配置

### 开发环境 (Development)
```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_DATABASE=jiebanke
NODE_ENV=development
```

### 测试环境 (Test)
```env
DB_HOST=192.168.0.240
DB_PORT=3306
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DATABASE=jiebandata_test
NODE_ENV=test
```

### 生产环境 (Production)
```env
DB_HOST=129.211.213.226
DB_PORT=9527
DB_USER=root
DB_PASSWORD=Aiot123
DB_DATABASE=jiebandata
NODE_ENV=production
```

## 🔌 API 设计

### 用户模块接口

#### 微信用户登录
- **Endpoint:** `POST /api/auth/wechat-login`
- **Method:** POST
- **Description:** 微信用户登录获取Token
- **Request Body:**
  ```json
  {
    "code": "string, required",
    "userInfo": {
      "nickName": "string, required",
      "avatarUrl": "string, required",
      "gender": "number, optional",
      "province": "string, optional",
      "city": "string, optional"
    }
  }
  ```
- **Response:**
  ```json
  {
    "code": 200,
    "message": "登录成功",
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "id": 1,
        "username": "旅行达人",
        "avatar": "https://avatar.url",
        "gender": "male",
        "phone": "13800138000"
      }
    }
  }
  ```

#### 获取用户信息
- **Endpoint:** `GET /api/users/profile`
- **Method:** GET
- **Description:** 获取当前登录用户详细信息
- **Headers:** `Authorization: Bearer <token>`
- **Response:**
  ```json
  {
    "code": 200,
    "message": "获取成功",
    "data": {
      "id": 1,
      "username": "旅行达人",
      "avatar": "https://avatar.url",
      "gender": "male",
      "birthday": "1990-01-01",
      "phone": "13800138000",
      "email": "test@jiebanke.com",
      "travelCount": 5,
      "animalClaimCount": 2,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
  ```

## 🚀 部署架构

### 开发部署
```mermaid
graph LR
    A[本地开发机] --> B[Docker Compose]
    B --> C[MySQL容器]
    B --> D[Redis容器]
    B --> E[RabbitMQ容器]
    B --> F[微服务容器]
```

### 生产部署
```mermaid
graph TB
    subgraph "负载均衡器"
        A[Nginx]
    end
    
    subgraph "微服务集群"
        B[API网关集群]
        C[认证服务集群]
        D[用户服务集群]
        E[旅行服务集群]
        F[动物服务集群]
        G[订单服务集群]
        H[推广服务集群]
    end
    
    subgraph "基础设施"
        I[MySQL主从]
        J[Redis集群]
        K[RabbitMQ集群]
        L[Eureka集群]
    end
    
    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H
    C --> I
    C --> J
    C --> K
    D --> I
    D --> J
    D --> K
    E --> I
    E --> J
    E --> K
    F --> I
    F --> J
    F --> K
    G --> I
    G --> J
    G --> K
    H --> I
    H --> J
    H --> K
```

## 📊 监控与日志

- **应用监控**: Spring Boot Actuator + Prometheus + Grafana
- **日志管理**: Logback + ELK Stack
- **性能监控**: Micrometer + Prometheus
- **错误追踪**: Sentry

## 🔒 安全架构

### 认证授权
- JWT Token 认证
- RBAC (基于角色的访问控制)
- API 速率限制

### 数据安全
- HTTPS 加密传输
- 密码加盐哈希存储
- SQL 注入防护
- XSS 攻击防护

### 网络安全
- 防火墙规则
- IP 白名单
- DDoS 防护

## 📈 性能优化

### 数据库优化
- 索引优化
- 查询缓存
- 读写分离

### 应用优化
- JVM调优
- 连接池优化
- 缓存策略优化

### 微服务优化
- 负载均衡
- 熔断机制
- 服务降级

## 🛠️ 开发规范

### 代码规范
- Checkstyle + PMD 统一代码风格
- Git Commit 消息规范
- 代码审查流程

### 分支策略
- Git Flow 工作流
- 功能分支开发
- 发布分支管理

### 测试策略
- 单元测试覆盖核心逻辑
- 集成测试API接口
- 压力测试性能指标

## 📝 文档体系

1. **ARCHITECTURE.md** - 系统架构文档 (当前文件)
2. **README.md** - 项目说明文档
3. **API_DOCS.md** - API接口文档
4. **DEPLOYMENT.md** - 部署指南
5. **DEVELOPMENT.md** - 开发指南

## 🎯 后续规划

### 短期目标
- [x] 完成用户管理系统
- [x] 实现订单业务流程
- [x] 部署测试环境

### 中期目标
- [x] 微服务架构改造
- [x] 容器化部署
- [ ] 自动化测试覆盖

### 长期目标
- [ ] 大数据分析平台
- [ ] AI智能推荐
- [ ] 多语言国际化

---
*最后更新: 2025年* 📅