aiotagro/niumalll
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): 简化README结构，更新技术栈和项目结构描述

Browse Source
This commit is contained in:
aiotagro
2025-09-20 15:19:59 +08:00
parent cec08f89e2
commit b8c9e5c959
54 changed files with 14343 additions and 6124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

614
docs/系统架构文档.md
View File

@@ -1,266 +1,404 @@
# 活牛采购智能数字化系统 - 系统架构文档
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目架构整理更新 |
## 概述
## 1. 整体架构
活牛采购智能数字化系统是一个基于Node.js和Vue.js的全栈Web应用，采用前后端分离架构，为活牛采购业务提供完整的数字化解决方案。
### 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
## 技术栈
### 后端技术栈
- **运行环境**: 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请求 │ │ - 认证授权 │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### 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'
});
#### 分层架构
```
┌─────────────────────────────────────────────────────────────┐
│ 路由层 (Routes) │
│ 处理HTTP请求路由，参数验证，权限检查 │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 控制器层 (Controllers) │
│ 处理业务请求，调用服务层，返回响应 │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 服务层 (Services) │
│ 核心业务逻辑，数据处理，事务管理 │
└─────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────┐
│ 数据层 (Models) │
│ 数据模型定义，数据库操作，关联关系 │
└─────────────────────────────────────────────────────────────┘
```
## 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
#### 目录结构
```
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 # 项目说明
```
## 6. 接口与集成
## 核心模块设计
### 6.1 API接口规范
- 所有API接口统一以`/api/`开头
- 使用RESTful风格设计
- 统一的响应格式：`{ success: boolean, message: string, data?: any }`
- 使用JWT进行身份认证
- 支持分页查询：`page`和`pageSize`参数
### 1. 认证授权模块
- **JWT Token认证**: 无状态的用户认证机制
- **角色权限控制**: 基于用户角色的访问控制
- **资源权限检查**: 细粒度的资源访问控制
- **Token刷新机制**: 自动续期和安全退出
### 6.2 第三方服务集成
- **支付接口**：待集成主流支付平台
- **地图服务**：用于运输轨迹跟踪
- **短信服务**：用于用户验证和通知
- **文件存储**：用于视频和证件存储
### 2. 用户管理模块
- **用户注册登录**: 支持多种用户类型注册
- **用户信息管理**: 个人信息维护和更新
- **用户状态管理**: 激活、暂停、删除等状态控制
- **权限分配**: 动态权限分配和管理
## 7. 安全架构
### 3. 订单管理模块
- **订单创建**: 支持复杂的订单信息录入
- **订单跟踪**: 全流程订单状态跟踪
- **订单审核**: 多级审核流程支持
- **订单统计**: 丰富的订单数据分析
### 7.1 身份认证与授权
- 使用JWT进行无状态身份认证
- 基于角色的访问控制(RBAC)
- 密码加密存储(bcrypt)
### 4. 供应商管理模块
- **供应商注册**: 供应商信息录入和审核
- **资质管理**: 供应商资质证书管理
- **评价体系**: 供应商评价和信用管理
- **合作管理**: 供应商合作关系维护
### 7.2 数据安全
- HTTPS加密传输
- 敏感数据加密存储
- SQL注入防护
- XSS攻击防护
- 请求限流防刷
### 5. 运输管理模块
- **运输任务**: 运输任务创建和分配
- **实时跟踪**: GPS定位和运输状态跟踪
- **路线优化**: 智能路线规划和优化
- **运费结算**: 自动化运费计算和结算
### 7.3 日志与审计
- 关键操作日志记录
- 用户行为审计追踪
- 异常日志监控报警
### 6. 司机管理模块
- **司机档案**: 司机基本信息和资质管理
- **任务分配**: 智能任务分配和调度
- **绩效考核**: 司机绩效评估和奖惩
- **培训管理**: 司机培训记录和证书管理
## 8. 性能优化
### 7. 车辆管理模块
- **车辆档案**: 车辆基本信息和证件管理
- **维护保养**: 车辆维护计划和记录
- **保险管理**: 车辆保险信息和到期提醒
- **使用统计**: 车辆使用情况统计分析
### 8.1 前端性能优化
- 组件懒加载
- 路由懒加载
- 图片优化
- 资源缓存策略
### 8. 支付管理模块
- **支付处理**: 多种支付方式支持
- **账单管理**: 自动生成和管理账单
- **财务对账**: 支付记录和财务对账
- **结算管理**: 供应商和司机结算管理
### 8.2 后端性能优化
- Redis缓存热点数据
- 数据库索引优化
- 连接池管理
- API响应压缩
## 数据库设计
### 8.3 数据库性能优化
- 合理设计索引
- 分表分库策略(未来扩展)
- 读写分离(未来扩展)
### 核心数据表
## 9. 扩展性设计
#### 用户表 (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
);
```
### 9.1 微服务转型规划
当前系统采用单体架构，未来可考虑向微服务转型，主要拆分方向：
- 用户服务(user-service)
- 订单服务(order-service)
- 支付服务(payment-service)
- 运输服务(transport-service)
- 文件服务(file-service)
#### 订单表 (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)
);
```
### 9.2 API网关规划
未来微服务架构下，引入API网关统一管理：
- 路由转发
- 身份认证
- 限流熔断
- 监控日志
#### 运输表 (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)
);
```
## 10. 风险评估与应对
### 数据关系图
```
users ──┐
├── orders ── transports ──┐
suppliers ──┘ ├── drivers
└── vehicles
payments ──────┘
```
### 10.1 技术风险
- **数据库连接失败**：实现连接重试机制，支持多数据源
- **性能瓶颈**：引入缓存层，优化数据库查询，考虑读写分离
- **系统可用性**：部署多实例，实现负载均衡和故障转移
## 安全设计
### 10.2 业务风险
- **数据一致性**：使用事务确保关键业务操作的数据一致性
- **操作错误**：增加操作日志记录，支持关键操作撤销
- **合规性**：确保系统满足行业相关法规和标准要求
### 1. 认证安全
- **密码加密**: 使用bcrypt进行密码哈希
- **JWT安全**: 设置合理的过期时间和密钥管理
- **会话管理**: 支持主动登出和Token失效
### 10.3 安全风险
- **数据泄露**：实施数据加密，严格的权限控制，定期安全审计
- **DDoS攻击**：配置防火墙，实施请求限流
- **代码漏洞**：定期代码审计，使用安全扫描工具
### 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. 云原生架构升级
## 总结
本系统采用现代化的技术栈和架构设计，具有良好的可扩展性、可维护性和安全性。通过分层架构和模块化设计，系统能够满足活牛采购业务的复杂需求，并为未来的功能扩展和性能优化提供了良好的基础。