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

更新数据库配置为niumall，添加用户登出功能并集成axios

Browse Source
This commit is contained in:
aiotagro
2025-09-19 18:30:34 +08:00
parent 2d77e83fad
commit cec08f89e2
9 changed files with 7210 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1644
docs/API接口文档.md Normal file
View File

File diff suppressed because it is too large Load Diff

469
docs/产品需求文档.md Normal file
View File

@@ -0,0 +1,469 @@
# 活牛采购智能数字化系统 - 产品需求文档 (PRD)
## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| v1.0 | 2024-01-20 | 产品经理 | 初版PRD文档 |
| v1.1 | 2024-05-15 | 产品经理 | 更新小程序矩阵需求 |
| v2.0 | 2024-12-20 | 产品经理 | 重构文档结构，完善需求细节 |
## 1. 项目概述
### 1.1 项目背景
活牛采购行业长期存在以下核心痛点：
- **信息不透明**：采购流程中各环节信息孤岛，缺乏统一的信息管理平台
- **流程不规范**：缺乏标准化的操作流程，人为因素导致的错误率高
- **风险控制难**：质量检验、运输监控、资金结算等环节风险控制能力不足
- **效率低下**：大量手工操作，重复性工作多，整体效率有待提升
### 1.2 项目目标
**主要目标**：
- 建立标准化的活牛采购数字化管理平台
- 实现采购全流程的信息化、透明化管理
- 提升采购效率，降低操作风险
- 确保牛只质量可追溯，交易过程安全可靠
**具体目标**：
- 采购流程处理时间减少30%
- 操作错误率降低至1%以下
- 客户满意度提升至95%以上
- 系统可用性达到99.9%
### 1.3 成功标准
**业务指标**：
- 月活跃用户数 > 500人
- 订单处理成功率 > 99%
- 平均订单处理时间 < 2小时
- 用户满意度评分 > 4.5/5.0
**技术指标**：
- 系统响应时间 < 2秒
- 系统可用性 > 99.9%
- 数据准确性 > 99.9%
- 安全事故 = 0
## 2. 用户角色与用例
### 2.1 用户角色定义
| 角色名称 | 角色描述 | 主要职责 | 使用场景 |
|---------|---------|---------|---------|
| **采购人** | 活牛采购需求方 | 发起采购需求、验收确认、支付审批 | 创建订单、跟踪运输、验收支付 |
| **贸易商** | 中间贸易服务商 | 订单转发、供应商管理、资金结算 | 订单管理、供应商协调、结算处理 |
| **供应商** | 活牛供应方 | 牛只准备、装车管理、单据提供 | 接收订单、准备牛只、上传证件 |
| **司机** | 运输服务提供方 | 运输执行、状态上报、单据交接 | 运输跟踪、状态更新、异常上报 |
| **系统管理员** | 平台运营管理 | 用户管理、系统配置、数据监控 | 后台管理、系统维护、数据分析 |
### 2.2 用户权限矩阵
| 功能模块 | 采购人 | 贸易商 | 供应商 | 司机 | 管理员 |
|---------|-------|-------|-------|------|-------|
| 订单创建 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 订单查看 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 订单转发 | ❌ | ✅ | ❌ | ❌ | ✅ |
| 牛只管理 | ❌ | ❌ | ✅ | ❌ | ✅ |
| 运输跟踪 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 验收确认 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 支付处理 | ✅ | ✅ | ❌ | ❌ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ❌ | ✅ |
### 2.3 核心用例场景
**用例1：采购订单创建**
- **参与者**：采购人、贸易商
- **前置条件**：采购人已登录系统
- **主要流程**：采购人创建订单 → 贸易商审核确认 → 订单生效
- **后置条件**：订单进入待处理状态
**用例2：运输全程跟踪**
- **参与者**：司机、采购人、贸易商
- **前置条件**：订单已确认，司机已接单
- **主要流程**：司机上报位置 → 系统记录轨迹 → 相关方实时查看
- **后置条件**：运输状态实时更新
**用例3：到货验收支付**
- **参与者**：采购人、系统
- **前置条件**：牛只已到达目的地
- **主要流程**：采购人验收 → 系统计算金额 → 在线支付
- **后置条件**：交易完成，订单结束
## 3. 功能需求
### 3.1 采购计划阶段
#### 3.1.1 订单创建功能
**用户故事**：As a 采购人, I want to 创建采购订单, so that 明确采购需求并启动采购流程
**验收标准**：
```gherkin
Given 采购人已登录系统
When 采购人填写采购订单信息
And 包含牛只品种、重量范围、数量、单价、交货地点、交货时间
And 上传相关采购文件
Then 系统生成唯一订单号
And 订单状态设置为"待确认"
And 发送通知给指定贸易商
```
**详细需求**：
- 支持多种牛只品种选择（西门塔尔、安格斯、夏洛莱等）
- 重量范围可配置（如：300-400kg、400-500kg等）
- 支持批量订单创建
- 订单模板功能，快速创建相似订单
- 订单草稿保存功能
#### 3.1.2 供应商资质审核
**用户故事**：As a 贸易商, I want to 审核供应商资质, so that 确保供应商具备合规供应能力
**验收标准**：
```gherkin
Given 贸易商查看供应商信息
When 核实营业执照、动物防疫条件合格证等证件
And 检查检疫证明开具能力
And 评估供应商历史表现
Then 系统记录审核结果
And 更新供应商资质状态
And 支持证件到期提醒功能
```
### 3.2 装车前准备阶段
#### 3.2.1 车辆备案管理
**用户故事**：As a 司机, I want to 完成车辆备案, so that 确保运输车辆符合运输要求
**验收标准**：
```gherkin
Given 司机准备装车
When 上传空车过磅视频（时长≥30秒）
And 上传车辆消毒证明
And 填写车辆基本信息（车牌号、载重等）
Then 系统验证视频完整性和清晰度
And 驻场兽医在线确认消毒证明
And 车辆状态更新为"已备案"
```
#### 3.2.2 牛只核验管理
**用户故事**：As a 供应商, I want to 准备牛只核验, so that 确保牛只符合采购要求
**验收标准**：
```gherkin
Given 供应商准备装车
When 提供《动物检疫合格证明》
And 确保牛只空水空槽时间≥8小时
And 上传牛只现场照片或视频
Then 系统记录核验信息
And 支持不同品种的重量区间验证
And 生成装车准备清单
```
### 3.3 运输交付阶段
#### 3.3.1 实时运输跟踪
**用户故事**：As a 司机, I want to 实时上报运输状态, so that 让采购方及时了解运输进度
**验收标准**：
```gherkin
Given 司机在运输途中
When 系统每10分钟自动获取GPS位置
And 司机可手动上报牛只状态
And 支持视频状态上报功能
Then 系统记录完整运输轨迹
And 计算预计到达时间
And 异常情况自动告警
```
#### 3.3.2 到货验收管理
**用户故事**：As a 采购人, I want to 进行到货验收, so that 确保收到的牛只符合订单要求
**验收标准**：
```gherkin
Given 牛只到达目的地
When 采购人在2小时内完成验收
And 核对牛只数量、品种、重量
And 检查牛只健康状况
Then 系统记录验收结果
And 支持异常情况记录（死亡、受伤、重量不符等）
And 生成验收报告
```
### 3.4 结算支付阶段
#### 3.4.1 自动结算计算
**用户故事**：As a 系统, I want to 自动计算结算金额, so that 减少人工计算错误
**验收标准**：
```gherkin
Given 验收完成
When 系统获取实际上车重量和约定单价
Then 自动计算：实际重量 × 单价 - 预付款 = 尾款
And 生成详细结算清单
And 支持多种计价方式（按头计价、按重量计价）
```
#### 3.4.2 在线支付处理
**用户故事**：As a 采购人, I want to 在线支付尾款, so that 快速完成交易
**验收标准**：
```gherkin
Given 结算单已生成
When 采购人确认结算金额
And 选择支付方式（银行转账、支付宝、微信等）
Then 系统处理支付请求
And 生成支付凭证
And 更新订单状态为"已完成"
```
### 3.5 异常处理
#### 3.5.1 违约处理管理
**用户故事**：As a 系统, I want to 自动处理违约情况, so that 规范化违约处理流程
**验收标准**：
```gherkin
Given 发生违约情况（延期交货、质量不符等）
When 系统识别违约类型和责任方
Then 按合同约定计算违约金（每日合同金额0.5%）
And 生成违约处理单
And 发送通知给相关方
```
## 4. 非功能需求
### 4.1 性能要求
| 指标 | 要求 | 测试方法 |
|------|------|----------|
| 响应时间 | 页面加载 < 2秒，API响应 < 1秒 | 性能测试工具 |
| 并发用户 | 支持100+用户同时在线 | 压力测试 |
| 数据处理 | 支持10万+订单数据查询 | 数据库性能测试 |
| 文件上传 | 视频文件上传 < 30秒 | 文件上传测试 |
### 4.2 安全要求
| 安全项 | 要求 | 实现方式 |
|--------|------|----------|
| 数据传输 | HTTPS加密传输 | SSL证书配置 |
| 身份认证 | 多因素认证 | 手机验证码 + 密码 |
| 权限控制 | 基于角色的访问控制 | RBAC权限模型 |
| 数据备份 | 每日自动备份 | 数据库定时备份 |
| 操作日志 | 关键操作全记录 | 审计日志系统 |
### 4.3 可靠性要求
| 可靠性指标 | 要求 | 保障措施 |
|-----------|------|----------|
| 系统可用性 | 99.9% | 集群部署 + 负载均衡 |
| 故障恢复 | < 30分钟 | 自动故障切换 |
| 数据一致性 | 事务完整性保证 | 数据库事务控制 |
| 容灾备份 | 异地备份 | 云端数据备份 |
### 4.4 兼容性要求
| 兼容性类型 | 要求 | 支持范围 |
|-----------|------|----------|
| 浏览器兼容 | 主流浏览器支持 | Chrome、Firefox、Safari、Edge |
| 移动端兼容 | 响应式设计 | iOS、Android |
| 小程序兼容 | 微信小程序平台 | 微信小程序最新版本 |
## 5. 小程序矩阵需求
### 5.1 小程序架构设计
系统采用多小程序架构，为不同用户角色提供专属应用：
```
┌─────────────────────────────────────────────────┐
│ 小程序矩阵 │
├─────────────┬─────────────┬─────────────┬─────────────┤
│ 采购人小程序 │ 供应商小程序 │ 司机小程序 │ 内部员工小程序 │
│ (client-mp) │(supplier-mp)│ (driver-mp) │ (staff-mp) │
└─────────────┴─────────────┴─────────────┴─────────────┘
```
### 5.2 采购人小程序 (client-mp)
**核心功能需求**：
- **订单管理**：创建订单、查看订单列表、订单详情查看
- **运输跟踪**：实时查看运输位置、预计到达时间
- **验收管理**：扫码验收、异常记录、验收确认
- **支付管理**：查看结算单、在线支付、支付记录
- **供应商评价**：对供应商服务进行评价
**界面设计要求**：
- 简洁直观的订单列表，支持状态筛选
- 地图式运输轨迹展示，实时更新位置
- 扫码验收功能，快速录入验收信息
- 支付流程简化，支持多种支付方式
### 5.3 供应商小程序 (supplier-mp)
**核心功能需求**：
- **订单处理**：接收订单、确认订单、订单状态更新
- **牛只管理**：牛只信息录入、库存管理、质量记录
- **证件管理**：检疫证明上传、证件到期提醒
- **装车管理**：装车视频录制、装车清单确认
- **财务查看**：结算记录查看、收款确认
**界面设计要求**：
- 订单状态可视化展示，清晰的流程指引
- 证件上传便捷操作，支持拍照和相册选择
- 视频录制功能，支持实时录制和本地上传
- 财务数据清晰展示，支持历史记录查询
### 5.4 司机小程序 (driver-mp)
**核心功能需求**：
- **任务管理**：接收运输任务、任务状态更新
- **位置上报**：自动GPS定位、手动位置上报
- **状态记录**：牛只状态视频记录、异常情况上报
- **路线导航**：集成地图导航功能
- **单据管理**：运输单据拍照上传、电子签名
**界面设计要求**：
- 简洁的任务列表，突出当前任务
- 一键式状态上报，减少操作步骤
- 离线操作支持，网络恢复后自动同步
- 紧急情况快速处理，一键求助功能
### 5.5 内部员工小程序 (staff-mp)
**核心功能需求**：
- **全流程监控**：订单全生命周期监控
- **数据统计**：业务数据统计分析
- **用户管理**：用户信息管理、权限设置
- **系统配置**：业务参数配置、规则设置
- **异常处理**：异常订单处理、客服支持
**界面设计要求**：
- 数据驾驶舱式展示，关键指标一目了然
- 多维度统计分析，支持图表展示
- 实时监控预警，异常情况及时提醒
- 管理操作便捷，支持批量操作
## 6. 原型设计说明
### 6.1 界面设计原则
- **简洁性**：界面简洁明了，突出核心功能
- **一致性**：统一的设计语言和交互模式
- **易用性**：符合用户操作习惯，学习成本低
- **响应性**：适配不同屏幕尺寸和设备
### 6.2 关键界面元素
**管理后台界面**：
- **导航栏**：左侧菜单导航，支持收缩展开
- **数据驾驶舱**：关键业务指标可视化展示
- **列表页面**：统一的列表样式，支持搜索、筛选、分页
- **详情页面**：信息层次清晰，操作按钮明显
- **表单页面**：表单验证友好，支持自动保存
**小程序界面**：
- **底部导航**：主要功能模块快速切换
- **卡片式设计**：信息模块化展示
- **浮动按钮**：常用操作快速访问
- **状态指示**：清晰的状态标识和进度展示
### 6.3 交互流程设计
**订单创建流程**：
```
采购人登录 → 选择创建订单 → 填写订单信息 → 确认提交 →
等待贸易商确认 → 订单生效 → 通知供应商
```
**运输跟踪流程**：
```
司机接单 → 车辆备案 → 开始运输 → 实时位置上报 →
异常情况处理 → 到达目的地 → 验收确认
```
**支付结算流程**：
```
验收完成 → 系统自动计算 → 生成结算单 → 采购人确认 →
选择支付方式 → 完成支付 → 生成凭证
```
## 7. 范围界定
### 7.1 本版本包含功能
**核心业务功能**：
- ✅ 活牛采购全流程数字化管理
- ✅ 四类用户角色完整功能支持
- ✅ 双订单流程（采购人→贸易商→供应商）
- ✅ 运输实时跟踪和状态上报
- ✅ 自动化结算和支付处理
- ✅ 小程序矩阵（4个专业小程序）
- ✅ 管理后台系统
- ✅ 企业官网展示
**技术功能**：
- ✅ 用户认证和权限管理
- ✅ 文件上传和存储
- ✅ 实时通信和消息推送
- ✅ 数据统计和报表
- ✅ 系统监控和日志
### 7.2 本版本不包含功能
**业务功能限制**：
- ❌ 牛只养殖管理功能
- ❌ 销售端功能模块
- ❌ 复杂的财务核算功能
- ❌ 多语言支持
- ❌ 第三方ERP系统集成
- ❌ 高级数据分析和AI功能
**技术功能限制**：
- ❌ 移动端原生APP
- ❌ 区块链技术应用
- ❌ 大数据分析平台
- ❌ 人工智能算法
## 8. 风险评估与应对
### 8.1 技术风险
| 风险项 | 风险等级 | 影响 | 应对措施 |
|--------|---------|------|----------|
| 数据库性能瓶颈 | 中 | 系统响应慢 | 数据库优化、读写分离 |
| 第三方服务依赖 | 中 | 功能不可用 | 备用方案、服务降级 |
| 安全漏洞 | 高 | 数据泄露 | 安全审计、渗透测试 |
### 8.2 业务风险
| 风险项 | 风险等级 | 影响 | 应对措施 |
|--------|---------|------|----------|
| 用户接受度低 | 中 | 推广困难 | 用户培训、功能优化 |
| 行业政策变化 | 高 | 合规问题 | 政策跟踪、快速调整 |
| 竞争对手压力 | 中 | 市场份额 | 差异化竞争、功能创新 |
## 9. 项目里程碑
### 9.1 开发计划
| 阶段 | 时间 | 主要交付物 | 负责人 |
|------|------|-----------|--------|
| 需求分析 | Week 1-2 | PRD文档、原型设计 | 产品经理 |
| 技术设计 | Week 3-4 | 技术方案、数据库设计 | 架构师 |
| 后端开发 | Week 5-8 | API接口、核心功能 | 后端团队 |
| 前端开发 | Week 6-10 | 管理后台、小程序 | 前端团队 |
| 测试验收 | Week 11-12 | 测试报告、Bug修复 | 测试团队 |
| 部署上线 | Week 13-14 | 生产环境部署 | 运维团队 |
### 9.2 版本发布计划
- **v1.0 MVP版本**：核心功能实现，支持基本业务流程
- **v1.1 优化版本**：性能优化，用户体验改进
- **v2.0 增强版本**：高级功能，数据分析能力
- **v3.0 智能版本**：AI功能，智能推荐
---
**文档维护**：本文档由产品团队负责维护，每月更新一次，重大变更及时更新。
**最后更新时间**：2024年12月20日

1046
docs/小程序开发指南.md Normal file
View File

File diff suppressed because it is too large Load Diff

349
docs/开发指南.md Normal file
View File

@@ -0,0 +1,349 @@
# 开发指南
## 版本历史
| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|----------|
| 1.0.0 | 2024-01-20 | 开发团队 | 初始版本 |
## 1. 开发环境搭建
### 1.1 系统要求
- **操作系统**: macOS 10.15+, Ubuntu 18.04+, Windows 10+
- **Node.js**: 16.x 或更高版本
- **MySQL**: 8.0 或更高版本
- **Redis**: 6.0 或更高版本
- **Git**: 2.20 或更高版本
### 1.2 开发工具推荐
- **IDE**: VS Code, WebStorm
- **数据库管理**: Navicat, DBeaver
- **API测试**: Postman, Insomnia
- **版本控制**: Git, SourceTree
### 1.3 环境安装
#### 1.3.1 Node.js 环境
```bash
# 使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```
#### 1.3.2 数据库安装
```bash
# MySQL 安装 (macOS)
brew install mysql
brew services start mysql
# Redis 安装 (macOS)
brew install redis
brew services start redis
```
#### 1.3.3 项目克隆与依赖安装
```bash
# 克隆项目
git clone https://github.com/your-org/niumall.git
cd niumall
# 安装后端依赖
cd backend
npm install
# 安装前端管理系统依赖
cd ../admin-system
npm install
# 安装小程序依赖
cd ../mini_program/staff-mp
npm install
```
## 2. 项目结构
```
niumall/
├── backend/ # 后端服务 (Node.js)
│ ├── src/
│ │ ├── controllers/ # 控制器
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑
│ │ ├── middleware/ # 中间件
│ │ ├── routes/ # 路由配置
│ │ └── utils/ # 工具函数
│ └── package.json
├── admin-system/ # 前端管理系统 (Vue3 + TypeScript)
│ ├── src/
│ │ ├── views/ # 页面组件
│ │ ├── api/ # API服务
│ │ ├── utils/ # 工具函数
│ │ └── stores/ # 状态管理
│ └── package.json
├── mini_program/ # 小程序矩阵
│ ├── staff-mp/ # 员工小程序
│ ├── driver-mp/ # 司机小程序
│ ├── supplier-mp/ # 供应商小程序
│ └── client-mp/ # 客户小程序
├── go-backend/ # Go后端服务 (备选)
├── fastapi-backend/ # FastAPI后端服务 (备选)
├── website/ # 官方网站
└── docs/ # 项目文档
```
## 3. 开发流程
### 3.1 分支管理
采用 Git Flow 工作流：
- **main**: 生产环境分支
- **develop**: 开发环境分支
- **feature/***: 功能开发分支
- **hotfix/***: 紧急修复分支
- **release/***: 发布准备分支
### 3.2 开发步骤
1. **创建功能分支**
```bash
git checkout develop
git pull origin develop
git checkout -b feature/订单管理优化
```
2. **开发与提交**
```bash
# 开发完成后提交
git add .
git commit -m "feat: 添加订单状态自动更新功能"
```
3. **代码审查**
```bash
# 推送到远程分支
git push origin feature/订单管理优化
# 在 GitHub/GitLab 创建 Pull Request
```
### 3.3 提交规范
使用 Conventional Commits 规范：
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动
## 4. 本地开发
### 4.1 环境配置
#### 4.1.1 后端配置
创建 `backend/.env` 文件：
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=niumall
DB_USER=root
DB_PASSWORD=your_password
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
# JWT配置
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=7d
# 微信小程序配置
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```
#### 4.1.2 前端配置
创建 `admin-system/.env.development` 文件：
```env
# API基础URL
VITE_API_BASE_URL=http://localhost:3000/api
VITE_UPLOAD_URL=http://localhost:3000/uploads
```
### 4.2 启动服务
#### 4.2.1 启动后端服务
```bash
cd backend
npm run dev
# 服务启动在 http://localhost:3000
```
#### 4.2.2 启动前端管理系统
```bash
cd admin-system
npm run dev
# 服务启动在 http://localhost:5173
```
#### 4.2.3 启动小程序开发
```bash
cd mini_program/staff-mp
# 使用微信开发者工具打开项目目录
```
### 4.3 数据库初始化
```bash
# 创建数据库
mysql -u root -p
CREATE DATABASE niumall CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 运行初始化脚本
cd backend
node init_database.js
```
## 5. 代码规范
### 5.1 JavaScript/TypeScript 规范
- 使用 ESLint + Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 TypeScript 进行类型检查
### 5.2 Vue 组件规范
- 使用 Composition API
- 组件命名采用 PascalCase
- Props 定义使用 TypeScript 接口
### 5.3 API 接口规范
- 遵循 RESTful 设计原则
- 统一的响应格式
- 完善的错误处理
## 6. 测试指南
### 6.1 单元测试
```bash
# 运行后端单元测试
cd backend
npm test
# 运行前端单元测试
cd admin-system
npm run test:unit
```
### 6.2 API测试
使用 Postman 或 Insomnia 进行 API 测试，测试文件位于 `docs/api/` 目录。
## 7. 调试技巧
### 7.1 后端调试
- 使用 VS Code 调试配置
- 查看日志文件
- 使用 Postman 测试 API
### 7.2 前端调试
- 使用浏览器开发者工具
- Vue DevTools 扩展
- 网络请求监控
### 7.3 小程序调试
- 微信开发者工具调试器
- 真机调试
- 性能监控
## 8. 常见问题
### 8.1 环境问题
**Q: 数据库连接失败**
```bash
# 检查数据库服务状态
brew services list | grep mysql
# 重启数据库服务
brew services restart mysql
```
**Q: 端口被占用**
```bash
# 查看端口占用
lsof -i :3000
# 杀死进程
kill -9 <PID>
```
### 8.2 开发问题
**Q: 热重载不生效**
```bash
# 清除缓存重启
rm -rf node_modules/.cache
npm run dev
```
**Q: 小程序真机预览失败**
- 检查网络连接
- 确认域名配置
- 查看控制台错误信息
## 9. 性能优化
### 9.1 后端优化
- 数据库查询优化
- Redis 缓存策略
- 异步处理优化
### 9.2 前端优化
- 代码分割
- 懒加载
- 图片优化
### 9.3 小程序优化
- 分包加载
- 图片压缩
- 请求合并
## 10. 联系信息
- **技术支持**: tech-support@company.com
- **开发团队**: dev-team@company.com
- **文档维护**: docs@company.com
## 相关文档
- [项目总览](./项目总览.md)
- [产品需求文档](./产品需求文档.md)
- [系统架构设计](./系统架构设计.md)
- [API接口文档](./API接口文档.md)
- [数据库设计](./数据库设计.md)
- [部署运维指南](./部署运维指南.md)
- [测试指南](./测试指南.md)

1059
docs/数据库设计.md Normal file
View File

File diff suppressed because it is too large Load Diff

1181
docs/测试指南.md Normal file
View File

File diff suppressed because it is too large Load Diff

904
docs/系统架构设计.md Normal file
View File

@@ -0,0 +1,904 @@
# 活牛采购智能数字化系统 - 系统架构设计
## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目架构整理 |
| v2.0 | 2024-12-20 | 系统架构师 | 重构架构文档，完善技术细节 |
## 1. 整体架构概览
### 1.1 系统架构图
```mermaid
graph TB
subgraph "用户层"
A[采购人] --> B[小程序矩阵]
C[供应商] --> B
D[司机] --> B
E[管理员] --> F[管理后台]
G[访客] --> H[企业官网]
end
subgraph "应用层"
B[小程序矩阵<br/>Uni-app] --> I[API网关]
F[管理后台<br/>Vue 3] --> I
H[企业官网<br/>HTML5] --> J[静态资源]
end
subgraph "服务层"
I[API网关<br/>Nginx] --> K[认证服务]
I --> L[业务服务集群]
K[认证服务<br/>JWT] --> L
L[业务服务<br/>Express.js] --> M[数据访问层]
end
subgraph "数据层"
M[数据访问层<br/>Sequelize ORM] --> N[MySQL主库]
M --> O[MySQL从库]
M --> P[Redis缓存]
M --> Q[文件存储<br/>MinIO/OSS]
end
subgraph "基础设施层"
R[容器化部署<br/>Docker] --> S[负载均衡<br/>Nginx]
S --> T[应用服务器]
T --> U[数据库服务器]
V[监控告警<br/>Prometheus] --> W[日志收集<br/>ELK]
end
```
### 1.2 架构分层说明
| 层级 | 职责 | 技术栈 | 说明 |
|------|------|--------|------|
| **用户层** | 用户交互界面 | 浏览器、微信小程序 | 提供多端用户访问入口 |
| **应用层** | 前端应用 | Vue 3、Uni-app、HTML5 | 负责用户界面展示和交互 |
| **服务层** | 业务逻辑处理 | Express.js、JWT | 处理业务逻辑和数据处理 |
| **数据层** | 数据存储管理 | MySQL、Redis、MinIO | 负责数据持久化和缓存 |
| **基础设施层** | 运行环境支撑 | Docker、Nginx、监控 | 提供系统运行基础环境 |
## 2. 技术栈选型
### 2.1 前端技术栈
| 技术/框架 | 版本 | 用途 | 选型理由 |
|-----------|------|------|----------|
| **Vue 3** | 3.4+ | 管理后台框架 | 组合式API、更好的TypeScript支持、性能优化 |
| **TypeScript** | 5.0+ | 类型系统 | 静态类型检查、提高代码质量和可维护性 |
| **Element Plus** | 2.4+ | UI组件库 | Vue 3生态、组件丰富、文档完善 |
| **Vite** | 5.0+ | 构建工具 | 极速开发体验、优化的构建性能 |
| **Pinia** | 2.1+ | 状态管理 | Vue 3官方推荐、API简洁、性能优异 |
| **Vue Router** | 4.2+ | 路由管理 | Vue 3官方路由、支持组合式API |
| **Uni-app** | 3.8+ | 小程序框架 | 一套代码多端运行、降低开发维护成本 |
### 2.2 后端技术栈
| 技术/框架 | 版本 | 用途 | 选型理由 |
|-----------|------|------|----------|
| **Node.js** | 18+ | 运行环境 | 高性能、生态丰富、JavaScript全栈 |
| **Express.js** | 4.18+ | Web框架 | 轻量灵活、中间件丰富、学习成本低 |
| **Sequelize** | 6.35+ | ORM框架 | 支持多种数据库、简化数据库操作 |
| **JWT** | 9.0+ | 身份认证 | 无状态认证、跨域支持 |
| **Joi** | 17.11+ | 数据验证 | 强大的数据校验能力 |
| **Multer** | 1.4+ | 文件上传 | Express文件上传中间件 |
| **Socket.io** | 4.7+ | 实时通信 | WebSocket封装、实时数据推送 |
### 2.3 数据存储技术栈
| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **MySQL** | 8.0+ | 关系型数据库 | 成熟稳定、ACID特性、适合复杂业务关系 |
| **Redis** | 7.0+ | 缓存数据库 | 高性能缓存、支持多种数据结构 |
| **MinIO** | Latest | 对象存储 | S3兼容、私有化部署、适合文件存储 |
### 2.4 基础设施技术栈
| 技术 | 版本 | 用途 | 选型理由 |
|------|------|------|----------|
| **Docker** | 24.0+ | 容器化 | 环境一致性、部署便捷 |
| **Nginx** | 1.24+ | 反向代理 | 高性能、负载均衡、静态资源服务 |
| **PM2** | 5.3+ | 进程管理 | Node.js进程管理、自动重启 |
| **Prometheus** | 2.47+ | 监控系统 | 时序数据库、强大的查询语言 |
| **Grafana** | 10.2+ | 监控面板 | 可视化监控、丰富的图表 |
## 3. 系统模块设计
### 3.1 核心业务模块
```mermaid
graph LR
A[用户管理模块] --> B[订单管理模块]
B --> C[供应商管理模块]
C --> D[运输管理模块]
D --> E[质量管理模块]
E --> F[财务管理模块]
F --> G[通知管理模块]
H[权限管理] --> A
I[文件管理] --> C
I --> D
I --> E
J[日志管理] --> B
J --> D
J --> F
```
#### 3.1.1 用户管理模块 (User Management)
**职责**：
- 用户注册、登录、注销
- 用户信息管理和维护
- 角色权限分配和控制
- 用户状态管理
**核心功能**：
```javascript
/**
* 用户管理服务
*/
class UserService {
// 用户注册
async register(userData) { }
// 用户登录
async login(phone, password) { }
// 获取用户信息
async getUserInfo(userId) { }
// 更新用户信息
async updateUser(userId, updateData) { }
// 用户权限验证
async checkPermission(userId, permission) { }
}
```
**数据模型**：
- User（用户基本信息）
- Role（角色定义）
- Permission（权限定义）
- UserRole（用户角色关联）
#### 3.1.2 订单管理模块 (Order Management)
**职责**：
- 订单创建、查询、更新
- 订单状态流转管理
- 订单审核和确认
- 订单统计和分析
**核心功能**：
```javascript
/**
* 订单管理服务
*/
class OrderService {
// 创建订单
async createOrder(orderData) { }
// 查询订单列表
async getOrderList(filters, pagination) { }
// 获取订单详情
async getOrderDetail(orderId) { }
// 更新订单状态
async updateOrderStatus(orderId, status) { }
// 订单统计
async getOrderStatistics(dateRange) { }
}
```
**状态流转**：
```
待确认 → 已确认 → 准备中 → 运输中 → 已到达 → 已验收 → 已完成
```
#### 3.1.3 运输管理模块 (Transport Management)
**职责**：
- 运输任务分配和管理
- 实时位置跟踪
- 运输状态监控
- 异常情况处理
**核心功能**：
```javascript
/**
* 运输管理服务
*/
class TransportService {
// 创建运输任务
async createTransportTask(taskData) { }
// 更新位置信息
async updateLocation(taskId, locationData) { }
// 获取运输轨迹
async getTransportTrack(taskId) { }
// 异常情况上报
async reportException(taskId, exceptionData) { }
}
```
### 3.2 前端模块结构
#### 3.2.1 管理后台模块结构
```
admin-system/src/
├── components/ # 公共组件
│ ├── Layout/ # 布局组件
│ ├── Charts/ # 图表组件
│ ├── Forms/ # 表单组件
│ └── Tables/ # 表格组件
├── views/ # 页面组件
│ ├── dashboard/ # 数据驾驶舱
│ ├── order/ # 订单管理
│ ├── user/ # 用户管理
│ ├── transport/ # 运输管理
│ ├── finance/ # 财务管理
│ └── system/ # 系统管理
├── stores/ # 状态管理
│ ├── user.ts # 用户状态
│ ├── order.ts # 订单状态
│ └── app.ts # 应用状态
├── api/ # API接口
│ ├── user.ts # 用户接口
│ ├── order.ts # 订单接口
│ └── transport.ts # 运输接口
├── utils/ # 工具函数
│ ├── request.ts # HTTP请求封装
│ ├── auth.ts # 认证工具
│ └── common.ts # 通用工具
└── types/ # TypeScript类型定义
├── user.ts # 用户类型
├── order.ts # 订单类型
└── api.ts # API类型
```
#### 3.2.2 小程序模块结构
```
mini_program/
├── client-mp/ # 采购人小程序
│ ├── pages/
│ │ ├── index/ # 首页
│ │ ├── order/ # 订单管理
│ │ ├── transport/ # 运输跟踪
│ │ └── profile/ # 个人中心
│ ├── components/ # 组件
│ ├── utils/ # 工具函数
│ └── api/ # 接口调用
├── supplier-mp/ # 供应商小程序
├── driver-mp/ # 司机小程序
└── staff-mp/ # 内部员工小程序
```
## 4. 数据库设计
### 4.1 数据库架构
```mermaid
graph TB
A[应用服务] --> B[读写分离中间件]
B --> C[MySQL主库<br/>写操作]
B --> D[MySQL从库1<br/>读操作]
B --> E[MySQL从库2<br/>读操作]
A --> F[Redis集群<br/>缓存层]
F --> G[Redis主节点]
F --> H[Redis从节点]
A --> I[文件存储<br/>MinIO集群]
```
### 4.2 核心数据表设计
#### 4.2.1 用户相关表
```sql
-- 用户表
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
phone VARCHAR(20) UNIQUE NOT NULL COMMENT '手机号',
password VARCHAR(255) NOT NULL COMMENT '密码',
name VARCHAR(100) NOT NULL COMMENT '姓名',
role ENUM('client', 'supplier', 'driver', 'trader', 'admin') NOT NULL COMMENT '角色',
status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '状态',
avatar VARCHAR(500) COMMENT '头像URL',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_phone (phone),
INDEX idx_role (role),
INDEX idx_status (status)
) COMMENT '用户表';
-- 用户详情表
CREATE TABLE user_profiles (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
user_id BIGINT NOT NULL,
company_name VARCHAR(200) COMMENT '公司名称',
business_license VARCHAR(500) COMMENT '营业执照',
contact_address TEXT COMMENT '联系地址',
emergency_contact VARCHAR(100) COMMENT '紧急联系人',
emergency_phone VARCHAR(20) COMMENT '紧急联系电话',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
INDEX idx_user_id (user_id)
) COMMENT '用户详情表';
```
#### 4.2.2 订单相关表
```sql
-- 订单表
CREATE TABLE orders (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
order_no VARCHAR(50) UNIQUE NOT NULL COMMENT '订单号',
client_id BIGINT NOT NULL COMMENT '采购人ID',
trader_id BIGINT COMMENT '贸易商ID',
supplier_id BIGINT COMMENT '供应商ID',
cattle_type VARCHAR(50) NOT NULL COMMENT '牛只品种',
quantity INT NOT NULL COMMENT '数量',
weight_range VARCHAR(50) COMMENT '重量范围',
unit_price DECIMAL(10,2) NOT NULL COMMENT '单价',
total_amount DECIMAL(12,2) NOT NULL COMMENT '总金额',
delivery_address TEXT NOT NULL COMMENT '交货地址',
delivery_time DATETIME COMMENT '要求交货时间',
status ENUM('pending', 'confirmed', 'preparing', 'transporting', 'arrived', 'accepted', 'completed', 'cancelled') DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (client_id) REFERENCES users(id),
FOREIGN KEY (trader_id) REFERENCES users(id),
FOREIGN KEY (supplier_id) REFERENCES users(id),
INDEX idx_order_no (order_no),
INDEX idx_client_id (client_id),
INDEX idx_status (status),
INDEX idx_created_at (created_at)
) COMMENT '订单表';
-- 订单状态变更记录表
CREATE TABLE order_status_logs (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
order_id BIGINT NOT NULL,
from_status VARCHAR(50) COMMENT '原状态',
to_status VARCHAR(50) NOT NULL COMMENT '新状态',
operator_id BIGINT COMMENT '操作人ID',
remark TEXT COMMENT '备注',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE,
FOREIGN KEY (operator_id) REFERENCES users(id),
INDEX idx_order_id (order_id),
INDEX idx_created_at (created_at)
) COMMENT '订单状态变更记录表';
```
#### 4.2.3 运输相关表
```sql
-- 运输任务表
CREATE TABLE transport_tasks (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
task_no VARCHAR(50) UNIQUE NOT NULL COMMENT '任务号',
order_id BIGINT NOT NULL COMMENT '订单ID',
driver_id BIGINT NOT NULL COMMENT '司机ID',
vehicle_no VARCHAR(20) NOT NULL COMMENT '车牌号',
start_location VARCHAR(200) COMMENT '起始地点',
end_location VARCHAR(200) COMMENT '目的地点',
start_time DATETIME COMMENT '开始时间',
end_time DATETIME COMMENT '结束时间',
status ENUM('assigned', 'started', 'transporting', 'arrived', 'completed') DEFAULT 'assigned',
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 users(id),
INDEX idx_task_no (task_no),
INDEX idx_order_id (order_id),
INDEX idx_driver_id (driver_id),
INDEX idx_status (status)
) COMMENT '运输任务表';
-- 位置跟踪表
CREATE TABLE location_tracks (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
task_id BIGINT NOT NULL COMMENT '任务ID',
latitude DECIMAL(10,6) NOT NULL COMMENT '纬度',
longitude DECIMAL(10,6) NOT NULL COMMENT '经度',
address VARCHAR(500) COMMENT '地址',
speed DECIMAL(5,2) COMMENT '速度',
direction DECIMAL(5,2) COMMENT '方向',
recorded_at TIMESTAMP NOT NULL COMMENT '记录时间',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (task_id) REFERENCES transport_tasks(id) ON DELETE CASCADE,
INDEX idx_task_id (task_id),
INDEX idx_recorded_at (recorded_at)
) COMMENT '位置跟踪表';
```
### 4.3 数据库优化策略
#### 4.3.1 索引优化
- **主键索引**：所有表使用自增主键
- **唯一索引**：手机号、订单号等唯一字段
- **复合索引**：常用查询条件组合
- **覆盖索引**：减少回表查询
#### 4.3.2 分区策略
```sql
-- 按时间分区的位置跟踪表
CREATE TABLE location_tracks (
-- 字段定义...
) PARTITION BY RANGE (YEAR(recorded_at)) (
PARTITION p2024 VALUES LESS THAN (2025),
PARTITION p2025 VALUES LESS THAN (2026),
PARTITION p_future VALUES LESS THAN MAXVALUE
);
```
#### 4.3.3 读写分离
- **主库**：处理所有写操作和实时性要求高的读操作
- **从库**：处理统计查询、报表生成等读操作
- **中间件**：自动路由读写请求
## 5. API设计规范
### 5.1 RESTful API设计原则
#### 5.1.1 URL设计规范
```
GET /api/v1/orders # 获取订单列表
POST /api/v1/orders # 创建订单
GET /api/v1/orders/:id # 获取订单详情
PUT /api/v1/orders/:id # 更新订单
DELETE /api/v1/orders/:id # 删除订单
```
#### 5.1.2 HTTP状态码规范
| 状态码 | 含义 | 使用场景 |
|--------|------|----------|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未认证 |
| 403 | Forbidden | 无权限 |
| 404 | Not Found | 资源不存在 |
| 500 | Internal Server Error | 服务器内部错误 |
#### 5.1.3 响应格式规范
```json
{
"code": 200,
"message": "success",
"data": {
// 响应数据
},
"timestamp": "2024-12-20T10:00:00Z"
}
```
### 5.2 核心API接口设计
#### 5.2.1 用户认证接口
```javascript
// 用户登录
POST /api/v1/auth/login
{
"phone": "13800138000",
"password": "password123"
}
// 响应
{
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"name": "张三",
"role": "client",
"avatar": "https://example.com/avatar.jpg"
}
}
}
```
#### 5.2.2 订单管理接口
```javascript
// 创建订单
POST /api/v1/orders
{
"cattleType": "西门塔尔",
"quantity": 50,
"weightRange": "400-500kg",
"unitPrice": 28.5,
"deliveryAddress": "北京市朝阳区...",
"deliveryTime": "2024-12-25T10:00:00Z"
}
// 获取订单列表
GET /api/v1/orders?page=1&limit=20&status=pending
// 响应
{
"code": 200,
"message": "success",
"data": {
"list": [...],
"total": 100,
"page": 1,
"limit": 20
}
}
```
## 6. 安全架构设计
### 6.1 认证与授权
#### 6.1.1 JWT认证机制
```javascript
/**
* JWT Token结构
*/
{
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"userId": 1,
"role": "client",
"permissions": ["order:read", "order:create"],
"exp": 1640995200,
"iat": 1640908800
}
}
```
#### 6.1.2 权限控制模型
```javascript
/**
* RBAC权限控制
*/
const permissions = {
'client': ['order:create', 'order:read', 'transport:read'],
'supplier': ['order:read', 'order:update', 'cattle:manage'],
'driver': ['transport:read', 'transport:update', 'location:report'],
'admin': ['*'] // 所有权限
};
```
### 6.2 数据安全
#### 6.2.1 数据加密
- **传输加密**：HTTPS/TLS 1.3
- **存储加密**：敏感数据AES-256加密
- **密码加密**：bcrypt哈希算法
#### 6.2.2 输入验证
```javascript
/**
* 数据验证中间件
*/
const orderValidation = Joi.object({
cattleType: Joi.string().required(),
quantity: Joi.number().integer().min(1).max(1000).required(),
unitPrice: Joi.number().positive().precision(2).required(),
deliveryAddress: Joi.string().min(10).max(500).required()
});
```
### 6.3 安全防护
#### 6.3.1 防护措施
- **SQL注入防护**：参数化查询、ORM框架
- **XSS防护**：输入过滤、输出编码
- **CSRF防护**：CSRF Token验证
- **请求限流**：基于IP和用户的限流策略
#### 6.3.2 监控告警
```javascript
/**
* 安全事件监控
*/
const securityEvents = {
'login_failure': '登录失败次数过多',
'permission_denied': '权限访问被拒绝',
'sql_injection': 'SQL注入攻击尝试',
'unusual_activity': '异常活动检测'
};
```
## 7. 性能优化策略
### 7.1 前端性能优化
#### 7.1.1 代码分割与懒加载
```javascript
// 路由懒加载
const routes = [
{
path: '/order',
component: () => import('@/views/order/OrderList.vue')
}
];
// 组件懒加载
const LazyComponent = defineAsyncComponent(() =>
import('@/components/HeavyComponent.vue')
);
```
#### 7.1.2 资源优化
- **图片优化**：WebP格式、响应式图片
- **代码压缩**：Gzip/Brotli压缩
- **CDN加速**：静态资源CDN分发
- **缓存策略**：浏览器缓存、Service Worker
### 7.2 后端性能优化
#### 7.2.1 数据库优化
```javascript
/**
* 查询优化示例
*/
// 使用索引优化查询
const orders = await Order.findAll({
where: {
status: 'pending',
created_at: {
[Op.gte]: new Date('2024-01-01')
}
},
include: [{
model: User,
attributes: ['id', 'name'] // 只查询需要的字段
}],
limit: 20,
offset: (page - 1) * 20
});
```
#### 7.2.2 缓存策略
```javascript
/**
* Redis缓存策略
*/
class CacheService {
// 用户信息缓存（30分钟）
async getUserInfo(userId) {
const cacheKey = `user:${userId}`;
let user = await redis.get(cacheKey);
if (!user) {
user = await User.findByPk(userId);
await redis.setex(cacheKey, 1800, JSON.stringify(user));
}
return JSON.parse(user);
}
// 订单列表缓存（5分钟）
async getOrderList(filters) {
const cacheKey = `orders:${JSON.stringify(filters)}`;
let orders = await redis.get(cacheKey);
if (!orders) {
orders = await Order.findAll(filters);
await redis.setex(cacheKey, 300, JSON.stringify(orders));
}
return JSON.parse(orders);
}
}
```
### 7.3 系统性能监控
#### 7.3.1 关键性能指标
| 指标 | 目标值 | 监控方式 |
|------|--------|----------|
| 页面加载时间 | < 2秒 | 前端性能监控 |
| API响应时间 | < 1秒 | APM监控 |
| 数据库查询时间 | < 100ms | 慢查询日志 |
| 系统可用性 | > 99.9% | 健康检查 |
#### 7.3.2 性能监控工具
- **前端监控**：Web Vitals、Performance API
- **后端监控**：Prometheus + Grafana
- **数据库监控**：MySQL Performance Schema
- **日志分析**：ELK Stack
## 8. 部署架构
### 8.1 容器化部署
#### 8.1.1 Docker容器设计
```dockerfile
# Node.js应用容器
FROM node:18-alpine
WORKDIR /app
# 复制依赖文件
COPY package*.json ./
RUN npm ci --only=production
# 复制应用代码
COPY . .
# 暴露端口
EXPOSE 3000
# 启动应用
CMD ["npm", "start"]
```
#### 8.1.2 Docker Compose编排
```yaml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- DB_HOST=mysql
- REDIS_HOST=redis
depends_on:
- mysql
- redis
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
MYSQL_DATABASE: ${DB_NAME}
volumes:
- mysql_data:/var/lib/mysql
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/nginx/ssl
volumes:
mysql_data:
redis_data:
```
### 8.2 生产环境架构
```mermaid
graph TB
A[负载均衡器<br/>Nginx] --> B[Web服务器1<br/>Node.js]
A --> C[Web服务器2<br/>Node.js]
A --> D[Web服务器3<br/>Node.js]
B --> E[MySQL主库]
C --> E
D --> E
B --> F[MySQL从库1]
C --> F
D --> F
B --> G[Redis集群]
C --> G
D --> G
H[文件存储<br/>MinIO] --> I[对象存储]
J[监控系统<br/>Prometheus] --> K[告警系统<br/>AlertManager]
K --> L[通知渠道<br/>邮件/短信/钉钉]
```
### 8.3 CI/CD流水线
#### 8.3.1 自动化部署流程
```yaml
# GitHub Actions配置
name: Deploy to Production
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci
- run: npm test
- run: npm run lint
build:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: docker build -t niumall:${{ github.sha }} .
- name: Push to registry
run: docker push niumall:${{ github.sha }}
deploy:
needs: build
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: |
ssh user@server "docker pull niumall:${{ github.sha }}"
ssh user@server "docker-compose up -d"
```
## 9. 扩展性设计
### 9.1 水平扩展策略
#### 9.1.1 应用层扩展
- **无状态设计**：应用服务器无状态，支持水平扩展
- **负载均衡**：Nginx负载均衡，支持多实例部署
- **会话管理**：Redis集中式会话存储
#### 9.1.2 数据层扩展
- **读写分离**：主从复制，读写分离
- **分库分表**：按业务模块或时间分片
- **缓存集群**：Redis集群，提高缓存容量
### 9.2 微服务演进路径
#### 9.2.1 服务拆分策略
```
单体应用 → 模块化应用 → 微服务架构
Phase 1: 模块化重构
- 按业务领域拆分模块
- 统一数据访问层
- 服务接口标准化
Phase 2: 服务化改造
- 独立部署单元
- 服务间通信机制
- 配置中心建设
Phase 3: 微服务架构
- 服务注册发现
- 分布式链路追踪
- 熔断降级机制
```
#### 9.2.2 技术栈演进
| 阶段 | 架构模式 | 技术栈 | 复杂度 |
|------|---------|--------|--------|
| 当前 | 单体应用 | Express.js + MySQL | 低 |
| 中期 | 模块化应用 | Express.js + 微服务 | 中 |
| 长期 | 微服务架构 | Spring Cloud + K8s | 高 |
---
**文档维护**：本文档由架构团队负责维护，重大架构变更时及时更新。
**最后更新时间**：2024年12月20日

434
docs/部署运维指南.md Normal file
View File

@@ -0,0 +1,434 @@
# 活牛采购智能数字化系统 - 部署运维指南
## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| v1.0 | 2024-12-20 | 运维团队 | 初版部署运维指南 |
## 1. 环境要求
### 1.1 硬件要求
#### 生产环境最低配置
| 组件 | CPU | 内存 | 存储 | 网络 |
|------|-----|------|------|------|
| Web服务器 | 4核 | 8GB | 100GB SSD | 1Gbps |
| 应用服务器 | 8核 | 16GB | 200GB SSD | 1Gbps |
| 数据库服务器 | 8核 | 32GB | 500GB SSD | 1Gbps |
| Redis缓存 | 4核 | 8GB | 50GB SSD | 1Gbps |
| 文件存储 | 4核 | 8GB | 2TB HDD | 1Gbps |
#### 推荐配置
| 组件 | CPU | 内存 | 存储 | 网络 |
|------|-----|------|------|------|
| Web服务器 | 8核 | 16GB | 200GB SSD | 10Gbps |
| 应用服务器 | 16核 | 32GB | 500GB SSD | 10Gbps |
| 数据库服务器 | 16核 | 64GB | 1TB SSD | 10Gbps |
| Redis缓存 | 8核 | 16GB | 100GB SSD | 10Gbps |
| 文件存储 | 8核 | 16GB | 5TB SSD | 10Gbps |
### 1.2 软件要求
#### 操作系统
- **推荐**: Ubuntu 20.04 LTS / CentOS 8 / RHEL 8
- **最低**: Ubuntu 18.04 LTS / CentOS 7
#### 基础软件
```bash
# 必需软件版本
Node.js >= 18.0.0
npm >= 8.0.0
MySQL >= 8.0
Redis >= 6.0
Nginx >= 1.18
Docker >= 20.10
Docker Compose >= 2.0
```
## 2. 快速部署
### 2.1 一键部署脚本
```bash
#!/bin/bash
# quick_deploy.sh - 活牛采购系统一键部署脚本
set -e
echo "开始部署活牛采购智能数字化系统..."
# 检查系统
if [[ "$OSTYPE" != "linux-gnu"* ]]; then
echo "错误: 仅支持Linux系统"
exit 1
fi
# 更新系统
sudo apt update && sudo apt upgrade -y
# 安装基础依赖
sudo apt install -y curl wget git vim htop tree unzip
# 安装Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
# 安装Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.12.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# 创建应用目录
sudo mkdir -p /opt/niumall
sudo chown -R $USER:$USER /opt/niumall
# 克隆代码
cd /opt/niumall
git clone https://github.com/your-org/niumall.git .
# 启动服务
docker-compose up -d
echo "部署完成！"
echo "API服务: http://localhost:3000"
echo "管理后台: http://localhost"
```
### 2.2 Docker Compose配置
```yaml
# docker-compose.yml
version: '3.8'
services:
# MySQL数据库
mysql:
image: mysql:8.0
container_name: niumall-mysql
restart: unless-stopped
environment:
MYSQL_ROOT_PASSWORD: root_password
MYSQL_DATABASE: niumall
MYSQL_USER: niumall_user
MYSQL_PASSWORD: user_password
volumes:
- mysql_data:/var/lib/mysql
ports:
- "3306:3306"
networks:
- niumall-network
# Redis缓存
redis:
image: redis:7-alpine
container_name: niumall-redis
restart: unless-stopped
command: redis-server --requirepass redis_password
volumes:
- redis_data:/data
ports:
- "6379:6379"
networks:
- niumall-network
# 后端API服务
api:
build:
context: ./backend
dockerfile: Dockerfile
container_name: niumall-api
restart: unless-stopped
environment:
NODE_ENV: production
DB_HOST: mysql
REDIS_HOST: redis
ports:
- "3000:3000"
networks:
- niumall-network
depends_on:
- mysql
- redis
# 管理后台
admin:
build:
context: ./admin-system
dockerfile: Dockerfile
container_name: niumall-admin
restart: unless-stopped
ports:
- "80:80"
networks:
- niumall-network
depends_on:
- api
volumes:
mysql_data:
redis_data:
networks:
niumall-network:
driver: bridge
```
## 3. 监控与维护
### 3.1 健康检查脚本
```bash
#!/bin/bash
# health_check.sh
echo "=== 系统健康检查 $(date) ==="
# 检查服务状态
services=("mysql" "redis" "api" "admin")
for service in "${services[@]}"; do
if docker ps | grep -q "niumall-$service"; then
echo "$service: ✓ 运行中"
else
echo "$service: ✗ 已停止"
fi
done
# 检查API健康状态
if curl -f -s http://localhost:3000/health > /dev/null; then
echo "API服务: ✓ 健康"
else
echo "API服务: ✗ 异常"
fi
# 检查系统资源
echo "CPU使用率: $(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)"
echo "内存使用率: $(free -m | awk 'NR==2{printf "%.2f%%\n", $3*100/$2}')"
echo "磁盘使用率: $(df -h | awk '$NF=="/"{printf "%s\n", $5}')"
echo "=== 检查完成 ==="
```
### 3.2 备份脚本
```bash
#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup"
mkdir -p $BACKUP_DIR
# 数据库备份
echo "开始数据库备份..."
docker exec niumall-mysql mysqldump -u root -proot_password niumall > $BACKUP_DIR/niumall_$DATE.sql
gzip $BACKUP_DIR/niumall_$DATE.sql
# 删除7天前的备份
find $BACKUP_DIR -name "niumall_*.sql.gz" -mtime +7 -delete
echo "备份完成: niumall_$DATE.sql.gz"
```
### 3.3 日志查看
```bash
# 查看所有服务日志
docker-compose logs
# 查看特定服务日志
docker-compose logs api
docker-compose logs mysql
# 实时查看日志
docker-compose logs -f api
```
## 4. 故障排除
### 4.1 常见问题
#### 服务无法启动
```bash
# 检查容器状态
docker-compose ps
# 查看错误日志
docker-compose logs [service_name]
# 重启服务
docker-compose restart [service_name]
```
#### 数据库连接失败
```bash
# 检查MySQL容器
docker exec -it niumall-mysql mysql -u root -p
# 检查网络连接
docker network ls
docker network inspect niumall_niumall-network
```
#### 端口冲突
```bash
# 检查端口占用
sudo netstat -tulpn | grep :3000
sudo netstat -tulpn | grep :3306
# 修改docker-compose.yml中的端口映射
```
### 4.2 紧急恢复
```bash
#!/bin/bash
# emergency_recovery.sh
echo "开始紧急恢复..."
# 停止所有服务
docker-compose down
# 清理容器和网络
docker system prune -f
# 重新启动服务
docker-compose up -d
# 等待服务启动
sleep 30
# 健康检查
./health_check.sh
echo "紧急恢复完成"
```
## 5. 性能优化
### 5.1 数据库优化
```sql
-- 查看慢查询
SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';
-- 分析表
ANALYZE TABLE orders, users, transport_tasks;
-- 优化表
OPTIMIZE TABLE orders, users, transport_tasks;
```
### 5.2 缓存优化
```bash
# Redis内存使用情况
docker exec niumall-redis redis-cli info memory
# 清理过期键
docker exec niumall-redis redis-cli --scan --pattern "*" | xargs docker exec niumall-redis redis-cli del
```
## 6. 安全配置
### 6.1 防火墙设置
```bash
# 安装ufw
sudo apt install ufw
# 基本规则
sudo ufw default deny incoming
sudo ufw default allow outgoing
# 允许必要端口
sudo ufw allow ssh
sudo ufw allow 80
sudo ufw allow 443
# 启用防火墙
sudo ufw enable
```
### 6.2 SSL证书
```bash
# 安装Certbot
sudo apt install certbot
# 获取证书
sudo certbot certonly --standalone -d api.niumall.com -d admin.niumall.com
# 自动续期
echo "0 12 * * * /usr/bin/certbot renew --quiet" | sudo crontab -
```
## 7. 维护计划
### 7.1 定时任务
```bash
# 编辑crontab
crontab -e
# 添加定时任务
# 每天凌晨2点备份数据库
0 2 * * * /opt/niumall/scripts/backup.sh
# 每小时检查系统健康状态
0 * * * * /opt/niumall/scripts/health_check.sh >> /var/log/niumall/health.log
# 每周日凌晨清理日志
0 0 * * 0 docker system prune -f
```
### 7.2 更新流程
```bash
#!/bin/bash
# update.sh
echo "开始更新系统..."
# 拉取最新代码
git pull origin main
# 重新构建镜像
docker-compose build
# 滚动更新
docker-compose up -d --no-deps api
docker-compose up -d --no-deps admin
# 健康检查
sleep 30
./health_check.sh
echo "更新完成"
```
## 8. 联系信息
### 8.1 技术支持
- **运维团队**: ops@niumall.com
- **开发团队**: dev@niumall.com
- **紧急联系**: +86-138-0000-0000
### 8.2 相关文档
- [项目总览](./项目总览.md)
- [产品需求文档](./产品需求文档.md)
- [系统架构设计](./系统架构设计.md)
- [数据库设计](./数据库设计.md)
- [API接口文档](./API接口文档.md)
---
**注意**: 请根据实际环境调整配置参数，确保系统安全稳定运行。

124
docs/项目总览.md Normal file
View File

@@ -0,0 +1,124 @@
# 活牛采购智能数字化系统 - 项目总览
## 📋 项目简介
活牛采购智能数字化系统是一个专为活牛采购行业打造的全流程数字化管理平台。系统通过标准化采购流程、实时运输跟踪、智能结算支付等功能，解决传统活牛采购中信息不透明、流程不规范、风险控制难等核心痛点。
## 🎯 核心价值
- **流程标准化**：建立统一的采购流程规范，减少人为错误
- **信息透明化**：实时跟踪采购全流程，提升信息透明度
- **风险可控化**：通过数字化手段，降低采购风险
- **效率最大化**：自动化处理重复性工作，提升整体效率
## 🏗️ 系统架构
### 多端应用矩阵
- **管理后台**：基于Vue 3的Web管理系统，面向内部管理人员
- **小程序矩阵**：基于Uni-app的跨平台小程序，包含4个专业小程序
- 采购人小程序：订单管理、验收支付
- 供应商小程序：订单处理、牛只管理
- 司机小程序：运输跟踪、状态上报
- 内部员工小程序：全流程监控管理
- **企业官网**：基于HTML5的企业展示网站
### 技术栈
- **前端**：Vue 3 + TypeScript + Element Plus + Uni-app
- **后端**：Node.js + Express.js + MySQL + Redis
- **部署**：Docker + Nginx + PM2
## 📚 文档导航
### 📋 产品文档
- [产品需求文档 (PRD)](./产品需求文档.md) - 详细的产品功能需求和用户故事
- [用户角色与权限](./用户角色与权限.md) - 系统用户角色定义和权限矩阵
### 🏗️ 技术文档
- [系统架构设计](./系统架构设计.md) - 整体技术架构和模块划分
- [数据库设计](./数据库设计.md) - 数据表结构和关系设计
- [API接口文档](./API接口文档.md) - 后端接口规范和调用说明
- [前端开发规范](./前端开发规范.md) - 前端代码规范和开发指南
### 🚀 部署运维
- [环境配置指南](./环境配置指南.md) - 开发和生产环境配置
- [部署运维手册](./部署运维手册.md) - 系统部署和运维操作指南
- [监控告警方案](./监控告警方案.md) - 系统监控和故障处理
### 🧪 测试文档
- [测试计划](./测试计划.md) - 测试策略和测试用例
- [质量保证规范](./质量保证规范.md) - 代码质量和测试规范
### 📊 项目管理
- [开发计划](./开发计划.md) - 项目里程碑和开发进度
- [版本发布记录](./版本发布记录.md) - 系统版本更新记录
## 🚀 快速开始
### 环境要求
- Node.js 16+
- MySQL 5.7+
- Redis 6.0+
### 本地开发
```bash
# 1. 克隆项目
git clone [项目地址]
# 2. 安装依赖
cd niumall
npm install
# 3. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env 文件，配置数据库连接等信息
# 4. 初始化数据库
cd backend
npm run init:db
# 5. 启动后端服务
npm run dev
# 6. 启动前端服务
cd admin-system
npm run dev
```
### 项目结构
```
niumall/
├── admin-system/ # 管理后台 (Vue 3)
├── backend/ # 后端服务 (Node.js)
├── mini_program/ # 小程序矩阵 (Uni-app)
├── website/ # 企业官网 (HTML5)
├── docs/ # 项目文档
└── README.md # 项目说明
```
## 👥 团队协作
### 开发流程
1. **需求分析** → 产品经理编写PRD文档
2. **技术设计** → 架构师设计技术方案
3. **开发实现** → 开发团队按模块开发
4. **测试验收** → QA团队执行测试计划
5. **部署上线** → 运维团队执行部署方案
### 代码规范
- 遵循ESLint和Prettier配置
- 提交信息遵循Conventional Commits规范
- 代码审查通过后方可合并
## 📞 联系方式
- **项目负责人**：[姓名] - [邮箱]
- **技术负责人**：[姓名] - [邮箱]
- **产品负责人**：[姓名] - [邮箱]
## 📄 许可证
本项目采用 [MIT License](../LICENSE) 许可证。
---
*最后更新时间：2024年12月*