Files

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

2025-09-11 19:55:21 +08:00

18 KiB

Raw Blame History

活牛采购智能数字化系统 - 系统详细设计文档

版本历史

版本	日期	作者	说明
v1.0	2024-05-15	系统架构师	基于现有项目架构整理更新

1. 数据库详细设计

1.1 核心数据表ER图

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)

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)

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)

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)

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

请求体:

{
  "username": "string",
  "password": "string"
}

响应体:

{
  "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: 用户状态

响应体:

{
  "success": true,
  "message": "查询成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}

权限: admin/staff

2.2 订单管理API

2.2.1 创建订单

路径: /api/orders
方法: POST

请求体:

{
  "buyerId": 1,
  "supplierId": 2,
  "traderId": 3,
  "cattleBreed": "西门塔尔",
  "cattleCount": 50,
  "expectedWeight": 25000,
  "unitPrice": 28.5,
  "deliveryAddress": "山东省济南市某养殖场",
  "expectedDeliveryDate": "2024-01-15",
  "notes": "优质西门塔尔牛"
}

响应体:

{
  "success": true,
  "message": "创建成功",
  "data": {}
}

权限: client/staff/admin

2.2.2 获取订单列表

路径: /api/orders
方法: GET
请求参数:
- page: 页码
- pageSize: 每页条数
- orderNo: 订单编号
- buyerId: 采购方ID
- supplierId: 供应商ID
- status: 订单状态
- startDate: 开始日期
- endDate: 结束日期

响应体:

{
  "success": true,
  "message": "查询成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}

权限: 所有登录用户(根据用户类型过滤数据)

2.2.3 更新订单状态

路径: /api/orders/{id}/status
方法: PUT

请求体:

{
  "status": "confirmed",
  "notes": "确认订单"
}

响应体:

{
  "success": true,
  "message": "更新成功",
  "data": {}
}

权限: 根据订单状态和用户类型控制

2.3 供应商管理API

2.3.1 创建供应商

路径: /api/suppliers
方法: POST

请求体:

{
  "name": "山东优质牲畜合作社",
  "code": "SUP001",
  "contact": "李经理",
  "phone": "15888888888",
  "address": "山东省济南市历城区牲畜养殖基地",
  "qualificationLevel": "A",
  "cattleTypes": ["肉牛", "奶牛"],
  "capacity": 5000,
  "region": "east"
}

响应体:

{
  "success": true,
  "message": "创建成功",
  "data": {}
}

权限: staff/admin

2.3.2 获取供应商列表

路径: /api/suppliers
方法: GET
请求参数:
- page: 页码
- pageSize: 每页条数
- keyword: 搜索关键词
- region: 地区
- qualificationLevel: 资质等级
- status: 状态

响应体:

{
  "success": true,
  "message": "查询成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}

权限: staff/admin/client

2.4 财务管理API

2.4.1 创建结算单

路径: /api/finance/settlements
方法: POST

请求体:

{
  "orderId": 1,
  "cattleCount": 50,
  "unitPrice": 25000,
  "paymentMethod": "bank_transfer",
  "settlementDate": "2024-01-20",
  "invoiceNumber": "INV001"
}

响应体:

{
  "success": true,
  "message": "创建成功",
  "data": {}
}

权限: staff/admin

2.4.2 获取结算列表

路径: /api/finance/settlements
方法: GET
请求参数:
- page: 页码
- pageSize: 每页条数
- keyword: 搜索关键词
- paymentStatus: 支付状态
- startDate: 开始日期
- endDate: 结束日期

响应体:

{
  "success": true,
  "message": "查询成功",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}

权限: staff/admin/finance

3. 核心业务逻辑流程

3.1 订单创建与处理流程

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 牛只质量核验流程

flowchart TD
    A[开始
供应商提交牛只信息] --> B{系统检查
检疫证明}
    B -- 合格 --> C[上传消毒证明
和空车过磅视频]
    B -- 不合格 --> Z[结束
驳回申请]
    C --> D{驻场兽医
在线确认}
    D -- 确认 --> E[系统记录
核验信息]
    D -- 驳回 --> Z
    E --> F[进入装车环节]
    F --> G[结束
核验通过]

3.3 运输状态跟踪流程

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 后端部署

安装Node.js环境
克隆代码仓库
安装依赖: npm install
配置环境变量
启动服务: npm start (推荐使用PM2管理)

5.2.2 前端部署

安装Node.js环境
克隆代码仓库
安装依赖: npm install
构建项目: npm run build
部署静态文件到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辅助决策系统
区块链追溯系统集成
物联网设备接入
国际业务支持与多语言功能

18 KiB Raw Blame History Unescape Escape

活牛采购智能数字化系统 - 系统详细设计文档

版本历史

1. 数据库详细设计

1.1 核心数据表ER图

1.2 核心表结构定义

1.2.1 用户表 (users)

1.2.2 订单表 (orders)

1.2.3 供应商表 (suppliers)

1.2.4 运输跟踪表 (transport_tracks)

2. API详细设计

2.1 用户认证与管理API

2.1.1 登录接口

2.1.2 获取用户列表

2.2 订单管理API

2.2.1 创建订单

2.2.2 获取订单列表

2.2.3 更新订单状态

2.3 供应商管理API

2.3.1 创建供应商

2.3.2 获取供应商列表

2.4 财务管理API

2.4.1 创建结算单

2.4.2 获取结算列表

3. 核心业务逻辑流程

3.1 订单创建与处理流程

3.2 牛只质量核验流程

3.3 运输状态跟踪流程

4. 前端组件设计

4.1 管理后台组件结构

4.2 核心组件设计

4.2.1 订单管理组件

4.2.2 地图跟踪组件

5. 系统配置与部署

5.1 环境配置

5.1.1 开发环境配置 (.env.development)

5.1.2 生产环境配置 (.env.production)

5.2 部署步骤

5.2.1 后端部署

5.2.2 前端部署

5.3 监控与维护

6. 测试策略

6.1 单元测试

6.2 集成测试

6.3 端到端测试

6.4 性能测试

7. 文档与培训

7.1 开发文档

7.2 用户文档

7.3 培训计划

8. 扩展性与未来规划

8.1 系统扩展性设计

8.2 未来功能规划

18 KiB

Raw Blame History