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

## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目架构整理更新 |

## 1. 整体架构

### 1.1 系统架构图
```mermaid
flowchart TD
    subgraph "前端层"
        A[管理后台
Vue 3 + TypeScript] --> |API调用| G
        B[小程序
Uni-app] --> |API调用| G
        C[官网
HTML5 + Bootstrap] --> |静态展示| D
    end
    
    subgraph "后端层"
        G[API Gateway
认证与路由] --> H
        H[Express.js服务集群
业务逻辑处理] --> I
    end
    
    subgraph "数据层"
        I[MySQL数据库
业务数据存储] --> J
        J[Redis缓存
性能优化] --> K
        K[文件存储
视频与证件] --> L
    end
    
    subgraph "辅助服务"
        L[消息通知
流程提醒] --> M
        M[实时通信
WebSocket] --> N
        N[第三方服务
支付、地图等] --> O
    end
```

### 1.2 系统分层说明
- **前端层**：包含管理后台、小程序和官网三部分，分别面向不同用户群体提供服务
- **后端层**：采用Express.js作为主要框架，提供统一的API接口和业务逻辑处理
- **数据层**：使用MySQL存储业务数据，Redis提高性能，文件存储服务管理视频和证件
- **辅助服务**：包括消息通知、实时通信和第三方服务集成

## 2. 技术栈选型

### 2.1 核心技术栈
| 类别 | 技术/框架 | 版本 | 用途 | 选型理由 |
|------|-----------|------|------|----------|
| 前端框架 | Vue 3 | 3.x | 管理后台开发 | 生态成熟，TypeScript支持好，性能优秀 |
| 编程语言 | TypeScript | 4.x+ | 前端开发 | 静态类型检查，提高代码质量和可维护性 |
| UI组件库 | Element Plus | 2.x | 管理后台UI | Vue 3官方推荐，组件丰富，文档完善 |
| 构建工具 | Vite | 4.x | 前端构建 | 极速开发体验，优化构建性能 |
| 状态管理 | Pinia | 2.x | 前端状态管理 | Vue 3官方推荐，API简洁，性能优异 |
| 后端框架 | Express.js | 4.x | 后端服务 | 轻量灵活，生态丰富，学习成本低 |
| 数据库 | MySQL | 5.7 | 关系型数据存储 | 成熟稳定，适合复杂业务关系存储 |
| ORM框架 | Sequelize | 6.x | 数据库访问 | 支持多种数据库，简化数据库操作 |
| 缓存 | Redis | 6.x | 性能优化 | 提升系统响应速度，减轻数据库压力 |
| 小程序框架 | Uni-app | 3.x | 跨平台小程序 | 一套代码多端运行，降低开发维护成本 |

### 2.2 工具与中间件
| 类别 | 工具/中间件 | 用途 |
|------|------------|------|
| API文档 | Swagger | 自动生成API文档 |
| 身份验证 | JWT | 用户身份认证 |
| 安全加固 | Helmet | 增强Express应用安全性 |
| 跨域处理 | CORS | 解决跨域请求问题 |
| 请求限流 | Express-rate-limit | 防止API滥用 |
| 日志管理 | Morgan | HTTP请求日志记录 |
| 数据验证 | Joi | API请求数据校验 |
| 环境配置 | dotenv | 环境变量管理 |

## 3. 系统模块划分

### 3.1 核心业务模块
| 模块名称 | 主要职责 | 文件位置 | 备注 |
|---------|---------|---------|------|
| 用户管理 | 用户CRUD、权限控制、认证登录 | backend/routes/users.js | 已实现基础功能 |
| 订单管理 | 订单创建、查询、更新、取消 | backend/routes/orders.js | 已实现模拟数据接口 |
| 供应商管理 | 供应商信息管理、资质审核 | backend/routes/suppliers.js | 已实现模拟数据接口 |
| 运输管理 | 运输跟踪、状态上报 | backend/routes/transport.js | 待完善 |
| 财务管理 | 结算、支付、财务数据处理 | backend/routes/finance.js | 已实现模拟数据接口 |
| 质量管理 | 牛只质量检验、报告管理 | backend/routes/quality.js | 已实现模拟数据接口 |

### 3.2 前端模块结构
| 模块名称 | 功能描述 | 文件位置 |
|---------|---------|---------|
| 登录模块 | 用户认证登录 | admin-system/src/views/login/ |
| 数据驾驶舱 | 系统概览、关键指标 | admin-system/src/views/dashboard/ |
| 订单管理 | 订单列表、详情、操作 | admin-system/src/views/order/ |
| 用户管理 | 用户列表、角色权限 | admin-system/src/views/user/ |
| 供应商管理 | 供应商信息维护 | admin-system/src/views/supplier/ |
| 运输管理 | 运输状态跟踪 | admin-system/src/views/transport/ |
| 财务管理 | 财务结算管理 | admin-system/src/views/finance/ |
| 质量管理 | 质量检验记录 | admin-system/src/views/quality/ |
| 系统设置 | 系统参数配置 | admin-system/src/views/settings/ |

## 4. 数据库架构

### 4.1 主要数据表结构
| 表名 | 主要职责 | 关键字段 | 备注 |
|------|---------|---------|------|
| users | 用户信息存储 | id, username, phone, user_type, password_hash | 已实现模型定义 |
| orders | 订单信息存储 | id, orderNo, buyerId, supplierId, status, totalAmount | 已在路由中定义数据结构 |
| suppliers | 供应商信息 | id, name, code, contact, phone, address, status | 已在路由中定义数据结构 |
| settlements | 结算信息 | id, orderId, totalAmount, paymentStatus, paymentDate | 已在路由中定义数据结构 |
| quality_records | 质量检测记录 | id, orderId, inspectorName, healthStatus, qualityScore | 已在路由中定义数据结构 |

### 4.2 数据库连接配置
```javascript
// 数据库连接配置示例
const sequelize = new Sequelize({
  host: process.env.DB_HOST || '129.211.213.226',
  port: process.env.DB_PORT || 9527,
  database: process.env.DB_NAME || 'jiebandata',
  username: process.env.DB_USER || 'root',
  password: process.env.DB_PASSWORD || 'aiotAiot123!',
  dialect: process.env.DB_DIALECT || 'mysql',
  logging: process.env.NODE_ENV === 'development' ? console.log : false,
  pool: {
    max: 5,
    min: 0,
    acquire: 30000,
    idle: 10000
  },
  define: {
    timestamps: true,
    underscored: true,
    freezeTableName: true
  },
  timezone: '+08:00'
});
```

## 5. 系统部署架构

### 5.1 开发环境部署
- **前端**：本地开发服务器，通过Vite热更新
- **后端**：本地Express.js服务器
- **数据库**：远程MySQL服务器

### 5.2 生产环境部署建议
```mermaid
flowchart TD
    subgraph "负载均衡层"
        A[NGINX
负载均衡] --> B
    end
    
    subgraph "应用层"
        B[PM2集群
Express.js实例] --> C
        C[Redis缓存
会话与数据缓存] --> D
    end
    
    subgraph "数据层"
        D[MySQL主从
数据持久化] --> E
        E[文件存储
OSS/MinIO] --> F
    end
    
    subgraph "监控与日志"
        F[日志系统
ELK Stack] --> G
        G[监控系统
Prometheus+Grafana] --> H
    end
```

## 6. 接口与集成

### 6.1 API接口规范
- 所有API接口统一以`/api/`开头
- 使用RESTful风格设计
- 统一的响应格式：`{ success: boolean, message: string, data?: any }`
- 使用JWT进行身份认证
- 支持分页查询：`page`和`pageSize`参数

### 6.2 第三方服务集成
- **支付接口**：待集成主流支付平台
- **地图服务**：用于运输轨迹跟踪
- **短信服务**：用于用户验证和通知
- **文件存储**：用于视频和证件存储

## 7. 安全架构

### 7.1 身份认证与授权
- 使用JWT进行无状态身份认证
- 基于角色的访问控制(RBAC)
- 密码加密存储(bcrypt)

### 7.2 数据安全
- HTTPS加密传输
- 敏感数据加密存储
- SQL注入防护
- XSS攻击防护
- 请求限流防刷

### 7.3 日志与审计
- 关键操作日志记录
- 用户行为审计追踪
- 异常日志监控报警

## 8. 性能优化

### 8.1 前端性能优化
- 组件懒加载
- 路由懒加载
- 图片优化
- 资源缓存策略

### 8.2 后端性能优化
- Redis缓存热点数据
- 数据库索引优化
- 连接池管理
- API响应压缩

### 8.3 数据库性能优化
- 合理设计索引
- 分表分库策略(未来扩展)
- 读写分离(未来扩展)

## 9. 扩展性设计

### 9.1 微服务转型规划
当前系统采用单体架构，未来可考虑向微服务转型，主要拆分方向：
- 用户服务(user-service)
- 订单服务(order-service)
- 支付服务(payment-service)
- 运输服务(transport-service)
- 文件服务(file-service)

### 9.2 API网关规划
未来微服务架构下，引入API网关统一管理：
- 路由转发
- 身份认证
- 限流熔断
- 监控日志

## 10. 风险评估与应对

### 10.1 技术风险
- **数据库连接失败**：实现连接重试机制，支持多数据源
- **性能瓶颈**：引入缓存层，优化数据库查询，考虑读写分离
- **系统可用性**：部署多实例，实现负载均衡和故障转移

### 10.2 业务风险
- **数据一致性**：使用事务确保关键业务操作的数据一致性
- **操作错误**：增加操作日志记录，支持关键操作撤销
- **合规性**：确保系统满足行业相关法规和标准要求

### 10.3 安全风险
- **数据泄露**：实施数据加密，严格的权限控制，定期安全审计
- **DDoS攻击**：配置防火墙，实施请求限流
- **代码漏洞**：定期代码审计，使用安全扫描工具