# 活牛采购智能数字化系统 - 系统详细设计文档 ## 版本历史 | 版本 | 日期 | 作者 | 说明 | |------|------|------|------| | 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辅助决策系统 - 区块链追溯系统集成 - 物联网设备接入 - 国际业务支持与多语言功能