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

# 活牛采购智能数字化系统 - 系统架构文档

## 概述

活牛采购智能数字化系统是一个基于Node.js和Vue.js的全栈Web应用，采用前后端分离架构，为活牛采购业务提供完整的数字化解决方案。

## 技术栈

### 后端技术栈
- **运行环境**: Node.js 18+
- **Web框架**: Express.js 4.x
- **数据库**: MySQL 8.0
- **ORM框架**: Sequelize 6.x
- **认证授权**: JWT (jsonwebtoken)
- **API文档**: Swagger/OpenAPI 3.0
- **数据验证**: Joi
- **日志记录**: Morgan + Winston
- **进程管理**: PM2
- **容器化**: Docker

### 前端技术栈
- **框架**: Vue.js 3.x
- **构建工具**: Vite
- **UI组件库**: Element Plus
- **状态管理**: Pinia
- **路由管理**: Vue Router 4.x
- **HTTP客户端**: Axios
- **样式预处理**: SCSS

### 开发工具
- **版本控制**: Git
- **代码规范**: ESLint + Prettier
- **包管理**: npm
- **API测试**: Postman
- **数据库管理**: MySQL Workbench

## 系统架构

### 整体架构图

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端应用      │    │   后端API服务   │    │   数据库服务    │
│   (Vue.js)      │◄──►│   (Express.js)  │◄──►│   (MySQL)       │
│                 │    │                 │    │                 │
│ - 用户界面      │    │ - RESTful API   │    │ - 业务数据      │
│ - 状态管理      │    │ - 业务逻辑      │    │ - 用户数据      │
│ - 路由控制      │    │ - 数据验证      │    │ - 系统配置      │
│ - HTTP请求      │    │ - 认证授权      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

### 后端架构设计

#### 分层架构
```
┌─────────────────────────────────────────────────────────────┐
│                        路由层 (Routes)                      │
│  处理HTTP请求路由，参数验证，权限检查                        │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                       控制器层 (Controllers)                │
│  处理业务请求，调用服务层，返回响应                          │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                       服务层 (Services)                     │
│  核心业务逻辑，数据处理，事务管理                            │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                       数据层 (Models)                       │
│  数据模型定义，数据库操作，关联关系                          │
└─────────────────────────────────────────────────────────────┘
```

#### 目录结构
```
backend/
├── src/
│   ├── config/          # 配置文件
│   │   ├── config.js    # 应用配置
│   │   └── database.js  # 数据库配置
│   ├── controllers/     # 控制器层
│   │   ├── AuthController.js
│   │   ├── UserController.js
│   │   ├── OrderController.js
│   │   ├── SupplierController.js
│   │   ├── TransportController.js
│   │   ├── DriverController.js
│   │   ├── VehicleController.js
│   │   └── PaymentController.js
│   ├── services/        # 服务层
│   │   ├── AuthService.js
│   │   ├── UserService.js
│   │   ├── OrderService.js
│   │   ├── SupplierService.js
│   │   ├── TransportService.js
│   │   ├── DriverService.js
│   │   ├── VehicleService.js
│   │   └── PaymentService.js
│   ├── models/          # 数据模型
│   │   ├── User.js
│   │   ├── Order.js
│   │   ├── Supplier.js
│   │   ├── Transport.js
│   │   ├── Driver.js
│   │   ├── Vehicle.js
│   │   ├── Payment.js
│   │   └── index.js
│   ├── routes/          # 路由定义
│   │   ├── auth.js
│   │   ├── users.js
│   │   ├── orders.js
│   │   ├── suppliers.js
│   │   ├── transports.js
│   │   ├── drivers.js
│   │   ├── vehicles.js
│   │   └── payments.js
│   ├── middleware/      # 中间件
│   │   ├── auth.js      # 认证授权
│   │   ├── validation.js # 数据验证
│   │   ├── errorHandler.js # 错误处理
│   │   ├── logger.js    # 日志记录
│   │   └── healthCheck.js # 健康检查
│   ├── utils/           # 工具函数
│   │   └── response.js  # 响应格式化
│   └── main.js          # 应用入口
├── docs/                # API文档
├── tests/               # 测试文件
├── package.json         # 依赖配置
└── README.md           # 项目说明
```

## 核心模块设计

### 1. 认证授权模块
- **JWT Token认证**: 无状态的用户认证机制
- **角色权限控制**: 基于用户角色的访问控制
- **资源权限检查**: 细粒度的资源访问控制
- **Token刷新机制**: 自动续期和安全退出

### 2. 用户管理模块
- **用户注册登录**: 支持多种用户类型注册
- **用户信息管理**: 个人信息维护和更新
- **用户状态管理**: 激活、暂停、删除等状态控制
- **权限分配**: 动态权限分配和管理

### 3. 订单管理模块
- **订单创建**: 支持复杂的订单信息录入
- **订单跟踪**: 全流程订单状态跟踪
- **订单审核**: 多级审核流程支持
- **订单统计**: 丰富的订单数据分析

### 4. 供应商管理模块
- **供应商注册**: 供应商信息录入和审核
- **资质管理**: 供应商资质证书管理
- **评价体系**: 供应商评价和信用管理
- **合作管理**: 供应商合作关系维护

### 5. 运输管理模块
- **运输任务**: 运输任务创建和分配
- **实时跟踪**: GPS定位和运输状态跟踪
- **路线优化**: 智能路线规划和优化
- **运费结算**: 自动化运费计算和结算

### 6. 司机管理模块
- **司机档案**: 司机基本信息和资质管理
- **任务分配**: 智能任务分配和调度
- **绩效考核**: 司机绩效评估和奖惩
- **培训管理**: 司机培训记录和证书管理

### 7. 车辆管理模块
- **车辆档案**: 车辆基本信息和证件管理
- **维护保养**: 车辆维护计划和记录
- **保险管理**: 车辆保险信息和到期提醒
- **使用统计**: 车辆使用情况统计分析

### 8. 支付管理模块
- **支付处理**: 多种支付方式支持
- **账单管理**: 自动生成和管理账单
- **财务对账**: 支付记录和财务对账
- **结算管理**: 供应商和司机结算管理

## 数据库设计

### 核心数据表

#### 用户表 (users)
```sql
CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  username VARCHAR(50) UNIQUE NOT NULL,
  password VARCHAR(255) NOT NULL,
  name VARCHAR(100) NOT NULL,
  user_type ENUM('admin', 'buyer', 'supplier', 'driver') NOT NULL,
  phone VARCHAR(20),
  email VARCHAR(100),
  status ENUM('active', 'inactive', 'suspended') DEFAULT 'active',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

#### 订单表 (orders)
```sql
CREATE TABLE orders (
  id INT PRIMARY KEY AUTO_INCREMENT,
  order_number VARCHAR(50) UNIQUE NOT NULL,
  supplier_id INT NOT NULL,
  buyer_id INT NOT NULL,
  cattle_type VARCHAR(50) NOT NULL,
  quantity INT NOT NULL,
  unit_price DECIMAL(10,2) NOT NULL,
  total_amount DECIMAL(12,2) NOT NULL,
  delivery_date DATE,
  delivery_address TEXT,
  status ENUM('pending', 'confirmed', 'in_progress', 'completed', 'cancelled') DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  FOREIGN KEY (supplier_id) REFERENCES suppliers(id),
  FOREIGN KEY (buyer_id) REFERENCES users(id)
);
```

#### 运输表 (transports)
```sql
CREATE TABLE transports (
  id INT PRIMARY KEY AUTO_INCREMENT,
  transport_number VARCHAR(50) UNIQUE NOT NULL,
  order_id INT NOT NULL,
  driver_id INT,
  vehicle_id INT,
  pickup_address TEXT NOT NULL,
  delivery_address TEXT NOT NULL,
  scheduled_pickup_time DATETIME,
  scheduled_delivery_time DATETIME,
  actual_pickup_time DATETIME,
  actual_delivery_time DATETIME,
  transport_fee DECIMAL(10,2),
  status ENUM('pending', 'assigned', 'picked_up', 'in_transit', 'delivered', 'completed', 'cancelled') DEFAULT 'pending',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  FOREIGN KEY (order_id) REFERENCES orders(id),
  FOREIGN KEY (driver_id) REFERENCES drivers(id),
  FOREIGN KEY (vehicle_id) REFERENCES vehicles(id)
);
```

### 数据关系图
```
users ──┐
        ├── orders ── transports ──┐
suppliers ──┘                     ├── drivers
                                  └── vehicles
                    payments ──────┘
```

## 安全设计

### 1. 认证安全
- **密码加密**: 使用bcrypt进行密码哈希
- **JWT安全**: 设置合理的过期时间和密钥管理
- **会话管理**: 支持主动登出和Token失效

### 2. 授权安全
- **角色权限**: 基于角色的访问控制(RBAC)
- **资源权限**: 细粒度的资源访问控制
- **API权限**: 接口级别的权限验证

### 3. 数据安全
- **输入验证**: 严格的数据验证和过滤
- **SQL注入防护**: 使用ORM防止SQL注入
- **XSS防护**: 输出编码和CSP策略

### 4. 传输安全
- **HTTPS**: 强制使用HTTPS传输
- **CORS配置**: 合理的跨域资源共享配置
- **请求限流**: API请求频率限制

## 性能优化

### 1. 数据库优化
- **索引优化**: 合理设计数据库索引
- **查询优化**: 优化复杂查询和关联查询
- **连接池**: 数据库连接池管理
- **读写分离**: 支持主从数据库架构

### 2. 缓存策略
- **Redis缓存**: 热点数据缓存
- **查询缓存**: 频繁查询结果缓存
- **会话缓存**: 用户会话信息缓存

### 3. 接口优化
- **分页查询**: 大数据量分页处理
- **数据压缩**: 响应数据压缩
- **并发控制**: 合理的并发处理机制

### 4. 前端优化
- **代码分割**: 按需加载和代码分割
- **资源压缩**: 静态资源压缩和优化
- **CDN加速**: 静态资源CDN分发

## 部署架构

### 开发环境
```
开发者本地 ──► 本地数据库
    │
    └──► 本地前后端服务
```

### 生产环境
```
负载均衡器 ──► Web服务器集群 ──► 应用服务器集群 ──► 数据库集群
    │              │                │               │
    └─ SSL终结     └─ 静态资源      └─ API服务      └─ 主从复制
                     Nginx           PM2集群         MySQL集群
```

### 容器化部署
```yaml
# docker-compose.yml
version: '3.8'
services:
  frontend:
    build: ./frontend
    ports:
      - "80:80"
  
  backend:
    build: ./backend
    ports:
      - "3000:3000"
    depends_on:
      - database
  
  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
    volumes:
      - mysql_data:/var/lib/mysql
```

## 监控和日志

### 1. 应用监控
- **性能监控**: 接口响应时间和吞吐量
- **错误监控**: 异常和错误统计
- **资源监控**: CPU、内存、磁盘使用情况

### 2. 日志管理
- **访问日志**: HTTP请求访问记录
- **应用日志**: 应用运行状态日志
- **错误日志**: 异常和错误详细信息
- **审计日志**: 重要操作审计记录

### 3. 告警机制
- **阈值告警**: 性能指标超阈值告警
- **异常告警**: 系统异常实时告警
- **业务告警**: 关键业务指标告警

## 扩展性设计

### 1. 水平扩展
- **无状态设计**: 应用服务无状态化
- **负载均衡**: 支持多实例负载均衡
- **数据库分片**: 支持数据库水平分片

### 2. 垂直扩展
- **模块化设计**: 松耦合的模块化架构
- **微服务架构**: 支持向微服务架构演进
- **API网关**: 统一的API网关管理

### 3. 功能扩展
- **插件机制**: 支持功能插件扩展
- **配置管理**: 灵活的配置管理机制
- **版本管理**: API版本管理和兼容性

## 技术债务和改进计划

### 短期改进
1. 完善单元测试和集成测试
2. 优化数据库查询性能
3. 增强错误处理和日志记录
4. 完善API文档和使用说明

### 中期改进
1. 引入缓存机制提升性能
2. 实现实时通知和消息推送
3. 增加数据备份和恢复机制
4. 优化前端用户体验

### 长期规划
1. 微服务架构重构
2. 大数据分析和智能决策
3. 移动端应用开发
4. 云原生架构升级

## 总结

本系统采用现代化的技术栈和架构设计，具有良好的可扩展性、可维护性和安全性。通过分层架构和模块化设计，系统能够满足活牛采购业务的复杂需求，并为未来的功能扩展和性能优化提供了良好的基础。