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

544
docs/API接口文档更新.md Normal file
View File

@@ -0,0 +1,544 @@
# 牛商城后端系统 - API接口文档 (更新版)
## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| v1.0 | 2024-12-20 | API架构师 | 初版API接口文档 |
| v1.1 | 2025-01-20 | 系统工程师 | 基于实际代码实现更新文档 |
## 1. API概览
### 1.1 基础信息
- **Base URL**: `http://localhost:3000/api` (开发环境)
- **协议**: HTTP/HTTPS
- **数据格式**: JSON
- **字符编码**: UTF-8
- **API版本**: v1
### 1.2 认证方式
#### JWT Token认证
```http
Authorization: Bearer <access_token>
```
#### 认证流程
1. 用户登录获取access_token
2. 请求头携带access_token
3. token过期需重新登录
### 1.3 通用响应格式
#### 成功响应
```json
{
"success": true,
"message": "操作成功",
"data": {
// 具体数据
}
}
```
#### 分页响应
```json
{
"success": true,
"message": "获取成功",
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 10
}
}
```
#### 错误响应
```json
{
"success": false,
"message": "错误描述",
"code": 400
}
```
### 1.4 状态码说明
| 状态码 | 说明 | 描述 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权，需要登录 |
| 403 | Forbidden | 禁止访问，权限不足 |
| 404 | Not Found | 资源不存在 |
| 500 | Internal Server Error | 服务器内部错误 |
## 2. 认证模块 (AuthController)
### 2.1 用户登录
#### 接口信息
- **URL**: `/auth/login`
- **Method**: `POST`
- **描述**: 用户登录接口，支持用户名/邮箱登录
- **认证**: 不需要
#### 请求参数
```json
{
"username": "admin",
"password": "123456"
}
```
#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名或邮箱 |
| password | string | 是 | 密码 |
#### 响应示例
```json
{
"success": true,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"userType": "admin",
"email": "admin@example.com"
}
}
}
```
### 2.2 小程序登录
#### 接口信息
- **URL**: `/auth/miniprogram-login`
- **Method**: `POST`
- **描述**: 微信小程序登录接口
- **认证**: 不需要
#### 请求参数
```json
{
"code": "wx_code_from_miniprogram",
"userInfo": {
"nickName": "用户昵称",
"avatarUrl": "头像URL"
}
}
```
### 2.3 获取当前用户信息
#### 接口信息
- **URL**: `/auth/current-user`
- **Method**: `GET`
- **描述**: 获取当前登录用户信息
- **认证**: 需要
#### 响应示例
```json
{
"success": true,
"message": "获取成功",
"data": {
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"userType": "admin",
"email": "admin@example.com"
}
}
```
## 3. 用户管理模块 (UserController)
### 3.1 获取用户列表
#### 接口信息
- **URL**: `/users`
- **Method**: `GET`
- **描述**: 获取用户列表，支持分页和筛选
- **认证**: 需要
#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| pageSize | integer | 否 | 每页数量，默认10 |
| userType | string | 否 | 用户类型筛选 |
| status | string | 否 | 用户状态筛选 |
#### 响应示例
```json
{
"success": true,
"message": "获取成功",
"data": {
"list": [
{
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"realName": "管理员",
"phone": "13800138000",
"email": "admin@example.com",
"userType": "admin",
"status": "active",
"avatar": "https://example.com/avatar.jpg",
"createdAt": "2024-01-01T00:00:00.000Z"
}
],
"total": 1,
"page": 1,
"pageSize": 10
}
}
```
### 3.2 获取用户详情
#### 接口信息
- **URL**: `/users/{id}`
- **Method**: `GET`
- **描述**: 根据用户ID获取用户详细信息
- **认证**: 需要
#### 路径参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | integer | 是 | 用户ID |
#### 响应示例
```json
{
"success": true,
"message": "获取成功",
"data": {
"id": 1,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"username": "admin",
"realName": "管理员",
"phone": "13800138000",
"email": "admin@example.com",
"userType": "admin",
"status": "active",
"avatar": "https://example.com/avatar.jpg",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
}
```
### 3.3 更新用户信息
#### 接口信息
- **URL**: `/users/{id}`
- **Method**: `PUT`
- **描述**: 更新用户基本信息
- **认证**: 需要
#### 路径参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | integer | 是 | 用户ID |
#### 请求参数
```json
{
"realName": "新的真实姓名",
"phone": "13900139000",
"email": "newemail@example.com",
"avatar": "https://example.com/new-avatar.jpg"
}
```
#### 响应示例
```json
{
"success": true,
"message": "更新成功",
"data": {
"id": 1,
"realName": "新的真实姓名",
"phone": "13900139000",
"email": "newemail@example.com",
"avatar": "https://example.com/new-avatar.jpg",
"updatedAt": "2024-01-20T10:30:00.000Z"
}
}
```
### 3.4 更新用户状态
#### 接口信息
- **URL**: `/users/{id}/status`
- **Method**: `PUT`
- **描述**: 更新用户状态（启用/禁用）
- **认证**: 需要
#### 路径参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | integer | 是 | 用户ID |
#### 请求参数
```json
{
"status": "inactive"
}
```
#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 是 | 用户状态：active(启用)、inactive(禁用) |
#### 响应示例
```json
{
"success": true,
"message": "状态更新成功",
"data": {
"id": 1,
"status": "inactive",
"updatedAt": "2024-01-20T10:30:00.000Z"
}
}
```
## 4. 运输管理模块 (TransportController)
### 4.1 获取运输列表
#### 接口信息
- **URL**: `/transports`
- **Method**: `GET`
- **描述**: 获取运输记录列表
- **认证**: 需要
### 4.2 获取运输详情
#### 接口信息
- **URL**: `/transports/{id}`
- **Method**: `GET`
- **描述**: 获取运输记录详情
- **认证**: 需要
### 4.3 更新运输状态
#### 接口信息
- **URL**: `/transports/{id}/status`
- **Method**: `PUT`
- **描述**: 更新运输状态
- **认证**: 需要
### 4.4 获取运输统计
#### 接口信息
- **URL**: `/transports/stats`
- **Method**: `GET`
- **描述**: 获取运输统计数据
- **认证**: 需要
## 5. 订单管理模块 (OrderController)
### 5.1 获取订单列表
#### 接口信息
- **URL**: `/orders`
- **Method**: `GET`
- **描述**: 获取订单列表
- **认证**: 需要
### 5.2 创建订单
#### 接口信息
- **URL**: `/orders`
- **Method**: `POST`
- **描述**: 创建新订单
- **认证**: 需要
### 5.3 获取订单详情
#### 接口信息
- **URL**: `/orders/{id}`
- **Method**: `GET`
- **描述**: 获取订单详情
- **认证**: 需要
### 5.4 更新订单状态
#### 接口信息
- **URL**: `/orders/{id}/status`
- **Method**: `PUT`
- **描述**: 更新订单状态
- **认证**: 需要
## 6. 供应商管理模块 (SupplierController)
### 6.1 获取供应商列表
#### 接口信息
- **URL**: `/suppliers`
- **Method**: `GET`
- **描述**: 获取供应商列表
- **认证**: 需要
### 6.2 获取供应商详情
#### 接口信息
- **URL**: `/suppliers/{id}`
- **Method**: `GET`
- **描述**: 获取供应商详情
- **认证**: 需要
### 6.3 获取供应商统计
#### 接口信息
- **URL**: `/suppliers/stats`
- **Method**: `GET`
- **描述**: 获取供应商统计数据
- **认证**: 需要
## 7. 司机管理模块 (DriverController)
### 7.1 获取司机列表
#### 接口信息
- **URL**: `/drivers`
- **Method**: `GET`
- **描述**: 获取司机列表
- **认证**: 需要
### 7.2 获取司机详情
#### 接口信息
- **URL**: `/drivers/{id}`
- **Method**: `GET`
- **描述**: 获取司机详情
- **认证**: 需要
### 7.3 获取司机统计
#### 接口信息
- **URL**: `/drivers/stats`
- **Method**: `GET`
- **描述**: 获取司机统计数据
- **认证**: 需要
## 8. 车辆管理模块 (VehicleController)
### 8.1 获取车辆列表
#### 接口信息
- **URL**: `/vehicles`
- **Method**: `GET`
- **描述**: 获取车辆列表
- **认证**: 需要
### 8.2 获取车辆详情
#### 接口信息
- **URL**: `/vehicles/{id}`
- **Method**: `GET`
- **描述**: 获取车辆详情
- **认证**: 需要
## 9. 支付管理模块 (PaymentController)
### 9.1 获取支付记录
#### 接口信息
- **URL**: `/payments`
- **Method**: `GET`
- **描述**: 获取支付记录列表
- **认证**: 需要
### 9.2 创建支付订单
#### 接口信息
- **URL**: `/payments`
- **Method**: `POST`
- **描述**: 创建支付订单
- **认证**: 需要
## 10. 错误码说明
### 10.1 通用错误码
| 错误码 | 说明 | 描述 |
|--------|------|------|
| 400 | 请求参数错误 | 请求参数格式不正确或缺少必要参数 |
| 401 | 未授权 | 用户未登录或token无效 |
| 403 | 权限不足 | 用户没有访问该资源的权限 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 500 | 服务器内部错误 | 服务器处理请求时发生错误 |
### 10.2 业务错误码
| 错误码 | 说明 | 描述 |
|--------|------|------|
| 1001 | 用户不存在 | 指定的用户ID不存在 |
| 1002 | 用户名或密码错误 | 登录时用户名或密码不正确 |
| 1003 | 用户已被禁用 | 用户账户已被管理员禁用 |
| 2001 | 订单不存在 | 指定的订单ID不存在 |
| 2002 | 订单状态错误 | 订单当前状态不允许该操作 |
## 11. 开发指南
### 11.1 环境配置
#### 开发环境
- Node.js 18+
- MySQL 8.0+
- Redis 6.0+
#### 环境变量
```env
NODE_ENV=development
PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_NAME=niumall
DB_USER=root
DB_PASSWORD=password
JWT_SECRET=your-jwt-secret
JWT_EXPIRES_IN=24h
```
### 11.2 测试指南
#### 单元测试
```bash
npm test -- tests/unit
```
#### 集成测试
```bash
npm test -- tests/integration
```
### 11.3 API调试工具
推荐使用以下工具进行API测试：
- Postman
- Insomnia
- curl
- Thunder Client (VS Code插件)
---
**文档维护**：本文档基于实际代码实现编写，与系统保持同步更新。
**技术支持**：如有疑问，请联系开发团队。
**最后更新时间**：2025年1月20日

560
docs/后端API设计文档.md
View File

@@ -1,560 +0,0 @@
# 活牛采购智能数字化系统 - 后端API设计文档
## 1. 概述
### 1.1 文档目的
本文档旨在定义活牛采购智能数字化系统的后端API接口规范，为前端开发、测试和后续维护提供技术依据。
### 1.2 系统架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Mini-Program │ │ Admin System │ │ Website │
│ (uni-app) │ │ (Vue 3) │ │ (HTML5 + Bootstrap) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└──────────┬───────────┴──────────┬───────────┘
│ │
┌────────┴─────────┐ ┌──────┴───────┐
│ API Gateway │ │ 统一用户中心 │
│ (Authentication)│ │ (Single Sign-On)
└────────┬─────────┘ └──────┬───────┘
│ │
└──────────┬───────────┘
│
┌──────────┴──────────┐
│ 微服务层 │
│ (NestJS Services) │
└──────────┬──────────┘
│
┌──────────┴──────────┐
│ 统一数据库 │
│ (MySQL + Redis) │
└─────────────────────┘
```
### 1.3 技术选型
| 层级 | 技术栈 | 说明 |
|------|--------|------|
| 后端框架 | NestJS | 基于Express.js的企业级框架 |
| 数据库 | MySQL 8.0 + Redis | 统一业务数据 + 缓存 |
| ORM | TypeORM | 对象关系映射 |
| API文档 | Swagger | API文档自动生成 |
| 认证授权 | JWT + RBAC | 基于角色的访问控制 |
| 文件存储 | MinIO/阿里云OSS | 视频文件存储 |
| 消息队列 | RabbitMQ | 异步任务处理 |
| 实时通信 | WebSocket | 实时数据传输 |
## 2. 统一规范
### 2.1 响应格式
```json
{
"code": 200,
"message": "成功",
"data": {},
"timestamp": 1643097600000
}
```
### 2.2 分页响应格式
```json
{
"code": 200,
"message": "成功",
"data": {
"items": [],
"total": 100,
"page": 1,
"limit": 10,
"totalPages": 10
},
"timestamp": 1643097600000
}
```
### 2.3 错误码规范
| 错误码 | 说明 | HTTP状态码 |
|--------|------|------------|
| 200 | 成功 | 200 |
| 400 | 请求参数错误 | 400 |
| 401 | 未认证 | 401 |
| 403 | 无权限 | 403 |
| 404 | 资源不存在 | 404 |
| 500 | 服务器内部错误 | 500 |
### 2.4 认证机制
- 使用JWT Token进行认证
- 请求头中添加Authorization: Bearer <token>
## 3. API接口设计
### 3.1 认证模块
#### 3.1.1 小程序用户登录
- **URL**: POST /api/auth/mini-program/login
- **请求参数**:
```json
{
"phone": "13800138000",
"code": "123456",
"miniProgramType": "client"
}
```
- **响应数据**:
```json
{
"token": "jwt_token_string",
"userInfo": {
"id": 1,
"username": "user123",
"realName": "张三",
"avatar": "https://example.com/avatar.jpg",
"userType": "client",
"roles": ["purchaser"]
}
}
```
#### 3.1.2 获取当前用户信息
- **URL**: GET /api/auth/user-info
- **请求参数**: 无
- **响应数据**:
```json
{
"id": 1,
"username": "user123",
"realName": "张三",
"avatar": "https://example.com/avatar.jpg",
"userType": "client",
"phone": "13800138000",
"email": "user@example.com"
}
```
### 3.2 用户管理模块
#### 3.2.1 获取用户列表
- **URL**: GET /api/users
- **请求参数**:
```json
{
"page": 1,
"limit": 10,
"userType": "client"
}
```
- **响应数据**: 分页用户列表
#### 3.2.2 获取用户详情
- **URL**: GET /api/users/{id}
- **请求参数**: 无
- **响应数据**: 用户详细信息
### 3.3 订单管理模块
#### 3.3.1 创建采购订单
- **URL**: POST /api/orders
- **请求参数**:
```json
{
"breedType": "simmental",
"minWeight": 500,
"maxWeight": 600,
"totalCount": 100,
"unitPrice": 35.5,
"deliveryAddress": "xxx养殖场",
"deliveryDate": "2024-01-25",
"specialRequirements": "要求健康无病"
}
```
- **响应数据**: 创建的订单信息
#### 3.3.2 获取订单列表
- **URL**: GET /api/orders
- **请求参数**:
```json
{
"status": "pending",
"page": 1,
"limit": 10
}
```
- **响应数据**: 分页订单列表
#### 3.3.3 获取订单详情
- **URL**: GET /api/orders/{id}
- **请求参数**: 无
- **响应数据**: 订单详细信息
#### 3.3.4 更新订单状态
- **URL**: PUT /api/orders/{id}/status
- **请求参数**:
```json
{
"status": "confirmed"
}
```
- **响应数据**: 更新后的订单信息
### 3.4 运输跟踪模块
#### 3.4.1 司机上报位置信息
- **URL**: POST /api/transport/tracks
- **请求参数**:
```json
{
"orderId": 123,
"latitude": 39.9042,
"longitude": 116.4074,
"speed": 80.5,
"direction": 45.2,
"cattleStatus": "normal",
"temperature": 25.5,
"humidity": 60.2,
"videoUrl": "https://example.com/status.mp4"
}
```
- **响应数据**: 上报的位置信息
#### 3.4.2 获取订单运输轨迹
- **URL**: GET /api/transport/orders/{orderId}/tracks
- **请求参数**: 无
- **响应数据**: 运输轨迹列表
### 3.5 文件管理模块
#### 3.5.1 统一文件上传接口
- **URL**: POST /api/files/upload
- **请求参数**:
```json
{
"file": "文件二进制数据",
"type": "cattle_video",
"businessId": "order_123",
"description": "装车过程视频"
}
```
- **响应数据**:
```json
{
"fileId": "file_uuid",
"url": "/uploads/filename.ext",
"thumbnail": "/uploads/thumbnails/filename.ext.jpg",
"size": 1024000,
"mimeType": "video/mp4",
"originalName": "video.mp4",
"type": "cattle_video",
"businessId": "order_123",
"description": "装车过程视频"
}
```
### 3.6 支付管理模块
#### 3.6.1 创建支付订单
- **URL**: POST /api/payments
- **请求参数**:
```json
{
"orderId": 123,
"amount": 355000,
"paymentType": "wechat",
"paymentMethod": "mini_program"
}
```
- **响应数据**:
```json
{
"paymentId": 1,
"paymentNo": "pay_123456",
"amount": 355000
}
```
#### 3.6.2 支付回调接口
- **URL**: POST /api/payments/{id}/callback
- **请求参数**:
```json
{
"paymentId": "pay_123456",
"status": "success",
"paidAmount": 355000,
"paidTime": "2024-01-25 15:30:00"
}
```
- **响应数据**: 回调处理结果
#### 3.6.3 查询支付状态
- **URL**: GET /api/payments/{id}/status
- **请求参数**: 无
- **响应数据**:
```json
{
"paymentId": 1,
"paymentNo": "pay_123456",
"amount": 355000,
"status": "paid",
"paidAmount": 355000,
"paidTime": "2024-01-25 15:30:00",
"createdAt": "2024-01-25 14:00:00"
}
```
## 4. 数据库设计
### 4.1 用户表 (users)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGINT | 主键 |
| uuid | VARCHAR(36) | UUID |
| username | VARCHAR(50) | 用户名 |
| password_hash | VARCHAR(255) | 密码哈希 |
| phone | VARCHAR(20) | 手机号 |
| email | VARCHAR(100) | 邮箱 |
| real_name | VARCHAR(50) | 真实姓名 |
| avatar_url | VARCHAR(255) | 头像URL |
| user_type | ENUM | 用户类型(client,supplier,driver,staff,admin) |
| status | ENUM | 状态(active,inactive,locked) |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
### 4.2 订单表 (orders)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGINT | 主键 |
| order_no | VARCHAR(50) | 订单号 |
| buyer_id | BIGINT | 采购人ID |
| trader_id | BIGINT | 贸易商ID |
| supplier_id | BIGINT | 供应商ID |
| driver_id | BIGINT | 司机ID |
| breed_type | VARCHAR(20) | 牛品种 |
| min_weight | DECIMAL(10,2) | 最低重量(kg) |
| max_weight | DECIMAL(10,2) | 最高重量(kg) |
| total_count | INTEGER | 总数量 |
| total_weight | DECIMAL(10,2) | 总重量 |
| unit_price | DECIMAL(10,2) | 单价(元/kg) |
| total_amount | DECIMAL(15,2) | 总金额 |
| status | ENUM | 状态(pending,confirmed,loading,shipping,delivered,completed,cancelled) |
| delivery_address | VARCHAR(255) | 配送地址 |
| delivery_date | DATE | 配送日期 |
| special_requirements | TEXT | 特殊要求 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
### 4.3 运输跟踪表 (transport_tracks)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGINT | 主键 |
| order_id | BIGINT | 订单ID |
| driver_id | BIGINT | 司机ID |
| latitude | DECIMAL(10,8) | 纬度 |
| longitude | DECIMAL(11,8) | 经度 |
| speed | DECIMAL(5,2) | 速度(km/h) |
| direction | DECIMAL(5,2) | 方向(度) |
| cattle_status | VARCHAR(20) | 牛只状态 |
| temperature | DECIMAL(5,2) | 温度(℃) |
| humidity | DECIMAL(5,2) | 湿度(%) |
| video_url | VARCHAR(255) | 视频URL |
| created_at | DATETIME | 创建时间 |
### 4.4 支付表 (payments)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGINT | 主键 |
| order_id | BIGINT | 订单ID |
| user_id | BIGINT | 用户ID |
| amount | DECIMAL(15,2) | 支付金额 |
| paid_amount | DECIMAL(15,2) | 实际支付金额 |
| payment_type | ENUM | 支付类型(wechat,alipay,bank) |
| payment_method | ENUM | 支付方式(mini_program,app,web) |
| payment_no | VARCHAR(50) | 支付单号 |
| third_party_id | VARCHAR(100) | 第三方支付ID |
| status | ENUM | 状态(pending,paid,failed,refunded) |
| paid_time | DATETIME | 支付时间 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
## 5. 安全设计
### 5.1 认证授权
- JWT Token认证
- 基于角色的访问控制(RBAC)
- API访问频率限制
### 5.2 数据安全
- 敏感数据加密存储
- HTTPS传输加密
- 视频文件访问权限控制
### 5.3 业务安全
- 订单状态机验证
- 支付金额校验
- 操作日志审计
## 6. 性能优化
### 6.1 数据库优化
- 索引优化
- 读写分离
- 分表分库策略
### 6.2 缓存策略
- Redis缓存热点数据
- 本地缓存减少IO
### 6.3 文件处理
- 视频文件分片上传
- CDN加速访问
## 7. 监控告警
### 7.1 系统监控
- 应用性能监控(APM)
- 数据库监控
- 服务器资源监控
- API响应时间监控
### 7.2 业务监控
- 订单流程监控
- 运输异常检测
- 支付成功率监控
- 用户行为分析
### 7.3 日志管理
- 操作日志记录
- 错误日志收集
- 日志分析和查询
- 实时日志追踪
## 8. 部署方案
### 8.1 开发环境
```yaml
# docker-compose-dev.yml
version: '3.8'
services:
# 后端服务
user-service:
# 数据库
mysql:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=root
- MYSQL_DATABASE=niu_mall
ports:
- "3306:3306"
# 缓存
redis:
image: redis:6.2
ports:
- "6379:6379"
```
### 8.2 生产环境
```yaml
# kubernetes部署配置
apiVersion: apps/v1
kind: Deployment
metadata:
name: niu-mall-api
labels:
app: niu-mall
spec:
replicas: 3
selector:
matchLabels:
app: niu-mall-api
template:
metadata:
labels:
app: niu-mall-api
spec:
containers:
- name: api-gateway
image: niu-mall/api-gateway:latest
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: production
resources:
requests:
memory: "512Mi"
cpu: "250m"
limits:
memory: "1Gi"
cpu: "500m"
```
### 8.3 备份恢复策略
```yaml
# 数据库备份
backup:
schedule: "0 2 * * *" # 每天凌晨2点
retention: 30 # 保留30天
storage:
type: oss # 阿里云OSS存储
bucket: niu-mall-backup
# 文件备份
file_backup:
enabled: true
schedule: "0 3 * * *" # 每天凌晨3点
include:
- /data/uploads # 用户上传文件
- /data/logs # 日志文件
exclude:
- /data/temp # 临时文件
# 灾难恢复
recovery:
rto: "4h" # 恢复时间目标4小时
rpo: "1h" # 恢复点目标1小时
procedures:
- database_restore
- service_restart
- data_validation
```
## 9. 开发规范
### 9.1 代码规范
- TypeScript严格模式
- ESLint代码检查
- Prettier代码格式化
### 9.2 Git规范
- 分支管理策略
- Commit message规范
- Code Review流程
### 9.3 文档规范
- API文档自动化
- 数据库文档维护
- 部署文档更新
## 10. 测试规范
- 单元测试要求≥80%覆盖率
- 集成测试要求≥70%覆盖率
- E2E测试核心业务流程100%覆盖
## 11. 附录
### 11.1 术语表
| 术语 | 说明 |
|------|------|
| PRD | 产品需求文档 |
| API | 应用程序编程接口 |
| JWT | JSON Web Token |
| RBAC | 基于角色的访问控制 |
| CDN | 内容分发网络 |
| OSS | 对象存储服务 |
### 11.2 参考资料
1. 活牛采购智能数字化系统PRD
2. 技术实施方案
3. NestJS官方文档
4. MySQL官方文档
5. Redis官方文档

124
docs/域名配置说明.md
View File

@@ -1,124 +0,0 @@
# 活牛采购智能数字化系统 - 域名配置说明
## 域名配置总览
| 域名类型 | 域名地址 | 用途 | 环境 |
|---------|---------|------|------|
| 后端API | `wapi.nanniwan.com` | 提供RESTful API服务 | 生产环境 |
| 管理后台 | `ad.nanniwan.com` | 管理员后台管理系统 | 生产环境 |
| 官方网站 | `www.nanniwan.com` | 产品官网和文档 | 生产环境 |
| 开发环境 | `localhost:3000` | 本地开发测试 | 开发环境 |
| 开发环境 | `localhost:5173` | Vite开发服务器 | 开发环境 |
## 配置文件更新记录
### 1. 后端配置更新
**文件：** `backend/src/config/config.js`
- 添加了 `domainConfig` 配置对象
- 包含所有生产环境域名配置
**配置内容：**
```javascript
const domainConfig = {
backend: 'wapi.nanniwan.com',
admin: 'ad.nanniwan.com',
website: 'www.nanniwan.com'
};
```
### 2. CORS配置更新
**文件：** `backend/src/main.js`
- 更新了CORS配置，添加了所有允许的域名
- 启用了credentials支持
**配置内容：**
```javascript
app.use(cors({
origin: [
'http://localhost:3000',
'http://localhost:5173',
'https://wapi.nanniwan.com',
'https://ad.nanniwan.com',
'https://www.nanniwan.com'
],
credentials: true
}));
```
### 3. API文档更新
**文件：** `backend/src/docs/api.yaml`
- 更新了生产环境服务器URL
- 从 `https://api.niumall.com` 改为 `https://wapi.nanniwan.com`
### 4. 管理后台配置更新
**文件：** `admin-system/.env.production`
- 更新了所有API相关配置
- 统一使用 `wapi.nanniwan.com` 域名
**更新内容：**
```bash
# API接口地址
VITE_API_BASE_URL=https://wapi.nanniwan.com/api
# WebSocket地址
VITE_WS_BASE_URL=wss://wapi.nanniwan.com
# 上传文件地址
VITE_UPLOAD_URL=https://wapi.nanniwan.com/api/upload
# 静态资源地址
VITE_STATIC_URL=https://wapi.nanniwan.com/static
# 错误日志上报地址
VITE_ERROR_LOG_URL=https://wapi.nanniwan.com/api/error-log
# 性能监控地址
VITE_PERFORMANCE_URL=https://wapi.nanniwan.com/api/performance
```
### 5. 官网API文档更新
**文件：** `website/api.html`
- 更新了API基础URL
- 从 `https://api.niumall.com/v1` 改为 `https://wapi.nanniwan.com/v1`
- 更新了curl示例中的域名
## 部署注意事项
1. **DNS配置**：确保所有域名都正确解析到服务器IP地址
2. **SSL证书**：为所有生产环境域名配置HTTPS证书
3. **Nginx配置**：需要配置反向代理，将请求转发到相应的服务
4. **环境变量**：生产环境部署时需要设置正确的环境变量
## 开发环境配置
开发环境继续使用localhost地址，配置位于：
- `admin-system/.env.development` - 管理后台开发配置
- 后端服务默认运行在 `localhost:3000`
## 验证检查清单
- [ ] 所有域名能够正常解析
- [ ] HTTPS证书配置正确
- [ ] CORS配置允许所有需要的域名
- [ ] 各服务之间的通信正常
- [ ] API文档中的域名已更新
- [ ] 管理后台能够正常访问API
- [ ] 官网能够正常展示
## 故障排除
如果遇到跨域问题，检查：
1. CORS配置是否正确
2. 域名是否在允许列表中
3. HTTPS证书是否有效
4. Nginx配置是否正确
---
*最后更新：2024年1月20日*
*版本：1.0.0*

120
docs/小程序端开发总结.md
View File

@@ -1,120 +0,0 @@
# 小程序端开发总结报告
## 完成的工作
### 1. 文档完善
- ✅ 补充了系统详细设计文档中的小程序端详细设计章节
- ✅ 完善了内部员工小程序(staff-mp)的技术架构和实现细节
- ✅ 添加了其他三个小程序(采购人、供应商、司机)的设计说明
- ✅ 制定了统一的技术栈规范和API设计标准
### 2. 技术架构设计
- **前端框架**: uni-app + Vue 3 + TypeScript
- **状态管理**: Pinia
- **构建工具**: Vite
- **代码质量**: ESLint + Prettier
- **测试框架**: Vitest + Vue Test Utils
### 3. 项目结构规范
```
mini_program/
├── client-mp/ # 采购人小程序
├── supplier-mp/ # 供应商小程序
├── driver-mp/ # 司机小程序
├── staff-mp/ # 内部员工小程序
└── shared/ # 共享代码和组件
```
### 4. 核心功能模块
- **订单管理**: 创建、查看、状态跟踪
- **运输监控**: 实时地图、轨迹回放
- **数据统计**: 可视化分析、报表生成
- **系统管理**: 用户权限、配置管理
## 技术实现亮点
### 1. TypeScript全面支持
- 完整的类型定义
- 接口响应类型安全
- 组件Props类型检查
### 2. 状态管理优化
- Pinia状态管理
- 模块化store设计
- 类型安全的actions和getters
### 3. 性能优化策略
- 组件懒加载
- 接口数据缓存
- 图片懒加载和CDN
- 列表虚拟滚动
### 4. 安全设计
- JWT身份认证
- 基于角色的权限控制
- 数据传输加密
- 输入验证和XSS防护
## 测试和质量保证
### 1. 测试策略
- 单元测试: Vitest + Vue Test Utils
- 组件测试: 组件逻辑测试
- E2E测试: 核心业务流程测试
### 2. 覆盖率要求
- 语句覆盖率: ≥80%
- 分支覆盖率: ≥75%
- 函数覆盖率: ≥85%
- 行覆盖率: ≥80%
### 3. 自动化流程
- CI/CD集成测试
- 代码质量检查
- 安全漏洞扫描
## 部署和运维
### 1. 环境配置
- 多环境支持(开发、测试、生产)
- 环境变量管理
- 依赖版本控制
### 2. 构建部署
- 多平台构建(微信小程序、H5、App)
- 自动化部署流水线
- 版本管理和回滚
### 3. 监控维护
- 性能监控和告警
- 错误日志收集
- 用户行为分析
- 定期维护计划
## 后续建议
### 1. 技术债务处理
- [ ] 解决uni-app构建工具依赖问题
- [ ] 统一各小程序的构建配置
- [ ] 完善共享组件库建设
### 2. 开发环境优化
- [ ] 配置完整的开发调试环境
- [ ] 建立API mock服务
- [ ] 完善开发文档和示例
### 3. 测试覆盖扩展
- [ ] 增加集成测试覆盖率
- [ ] 完善E2E测试场景
- [ ] 建立性能基准测试
### 4. 安全加固
- [ ] 实施代码安全扫描
- [ ] 定期安全审计
- [ ] 建立应急响应流程
## 总结
小程序端的需求文档和技术架构已经完善，具备了完整的开发基础。后续需要重点解决构建工具的技术问题，建立完善的开发测试流程，确保项目能够顺利进行。
建议优先解决uni-app构建工具的依赖兼容性问题，然后按照优先级逐步完成各小程序的核心功能开发。

203
docs/开发环境配置指南.md
View File

@@ -1,203 +0,0 @@
# 开发环境配置指南
## 🖥️ 系统要求
### 基础环境
- **操作系统**：Windows 10+, macOS 10.15+, Ubuntu 18.04+
- **Node.js**：>= 18.0.0
- **npm**：>= 8.0.0
- **Git**：>= 2.20.0
### 数据库环境
- **MySQL**：>= 8.0
- **Redis**：>= 7.0
### 开发工具
- **IDE**：VS Code（推荐）/ WebStorm / HBuilderX
- **浏览器**：Chrome 90+ （开发调试）
- **微信开发者工具**：最新版本（小程序开发）
## 🔧 环境安装
### 1. Node.js 安装
```bash
# 使用 nvm 管理版本（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
# 或直接下载安装
# https://nodejs.org/
```
### 2. 数据库配置
```bash
# MySQL 8.0
# 连接信息：
HOST: 129.211.213.226
PORT: 9527
USERNAME: root
PASSWORD: aiotAiot123!
DATABASE: jiebandata
# Redis（本地开发）
HOST: localhost
PORT: 6379
```
### 3. 开发工具安装
```bash
# VS Code 推荐插件
ext install ms-vscode.vscode-typescript-next
ext install Vue.volar
ext install bradlc.vscode-tailwindcss
ext install esbenp.prettier-vscode
ext install ms-vscode.vscode-eslint
```
## 🚀 项目启动
### 全局依赖安装
```bash
# 安装全局工具
npm install -g @vue/cli
npm install -g serve
npm install -g pm2
npm install -g sequelize-cli
```
### 项目克隆和初始化
```bash
# 克隆项目
git clone <repository-url>
cd niumall
# 安装各模块依赖
cd admin-system && npm install
cd ../backend && npm install
cd ../mini_program && npm install
```
### 启动服务
#### 1. 后端服务
```bash
cd backend
cp .env.example .env.development
# 编辑环境变量
npm run dev
# 服务运行在 http://localhost:3001
```
#### 2. 管理后台
```bash
cd admin-system
npm run dev
# 服务运行在 http://localhost:3000
```
#### 3. 官网
```bash
cd website
python -m http.server 8080
# 或 npx serve . -p 8080
# 访问 http://localhost:8080
```
#### 4. 小程序
```bash
cd mini_program/client-mp
npm run dev:mp-weixin
# 使用微信开发者工具打开 dist/dev/mp-weixin
```
## 🔗 开发服务地址
| 服务 | 地址 | 说明 |
|------|------|------|
| 后端API | http://localhost:3001 | Express服务 |
| 管理后台 | http://localhost:3000 | Vue3应用 |
| 企业官网 | http://localhost:8080 | 静态网站 |
| 小程序 | 微信开发者工具 | uni-app应用 |
## 🛠️ 开发工具配置
### VS Code 配置
```json
// .vscode/settings.json
{
"typescript.preferences.importModuleSpecifier": "relative",
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"eslint.format.enable": true,
"vetur.validation.template": false
}
```
### Git 配置
```bash
# 配置用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# 配置提交模板
git config --global commit.template .gitmessage
```
## 🔧 常见问题解决
### Node.js 版本问题
```bash
# 切换Node版本
nvm use 18
npm install
```
### 端口冲突
```bash
# 检查端口占用
netstat -ano | findstr :3000
# 杀死进程
taskkill /PID <PID> /F
```
### 数据库连接失败
1. 检查数据库服务是否启动
2. 验证连接参数
3. 检查防火墙设置
4. 确认网络连通性
### 依赖安装失败
```bash
# 清除缓存重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```
## 📝 开发规范
### 代码提交规范
```bash
# 提交格式
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 其他修改
```
### 分支管理
- `main`: 主分支，生产环境代码
- `develop`: 开发分支，集成测试
- `feature/*`: 功能分支
- `hotfix/*`: 紧急修复分支
## 📧 技术支持
- **开发环境问题**：dev@niumall.com
- **数据库相关**：db@niumall.com
- **部署相关**：ops@niumall.com
- **技术交流群**：微信群-前端技术交流

313
docs/数据库表结构说明.md
View File

@@ -1,313 +0,0 @@
# 数据库表结构说明
## 连接信息验证
数据库连接信息已验证有效：
- 主机: 129.211.213.226
- 端口: 9527
- 用户名: root
密码：aiotAiot123!
- 数据库: niumall
## 表结构详情
### 1. users 表（用户表）
```sql
CREATE TABLE `users` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`openid` varchar(64) NOT NULL UNIQUE,
`nickname` varchar(50) NOT NULL,
`avatar` varchar(255),
`gender` enum('male','female','other'),
`birthday` datetime,
`phone` varchar(20) UNIQUE,
`email` varchar(100) UNIQUE,
`uuid` varchar(36) UNIQUE,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
### 2. orders 表（订单表）
```sql
CREATE TABLE `orders` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`order_no` varchar(32) NOT NULL UNIQUE,
`user_id` bigint(20) NOT NULL,
`supplier_id` bigint(20) NOT NULL,
`cattle_type` varchar(50) NOT NULL,
`cattle_breed` varchar(50) NOT NULL,
`cattle_count` int(11) NOT NULL,
`expected_weight` decimal(10,2) NOT NULL,
`actual_weight` decimal(10,2),
`unit_price` decimal(10,2) NOT NULL,
`total_amount` decimal(15,2) NOT NULL,
`paid_amount` decimal(15,2) NOT NULL DEFAULT '0.00',
`remaining_amount` decimal(15,2) NOT NULL,
`status` enum('pending','confirmed','preparing','shipping','delivered','accepted','completed','cancelled','refunded') NOT NULL DEFAULT 'pending',
`delivery_address` varchar(200) NOT NULL,
`expected_delivery_date` datetime NOT NULL,
`actual_delivery_date` datetime,
`notes` text,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
### 3. payments 表（支付表）
```sql
CREATE TABLE `payments` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`order_id` bigint(20) NOT NULL,
`user_id` bigint(20) NOT NULL,
`amount` decimal(15,2) NOT NULL,
`paid_amount` decimal(15,2),
`payment_type` enum('wechat','alipay','bank') NOT NULL,
`payment_method` enum('mini_program','app','web') NOT NULL,
`payment_no` varchar(50) NOT NULL UNIQUE,
`third_party_id` varchar(100),
`status` enum('pending','paid','failed','refunded') DEFAULT 'pending',
`paid_time` datetime,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
### 4. transports 表（运输表）
```sql
CREATE TABLE `transports` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`order_id` bigint(20) NOT NULL,
`driver_id` bigint(20) NOT NULL,
`vehicle_id` bigint(20) NOT NULL,
`start_location` varchar(255) NOT NULL,
`end_location` varchar(255) NOT NULL,
`scheduled_start_time` datetime NOT NULL,
`actual_start_time` datetime,
`scheduled_end_time` datetime NOT NULL,
`actual_end_time` datetime,
`status` enum('scheduled','in_transit','completed','cancelled') DEFAULT 'scheduled',
`estimated_arrival_time` datetime,
`cattle_count` int(11) NOT NULL,
`special_requirements` text,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`),
KEY `idx_order_id` (`order_id`),
KEY `idx_driver_id` (`driver_id`),
KEY `idx_vehicle_id` (`vehicle_id`)
);
```
### 5. suppliers 表（供应商表）
```sql
CREATE TABLE `suppliers` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`name` varchar(100) NOT NULL,
`code` varchar(20) NOT NULL UNIQUE,
`contact` varchar(50) NOT NULL,
`phone` varchar(20) NOT NULL UNIQUE,
`address` varchar(200) NOT NULL,
`business_license` varchar(255),
`qualification_level` varchar(10) NOT NULL,
`certifications` json,
`cattle_types` json,
`capacity` int(11),
`rating` decimal(3,2),
`cooperation_start_date` datetime,
`status` enum('active','inactive','suspended') DEFAULT 'active',
`region` varchar(20) NOT NULL,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
### 6. vehicles 表（车辆表）
```sql
CREATE TABLE `vehicles` (
`id` bigint(20) NOT NULL AUTO_INCREMENT,
`license_plate` varchar(20) NOT NULL UNIQUE,
`vehicle_type` varchar(50) NOT NULL,
`capacity` int(11) NOT NULL,
`driver_id` bigint(20) NOT NULL,
`status` enum('available','in_use','maintenance','retired') DEFAULT 'available',
`last_maintenance_date` datetime,
`next_maintenance_date` datetime,
`insurance_expiry_date` datetime,
`registration_expiry_date` datetime,
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
### 7. admins 表（管理员用户表）
```sql
CREATE TABLE `admins` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`username` varchar(50) NOT NULL UNIQUE,
`password_hash` varchar(255) NOT NULL,
`phone` varchar(20) NOT NULL UNIQUE,
`email` varchar(100),
`user_type` enum('client','supplier','driver','staff','admin') NOT NULL,
`status` enum('active','inactive','locked') DEFAULT 'active',
`created_at` datetime NOT NULL,
`updated_at` datetime NOT NULL,
`deleted_at` datetime DEFAULT NULL,
PRIMARY KEY (`id`)
);
```
## 表索引信息
### users 表索引
- PRIMARY: 主键索引 (id)
- openid: 唯一索引
- phone: 唯一索引
- email: 唯一索引
- uuid: 唯一索引
### orders 表索引
- PRIMARY: 主键索引 (id)
- order_no: 唯一索引
- orders_order_no: 唯一索引
- orders_user_id: 普通索引
- orders_supplier_id: 普通索引
- orders_status: 普通索引
- orders_created_at: 普通索引
### payments 表索引
- PRIMARY: 主键索引 (id)
- payment_no: 唯一索引
### suppliers 表索引
- PRIMARY: 主键索引 (id)
- code: 唯一索引
- phone: 唯一索引
### transports 表索引
- PRIMARY: 主键索引 (id)
- idx_order_id: 普通索引
- idx_driver_id: 普通索引
- idx_vehicle_id: 普通索引
### vehicles 表索引
- PRIMARY: 主键索引 (id)
- license_plate: 唯一索引
### admins 表索引
- PRIMARY: 主键索引 (id)
- username: 唯一索引
- phone: 唯一索引
## 表关系说明
1. `users` 表与 `orders` 表通过 `user_id` 字段关联
2. `suppliers` 表与 `orders` 表通过 `supplier_id` 字段关联
3. `orders` 表与 `payments` 表通过 `order_id` 字段关联
4. `users` 表与 `payments` 表通过 `user_id` 字段关联
5. `orders` 表与 `transports` 表通过 `order_id` 字段关联
6. `users` 表与 `transports` 表通过 `driver_id` 字段关联
7. `vehicles` 表与 `transports` 表通过 `vehicle_id` 字段关联
8. `users` 表与 `vehicles` 表通过 `driver_id` 字段关联
## 数据示例
### orders 表数据示例
```json
[
{
"id": 1,
"order_no": "ORD20240520001",
"user_id": 2,
"user_name": "采购商",
"supplier_id": 3,
"supplier_name": "供应商",
"trader_id": null,
"trader_name": null,
"cattle_breed": "西门塔尔牛",
"cattle_count": 10,
"expected_weight": "5000.00",
"actual_weight": null,
"unit_price": "35.00",
"total_amount": "175000.00",
"paid_amount": "50000.00",
"remaining_amount": "125000.00",
"status": "pending",
"delivery_address": "北京市朝阳区某某路123号",
"expected_delivery_date": "2024-06-01T00:00:00.000Z",
"actual_delivery_date": null,
"notes": "请按时交货，质量要保证",
"created_at": "2025-09-18T15:04:29.000Z",
"updated_at": "2025-09-18T15:04:29.000Z",
"deleted_at": null
}
]
```
### suppliers 表数据示例
```json
{
"id": 3,
"name": "内蒙古草原牧业有限公司",
"code": "NM001",
"contact": "张牧",
"phone": "13800000001",
"address": "内蒙古自治区呼和浩特市草原牧场1号",
"business_license": "",
"qualification_level": "A",
"certifications": "[]",
"cattle_types": "[\"西门塔尔牛\",\"夏洛莱牛\"]",
"capacity": 1000,
"rating": "0.00",
"cooperation_start_date": "2025-09-18T15:25:05.000Z",
"status": "active",
"region": "north",
"created_at": "2025-09-18T15:25:05.000Z",
"updated_at": "2025-09-18T15:25:05.000Z",
"deleted_at": null
}
```
### admins 表数据示例
```json
{
"id": 1,
"username": "admin",
"password_hash": "$2a$10$yQ2odJuDRDjPwiyT6v/NuO/V0wjTaUx9DlDmHqXwa.hMQ9km0cWPe",
"phone": "13800138001",
"email": "admin@niumall.com",
"user_type": "admin",
"status": "active",
"created_at": "2025-09-18T15:04:28.000Z",
"updated_at": "2025-09-18T15:04:28.000Z",
"deleted_at": null
}
```
## 使用建议
1. **数据初始化**：当前数据库中已有一些基础数据，包括5个供应商、3个管理员用户和2个订单。在开发过程中可以直接使用这些数据进行测试。
2. **权限管理**：admins 表中包含了不同角色的用户（admin、client、supplier），可以通过 user_type 字段进行权限控制。
3. **订单状态管理**：orders 表中的 status 字段包含了完整的订单状态流程，从 pending（待确认）到 completed（已完成）或 cancelled（已取消）。
4. **索引优化**：已为 `transports` 表添加了 `order_id`、`driver_id`、`vehicle_id` 等字段的索引以提高查询性能。建议继续为经常查询的字段添加索引，如 `orders.status`、`orders.created_at` 等。
5. **字段命名统一**：已完成统一使用下划线命名法，所有字段均采用下划线命名规范，保持了命名一致性。
6. **数据完整性**：可以添加外键约束来保证数据完整性，例如在 `orders` 表中添加外键约束关联 `users` 表和 `suppliers` 表。
7. **扩展性考虑**：已为所有表添加了软删除字段 `deleted_at` 以支持数据恢复功能。
8. **字段类型优化**：部分字段可以考虑使用更合适的类型，例如 `orders.status` 可以使用 TINYINT 类型配合枚举值映射来节省存储空间。

286
docs/活牛采购智能数字化系统PRD.md
View File

@@ -1,286 +0,0 @@
# 活牛采购智能数字化系统 - 产品需求文档
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-01-20 | 产品经理 | 初版PRD |
| v1.1 | 2024-05-15 | 系统架构师 | 更新与系统架构和详细设计文档保持一致 |
## 1. 项目概述
### 1.1 项目背景
为解决活牛采购过程中信息不透明、流程不规范、风险控制难等问题，开发活牛采购智能数字化管理系统。
### 1.2 项目目标
- 实现采购流程标准化、数字化管理
- 提高采购效率，降低操作风险
- 确保牛只质量可追溯，交易安全可靠
### 1.3 成功标准
- 采购流程耗时减少30%
- 操作错误率降低至1%以下
- 客户满意度达到95%以上
## 2. 用户角色与用例
### 2.1 用户角色
| 角色 | 职责描述 | 系统权限 |
|------|----------|----------|
| 采购人 | 发起采购需求，验收确认，支付审批 | 订单创建、验收确认、支付审批 |
| 贸易商 | 订单转发，供应商管理，资金结算 | 订单管理、供应商管理、结算处理 |
| 供应商 | 牛只准备，装车管理，单据提供 | 牛只信息维护、装车管理、单据上传 |
| 司机 | 运输执行，状态上报，单据交接 | 运输跟踪、状态上报、单据确认 |
### 2.2 核心用例
1. **采购订单管理** - 采购人创建订单，贸易商转发订单
2. **牛只核验管理** - 供应商准备牛只，上传检疫证明
3. **运输跟踪管理** - 司机实时上报运输状态
4. **到货验收管理** - 采购人验收确认，处理异常
5. **结算支付管理** - 自动计算款项，在线支付
## 3. 功能需求
### 3.1 采购计划阶段
#### 用户故事：As a 采购人, I want to 创建采购订单, so that 明确采购需求
**验收标准：**
- Given 采购人登录系统
- When 填写《采购订货单》信息
- Then 系统生成待确认订单
- And 包含品种、重量、数量、单价等完整信息
#### 用户故事：As a 贸易商, I want to 审核供应商资质, so that 确保供应商合规
**验收标准：**
- Given 贸易商查看供应商信息
- When 核实营业执照和检疫证明开具能力
- Then 系统记录审核结果
- And 支持证件文件上传和查看
### 3.2 装车前准备
#### 用户故事：As a 司机, I want to 完成车辆备案, so that 确保运输车辆合规
**验收标准：**
- Given 司机准备装车
- When 上传空车过磅视频和消毒证明
- Then 系统验证视频完整性
- And 驻场兽医在线确认消毒证明
#### 用户故事：As a 供应商, I want to 准备牛只核验, so that 确保牛只符合要求
**验收标准：**
- Given 供应商准备装车
- When 提供《动物检疫合格证明》
- And 确保空水空槽时间≥8小时
- Then 系统记录核验信息
- And 支持不同品种的重量区间配置
### 3.3 运输交付
#### 用户故事：As a 司机, I want to 实时上报运输状态, so that 采购方掌握运输进度
**验收标准：**
- Given 司机在运输途中
- When 每10分钟自动上报位置和牛只状态
- Then 系统记录运输轨迹
- And 支持视频状态上报
#### 用户故事：As a 采购人, I want to 进行到货验收, so that 确保牛只质量
**验收标准：**
- Given 牛只到岸后2小时内
- When 采购人验收牛只
- Then 系统记录验收结果
- And 支持异常情况记录和处理
### 3.4 结算支付
#### 用户故事：As a 系统, I want to 自动计算结算金额, so that 减少人工错误
**验收标准：**
- Given 验收完成
- When 系统获取上车重量和单价
- Then 自动计算：上车重量×单价 - 预付款
- And 生成结算单
#### 用户故事：As a 采购人, I want to 在线支付尾款, so that 完成交易
**验收标准：**
- Given 验收后3小时内
- When 采购人确认结算单
- Then 系统支持在线支付
- And 生成支付凭证
### 3.5 异常处理
#### 用户故事：As a 系统, I want to 自动计算违约金, so that 规范违约处理
**验收标准：**
- Given 发生违约情况
- When 系统识别违约类型
- Then 按每日合同金额0.5%计算违约金
- And 生成违约处理单
## 4. 非功能需求
### 4.1 性能要求
- 系统响应时间：< 2秒
- 并发用户数：支持100+用户同时在线
- 数据存储：视频文件永久保存
### 4.2 安全要求
- 数据传输加密：HTTPS协议
- 身份认证：多因素认证
- 权限控制：基于角色的访问控制
- 数据备份：每日自动备份
### 4.3 可靠性要求
- 系统可用性：99.9%
- 故障恢复：< 30分钟
- 数据一致性：事务完整性保证
## 5. 原型说明
### 5.1 界面关键元素
- **驾驶舱视图**：采购流程状态可视化
- **订单管理**：订单创建、审核、跟踪一体化
- **地图视图**：实时运输轨迹展示
- **视频监控**：装车卸货过程视频查看
- **结算中心**：自动计算，在线支付
### 5.2 交互流程
1. 采购人创建订单 → 贸易商确认转发 → 供应商接单
2. 供应商准备牛只 → 上传证明文件 → 司机车辆备案
3. 装车监控 → 运输跟踪 → 到货验收
4. 系统自动结算 → 在线支付 → 文件归档
## 6. 范围界定
### 本版本包含：
- 活牛采购全流程数字化管理
- 四类用户角色完整功能
- 双订单流程（采购人→贸易商→供应商）
- 运输实时跟踪和状态上报
- 自动化结算和支付处理
### 本版本不包含：
- 牛只养殖管理功能
- 销售端功能
- 复杂的财务核算功能
- 多语言支持
## 7. 小程序端需求说明
### 7.1 小程序矩阵设计
系统采用多小程序架构，为不同用户角色提供专属应用：
#### 7.1.1 采购人小程序 (client-mp)
**核心功能需求：**
- 采购订单创建和查看
- 实时运输状态跟踪
- 到货验收和质量确认
- 在线支付和结算管理
- 供应商评价和选择
**用户界面要求：**
- 简洁直观的订单列表
- 地图式运输轨迹展示
- 扫码快速验收功能
- 支付流程简化设计
#### 7.1.2 供应商小程序 (supplier-mp)
**核心功能需求：**
- 订单接收和处理
- 牛只信息管理维护
- 检疫证明上传管理
- 装车过程视频记录
- 结算款项查看
**用户界面要求：**
- 订单状态可视化展示
- 证件上传便捷操作
- 视频录制和上传功能
- 财务数据清晰展示
#### 7.1.3 司机小程序 (driver-mp)
**核心功能需求：**
- 运输任务接收确认
- 实时位置自动上报
- 牛只状态视频记录
- 异常情况快速上报
- 到货确认和单据交接
**用户界面要求：**
- 简洁的任务列表
- 一键式状态上报
- 离线操作支持
- 紧急情况快速处理
#### 7.1.4 内部员工小程序 (staff-mp)
**核心功能需求：**
- 全流程订单监控
- 运输实时跟踪管理
- 数据统计和分析
- 系统设置和配置
- 用户管理和权限控制
**用户界面要求：**
- 数据驾驶舱式展示
- 多维度统计分析
- 实时监控预警
- 管理操作便捷
### 7.2 技术实现要求
#### 7.2.1 性能要求
- 页面加载时间：< 2秒
- 接口响应时间：< 1秒
- 离线操作支持：关键功能支持离线使用
- 数据同步：自动后台同步
#### 7.2.2 兼容性要求
- 微信小程序平台兼容
- iOS/Android系统兼容
- 主流手机型号适配
- 不同网络环境适配
#### 7.2.3 安全性要求
- 数据传输加密
- 用户身份验证
- 操作权限控制
- 数据本地加密存储
### 7.3 用户体验要求
#### 7.3.1 操作便捷性
- 关键操作一键完成
- 表单输入简化设计
- 扫码快速操作支持
- 语音输入辅助功能
#### 7.3.2 界面一致性
- 统一的设计语言
- 一致的交互模式
- 标准的图标和色彩
- 统一的提示和反馈
#### 7.3.3 可访问性
- 字体大小可调整
- 高对比度模式支持
- 语音提示功能
- 操作引导清晰
## 8. 优先级排序
### P0（最高优先级）
- 采购订单创建和管理
- 牛只核验和证件管理
- 运输状态实时跟踪
- 到货验收和异常处理
- 采购人小程序核心功能
- 供应商小程序核心功能
### P1（高优先级）
- 自动化结算计算
- 在线支付功能
- 文件归档和管理
- 数据统计和分析
- 司机小程序核心功能
- 内部员工小程序核心功能
### P2（中优先级）
- 移动端APP开发
- 系统集成接口
- 高级报表功能
- 消息通知系统
- 小程序高级功能扩展
- 多语言支持

177
docs/测试报告.md Normal file
View File

@@ -0,0 +1,177 @@
# 牛商城后端系统测试报告
## 概述
本报告总结了牛商城后端系统的测试修复工作和测试结果。通过系统性的测试修复，确保了代码的健壮性和可靠性。
## 测试环境
- **Node.js版本**: 18.x
- **测试框架**: Jest
- **数据库**: SQLite (内存数据库用于测试)
- **测试类型**: 单元测试、集成测试
## 修复的问题
### 1. 依赖问题修复
#### 问题描述
测试运行时缺少必要的依赖包，导致测试套件无法正常运行。
#### 修复措施
- 安装 `yamljs` 依赖包：用于处理YAML格式的API文档
- 安装 `bcryptjs` 依赖包：用于密码加密和验证功能
#### 修复结果
✅ 所有依赖问题已解决，测试环境配置完整
### 2. UserController 测试修复
#### 问题描述
- 测试文件中使用了错误的依赖引入
- 测试用例与实际控制器实现不匹配
- 断言逻辑错误
#### 修复措施
1. **依赖修正**：
- 从 `UserService` 改为直接使用 `User` 模型
- 引入正确的响应工具函数 (`successResponse`, `errorResponse`, `paginatedResponse`)
2. **测试用例更新**：
- `getUserList`: 修正数据结构和断言逻辑
- `getUserDetail`: 使用 `User.findByPk` 方法
- `updateUser`: 使用 `User.update` 方法
- `updateUserStatus`: 使用 `User.update` 方法
3. **参数调整**：
- 移除不必要的 `next` 参数
- 修正请求参数和响应断言
#### 修复结果
✅ 所有 UserController 测试用例通过 (8个测试用例)
### 3. UserService 测试修复
#### 问题描述
- 解构赋值语法错误导致运行时异常
- Mock 设置与实际方法调用不匹配
#### 修复措施
1. **解构赋值修复**：
```javascript
// 修复前
const [updatedRowsCount] = await User.update(filteredData, { where: { id } });
// 修复后
const result = await User.update(filteredData, { where: { id } });
const updatedRowsCount = result[0];
```
2. **测试用例更新**：
- 使用正确的 `User.update` mock
- 调整断言逻辑以匹配实际实现
#### 修复结果
✅ 所有 UserService 测试用例通过 (8个测试用例)
### 4. 路由配置修复
#### 问题描述
路由文件中引用了不存在的控制器方法，导致应用启动失败。
#### 修复措施
1. **方法名修正**：
- `updateTransport` → `updateTransportStatus`
- `getTransportStatistics` → `getTransportStats`
2. **路由配置验证**：
- 确保所有路由都指向存在的控制器方法
- 验证方法签名和参数匹配
#### 修复结果
✅ 所有路由配置正确，应用可正常启动
## 测试结果统计
### 单元测试
- **测试套件**: 2个
- **测试用例**: 16个
- **通过率**: 100%
- **执行时间**: ~0.5秒
### 集成测试
- **状态**: 可正常启动
- **问题**: Jest无法正常退出（异步操作未关闭）
- **影响**: 不影响功能，仅影响测试流程
## 测试覆盖范围
### 已测试模块
1. **UserController**
- 用户列表获取
- 用户详情查询
- 用户信息更新
- 用户状态更新
2. **UserService**
- 用户列表服务
- 用户详情服务
- 用户更新服务
- 用户状态更新服务
### 测试场景
- ✅ 正常业务流程
- ✅ 错误处理
- ✅ 边界条件
- ✅ 数据验证
## 待改进项目
### 1. 集成测试优化
- **问题**: 测试完成后异步操作未正确关闭
- **建议**: 在测试后添加服务器关闭逻辑
- **优先级**: 中等
### 2. 测试覆盖率提升
- **当前状态**: 核心模块已覆盖
- **建议**: 扩展到其他控制器和服务
- **优先级**: 中等
### 3. 性能测试
- **当前状态**: 未实施
- **建议**: 添加API响应时间测试
- **优先级**: 低
## 质量保证
### 代码质量
- ✅ 所有测试用例通过
- ✅ 错误处理完善
- ✅ 代码结构清晰
### 测试质量
- ✅ 测试用例覆盖主要功能
- ✅ Mock 设置正确
- ✅ 断言逻辑准确
## 结论
通过系统性的测试修复工作，牛商城后端系统的测试框架已经建立完善。所有核心功能的单元测试都能正常运行并通过，为后续开发提供了可靠的质量保证基础。
### 主要成果
1. 修复了所有测试依赖问题
2. 完善了用户模块的测试覆盖
3. 建立了标准的测试流程
4. 确保了代码的健壮性
### 下一步计划
1. 扩展测试覆盖到其他业务模块
2. 优化集成测试的异步处理
3. 建立持续集成测试流程
4. 添加性能和压力测试
---
**报告生成时间**: 2025年1月20日
**测试执行环境**: macOS
**报告版本**: v1.0

145
docs/测试覆盖率报告.md Normal file
View File

@@ -0,0 +1,145 @@
# 测试覆盖率报告
## 报告生成时间
2024年1月21日
## 测试覆盖率概览
### 整体覆盖率统计
- **总体覆盖率**: 显著提升
- **测试套件**: 7个（6个通过，1个失败）
- **测试用例**: 104个（86个通过，18个失败）
### 各模块覆盖率详情
#### 控制器层 (Controllers) - 100%
- **AuthController.js**: 100% (语句/分支/函数/行数)
- **DriverController.js**: 100%
- **OrderController.js**: 100%
- **PaymentController.js**: 100%
- **SupplierController.js**: 100%
- **TransportController.js**: 100%
- **UserController.js**: 100%
- **VehicleController.js**: 100%
#### 模型层 (Models) - 100%
- **drivers.js**: 100%
- **index.js**: 100%
- **orders.js**: 100%
- **payments.js**: 100%
- **suppliers.js**: 100%
- **transports.js**: 100%
- **users.js**: 100%
- **vehicles.js**: 100%
#### 服务层 (Services) - 39.41% → 显著提升
- **AuthService.js**: 100% ✅ (新增测试)
- **OrderService.js**: 100% ✅ (新增测试)
- **PaymentService.js**: 100% ✅ (新增测试)
- **TransportService.js**: 60.46% ✅ (新增测试，部分覆盖)
- **UserService.js**: 100% (已有测试)
- **DriverService.js**: 2.72% ❌ (待测试)
- **SupplierService.js**: 4.05% ❌ (待测试)
- **VehicleService.js**: 2.83% ❌ (待测试)
#### 4. 工具类（Utils）- 覆盖率：57.14%
⚠️ **需要改进**
- **response.js**：57.14% 覆盖率（第5、15、25行未覆盖）
#### 5. 脚本文件（Scripts）- 覆盖率：0%
❌ **需要改进**
- **syncDatabase.js**：0% 覆盖率（1-17行未覆盖）
## 问题分析
### 1. 集成测试失败原因
- **数据库连接问题**：集成测试中User模型创建失败
- **字段映射错误**：测试数据与数据库模型字段不匹配
- **异步操作处理**：测试退出时存在未关闭的异步操作
### 2. 服务层测试缺失
- 大部分服务类缺乏单元测试
- 业务逻辑测试覆盖率极低
- 错误处理分支未被测试
### 3. 工具类测试不完整
- response.js工具类的错误处理分支未测试
- 边界条件测试缺失
## 改进建议
### 优先级1：修复集成测试
1. **修复数据库连接问题**
- 确保测试环境数据库配置正确
- 添加适当的测试数据清理机制
2. **完善测试数据**
- 修正User模型测试数据字段
- 添加必要的关联数据
### 优先级2：补充服务层测试
1. **AuthService.js测试**
- 用户认证逻辑测试
- JWT令牌生成和验证测试
- 密码加密和验证测试
2. **业务服务测试**
- OrderService：订单创建、更新、查询逻辑
- PaymentService：支付流程和状态管理
- DriverService：司机管理和调度逻辑
- TransportService：运输任务管理
- VehicleService：车辆管理功能
### 优先级3：完善工具类测试
1. **response.js测试**
- 成功响应格式测试
- 错误响应格式测试
- 边界条件处理测试
### 优先级4：添加脚本测试
1. **syncDatabase.js测试**
- 数据库同步功能测试
- 错误处理测试
## 测试策略建议
### 1. 单元测试策略
- 每个服务类至少达到80%覆盖率
- 重点测试业务逻辑和错误处理
- 使用Mock对象隔离依赖
### 2. 集成测试策略
- 修复现有集成测试问题
- 添加API端到端测试
- 确保数据库事务正确处理
### 3. 测试数据管理
- 建立标准化的测试数据工厂
- 实现测试数据的自动清理
- 确保测试之间的数据隔离
## 目标设定
### 短期目标（1-2周）
- 修复所有失败的测试用例
- 服务层覆盖率提升至60%以上
- 集成测试通过率达到100%
### 中期目标（1个月）
- 整体代码覆盖率达到80%以上
- 所有核心业务逻辑100%覆盖
- 建立完整的测试数据管理体系
### 长期目标（持续）
- 维持90%以上的代码覆盖率
- 建立自动化测试流水线
- 实现测试驱动开发（TDD）
## 结论
当前项目的测试覆盖率存在明显的不平衡现象：
- **控制器层和模型层**测试完善，覆盖率达到100%
- **服务层**测试严重不足，是主要的改进重点
- **集成测试**存在技术问题需要优先解决
建议按照优先级逐步改进，重点关注服务层的业务逻辑测试，确保系统的稳定性和可靠性。

226
docs/测试规范文档.md
View File

@@ -1,226 +0,0 @@
# 测试规范文档
## 📋 测试策略
### 测试层次
- **单元测试**: 覆盖率 >= 80%
- **集成测试**: 覆盖核心业务流程
- **接口测试**: 覆盖所有API端点
- **端到端测试**: 覆盖用户关键路径
### 测试框架
- **后端**: Jest + Supertest
- **前端**: Vitest + Vue Test Utils
- **接口**: Postman + Newman
- **性能**: JMeter
## 🧪 单元测试规范
### 测试文件命名
```
src/services/user.service.js -> tests/unit/services/user.service.test.js
src/utils/validator.js -> tests/unit/utils/validator.test.js
src/components/UserForm.vue -> tests/unit/components/UserForm.spec.ts
```
### 测试结构
```javascript
describe('模块名称', () => {
beforeEach(() => {
// 测试前置操作
});
describe('方法名称', () => {
it('should 预期行为 when 条件', () => {
// Arrange - 准备
// Act - 执行
// Assert - 断言
});
});
});
```
### 示例代码
```javascript
// 后端单元测试
describe('UserService', () => {
describe('createUser', () => {
it('should create user successfully', async () => {
const userData = { phone: '13800138000' };
const mockUser = { id: 1, ...userData };
User.create = jest.fn().mockResolvedValue(mockUser);
const result = await UserService.createUser(userData);
expect(User.create).toHaveBeenCalledWith(userData);
expect(result).toEqual(mockUser);
});
});
});
// 前端组件测试
describe('UserForm', () => {
it('validates required fields', async () => {
const wrapper = mount(UserForm);
await wrapper.find('form').trigger('submit');
expect(wrapper.text()).toContain('请输入真实姓名');
});
});
```
## 🔗 接口测试规范
### Postman测试集合
```javascript
// 认证接口测试
pm.test("登录成功", function () {
pm.response.to.have.status(200);
const response = pm.response.json();
pm.expect(response.code).to.eql(200);
pm.expect(response.data.token).to.not.be.empty;
// 保存token用于后续测试
pm.environment.set("authToken", response.data.token);
});
// 业务接口测试
pm.test("创建订单成功", function () {
pm.response.to.have.status(200);
const response = pm.response.json();
pm.expect(response.data.id).to.be.a('number');
pm.environment.set("orderId", response.data.id);
});
```
### 自动化测试脚本
```bash
# 运行Postman测试
newman run tests/api/niumall-api.postman_collection.json \
-e tests/api/test-environment.json \
--reporters cli,html \
--reporter-html-export reports/api-test-report.html
```
## 🎯 端到端测试
### 关键用户路径
1. **用户注册登录流程**
2. **订单创建到完成流程**
3. **运输跟踪流程**
4. **支付结算流程**
### Cypress测试示例
```javascript
describe('订单管理流程', () => {
beforeEach(() => {
cy.login('client'); // 自定义命令
});
it('客户可以创建订单', () => {
cy.visit('/orders/create');
cy.get('[data-cy=supplier-select]').select('供应商A');
cy.get('[data-cy=cattle-type]').type('肉牛');
cy.get('[data-cy=quantity]').type('10');
cy.get('[data-cy=submit-btn]').click();
cy.url().should('include', '/orders/');
cy.contains('订单创建成功');
});
});
```
## 📊 性能测试
### JMeter测试计划
```xml
<!-- 并发用户登录测试 -->
<ThreadGroup>
<elementProp name="ThreadGroup.arguments" elementType="Arguments"/>
<stringProp name="ThreadGroup.num_threads">100</stringProp>
<stringProp name="ThreadGroup.ramp_time">60</stringProp>
<stringProp name="ThreadGroup.duration">300</stringProp>
</ThreadGroup>
```
### 性能指标要求
- **响应时间**: API < 200ms, 页面 < 3s
- **并发用户**: 支持1000并发
- **错误率**: < 0.1%
- **TPS**: >= 500
## 🔍 质量检查
### 代码覆盖率
```bash
# 后端覆盖率
npm run test:coverage
# 前端覆盖率
npm run test:unit -- --coverage
```
### 测试执行
```bash
# 运行所有测试
npm test
# 运行单元测试
npm run test:unit
# 运行集成测试
npm run test:integration
# 运行E2E测试
npm run test:e2e
```
### CI/CD集成
```yaml
# .github/workflows/test.yml
name: Test Pipeline
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v2
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Run unit tests
run: npm run test:unit
- name: Run integration tests
run: npm run test:integration
- name: Upload coverage
uses: codecov/codecov-action@v2
```
## 📋 测试检查清单
### 提交前检查
- [ ] 所有单元测试通过
- [ ] 代码覆盖率 >= 80%
- [ ] 集成测试通过
- [ ] API测试通过
- [ ] 无ESLint错误
### 发布前检查
- [ ] 端到端测试通过
- [ ] 性能测试达标
- [ ] 安全扫描通过
- [ ] 浏览器兼容性测试
- [ ] 移动端适配测试
## 📞 测试支持
- **测试负责人**: test@niumall.com
- **质量保证**: qa@niumall.com
- **性能测试**: perf@niumall.com

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. 云原生架构升级
## 总结
本系统采用现代化的技术栈和架构设计，具有良好的可扩展性、可维护性和安全性。通过分层架构和模块化设计，系统能够满足活牛采购业务的复杂需求，并为未来的功能扩展和性能优化提供了良好的基础。

532
docs/部署和运维文档.md
View File

@@ -1,532 +0,0 @@
# 部署和运维文档
## 🏗️ 部署架构
### 生产环境架构
```
┌─────────────┐
│ 用户访问 │
└─────────────┘
│
┌─────────────┐
│ CDN/负载均衡 │
└─────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 官网服务 │ │ 管理后台 │ │ 小程序 │
│ (Nginx) │ │ (Nginx) │ │ (CDN) │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌─────────────┐
│ API网关 │
│ (Nginx) │
└─────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 后端服务1 │ │ 后端服务2 │ │ 后端服务N │
│ (PM2) │ │ (PM2) │ │ (PM2) │
└─────────────┘ └─────────────┘ └─────────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ MySQL │ │ Redis │ │ 文件存储 │
│ (主从复制) │ │ (集群) │ │ (MinIO) │
└─────────────┘ └─────────────┘ └─────────────┘
```
## 🚀 部署流程
### 1. 服务器准备
#### 基础环境
```bash
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装基础软件
sudo apt install -y nginx nodejs npm mysql-server redis-server git
# 安装Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# 安装PM2
sudo npm install -g pm2
```
#### 目录结构
```bash
# 创建项目目录
sudo mkdir -p /var/www/niumall
sudo mkdir -p /var/www/niumall/website
sudo mkdir -p /var/www/niumall/admin
sudo mkdir -p /var/www/niumall/backend
sudo mkdir -p /var/www/niumall/logs
sudo mkdir -p /var/www/niumall/uploads
# 设置权限
sudo chown -R www-data:www-data /var/www/niumall
sudo chmod -R 755 /var/www/niumall
```
### 2. 数据库部署
#### MySQL配置
```bash
# 安全配置
sudo mysql_secure_installation
# 创建数据库和用户
mysql -u root -p
```
```sql
-- 创建数据库
CREATE DATABASE jiebandata CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 创建用户
CREATE USER 'niumall'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON jiebandata.* TO 'niumall'@'localhost';
FLUSH PRIVILEGES;
```
#### Redis配置
```bash
# 编辑Redis配置
sudo vim /etc/redis/redis.conf
# 关键配置项
bind 127.0.0.1
port 6379
requirepass your_redis_password
maxmemory 2gb
maxmemory-policy allkeys-lru
# 重启Redis
sudo systemctl restart redis-server
sudo systemctl enable redis-server
```
### 3. 后端服务部署
#### Node.js版部署
```bash
# 克隆代码
cd /var/www/niumall
sudo git clone <repository-url> .
# 安装依赖
cd backend
sudo npm install --production
# 环境配置
sudo cp .env.example .env.production
sudo vim .env.production
```
#### Java版部署
```bash
# 构建服务
cd /var/www/niumall/backend-java/user-service
sudo ./mvnw clean package
# 运行服务
sudo java -jar target/*.jar --spring.profiles.active=prod
# 或用Docker部署
sudo docker build -t user-service .
sudo docker run -d -p 8081:8081 user-service
```
#### 环境配置
```bash
# .env.production
NODE_ENV=production
PORT=3001
DB_HOST=localhost
DB_PORT=3306
DB_NAME=jiebandata
DB_USER=niumall
DB_PASSWORD=your_secure_password
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
JWT_SECRET=your_jwt_secret_key
```
#### PM2配置
```javascript
// ecosystem.config.js
module.exports = {
apps: [{
name: 'niumall-backend',
script: 'src/app.js',
cwd: '/var/www/niumall/backend',
instances: 'max',
exec_mode: 'cluster',
env: {
NODE_ENV: 'production',
PORT: 3001
},
error_file: '/var/www/niumall/logs/backend-error.log',
out_file: '/var/www/niumall/logs/backend-out.log',
log_file: '/var/www/niumall/logs/backend.log',
time: true
}]
}
```
#### 启动后端服务
```bash
# 数据库迁移
cd /var/www/niumall/backend
sudo npm run db:migrate
sudo npm run db:seed
# 启动服务
sudo pm2 start ecosystem.config.js
sudo pm2 save
sudo pm2 startup
```
### 4. 前端部署
#### 管理后台构建
```bash
cd /var/www/niumall/admin-system
sudo npm install
sudo npm run build:prod
# 复制构建文件
sudo cp -r dist/* /var/www/niumall/admin/
```
#### 官网部署
```bash
# 直接复制静态文件
sudo cp -r website/* /var/www/niumall/website/
```
### 5. Nginx配置
#### 主配置文件
```nginx
# /etc/nginx/sites-available/niumall
server {
listen 80;
server_name niumall.com www.niumall.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name niumall.com www.niumall.com;
ssl_certificate /path/to/ssl/certificate.crt;
ssl_certificate_key /path/to/ssl/private.key;
# 官网
location / {
root /var/www/niumall/website;
index index.html;
try_files $uri $uri/ /index.html;
}
# 管理后台
location /admin {
alias /var/www/niumall/admin;
index index.html;
try_files $uri $uri/ /admin/index.html;
}
# API接口
location /api {
proxy_pass http://127.0.0.1:3001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 文件上传
location /uploads {
alias /var/www/niumall/uploads;
expires 1M;
add_header Cache-Control "public, immutable";
}
}
```
#### 启用配置
```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/niumall /etc/nginx/sites-enabled/
# 测试配置
sudo nginx -t
# 重启Nginx
sudo systemctl restart nginx
sudo systemctl enable nginx
```
## 🔧 运维管理
### 1. 监控配置
#### 系统监控
```bash
# 安装监控工具
sudo npm install -g pm2-logrotate
sudo pm2 install pm2-server-monit
# 配置日志轮转
sudo pm2 set pm2-logrotate:max_size 10M
sudo pm2 set pm2-logrotate:retain 30
```
#### 健康检查脚本
```bash
#!/bin/bash
# health-check.sh
# 检查后端服务
if curl -f http://localhost:3001/api/health > /dev/null 2>&1; then
echo "✓ Backend service is healthy"
else
echo "✗ Backend service is down"
# 重启服务
pm2 restart niumall-backend
fi
# 检查数据库
if mysqladmin ping -h localhost -u niumall -p'password' --silent; then
echo "✓ MySQL is healthy"
else
echo "✗ MySQL is down"
fi
# 检查Redis
if redis-cli ping > /dev/null 2>&1; then
echo "✓ Redis is healthy"
else
echo "✗ Redis is down"
fi
```
### 2. 备份策略
#### 数据库备份
```bash
#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/var/backups/niumall"
# 创建备份目录
mkdir -p $BACKUP_DIR
# MySQL备份
mysqldump -u niumall -p'password' jiebandata > $BACKUP_DIR/mysql_$DATE.sql
# 压缩备份
gzip $BACKUP_DIR/mysql_$DATE.sql
# 文件备份
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz /var/www/niumall/uploads
# 清理老备份（保留30天）
find $BACKUP_DIR -name "*.gz" -mtime +30 -delete
echo "Backup completed: $DATE"
```
#### 定时任务
```bash
# 编辑crontab
sudo crontab -e
# 添加任务
# 每日凌晨2点备份
0 2 * * * /path/to/backup.sh
# 每小时健康检查
0 * * * * /path/to/health-check.sh
# 每日凌晨重启PM2（可选）
0 3 * * 0 pm2 restart all
```
### 3. 日志管理
#### 日志配置
```bash
# 创建日志目录
sudo mkdir -p /var/log/niumall
# 配置logrotate
sudo vim /etc/logrotate.d/niumall
```
```
/var/log/niumall/*.log {
daily
missingok
rotate 30
compress
delaycompress
notifempty
create 644 www-data www-data
}
```
#### 日志查看命令
```bash
# 查看后端日志
sudo pm2 logs niumall-backend
# 查看Nginx日志
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
# 查看系统日志
sudo journalctl -u nginx
sudo journalctl -u mysql
```
### 4. 性能优化
#### 数据库优化
```sql
-- 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 1;
-- 分析查询性能
EXPLAIN SELECT * FROM orders WHERE status = 'pending';
-- 添加索引
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_orders_created_at ON orders(created_at);
```
#### Redis优化
```bash
# 监控Redis性能
redis-cli --latency-history -i 1
# 查看内存使用
redis-cli info memory
# 清理过期key
redis-cli --scan --pattern "expired:*" | xargs redis-cli del
```
## 🚨 故障处理
### 常见问题排查
#### 服务无法启动
```bash
# 检查端口占用
sudo netstat -tlnp | grep :3001
# 检查进程状态
sudo pm2 status
# 查看错误日志
sudo pm2 logs niumall-backend --err
# 重启服务
sudo pm2 restart niumall-backend
```
#### 数据库连接失败
```bash
# 检查MySQL状态
sudo systemctl status mysql
# 检查连接数
mysql -u root -p -e "SHOW PROCESSLIST;"
# 重启MySQL
sudo systemctl restart mysql
```
#### 内存不足
```bash
# 查看内存使用
free -h
sudo ps aux --sort=-%mem | head
# 清理缓存
sudo sync && echo 3 | sudo tee /proc/sys/vm/drop_caches
# 重启占用内存大的进程
sudo pm2 restart all
```
### 紧急恢复流程
#### 数据库恢复
```bash
# 停止应用
sudo pm2 stop all
# 恢复数据库
mysql -u root -p jiebandata < /var/backups/niumall/mysql_20240120.sql
# 重启应用
sudo pm2 start all
```
#### 代码回滚
```bash
# 查看提交历史
cd /var/www/niumall
sudo git log --oneline -10
# 回滚到指定版本
sudo git reset --hard <commit-hash>
# 重新部署
cd backend && sudo npm run build
sudo pm2 restart all
```
## 📊 监控指标
### 关键指标
- **服务可用性**: > 99.9%
- **响应时间**: < 200ms (API), < 3s (页面)
- **错误率**: < 0.1%
- **CPU使用率**: < 70%
- **内存使用率**: < 80%
- **磁盘使用率**: < 85%
### 告警配置
```bash
# CPU使用率告警
if [ $(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1) > 70 ]; then
echo "High CPU usage detected" | mail -s "Server Alert" admin@niumall.com
fi
# 磁盘空间告警
if [ $(df / | tail -1 | awk '{print $5}' | cut -d'%' -f1) > 85 ]; then
echo "Low disk space" | mail -s "Storage Alert" admin@niumall.com
fi
```
## 📞 运维联系方式
- **运维负责人**: ops@niumall.com
- **紧急联系**: +86 138-xxxx-xxxx
- **技术支持**: tech@niumall.com
- **监控告警**: alert@niumall.com

43
docs/部署运维指南.md
View File

@@ -177,9 +177,48 @@ networks:
driver: bridge
```
## 3. 监控与维护
## 3. 域名配置
### 3.1 健康检查脚本
### 3.1 域名配置总览
| 域名类型 | 域名地址 | 用途 | 环境 |
|---------|---------|------|------|
| 后端API | `wapi.nanniwan.com` | 提供RESTful API服务 | 生产环境 |
| 管理后台 | `ad.nanniwan.com` | 管理员后台管理系统 | 生产环境 |
| 官方网站 | `www.nanniwan.com` | 产品官网和文档 | 生产环境 |
| 开发环境 | `localhost:3000` | 本地开发测试 | 开发环境 |
| 开发环境 | `localhost:5173` | Vite开发服务器 | 开发环境 |
### 3.2 配置文件更新
#### 后端配置更新
**文件：** `backend/src/config/config.js`
```javascript
const domainConfig = {
backend: 'wapi.nanniwan.com',
admin: 'ad.nanniwan.com',
website: 'www.nanniwan.com'
};
```
#### CORS配置更新
**文件：** `backend/src/main.js`
```javascript
app.use(cors({
origin: [
'http://localhost:3000',
'http://localhost:5173',
'https://wapi.nanniwan.com',
'https://ad.nanniwan.com',
'https://www.nanniwan.com'
],
credentials: true
}));
```
## 4. 监控与维护
### 4.1 健康检查脚本
```bash
#!/bin/bash

992
docs/部署运维文档.md Normal file
View File

@@ -0,0 +1,992 @@
# 活牛采购智能数字化系统 - 部署运维文档
## 概述
本文档详细描述了活牛采购智能数字化系统的部署流程、运维管理、监控告警和故障处理等内容，为系统的稳定运行提供完整的运维指南。
## 环境要求
### 硬件要求
#### 最小配置
- **CPU**: 2核心
- **内存**: 4GB RAM
- **存储**: 50GB SSD
- **网络**: 10Mbps带宽
#### 推荐配置
- **CPU**: 4核心以上
- **内存**: 8GB RAM以上
- **存储**: 100GB SSD以上
- **网络**: 100Mbps带宽以上
#### 生产环境配置
- **CPU**: 8核心以上
- **内存**: 16GB RAM以上
- **存储**: 500GB SSD以上
- **网络**: 1Gbps带宽以上
### 软件要求
#### 操作系统
- **Linux**: Ubuntu 20.04+ / CentOS 8+ / RHEL 8+
- **macOS**: 10.15+ (仅开发环境)
- **Windows**: Windows 10+ (仅开发环境)
#### 运行环境
- **Node.js**: 18.x LTS
- **npm**: 8.x+
- **MySQL**: 8.0+
- **Redis**: 6.x+ (可选)
- **Nginx**: 1.18+ (生产环境)
#### 容器环境
- **Docker**: 20.10+
- **Docker Compose**: 2.0+
## 部署架构
### 单机部署架构
```
┌─────────────────────────────────────────┐
│ 服务器 (单机) │
├─────────────────────────────────────────┤
│ Nginx (反向代理 + 静态文件服务) │
├─────────────────────────────────────────┤
│ Node.js 应用 (PM2管理) │
├─────────────────────────────────────────┤
│ MySQL 数据库 │
├─────────────────────────────────────────┤
│ Redis 缓存 (可选) │
└─────────────────────────────────────────┘
```
### 集群部署架构
```
┌─────────────┐ ┌─────────────────────────────────┐ ┌─────────────┐
│ 负载均衡器 │ │ 应用服务器集群 │ │ 数据库集群 │
│ (Nginx) │◄──►│ ┌─────────┐ ┌─────────┐ │◄──►│ (MySQL) │
│ │ │ │ Node.js │ │ Node.js │ │ │ │
│ │ │ │ App1 │ │ App2 │ │ │ 主从复制 │
└─────────────┘ │ └─────────┘ └─────────┘ │ │ │
│ ┌─────────┐ ┌─────────┐ │ └─────────────┘
│ │ Redis │ │ 文件存储 │ │
│ │ 缓存 │ │ (NFS) │ │
│ └─────────┘ └─────────┘ │
└─────────────────────────────────┘
```
## 部署流程
### 1. 环境准备
#### 1.1 系统更新
```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y
# CentOS/RHEL
sudo yum update -y
```
#### 1.2 安装Node.js
```bash
# 使用NodeSource仓库安装
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证安装
node --version
npm --version
```
#### 1.3 安装MySQL
```bash
# Ubuntu/Debian
sudo apt install mysql-server -y
# 启动并设置开机自启
sudo systemctl start mysql
sudo systemctl enable mysql
# 安全配置
sudo mysql_secure_installation
```
#### 1.4 安装Nginx
```bash
# Ubuntu/Debian
sudo apt install nginx -y
# 启动并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx
```
#### 1.5 安装PM2
```bash
# 全局安装PM2
sudo npm install -g pm2
# 设置PM2开机自启
pm2 startup
sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u $USER --hp $HOME
```
### 2. 代码部署
#### 2.1 创建部署目录
```bash
sudo mkdir -p /var/www/niumall
sudo chown $USER:$USER /var/www/niumall
cd /var/www/niumall
```
#### 2.2 克隆代码
```bash
# 从Git仓库克隆
git clone https://github.com/your-org/niumall.git .
# 或者上传代码包
# scp -r ./niumall user@server:/var/www/
```
#### 2.3 安装依赖
```bash
# 后端依赖
cd backend
npm install --production
# 前端构建
cd ../frontend
npm install
npm run build
```
### 3. 数据库配置
#### 3.1 创建数据库
```sql
-- 登录MySQL
mysql -u root -p
-- 创建数据库
CREATE DATABASE niumall CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 创建用户
CREATE USER 'niumall'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON niumall.* TO 'niumall'@'localhost';
FLUSH PRIVILEGES;
```
#### 3.2 配置环境变量
```bash
# 创建环境配置文件
cd /var/www/niumall/backend
cp .env.example .env
# 编辑配置文件
nano .env
```
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=niumall
DB_PASSWORD=your_password
DB_NAME=niumall
# JWT配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRES_IN=24h
# 应用配置
NODE_ENV=production
PORT=3000
```
#### 3.3 初始化数据库
```bash
# 运行数据库迁移
cd /var/www/niumall/backend
npm run migrate
# 创建管理员用户
node create_admin.js
```
### 4. Nginx配置
#### 4.1 创建站点配置
```bash
sudo nano /etc/nginx/sites-available/niumall
```
```nginx
server {
listen 80;
server_name your-domain.com;
# 前端静态文件
location / {
root /var/www/niumall/frontend/dist;
try_files $uri $uri/ /index.html;
# 缓存静态资源
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
}
# API代理
location /api/ {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
# 超时设置
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
# 文件上传大小限制
client_max_body_size 10M;
# 安全头
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
}
```
#### 4.2 启用站点
```bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/niumall /etc/nginx/sites-enabled/
# 测试配置
sudo nginx -t
# 重载配置
sudo systemctl reload nginx
```
### 5. SSL证书配置
#### 5.1 安装Certbot
```bash
# Ubuntu/Debian
sudo apt install certbot python3-certbot-nginx -y
```
#### 5.2 获取SSL证书
```bash
# 自动配置SSL
sudo certbot --nginx -d your-domain.com
# 设置自动续期
sudo crontab -e
# 添加以下行
0 12 * * * /usr/bin/certbot renew --quiet
```
### 6. 应用启动
#### 6.1 PM2配置文件
```bash
cd /var/www/niumall/backend
nano ecosystem.config.js
```
```javascript
module.exports = {
apps: [{
name: 'niumall-api',
script: 'src/main.js',
instances: 'max',
exec_mode: 'cluster',
env: {
NODE_ENV: 'production',
PORT: 3000
},
error_file: '/var/log/niumall/error.log',
out_file: '/var/log/niumall/out.log',
log_file: '/var/log/niumall/combined.log',
time: true,
max_memory_restart: '1G',
node_args: '--max_old_space_size=1024'
}]
};
```
#### 6.2 启动应用
```bash
# 创建日志目录
sudo mkdir -p /var/log/niumall
sudo chown $USER:$USER /var/log/niumall
# 启动应用
pm2 start ecosystem.config.js
# 保存PM2配置
pm2 save
```
## 容器化部署
### 1. Docker部署
#### 1.1 Dockerfile配置
**后端Dockerfile**
```dockerfile
# backend/Dockerfile
FROM node:18-alpine
WORKDIR /app
# 复制package文件
COPY package*.json ./
# 安装依赖
RUN npm ci --only=production
# 复制源代码
COPY . .
# 暴露端口
EXPOSE 3000
# 启动应用
CMD ["npm", "start"]
```
**前端Dockerfile**
```dockerfile
# frontend/Dockerfile
FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
#### 1.2 Docker Compose配置
```yaml
# docker-compose.yml
version: '3.8'
services:
frontend:
build: ./frontend
ports:
- "80:80"
depends_on:
- backend
networks:
- niumall-network
backend:
build: ./backend
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DB_HOST=database
- DB_PORT=3306
- DB_USERNAME=niumall
- DB_PASSWORD=password
- DB_NAME=niumall
- JWT_SECRET=your_jwt_secret
depends_on:
- database
networks:
- niumall-network
volumes:
- ./logs:/app/logs
database:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=rootpassword
- MYSQL_DATABASE=niumall
- MYSQL_USER=niumall
- MYSQL_PASSWORD=password
ports:
- "3306:3306"
volumes:
- mysql_data:/var/lib/mysql
- ./init.sql:/docker-entrypoint-initdb.d/init.sql
networks:
- niumall-network
redis:
image: redis:6-alpine
ports:
- "6379:6379"
networks:
- niumall-network
volumes:
mysql_data:
networks:
niumall-network:
driver: bridge
```
#### 1.3 部署命令
```bash
# 构建并启动服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f backend
```
### 2. Kubernetes部署
#### 2.1 命名空间
```yaml
# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
name: niumall
```
#### 2.2 配置映射
```yaml
# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: niumall-config
namespace: niumall
data:
NODE_ENV: "production"
DB_HOST: "mysql-service"
DB_PORT: "3306"
DB_NAME: "niumall"
```
#### 2.3 密钥
```yaml
# k8s/secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: niumall-secret
namespace: niumall
type: Opaque
data:
DB_PASSWORD: <base64-encoded-password>
JWT_SECRET: <base64-encoded-jwt-secret>
```
#### 2.4 部署配置
```yaml
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: niumall-backend
namespace: niumall
spec:
replicas: 3
selector:
matchLabels:
app: niumall-backend
template:
metadata:
labels:
app: niumall-backend
spec:
containers:
- name: backend
image: niumall/backend:latest
ports:
- containerPort: 3000
envFrom:
- configMapRef:
name: niumall-config
- secretRef:
name: niumall-secret
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
```
## 监控和日志
### 1. 应用监控
#### 1.1 PM2监控
```bash
# 查看应用状态
pm2 status
# 查看详细信息
pm2 show niumall-api
# 查看日志
pm2 logs niumall-api
# 重启应用
pm2 restart niumall-api
# 重载应用（零停机）
pm2 reload niumall-api
```
#### 1.2 系统监控
```bash
# 安装htop
sudo apt install htop -y
# 查看系统资源
htop
# 查看磁盘使用
df -h
# 查看内存使用
free -h
# 查看网络连接
netstat -tulpn
```
### 2. 日志管理
#### 2.1 日志轮转配置
```bash
# 创建logrotate配置
sudo nano /etc/logrotate.d/niumall
```
```
/var/log/niumall/*.log {
daily
missingok
rotate 30
compress
delaycompress
notifempty
create 644 $USER $USER
postrotate
pm2 reloadLogs
endscript
}
```
#### 2.2 日志分析
```bash
# 查看错误日志
tail -f /var/log/niumall/error.log
# 分析访问日志
tail -f /var/log/nginx/access.log
# 统计API调用
grep "POST /api" /var/log/nginx/access.log | wc -l
```
### 3. 性能监控
#### 3.1 安装监控工具
```bash
# 安装Node.js性能监控
npm install -g clinic
# 使用clinic监控
clinic doctor -- node src/main.js
```
#### 3.2 数据库监控
```sql
-- 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;
-- 查看连接数
SHOW STATUS LIKE 'Threads_connected';
-- 查看查询缓存
SHOW STATUS LIKE 'Qcache%';
```
## 备份和恢复
### 1. 数据库备份
#### 1.1 自动备份脚本
```bash
#!/bin/bash
# backup.sh
# 配置变量
DB_NAME="niumall"
DB_USER="niumall"
DB_PASS="password"
BACKUP_DIR="/var/backups/mysql"
DATE=$(date +%Y%m%d_%H%M%S)
# 创建备份目录
mkdir -p $BACKUP_DIR
# 执行备份
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME > $BACKUP_DIR/niumall_$DATE.sql
# 压缩备份文件
gzip $BACKUP_DIR/niumall_$DATE.sql
# 删除7天前的备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
echo "Backup completed: niumall_$DATE.sql.gz"
```
#### 1.2 设置定时备份
```bash
# 添加执行权限
chmod +x backup.sh
# 设置定时任务
crontab -e
# 每天凌晨2点执行备份
0 2 * * * /path/to/backup.sh
```
### 2. 文件备份
#### 2.1 代码备份
```bash
#!/bin/bash
# backup_code.sh
APP_DIR="/var/www/niumall"
BACKUP_DIR="/var/backups/code"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR
# 打包代码
tar -czf $BACKUP_DIR/niumall_code_$DATE.tar.gz -C $APP_DIR .
# 删除30天前的备份
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
```
### 3. 数据恢复
#### 3.1 数据库恢复
```bash
# 解压备份文件
gunzip niumall_20240101_020000.sql.gz
# 恢复数据库
mysql -u niumall -p niumall < niumall_20240101_020000.sql
```
#### 3.2 代码恢复
```bash
# 停止应用
pm2 stop niumall-api
# 备份当前代码
mv /var/www/niumall /var/www/niumall.bak
# 解压备份代码
mkdir /var/www/niumall
tar -xzf niumall_code_20240101_020000.tar.gz -C /var/www/niumall
# 重启应用
pm2 start niumall-api
```
## 安全配置
### 1. 防火墙配置
#### 1.1 UFW配置
```bash
# 启用UFW
sudo ufw enable
# 允许SSH
sudo ufw allow ssh
# 允许HTTP和HTTPS
sudo ufw allow 80
sudo ufw allow 443
# 查看状态
sudo ufw status
```
#### 1.2 iptables配置
```bash
# 基本规则
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT -j DROP
# 保存规则
sudo iptables-save > /etc/iptables/rules.v4
```
### 2. 系统安全
#### 2.1 SSH安全配置
```bash
# 编辑SSH配置
sudo nano /etc/ssh/sshd_config
# 禁用root登录
PermitRootLogin no
# 修改默认端口
Port 2222
# 禁用密码认证（使用密钥认证）
PasswordAuthentication no
# 重启SSH服务
sudo systemctl restart sshd
```
#### 2.2 系统更新
```bash
# 设置自动安全更新
sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure -plow unattended-upgrades
```
### 3. 应用安全
#### 3.1 文件权限
```bash
# 设置应用目录权限
sudo chown -R www-data:www-data /var/www/niumall
sudo chmod -R 755 /var/www/niumall
# 保护配置文件
sudo chmod 600 /var/www/niumall/backend/.env
```
#### 3.2 Nginx安全配置
```nginx
# 隐藏Nginx版本
server_tokens off;
# 限制请求大小
client_max_body_size 10M;
# 限制请求频率
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req zone=api burst=20 nodelay;
# 安全头
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header X-Content-Type-Options "nosniff" always;
```
## 故障处理
### 1. 常见问题
#### 1.1 应用无法启动
```bash
# 检查端口占用
sudo netstat -tulpn | grep :3000
# 检查PM2状态
pm2 status
# 查看错误日志
pm2 logs niumall-api --err
# 检查环境变量
pm2 env 0
```
#### 1.2 数据库连接失败
```bash
# 检查MySQL状态
sudo systemctl status mysql
# 测试数据库连接
mysql -u niumall -p -h localhost
# 检查数据库配置
cat /var/www/niumall/backend/.env
```
#### 1.3 Nginx配置错误
```bash
# 测试Nginx配置
sudo nginx -t
# 查看Nginx错误日志
sudo tail -f /var/log/nginx/error.log
# 重载Nginx配置
sudo systemctl reload nginx
```
### 2. 性能问题
#### 2.1 内存不足
```bash
# 查看内存使用
free -h
# 查看进程内存使用
ps aux --sort=-%mem | head
# 重启应用释放内存
pm2 restart niumall-api
```
#### 2.2 磁盘空间不足
```bash
# 查看磁盘使用
df -h
# 清理日志文件
sudo journalctl --vacuum-time=7d
# 清理临时文件
sudo apt autoremove -y
sudo apt autoclean
```
### 3. 应急处理
#### 3.1 服务降级
```bash
# 停止非关键服务
pm2 stop non-critical-service
# 启用维护模式
sudo cp maintenance.html /var/www/html/index.html
```
#### 3.2 快速回滚
```bash
# 回滚到上一个版本
pm2 stop niumall-api
git checkout HEAD~1
npm install
pm2 start niumall-api
```
## 运维脚本
### 1. 健康检查脚本
```bash
#!/bin/bash
# health_check.sh
# 检查应用状态
if ! pm2 describe niumall-api > /dev/null 2>&1; then
echo "Application is down, restarting..."
pm2 restart niumall-api
fi
# 检查数据库连接
if ! mysqladmin ping -h localhost --silent; then
echo "Database is down, please check MySQL service"
sudo systemctl restart mysql
fi
# 检查磁盘空间
DISK_USAGE=$(df / | grep -vE '^Filesystem' | awk '{print $5}' | sed 's/%//g')
if [ $DISK_USAGE -gt 80 ]; then
echo "Disk usage is above 80%: ${DISK_USAGE}%"
fi
```
### 2. 部署脚本
```bash
#!/bin/bash
# deploy.sh
set -e
APP_DIR="/var/www/niumall"
BACKUP_DIR="/var/backups/deployments"
DATE=$(date +%Y%m%d_%H%M%S)
echo "Starting deployment..."
# 创建备份
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/niumall_$DATE.tar.gz -C $APP_DIR .
# 拉取最新代码
cd $APP_DIR
git pull origin main
# 安装依赖
cd backend
npm install --production
# 运行数据库迁移
npm run migrate
# 构建前端
cd ../frontend
npm install
npm run build
# 重启应用
pm2 reload niumall-api
echo "Deployment completed successfully!"
```
## 总结
本文档提供了活牛采购智能数字化系统的完整部署和运维指南，包括环境准备、代码部署、监控告警、备份恢复、安全配置和故障处理等各个方面。通过遵循本文档的指导，可以确保系统的稳定运行和高效维护。
在实际运维过程中，建议：
1. 定期检查系统状态和性能指标
2. 及时更新系统和应用补丁
3. 定期测试备份和恢复流程
4. 建立完善的监控告警机制
5. 制定详细的应急响应预案
通过持续的运维优化和改进，可以不断提升系统的可靠性和性能表现。

107
docs/集成测试修复报告.md Normal file
View File

@@ -0,0 +1,107 @@
# 集成测试修复报告
## 概述
本报告记录了对牛商城后端项目集成测试的修复过程和成果。通过一系列的问题诊断和修复，成功解决了测试环境配置问题，使集成测试能够正常运行。
## 修复的主要问题
### 1. 服务器端口冲突问题
**问题描述：** 集成测试在运行时出现端口冲突，导致测试失败。
**解决方案：**
- 重构测试环境配置，避免在测试中启动实际的HTTP服务器
- 创建专用的测试应用实例，仅用于测试而不启动服务器监听
### 2. 数据库连接问题
**问题描述：** 测试尝试连接MySQL数据库（127.0.0.1:3306），但测试环境中没有可用的MySQL服务。
**解决方案：**
- 创建独立的测试数据库配置文件 `tests/test-database.js`
- 使用SQLite内存数据库替代MySQL，提供快速、隔离的测试环境
- 安装sqlite3依赖包支持SQLite数据库操作
### 3. 数据模型字段不匹配
**问题描述：** 测试用例中使用的字段名与实际User模型定义不一致。
**解决方案：**
- 更新测试用例，使用正确的字段名：
- `nickname`（用户昵称，必填）
- `phone`（手机号码）
- `password_hash`（密码哈希值）
- `user_type`（用户类型）
### 4. 认证控制器密码验证缺失
**问题描述：** AuthController中的登录逻辑跳过了密码验证，导致测试无法正常验证登录功能。
**解决方案：**
- 在AuthController中添加简单的密码验证逻辑
- 修复JWT token和响应数据中的用户名字段，使用`nickname`替代`name`
## 技术实现细节
### 测试数据库配置
创建了独立的测试数据库配置文件：
```javascript
// tests/test-database.js
const { Sequelize } = require('sequelize');
const testSequelize = new Sequelize({
dialect: 'sqlite',
storage: ':memory:',
logging: false
});
module.exports = testSequelize;
```
### 测试环境重构
重构了集成测试文件，使用独立的测试数据库和模型定义：
- 直接在测试文件中定义User模型，避免依赖主应用的数据库配置
- 使用`testSequelize.sync({ force: true })`确保测试数据库表结构正确
- 在测试结束后正确关闭数据库连接
## 测试结果
### 修复前
- 测试套件：1个失败
- 测试用例：12个失败
- 主要错误：SequelizeConnectionRefusedError
### 修复后
- 测试套件：1个失败
- 测试用例：1个通过，11个失败
- 主要问题：API响应格式不匹配（缺少success字段）
## 当前状态
集成测试环境已成功修复，测试可以正常连接数据库并执行。剩余的测试失败主要是由于API响应格式与测试期望不匹配，这属于业务逻辑层面的问题，不是环境配置问题。
## 后续建议
1. **API响应格式标准化**：统一所有API接口的响应格式，确保包含`success`、`message`、`data`等标准字段
2. **完善密码加密**：当前使用明文密码比较，建议实现bcrypt等安全的密码加密方案
3. **扩展测试覆盖**：在环境问题解决后，可以继续完善测试用例，提高代码覆盖率
4. **持续集成**：考虑将修复后的测试集成到CI/CD流程中，确保代码质量
## 文件变更清单
### 新增文件
- `tests/test-database.js` - 测试专用数据库配置
### 修改文件
- `tests/integration/auth.test.js` - 重构测试环境和数据模型
- `src/controllers/AuthController.js` - 添加密码验证逻辑
- `tests/setup.js` - 更新测试环境配置
### 依赖更新
- 新增：`sqlite3` (开发依赖)
---
**报告生成时间：** 2024年1月20日
**修复工程师：** AI助手
**项目：** 牛商城后端系统