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

docs/系统详细设计文档.md

@@ -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辅助决策系统
+- 区块链追溯系统集成
+- 物联网设备接入
+- 国际业务支持与多语言功能