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

更新技术实施方案和PRD文档版本历史

Browse Source
This commit is contained in:
aiotagro
2025-09-11 19:55:21 +08:00
parent 5853953f79
commit 9aecda204b
17 changed files with 3058 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
docs/开发计划.md Normal file
View File

@@ -0,0 +1,251 @@
# 活牛采购智能数字化系统 - 开发计划
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目状态制定开发计划 |
## 1. 项目概述
基于当前项目状态，活牛采购智能数字化系统已完成基础架构搭建和部分功能的模拟实现。为确保系统按时、高质量交付，特制定本开发计划。
### 1.1 项目目标
- 完成活牛采购全流程的数字化管理
- 实现四类用户角色（采购人、贸易商、供应商、司机）的完整功能
- 确保系统性能、安全和可靠性满足需求
- 实现与第三方服务（支付、地图等）的集成
### 1.2 项目范围
根据PRD，本次开发覆盖以下范围：
- 采购订单管理
- 牛只核验管理
- 运输跟踪管理
- 到货验收管理
- 结算支付管理
- 异常处理
## 2. 开发团队构成
| 角色 | 人数 | 职责描述 |
|------|------|----------|
| 项目经理 | 1 | 整体项目管理、进度控制、风险管理 |
| 产品经理 | 1 | 需求分析、产品设计、用户体验 |
| 系统架构师 | 1 | 技术架构设计、技术选型、系统优化 |
| 前端开发工程师 | 2 | 管理后台、小程序开发、用户界面实现 |
| 后端开发工程师 | 2 | API接口开发、业务逻辑实现、数据库设计 |
| 测试工程师 | 1 | 功能测试、性能测试、自动化测试 |
| UI/UX设计师 | 1 | 界面设计、交互设计、用户体验优化 |
## 3. 开发方法论
采用敏捷开发方法论，通过迭代开发快速交付可用功能，持续优化和改进产品。
### 3.1 迭代周期
- 每2周为一个迭代周期
- 每个迭代包含需求分析、设计、开发、测试和评审环节
- 迭代结束后进行成果演示和回顾
### 3.2 开发流程
1. 需求确认与细化
2. 技术方案设计
3. 任务分解与分配
4. 代码开发与单元测试
5. 集成测试与系统测试
6. 产品评审与验收
7. 部署与上线
## 4. 任务分解与工时估算
### 4.1 总体开发阶段
| 阶段 | 时间范围 | 主要任务 | 参与角色 |
|------|----------|----------|----------|
| 需求分析与设计 | 第1周 | 需求细化、系统设计、数据库设计 | 产品经理、架构师、开发工程师 |
| 核心功能开发 | 第2-6周 | 用户管理、订单管理、供应商管理、运输管理、质量管理、财务管理 | 前端、后端开发工程师 |
| 第三方集成 | 第7-8周 | 支付接口、地图服务、文件存储服务集成 | 后端开发工程师 |
| 测试与优化 | 第9-10周 | 功能测试、性能测试、安全测试、Bug修复、性能优化 | 测试工程师、开发工程师 |
| 文档完善与培训 | 第11周 | 用户手册、开发文档完善、系统培训 | 产品经理、架构师、开发工程师 |
| 上线与运维 | 第12周 | 系统部署、上线、运维监控 | 架构师、开发工程师、运维人员 |
### 4.2 详细任务分解与工时估算
#### 4.2.1 后端开发任务
| 任务ID | 任务名称 | 任务描述 | 依赖 | 工时(人日) | 负责人 |
|--------|----------|----------|------|------------|--------|
| BE-001 | 数据库模型完善 | 根据详细设计文档完善所有数据表模型 | 系统详细设计文档 | 5 | 后端开发1 |
| BE-002 | 用户管理API完善 | 完善用户CRUD、认证、权限控制功能 | BE-001 | 4 | 后端开发1 |
| BE-003 | 订单管理API开发 | 实现订单创建、查询、更新、状态流转等功能 | BE-001 | 6 | 后端开发2 |
| BE-004 | 供应商管理API开发 | 实现供应商信息管理、资质审核等功能 | BE-001 | 4 | 后端开发2 |
| BE-005 | 运输管理API开发 | 实现运输跟踪、状态上报等功能 | BE-001 | 5 | 后端开发1 |
| BE-006 | 财务管理API开发 | 实现结算、支付等功能 | BE-001 | 6 | 后端开发2 |
| BE-007 | 质量管理API开发 | 实现牛只质量检验、报告管理等功能 | BE-001 | 4 | 后端开发1 |
| BE-008 | 文件上传与管理 | 实现视频、图片、文档等文件的上传和管理 | BE-001 | 3 | 后端开发2 |
| BE-009 | 支付接口集成 | 集成第三方支付平台接口 | BE-006 | 4 | 后端开发1 |
| BE-010 | 地图服务集成 | 集成地图API，实现位置跟踪功能 | BE-005 | 3 | 后端开发2 |
| BE-011 | 数据验证与异常处理 | 完善请求数据验证和异常处理机制 | 所有API开发 | 3 | 后端开发1 |
| BE-012 | API文档生成 | 生成Swagger API文档 | 所有API开发 | 2 | 后端开发2 |
| BE-013 | 性能优化 | 系统性能调优，包括缓存策略、查询优化等 | 所有API开发 | 3 | 架构师、后端开发 |
| BE-014 | 安全加固 | 系统安全加固，包括权限控制、数据加密等 | 所有API开发 | 3 | 架构师、后端开发 |
#### 4.2.2 前端开发任务
| 任务ID | 任务名称 | 任务描述 | 依赖 | 工时(人日) | 负责人 |
|--------|----------|----------|------|------------|--------|
| FE-001 | 项目结构优化 | 优化前端项目结构，完善组件化设计 | 系统详细设计文档 | 2 | 前端开发1 |
| FE-002 | 登录与用户管理模块 | 实现用户登录、注册、个人信息管理等功能 | BE-002 | 5 | 前端开发1 |
| FE-003 | 订单管理模块 | 实现订单列表、详情、创建、编辑等功能 | BE-003 | 6 | 前端开发2 |
| FE-004 | 供应商管理模块 | 实现供应商列表、详情、创建、编辑等功能 | BE-004 | 4 | 前端开发1 |
| FE-005 | 运输管理模块 | 实现运输跟踪、状态查看等功能，集成地图展示 | BE-005, BE-010 | 7 | 前端开发2 |
| FE-006 | 财务管理模块 | 实现结算列表、支付管理等功能 | BE-006 | 5 | 前端开发1 |
| FE-007 | 质量管理模块 | 实现质量检验记录、报告查看等功能 | BE-007 | 4 | 前端开发2 |
| FE-008 | 文件上传组件 | 实现文件上传、预览等功能 | BE-008 | 3 | 前端开发1 |
| FE-009 | 数据可视化 | 实现数据驾驶舱、报表等数据可视化功能 | BE-003, BE-006 | 6 | 前端开发2 |
| FE-010 | 响应式布局优化 | 优化移动端和桌面端布局，确保良好的用户体验 | 所有前端模块 | 3 | 前端开发1 |
| FE-011 | 性能优化 | 前端性能优化，包括懒加载、资源压缩等 | 所有前端模块 | 3 | 前端开发2 |
| FE-012 | 单元测试与集成测试 | 编写前端单元测试和集成测试用例 | 所有前端模块 | 4 | 测试工程师、前端开发 |
#### 4.2.3 测试与部署任务
| 任务ID | 任务名称 | 任务描述 | 依赖 | 工时(人日) | 负责人 |
|--------|----------|----------|------|------------|--------|
| TEST-001 | 测试计划制定 | 制定详细的测试计划和测试用例 | 系统详细设计文档 | 2 | 测试工程师 |
| TEST-002 | 功能测试 | 对系统所有功能进行测试，发现并报告Bug | 所有开发任务 | 8 | 测试工程师 |
| TEST-003 | 性能测试 | 测试系统在高并发下的性能表现 | 所有开发任务 | 3 | 测试工程师 |
| TEST-004 | 安全测试 | 测试系统的安全性，包括权限控制、数据加密等 | 所有开发任务 | 3 | 测试工程师 |
| TEST-005 | Bug修复 | 跟踪并修复测试过程中发现的Bug | TEST-002, TEST-003, TEST-004 | 5 | 开发工程师 |
| DEPLOY-001 | 部署环境准备 | 准备生产环境服务器、数据库等 | 系统架构文档 | 2 | 运维人员 |
| DEPLOY-002 | 系统部署 | 部署前端和后端应用到生产环境 | TEST-005 | 2 | 开发工程师、运维人员 |
| DEPLOY-003 | 监控与告警配置 | 配置系统监控和告警机制 | DEPLOY-002 | 2 | 运维人员 |
## 5. 里程碑与交付物
### 5.1 关键里程碑
| 里程碑名称 | 达成标准 | 时间点 |
|------------|----------|--------|
| 需求分析完成 | 需求文档、系统设计文档、数据库设计文档评审通过 | 第1周结束 |
| 核心功能开发完成 | 用户、订单、供应商、运输、财务、质量管理功能开发完成 | 第6周结束 |
| 第三方集成完成 | 支付、地图、文件存储等第三方服务集成完成 | 第8周结束 |
| 系统测试完成 | 功能测试、性能测试、安全测试通过，Bug修复完成 | 第10周结束 |
| 文档完善与培训完成 | 用户手册、开发文档完善，系统培训完成 | 第11周结束 |
| 系统上线 | 系统正式上线运行 | 第12周结束 |
### 5.2 主要交付物
| 交付物名称 | 交付时间 | 说明 |
|------------|----------|------|
| 需求分析文档 | 第1周 | 详细的需求分析和用户故事 |
| 系统架构文档 | 第1周 | 系统整体架构设计 |
| 系统详细设计文档 | 第1周 | 数据库设计、API设计、核心业务流程设计 |
| 后端源代码 | 第8周 | 完整的后端API实现 |
| 前端源代码 | 第8周 | 完整的前端应用实现 |
| 测试报告 | 第10周 | 功能、性能、安全测试报告 |
| 用户操作手册 | 第11周 | 详细的用户使用指南 |
| 系统部署文档 | 第11周 | 系统部署和运维指南 |
| 上线总结报告 | 第12周 | 系统上线总结和后续优化建议 |
## 6. 风险管理
### 6.1 风险识别与评估
| 风险ID | 风险描述 | 可能性 | 影响程度 | 应对策略 |
|--------|----------|--------|----------|----------|
| RISK-001 | 需求变更 | 高 | 中 | 建立变更控制流程，严格评估变更影响 |
| RISK-002 | 技术难点无法按时解决 | 中 | 高 | 提前识别技术难点，组织技术攻关 |
| RISK-003 | 第三方服务集成问题 | 中 | 中 | 提前调研第三方服务，预留集成时间 |
| RISK-004 | 人员变动 | 低 | 高 | 加强知识共享，建立备份机制 |
| RISK-005 | 性能问题 | 中 | 中 | 提前进行性能测试，优化系统架构 |
| RISK-006 | 安全漏洞 | 中 | 高 | 定期安全审计，及时修复漏洞 |
### 6.2 应急计划
- 预留10%的缓冲时间应对不可预见的问题
- 建立快速响应机制，及时解决突发问题
- 定期召开项目风险管理会议，评估和更新风险状态
## 7. 沟通与协作机制
### 7.1 会议制度
- 每日站立会议：15分钟，同步进度和问题
- 每周迭代计划会议：1小时，规划下周工作
- 每周迭代评审会议：1小时，演示迭代成果
- 每两周项目进度会议：1.5小时，向 stakeholders 汇报项目进度
### 7.2 工具与平台
- 项目管理：Jira/禅道
- 代码托管：Git
- 文档管理：Confluence
- 沟通协作：企业微信/钉钉
- CI/CD：Jenkins/GitLab CI
### 7.3 代码规范与版本控制
- 统一代码规范，使用ESLint/Prettier等工具进行代码质量控制
- 采用Git Flow工作流，确保代码版本管理规范
- 定期进行代码审查，确保代码质量
## 8. 质量保证计划
### 8.1 质量目标
- 功能测试覆盖率：100%
- 单元测试覆盖率：≥80%
- 系统可用性：99.9%
- 系统响应时间：<2秒
- 并发用户数：支持100+用户同时在线
- 缺陷密度：<0.5个/功能点
### 8.2 质量控制措施
- 严格的代码审查流程
- 自动化测试（单元测试、集成测试、端到端测试）
- 定期的性能测试和安全测试
- 完善的文档管理和知识共享机制
- 用户验收测试
## 9. 后续优化与维护计划
### 9.1 系统优化方向
- 性能优化：持续监控和优化系统性能
- 用户体验优化：根据用户反馈持续改进界面和交互
- 功能扩展：根据业务需求扩展系统功能
### 9.2 维护计划
- 建立运维监控体系，及时发现和解决问题
- 定期进行系统备份和安全检查
- 提供技术支持和问题排查服务
- 定期更新系统，修复漏洞和优化功能
## 10. 预算估算
### 10.1 开发成本
| 类别 | 预计成本(万元) | 说明 |
|------|---------------|------|
| 人力成本 | 60-80 | 开发团队人员工资 |
| 第三方服务 | 5-10 | 支付接口、地图服务、云存储等 |
| 硬件设施 | 3-5 | 服务器、网络设备等 |
| 软件工具 | 2-3 | 项目管理工具、协作工具等 |
| 培训与文档 | 1-2 | 用户培训、文档制作等 |
| 其他 | 2-3 | 差旅、沟通等 |
| **总计** | **73-103** | |
### 10.2 维护成本
| 类别 | 预计年成本(万元) | 说明 |
|------|----------------|------|
| 运维人力 | 15-20 | 运维人员工资 |
| 第三方服务 | 3-5 | 持续的第三方服务费用 |
| 硬件维护 | 1-2 | 服务器维护、升级等 |
| 系统优化 | 5-8 | 系统功能优化、性能提升等 |
| **总计** | **24-35** | |
## 11. 附录
### 11.1 术语表
- PRD: Product Requirements Document，产品需求文档
- API: Application Programming Interface，应用程序编程接口
- JWT: JSON Web Token，一种用于安全传输信息的标准
- ORM: Object-Relational Mapping，对象关系映射
- CI/CD: Continuous Integration/Continuous Deployment，持续集成/持续部署
- RBAC: Role-Based Access Control，基于角色的访问控制
### 11.2 参考文档
- 《活牛采购智能数字化系统PRD》
- 《系统架构文档》
- 《系统详细设计文档》
- 《开发环境配置指南》
- 《测试规范文档》
- 《部署和运维文档》

6
docs/技术实施方案.md
View File

@@ -1,5 +1,11 @@
# 活牛采购智能数字化系统 - 技术实施方案
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-01-20 | 技术团队 | 初版技术方案 |
| v1.1 | 2024-05-15 | 系统架构师 | 更新与系统架构和详细设计文档保持一致 |
## 1. 技术架构
### 1.1 系统架构

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

@@ -4,6 +4,7 @@
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-01-20 | 产品经理 | 初版PRD |
| v1.1 | 2024-05-15 | 系统架构师 | 更新与系统架构和详细设计文档保持一致 |
## 1. 项目概述

266
docs/系统架构文档.md Normal file
View File

@@ -0,0 +1,266 @@
# 活牛采购智能数字化系统 - 系统架构文档
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目架构整理更新 |
## 1. 整体架构
### 1.1 系统架构图
```mermaid
flowchart TD
subgraph "前端层"
A[管理后台
Vue 3 + TypeScript] --> |API调用| G
B[小程序
Uni-app] --> |API调用| G
C[官网
HTML5 + Bootstrap] --> |静态展示| D
end
subgraph "后端层"
G[API Gateway
认证与路由] --> H
H[Express.js服务集群
业务逻辑处理] --> I
end
subgraph "数据层"
I[MySQL数据库
业务数据存储] --> J
J[Redis缓存
性能优化] --> K
K[文件存储
视频与证件] --> L
end
subgraph "辅助服务"
L[消息通知
流程提醒] --> M
M[实时通信
WebSocket] --> N
N[第三方服务
支付、地图等] --> O
end
```
### 1.2 系统分层说明
- **前端层**：包含管理后台、小程序和官网三部分，分别面向不同用户群体提供服务
- **后端层**：采用Express.js作为主要框架，提供统一的API接口和业务逻辑处理
- **数据层**：使用MySQL存储业务数据，Redis提高性能，文件存储服务管理视频和证件
- **辅助服务**：包括消息通知、实时通信和第三方服务集成
## 2. 技术栈选型
### 2.1 核心技术栈
| 类别 | 技术/框架 | 版本 | 用途 | 选型理由 |
|------|-----------|------|------|----------|
| 前端框架 | Vue 3 | 3.x | 管理后台开发 | 生态成熟，TypeScript支持好，性能优秀 |
| 编程语言 | TypeScript | 4.x+ | 前端开发 | 静态类型检查，提高代码质量和可维护性 |
| UI组件库 | Element Plus | 2.x | 管理后台UI | Vue 3官方推荐，组件丰富，文档完善 |
| 构建工具 | Vite | 4.x | 前端构建 | 极速开发体验，优化构建性能 |
| 状态管理 | Pinia | 2.x | 前端状态管理 | Vue 3官方推荐，API简洁，性能优异 |
| 后端框架 | Express.js | 4.x | 后端服务 | 轻量灵活，生态丰富，学习成本低 |
| 数据库 | MySQL | 5.7 | 关系型数据存储 | 成熟稳定，适合复杂业务关系存储 |
| ORM框架 | Sequelize | 6.x | 数据库访问 | 支持多种数据库，简化数据库操作 |
| 缓存 | Redis | 6.x | 性能优化 | 提升系统响应速度，减轻数据库压力 |
| 小程序框架 | Uni-app | 3.x | 跨平台小程序 | 一套代码多端运行，降低开发维护成本 |
### 2.2 工具与中间件
| 类别 | 工具/中间件 | 用途 |
|------|------------|------|
| API文档 | Swagger | 自动生成API文档 |
| 身份验证 | JWT | 用户身份认证 |
| 安全加固 | Helmet | 增强Express应用安全性 |
| 跨域处理 | CORS | 解决跨域请求问题 |
| 请求限流 | Express-rate-limit | 防止API滥用 |
| 日志管理 | Morgan | HTTP请求日志记录 |
| 数据验证 | Joi | API请求数据校验 |
| 环境配置 | dotenv | 环境变量管理 |
## 3. 系统模块划分
### 3.1 核心业务模块
| 模块名称 | 主要职责 | 文件位置 | 备注 |
|---------|---------|---------|------|
| 用户管理 | 用户CRUD、权限控制、认证登录 | backend/routes/users.js | 已实现基础功能 |
| 订单管理 | 订单创建、查询、更新、取消 | backend/routes/orders.js | 已实现模拟数据接口 |
| 供应商管理 | 供应商信息管理、资质审核 | backend/routes/suppliers.js | 已实现模拟数据接口 |
| 运输管理 | 运输跟踪、状态上报 | backend/routes/transport.js | 待完善 |
| 财务管理 | 结算、支付、财务数据处理 | backend/routes/finance.js | 已实现模拟数据接口 |
| 质量管理 | 牛只质量检验、报告管理 | backend/routes/quality.js | 已实现模拟数据接口 |
### 3.2 前端模块结构
| 模块名称 | 功能描述 | 文件位置 |
|---------|---------|---------|
| 登录模块 | 用户认证登录 | admin-system/src/views/login/ |
| 数据驾驶舱 | 系统概览、关键指标 | admin-system/src/views/dashboard/ |
| 订单管理 | 订单列表、详情、操作 | admin-system/src/views/order/ |
| 用户管理 | 用户列表、角色权限 | admin-system/src/views/user/ |
| 供应商管理 | 供应商信息维护 | admin-system/src/views/supplier/ |
| 运输管理 | 运输状态跟踪 | admin-system/src/views/transport/ |
| 财务管理 | 财务结算管理 | admin-system/src/views/finance/ |
| 质量管理 | 质量检验记录 | admin-system/src/views/quality/ |
| 系统设置 | 系统参数配置 | admin-system/src/views/settings/ |
## 4. 数据库架构
### 4.1 主要数据表结构
| 表名 | 主要职责 | 关键字段 | 备注 |
|------|---------|---------|------|
| users | 用户信息存储 | id, username, phone, user_type, password_hash | 已实现模型定义 |
| orders | 订单信息存储 | id, orderNo, buyerId, supplierId, status, totalAmount | 已在路由中定义数据结构 |
| suppliers | 供应商信息 | id, name, code, contact, phone, address, status | 已在路由中定义数据结构 |
| settlements | 结算信息 | id, orderId, totalAmount, paymentStatus, paymentDate | 已在路由中定义数据结构 |
| quality_records | 质量检测记录 | id, orderId, inspectorName, healthStatus, qualityScore | 已在路由中定义数据结构 |
### 4.2 数据库连接配置
```javascript
// 数据库连接配置示例
const sequelize = new Sequelize({
host: process.env.DB_HOST || '129.211.213.226',
port: process.env.DB_PORT || 9527,
database: process.env.DB_NAME || 'jiebandata',
username: process.env.DB_USER || 'root',
password: process.env.DB_PASSWORD || 'aiotAiot123!',
dialect: process.env.DB_DIALECT || 'mysql',
logging: process.env.NODE_ENV === 'development' ? console.log : false,
pool: {
max: 5,
min: 0,
acquire: 30000,
idle: 10000
},
define: {
timestamps: true,
underscored: true,
freezeTableName: true
},
timezone: '+08:00'
});
```
## 5. 系统部署架构
### 5.1 开发环境部署
- **前端**：本地开发服务器，通过Vite热更新
- **后端**：本地Express.js服务器
- **数据库**：远程MySQL服务器
### 5.2 生产环境部署建议
```mermaid
flowchart TD
subgraph "负载均衡层"
A[NGINX
负载均衡] --> B
end
subgraph "应用层"
B[PM2集群
Express.js实例] --> C
C[Redis缓存
会话与数据缓存] --> D
end
subgraph "数据层"
D[MySQL主从
数据持久化] --> E
E[文件存储
OSS/MinIO] --> F
end
subgraph "监控与日志"
F[日志系统
ELK Stack] --> G
G[监控系统
Prometheus+Grafana] --> H
end
```
## 6. 接口与集成
### 6.1 API接口规范
- 所有API接口统一以`/api/`开头
- 使用RESTful风格设计
- 统一的响应格式：`{ success: boolean, message: string, data?: any }`
- 使用JWT进行身份认证
- 支持分页查询：`page`和`pageSize`参数
### 6.2 第三方服务集成
- **支付接口**：待集成主流支付平台
- **地图服务**：用于运输轨迹跟踪
- **短信服务**：用于用户验证和通知
- **文件存储**：用于视频和证件存储
## 7. 安全架构
### 7.1 身份认证与授权
- 使用JWT进行无状态身份认证
- 基于角色的访问控制(RBAC)
- 密码加密存储(bcrypt)
### 7.2 数据安全
- HTTPS加密传输
- 敏感数据加密存储
- SQL注入防护
- XSS攻击防护
- 请求限流防刷
### 7.3 日志与审计
- 关键操作日志记录
- 用户行为审计追踪
- 异常日志监控报警
## 8. 性能优化
### 8.1 前端性能优化
- 组件懒加载
- 路由懒加载
- 图片优化
- 资源缓存策略
### 8.2 后端性能优化
- Redis缓存热点数据
- 数据库索引优化
- 连接池管理
- API响应压缩
### 8.3 数据库性能优化
- 合理设计索引
- 分表分库策略(未来扩展)
- 读写分离(未来扩展)
## 9. 扩展性设计
### 9.1 微服务转型规划
当前系统采用单体架构，未来可考虑向微服务转型，主要拆分方向：
- 用户服务(user-service)
- 订单服务(order-service)
- 支付服务(payment-service)
- 运输服务(transport-service)
- 文件服务(file-service)
### 9.2 API网关规划
未来微服务架构下，引入API网关统一管理：
- 路由转发
- 身份认证
- 限流熔断
- 监控日志
## 10. 风险评估与应对
### 10.1 技术风险
- **数据库连接失败**：实现连接重试机制，支持多数据源
- **性能瓶颈**：引入缓存层，优化数据库查询，考虑读写分离
- **系统可用性**：部署多实例，实现负载均衡和故障转移
### 10.2 业务风险
- **数据一致性**：使用事务确保关键业务操作的数据一致性
- **操作错误**：增加操作日志记录，支持关键操作撤销
- **合规性**：确保系统满足行业相关法规和标准要求
### 10.3 安全风险
- **数据泄露**：实施数据加密，严格的权限控制，定期安全审计
- **DDoS攻击**：配置防火墙，实施请求限流
- **代码漏洞**：定期代码审计，使用安全扫描工具

839
docs/系统详细设计文档.md Normal file
View File

@@ -0,0 +1,839 @@
# 活牛采购智能数字化系统 - 系统详细设计文档
## 版本历史
| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| v1.0 | 2024-05-15 | 系统架构师 | 基于现有项目架构整理更新 |
## 1. 数据库详细设计
### 1.1 核心数据表ER图
```mermaid
erDiagram
USER ||--o{ ORDER : creates
USER ||--o{ ORDER : manages
USER ||--o{ ORDER : supplies
USER ||--o{ TRANSPORT_TRACK : reports
ORDER ||--o{ TRANSPORT_TRACK : has
ORDER ||--o{ QUALITY_RECORD : has
ORDER ||--o{ SETTLEMENT : has
SUPPLIER ||--o{ ORDER : provides
USER {
BIGINT id PK
STRING uuid
STRING username
STRING password_hash
STRING phone
STRING email
STRING real_name
STRING avatar_url
ENUM user_type
ENUM status
DATE last_login_at
INT login_count
}
ORDER {
BIGINT id PK
STRING orderNo
BIGINT buyerId FK
BIGINT supplierId FK
BIGINT traderId FK
STRING cattleBreed
INT cattleCount
DECIMAL expectedWeight
DECIMAL actualWeight
DECIMAL unitPrice
DECIMAL totalAmount
DECIMAL paidAmount
DECIMAL remainingAmount
ENUM status
STRING deliveryAddress
DATE expectedDeliveryDate
DATE actualDeliveryDate
STRING notes
}
SUPPLIER {
BIGINT id PK
STRING name
STRING code
STRING contact
STRING phone
STRING address
STRING businessLicense
STRING qualificationLevel
JSON certifications
JSON cattleTypes
INT capacity
DECIMAL rating
DATE cooperationStartDate
ENUM status
STRING region
}
TRANSPORT_TRACK {
BIGINT id PK
BIGINT orderId FK
BIGINT driverId FK
DECIMAL latitude
DECIMAL longitude
DECIMAL speed
DECIMAL direction
STRING cattle_status
STRING video_url
DATE timestamp
}
QUALITY_RECORD {
BIGINT id PK
BIGINT orderId FK
STRING inspectionCode
STRING inspectorName
DATE inspectionDate
STRING inspectionLocation
INT cattleCount
INT samplingCount
STRING inspectionType
STRING healthStatus
STRING quarantineCertificate
JSON vaccineRecords
JSON diseaseTests
JSON weightCheck
STRING qualityGrade
INT qualityScore
JSON issues
JSON recommendations
JSON photos
ENUM status
}
SETTLEMENT {
BIGINT id PK
BIGINT orderId FK
STRING settlementCode
DECIMAL prepaymentAmount
DECIMAL totalAmount
DECIMAL finalAmount
ENUM paymentStatus
DATE paymentDate
STRING invoiceNumber
ENUM invoiceStatus
DECIMAL taxAmount
DECIMAL actualPayment
STRING bankAccount
STRING bankName
}
```
### 1.2 核心表结构定义
#### 1.2.1 用户表 (users)
```javascript
const User = sequelize.define('User', {
id: {
type: DataTypes.BIGINT,
primaryKey: true,
autoIncrement: true
},
uuid: {
type: DataTypes.STRING(36),
allowNull: false,
unique: true,
defaultValue: DataTypes.UUIDV4
},
username: {
type: DataTypes.STRING(50),
allowNull: false,
unique: true,
validate: {
len: [2, 50]
}
},
password_hash: {
type: DataTypes.STRING(255),
allowNull: false
},
phone: {
type: DataTypes.STRING(20),
allowNull: false,
unique: true,
validate: {
is: /^1[3-9]\d{9}$/
}
},
email: {
type: DataTypes.STRING(100),
validate: {
isEmail: true
}
},
real_name: DataTypes.STRING(50),
avatar_url: DataTypes.STRING(255),
user_type: {
type: DataTypes.ENUM('client', 'supplier', 'driver', 'staff', 'admin'),
allowNull: false,
defaultValue: 'client'
},
status: {
type: DataTypes.ENUM('active', 'inactive', 'locked'),
defaultValue: 'active'
},
last_login_at: DataTypes.DATE,
login_count: {
type: DataTypes.INTEGER,
defaultValue: 0
}
}, {
tableName: 'users',
timestamps: true,
paranoid: true, // 软删除
indexes: [
{ fields: ['phone'] },
{ fields: ['user_type'] },
{ fields: ['status'] },
{ fields: ['username'] }
]
});
```
#### 1.2.2 订单表 (orders)
```javascript
const Order = sequelize.define('Order', {
id: {
type: DataTypes.BIGINT,
primaryKey: true,
autoIncrement: true
},
orderNo: {
type: DataTypes.STRING(50),
allowNull: false,
unique: true
},
buyerId: {
type: DataTypes.BIGINT,
allowNull: false
},
buyerName: {
type: DataTypes.STRING(100),
allowNull: false
},
supplierId: {
type: DataTypes.BIGINT,
allowNull: false
},
supplierName: {
type: DataTypes.STRING(100),
allowNull: false
},
traderId: DataTypes.BIGINT,
traderName: DataTypes.STRING(100),
cattleBreed: {
type: DataTypes.STRING(50),
allowNull: false
},
cattleCount: {
type: DataTypes.INTEGER,
allowNull: false
},
expectedWeight: {
type: DataTypes.DECIMAL(10, 2),
allowNull: false
},
actualWeight: DataTypes.DECIMAL(10, 2),
unitPrice: {
type: DataTypes.DECIMAL(10, 2),
allowNull: false
},
totalAmount: {
type: DataTypes.DECIMAL(15, 2),
allowNull: false
},
paidAmount: {
type: DataTypes.DECIMAL(15, 2),
defaultValue: 0
},
remainingAmount: {
type: DataTypes.DECIMAL(15, 2),
defaultValue: 0
},
status: {
type: DataTypes.ENUM('pending', 'confirmed', 'preparing', 'shipping', 'delivered', 'accepted', 'completed', 'cancelled', 'refunded'),
defaultValue: 'pending'
},
deliveryAddress: {
type: DataTypes.STRING(200),
allowNull: false
},
expectedDeliveryDate: {
type: DataTypes.DATE,
allowNull: false
},
actualDeliveryDate: DataTypes.DATE,
notes: DataTypes.TEXT
}, {
tableName: 'orders',
timestamps: true,
indexes: [
{ fields: ['orderNo'] },
{ fields: ['buyerId'] },
{ fields: ['supplierId'] },
{ fields: ['status'] },
{ fields: ['createdAt'] }
]
});
```
#### 1.2.3 供应商表 (suppliers)
```javascript
const Supplier = sequelize.define('Supplier', {
id: {
type: DataTypes.BIGINT,
primaryKey: true,
autoIncrement: true
},
name: {
type: DataTypes.STRING(100),
allowNull: false
},
code: {
type: DataTypes.STRING(20),
allowNull: false,
unique: true
},
contact: {
type: DataTypes.STRING(50),
allowNull: false
},
phone: {
type: DataTypes.STRING(20),
allowNull: false,
unique: true
},
address: {
type: DataTypes.STRING(200),
allowNull: false
},
businessLicense: DataTypes.STRING(255),
qualificationLevel: {
type: DataTypes.STRING(10),
allowNull: false
},
certifications: DataTypes.JSON,
cattleTypes: DataTypes.JSON,
capacity: DataTypes.INTEGER,
rating: DataTypes.DECIMAL(3, 2),
cooperationStartDate: DataTypes.DATE,
status: {
type: DataTypes.ENUM('active', 'inactive', 'suspended'),
defaultValue: 'active'
},
region: {
type: DataTypes.STRING(20),
allowNull: false
}
}, {
tableName: 'suppliers',
timestamps: true
});
```
#### 1.2.4 运输跟踪表 (transport_tracks)
```javascript
const TransportTrack = sequelize.define('TransportTrack', {
id: {
type: DataTypes.BIGINT,
primaryKey: true,
autoIncrement: true
},
orderId: {
type: DataTypes.BIGINT,
allowNull: false
},
driverId: {
type: DataTypes.BIGINT,
allowNull: false
},
latitude: DataTypes.DECIMAL(10, 8),
longitude: DataTypes.DECIMAL(11, 8),
speed: DataTypes.DECIMAL(5, 2),
direction: DataTypes.DECIMAL(5, 2),
cattle_status: DataTypes.STRING(50),
video_url: DataTypes.STRING(255)
}, {
tableName: 'transport_tracks',
timestamps: true
});
```
## 2. API详细设计
### 2.1 用户认证与管理API
#### 2.1.1 登录接口
- **路径**: `/api/auth/login`
- **方法**: POST
- **请求体**:
```json
{
"username": "string",
"password": "string"
}
```
- **响应体**:
```json
{
"success": true,
"message": "登录成功",
"data": {
"token": "string",
"userInfo": {
"id": 1,
"username": "string",
"real_name": "string",
"user_type": "string",
"avatar_url": "string"
}
}
}
```
- **错误码**: 401(认证失败), 403(账号锁定)
#### 2.1.2 获取用户列表
- **路径**: `/api/users`
- **方法**: GET
- **请求参数**:
- page: 页码
- pageSize: 每页条数
- keyword: 搜索关键词
- userType: 用户类型
- status: 用户状态
- **响应体**:
```json
{
"success": true,
"message": "查询成功",
"data": {
"list": [],
"total": 0,
"page": 1,
"pageSize": 10
}
}
```
- **权限**: admin/staff
### 2.2 订单管理API
#### 2.2.1 创建订单
- **路径**: `/api/orders`
- **方法**: POST
- **请求体**:
```json
{
"buyerId": 1,
"supplierId": 2,
"traderId": 3,
"cattleBreed": "西门塔尔",
"cattleCount": 50,
"expectedWeight": 25000,
"unitPrice": 28.5,
"deliveryAddress": "山东省济南市某养殖场",
"expectedDeliveryDate": "2024-01-15",
"notes": "优质西门塔尔牛"
}
```
- **响应体**:
```json
{
"success": true,
"message": "创建成功",
"data": {}
}
```
- **权限**: client/staff/admin
#### 2.2.2 获取订单列表
- **路径**: `/api/orders`
- **方法**: GET
- **请求参数**:
- page: 页码
- pageSize: 每页条数
- orderNo: 订单编号
- buyerId: 采购方ID
- supplierId: 供应商ID
- status: 订单状态
- startDate: 开始日期
- endDate: 结束日期
- **响应体**:
```json
{
"success": true,
"message": "查询成功",
"data": {
"list": [],
"total": 0,
"page": 1,
"pageSize": 10
}
}
```
- **权限**: 所有登录用户(根据用户类型过滤数据)
#### 2.2.3 更新订单状态
- **路径**: `/api/orders/{id}/status`
- **方法**: PUT
- **请求体**:
```json
{
"status": "confirmed",
"notes": "确认订单"
}
```
- **响应体**:
```json
{
"success": true,
"message": "更新成功",
"data": {}
}
```
- **权限**: 根据订单状态和用户类型控制
### 2.3 供应商管理API
#### 2.3.1 创建供应商
- **路径**: `/api/suppliers`
- **方法**: POST
- **请求体**:
```json
{
"name": "山东优质牲畜合作社",
"code": "SUP001",
"contact": "李经理",
"phone": "15888888888",
"address": "山东省济南市历城区牲畜养殖基地",
"qualificationLevel": "A",
"cattleTypes": ["肉牛", "奶牛"],
"capacity": 5000,
"region": "east"
}
```
- **响应体**:
```json
{
"success": true,
"message": "创建成功",
"data": {}
}
```
- **权限**: staff/admin
#### 2.3.2 获取供应商列表
- **路径**: `/api/suppliers`
- **方法**: GET
- **请求参数**:
- page: 页码
- pageSize: 每页条数
- keyword: 搜索关键词
- region: 地区
- qualificationLevel: 资质等级
- status: 状态
- **响应体**:
```json
{
"success": true,
"message": "查询成功",
"data": {
"list": [],
"total": 0,
"page": 1,
"pageSize": 10
}
}
```
- **权限**: staff/admin/client
### 2.4 财务管理API
#### 2.4.1 创建结算单
- **路径**: `/api/finance/settlements`
- **方法**: POST
- **请求体**:
```json
{
"orderId": 1,
"cattleCount": 50,
"unitPrice": 25000,
"paymentMethod": "bank_transfer",
"settlementDate": "2024-01-20",
"invoiceNumber": "INV001"
}
```
- **响应体**:
```json
{
"success": true,
"message": "创建成功",
"data": {}
}
```
- **权限**: staff/admin
#### 2.4.2 获取结算列表
- **路径**: `/api/finance/settlements`
- **方法**: GET
- **请求参数**:
- page: 页码
- pageSize: 每页条数
- keyword: 搜索关键词
- paymentStatus: 支付状态
- startDate: 开始日期
- endDate: 结束日期
- **响应体**:
```json
{
"success": true,
"message": "查询成功",
"data": {
"list": [],
"total": 0,
"page": 1,
"pageSize": 10
}
}
```
- **权限**: staff/admin/finance
## 3. 核心业务逻辑流程
### 3.1 订单创建与处理流程
```mermaid
sequenceDiagram
participant Buyer as 采购人
participant System as 系统
participant Trader as 贸易商
participant Supplier as 供应商
participant Driver as 司机
Buyer->>System: 创建采购订单
System-->>Buyer: 返回订单号
System->>Trader: 通知订单待确认
Trader->>System: 确认/拒绝订单
System->>Supplier: 转发订单给供应商
Supplier->>System: 接单/拒单
System->>Driver: 分配运输任务
Driver->>System: 上报运输状态
System->>Buyer: 实时更新订单状态
Driver->>System: 确认送达
Buyer->>System: 验收确认
System->>System: 自动计算结算金额
System->>Buyer: 生成结算单
Buyer->>System: 支付尾款
System->>Trader: 结算款项
System->>Supplier: 结算款项
System-->>Buyer: 订单完成通知
```
### 3.2 牛只质量核验流程
```mermaid
flowchart TD
A[开始
供应商提交牛只信息] --> B{系统检查
检疫证明}
B -- 合格 --> C[上传消毒证明
和空车过磅视频]
B -- 不合格 --> Z[结束
驳回申请]
C --> D{驻场兽医
在线确认}
D -- 确认 --> E[系统记录
核验信息]
D -- 驳回 --> Z
E --> F[进入装车环节]
F --> G[结束
核验通过]
```
### 3.3 运输状态跟踪流程
```mermaid
sequenceDiagram
participant DriverApp as 司机APP
participant System as 系统
participant Backend as 管理后台
participant BuyerApp as 采购方APP
DriverApp->>System: 定时上报位置
DriverApp->>System: 上传视频状态
System->>Backend: 实时更新运输轨迹
System->>BuyerApp: 推送运输状态
Backend->>System: 查询运输详情
BuyerApp->>System: 查询运输详情
alt 异常情况
DriverApp->>System: 上报异常
System->>Backend: 推送异常警报
System->>BuyerApp: 推送异常警报
Backend->>System: 处理异常
end
```
## 4. 前端组件设计
### 4.1 管理后台组件结构
```
├── layouts/ # 布局组件
│ └── index.vue # 主布局
├── views/ # 页面组件
│ ├── dashboard/ # 数据驾驶舱
│ ├── login/ # 登录页面
│ ├── order/ # 订单管理
│ ├── user/ # 用户管理
│ ├── supplier/ # 供应商管理
│ ├── transport/ # 运输管理
│ ├── finance/ # 财务管理
│ ├── quality/ # 质量管理
│ └── settings/ # 系统设置
├── components/ # 公共组件
│ ├── common/ # 通用组件
│ └── business/ # 业务组件
├── api/ # API调用
├── stores/ # 状态管理
└── utils/ # 工具函数
```
### 4.2 核心组件设计
#### 4.2.1 订单管理组件
- **功能**: 订单列表展示、筛选、排序、详情查看、状态更新
- **关键属性**:
- orderList: 订单数据列表
- loading: 加载状态
- searchParams: 搜索参数
- pagination: 分页信息
- **关键方法**:
- fetchOrders(): 获取订单列表
- handleStatusChange(): 处理订单状态变更
- handleSearch(): 处理搜索
- handlePagination(): 处理分页
#### 4.2.2 地图跟踪组件
- **功能**: 实时展示运输轨迹、车辆位置、牛只状态
- **关键属性**:
- orderId: 订单ID
- trackPoints: 轨迹点数据
- currentLocation: 当前位置
- cattleStatus: 牛只状态
- **关键方法**:
- initMap(): 初始化地图
- updateTrack(): 更新轨迹
- updateStatus(): 更新状态
- startTracking(): 开始跟踪
- stopTracking(): 停止跟踪
## 5. 系统配置与部署
### 5.1 环境配置
#### 5.1.1 开发环境配置 (.env.development)
```
NODE_ENV=development
PORT=3000
DB_HOST=129.211.213.226
DB_PORT=9527
DB_NAME=jiebandata
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DIALECT=mysql
JWT_SECRET=your_jwt_secret
```
#### 5.1.2 生产环境配置 (.env.production)
```
NODE_ENV=production
PORT=80
DB_HOST=129.211.213.226
DB_PORT=9527
DB_NAME=jiebandata
DB_USER=root
DB_PASSWORD=aiotAiot123!
DB_DIALECT=mysql
JWT_SECRET=your_production_jwt_secret
```
### 5.2 部署步骤
#### 5.2.1 后端部署
1. 安装Node.js环境
2. 克隆代码仓库
3. 安装依赖: `npm install`
4. 配置环境变量
5. 启动服务: `npm start` (推荐使用PM2管理)
#### 5.2.2 前端部署
1. 安装Node.js环境
2. 克隆代码仓库
3. 安装依赖: `npm install`
4. 构建项目: `npm run build`
5. 部署静态文件到Web服务器(Nginx等)
### 5.3 监控与维护
- **日志监控**: 使用日志收集工具收集和分析系统日志
- **性能监控**: 监控系统响应时间、数据库查询性能等指标
- **安全审计**: 定期检查系统安全漏洞，更新依赖包
- **数据备份**: 定期备份数据库，确保数据安全
## 6. 测试策略
### 6.1 单元测试
- 使用Jest框架进行后端API单元测试
- 重点测试业务逻辑和数据验证部分
- 覆盖率目标: ≥80%
### 6.2 集成测试
- 测试API接口之间的交互
- 测试前后端集成
- 测试数据库事务处理
### 6.3 端到端测试
- 使用Cypress或Puppeteer进行UI自动化测试
- 模拟用户真实操作流程
- 重点测试核心业务流程
### 6.4 性能测试
- 使用压测工具测试系统并发处理能力
- 测试大数据量下的系统响应性能
- 确保满足性能要求: 响应时间<2秒，支持100+并发用户
## 7. 文档与培训
### 7.1 开发文档
- 代码注释规范
- API文档(Swagger)
- 数据库设计文档
### 7.2 用户文档
- 操作手册
- 常见问题解答
- 视频教程
### 7.3 培训计划
- 管理员培训
- 操作人员培训
- 技术支持人员培训
## 8. 扩展性与未来规划
### 8.1 系统扩展性设计
- 模块化设计，便于功能扩展
- API标准化，便于集成第三方系统
- 数据库分库分表策略预留
- 微服务架构转型路径
### 8.2 未来功能规划
- 数据分析与报表功能增强
- AI辅助决策系统
- 区块链追溯系统集成
- 物联网设备接入
- 国际业务支持与多语言功能