Files

mapleaf a9209b9c75 docs(website): 重构关于页面布局和内容

- 更新页面布局，优化导航栏和面包屑导航
- 重新组织页面内容，突出公司使命和价值观
- 添加发展历程和核心团队介绍
- 更新合作伙伴展示方式
- 调整页脚内容，增加社交媒体链接

2025-09-10 20:09:58 +08:00

14 KiB

Raw Blame History

活牛采购智能数字化系统 - 后端API设计文档

1. 概述

1.1 文档目的

本文档旨在定义活牛采购智能数字化系统的后端API接口规范，为前端开发、测试和后续维护提供技术依据。

1.2 系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Mini-Program  │    │   Admin System   │    │    Website      │
│  (uni-app)      │    │  (Vue 3)         │    │  (HTML5 + Bootstrap)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                      │                      │
         └──────────┬───────────┴──────────┬───────────┘
                    │                      │
           ┌────────┴─────────┐    ┌──────┴───────┐
           │   API Gateway     │    │ 统一用户中心  │
           │  (Authentication)│    │ (Single Sign-On)
           └────────┬─────────┘    └──────┬───────┘
                    │                      │
                    └──────────┬───────────┘
                               │
                    ┌──────────┴──────────┐
                    │   微服务层           │
                    │  (NestJS Services)  │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │   统一数据库         │
                    │  (MySQL + Redis)    │
                    └─────────────────────┘

1.3 技术选型

层级	技术栈	说明
后端框架	NestJS	基于Express.js的企业级框架
数据库	MySQL 8.0 + Redis	统一业务数据 + 缓存
ORM	TypeORM	对象关系映射
API文档	Swagger	API文档自动生成
认证授权	JWT + RBAC	基于角色的访问控制
文件存储	MinIO/阿里云OSS	视频文件存储
消息队列	RabbitMQ	异步任务处理
实时通信	WebSocket	实时数据传输

2. 统一规范

2.1 响应格式

{
  "code": 200,
  "message": "成功",
  "data": {},
  "timestamp": 1643097600000
}

2.2 分页响应格式

{
  "code": 200,
  "message": "成功",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  },
  "timestamp": 1643097600000
}

2.3 错误码规范

错误码	说明	HTTP状态码
200	成功	200
400	请求参数错误	400
401	未认证	401
403	无权限	403
404	资源不存在	404
500	服务器内部错误	500

2.4 认证机制

使用JWT Token进行认证
请求头中添加Authorization: Bearer

3. API接口设计

3.1 认证模块

3.1.1 小程序用户登录

URL: POST /api/auth/mini-program/login

请求参数:

{
  "phone": "13800138000",
  "code": "123456",
  "miniProgramType": "client"
}

响应数据:

{
  "token": "jwt_token_string",
  "userInfo": {
    "id": 1,
    "username": "user123",
    "realName": "张三",
    "avatar": "https://example.com/avatar.jpg",
    "userType": "client",
    "roles": ["purchaser"]
  }
}

3.1.2 获取当前用户信息

URL: GET /api/auth/user-info
请求参数: 无

响应数据:

{
  "id": 1,
  "username": "user123",
  "realName": "张三",
  "avatar": "https://example.com/avatar.jpg",
  "userType": "client",
  "phone": "13800138000",
  "email": "user@example.com"
}

3.2 用户管理模块

3.2.1 获取用户列表

URL: GET /api/users

请求参数:

{
  "page": 1,
  "limit": 10,
  "userType": "client"
}

响应数据: 分页用户列表

3.2.2 获取用户详情

URL: GET /api/users/{id}
请求参数: 无
响应数据: 用户详细信息

3.3 订单管理模块

3.3.1 创建采购订单

URL: POST /api/orders

请求参数:

{
  "breedType": "simmental",
  "minWeight": 500,
  "maxWeight": 600,
  "totalCount": 100,
  "unitPrice": 35.5,
  "deliveryAddress": "xxx养殖场",
  "deliveryDate": "2024-01-25",
  "specialRequirements": "要求健康无病"
}

响应数据: 创建的订单信息

3.3.2 获取订单列表

URL: GET /api/orders

请求参数:

{
  "status": "pending",
  "page": 1,
  "limit": 10
}

响应数据: 分页订单列表

3.3.3 获取订单详情

URL: GET /api/orders/{id}
请求参数: 无
响应数据: 订单详细信息

3.3.4 更新订单状态

URL: PUT /api/orders/{id}/status
请求参数:
```
{
  "status": "confirmed"
}
```
响应数据: 更新后的订单信息

3.4 运输跟踪模块

3.4.1 司机上报位置信息

URL: POST /api/transport/tracks

请求参数:

{
  "orderId": 123,
  "latitude": 39.9042,
  "longitude": 116.4074,
  "speed": 80.5,
  "direction": 45.2,
  "cattleStatus": "normal",
  "temperature": 25.5,
  "humidity": 60.2,
  "videoUrl": "https://example.com/status.mp4"
}

响应数据: 上报的位置信息

3.4.2 获取订单运输轨迹

URL: GET /api/transport/orders/{orderId}/tracks
请求参数: 无
响应数据: 运输轨迹列表

3.5 文件管理模块

3.5.1 统一文件上传接口

URL: POST /api/files/upload

请求参数:

{
  "file": "文件二进制数据",
  "type": "cattle_video",
  "businessId": "order_123",
  "description": "装车过程视频"
}

响应数据:

{
  "fileId": "file_uuid",
  "url": "/uploads/filename.ext",
  "thumbnail": "/uploads/thumbnails/filename.ext.jpg",
  "size": 1024000,
  "mimeType": "video/mp4",
  "originalName": "video.mp4",
  "type": "cattle_video",
  "businessId": "order_123",
  "description": "装车过程视频"
}

3.6 支付管理模块

3.6.1 创建支付订单

URL: POST /api/payments

请求参数:

{
  "orderId": 123,
  "amount": 355000,
  "paymentType": "wechat",
  "paymentMethod": "mini_program"
}

响应数据:

{
  "paymentId": 1,
  "paymentNo": "pay_123456",
  "amount": 355000
}

3.6.2 支付回调接口

URL: POST /api/payments/{id}/callback

请求参数:

{
  "paymentId": "pay_123456",
  "status": "success",
  "paidAmount": 355000,
  "paidTime": "2024-01-25 15:30:00"
}

响应数据: 回调处理结果

3.6.3 查询支付状态

URL: GET /api/payments/{id}/status
请求参数: 无

响应数据:

{
  "paymentId": 1,
  "paymentNo": "pay_123456",
  "amount": 355000,
  "status": "paid",
  "paidAmount": 355000,
  "paidTime": "2024-01-25 15:30:00",
  "createdAt": "2024-01-25 14:00:00"
}

4. 数据库设计

4.1 用户表 (users)

字段名	类型	说明
id	BIGINT	主键
uuid	VARCHAR(36)	UUID
username	VARCHAR(50)	用户名
password_hash	VARCHAR(255)	密码哈希
phone	VARCHAR(20)	手机号
email	VARCHAR(100)	邮箱
real_name	VARCHAR(50)	真实姓名
avatar_url	VARCHAR(255)	头像URL
user_type	ENUM	用户类型(client,supplier,driver,staff,admin)
status	ENUM	状态(active,inactive,locked)
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

4.2 订单表 (orders)

字段名	类型	说明
id	BIGINT	主键
order_no	VARCHAR(50)	订单号
buyer_id	BIGINT	采购人ID
trader_id	BIGINT	贸易商ID
supplier_id	BIGINT	供应商ID
driver_id	BIGINT	司机ID
breed_type	VARCHAR(20)	牛品种
min_weight	DECIMAL(10,2)	最低重量(kg)
max_weight	DECIMAL(10,2)	最高重量(kg)
total_count	INTEGER	总数量
total_weight	DECIMAL(10,2)	总重量
unit_price	DECIMAL(10,2)	单价(元/kg)
total_amount	DECIMAL(15,2)	总金额
status	ENUM	状态(pending,confirmed,loading,shipping,delivered,completed,cancelled)
delivery_address	VARCHAR(255)	配送地址
delivery_date	DATE	配送日期
special_requirements	TEXT	特殊要求
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

4.3 运输跟踪表 (transport_tracks)

字段名	类型	说明
id	BIGINT	主键
order_id	BIGINT	订单ID
driver_id	BIGINT	司机ID
latitude	DECIMAL(10,8)	纬度
longitude	DECIMAL(11,8)	经度
speed	DECIMAL(5,2)	速度(km/h)
direction	DECIMAL(5,2)	方向(度)
cattle_status	VARCHAR(20)	牛只状态
temperature	DECIMAL(5,2)	温度(℃)
humidity	DECIMAL(5,2)	湿度(%)
video_url	VARCHAR(255)	视频URL
created_at	DATETIME	创建时间

4.4 支付表 (payments)

字段名	类型	说明
id	BIGINT	主键
order_id	BIGINT	订单ID
user_id	BIGINT	用户ID
amount	DECIMAL(15,2)	支付金额
paid_amount	DECIMAL(15,2)	实际支付金额
payment_type	ENUM	支付类型(wechat,alipay,bank)
payment_method	ENUM	支付方式(mini_program,app,web)
payment_no	VARCHAR(50)	支付单号
third_party_id	VARCHAR(100)	第三方支付ID
status	ENUM	状态(pending,paid,failed,refunded)
paid_time	DATETIME	支付时间
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

5. 安全设计

5.1 认证授权

JWT Token认证
基于角色的访问控制(RBAC)
API访问频率限制

5.2 数据安全

敏感数据加密存储
HTTPS传输加密
视频文件访问权限控制

5.3 业务安全

订单状态机验证
支付金额校验
操作日志审计

6. 性能优化

6.1 数据库优化

索引优化
读写分离
分表分库策略

6.2 缓存策略

Redis缓存热点数据
本地缓存减少IO

6.3 文件处理

视频文件分片上传
CDN加速访问

7. 监控告警

7.1 系统监控

应用性能监控(APM)
数据库监控
服务器资源监控
API响应时间监控

7.2 业务监控

订单流程监控
运输异常检测
支付成功率监控
用户行为分析

7.3 日志管理

操作日志记录
错误日志收集
日志分析和查询
实时日志追踪

8. 部署方案

8.1 开发环境

# docker-compose-dev.yml
version: '3.8'
services:
  # 后端服务
  user-service:
  
  # 数据库
  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_DATABASE=niu_mall
    ports:
      - "3306:3306"
  
  # 缓存
  redis:
    image: redis:6.2
    ports:
      - "6379:6379"

8.2 生产环境

# kubernetes部署配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: niu-mall-api
  labels:
    app: niu-mall
spec:
  replicas: 3
  selector:
    matchLabels:
      app: niu-mall-api
  template:
    metadata:
      labels:
        app: niu-mall-api
    spec:
      containers:
      - name: api-gateway
        image: niu-mall/api-gateway:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: production
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"

8.3 备份恢复策略

# 数据库备份
backup:
  schedule: "0 2 * * *"  # 每天凌晨2点
  retention: 30          # 保留30天
  storage: 
    type: oss            # 阿里云OSS存储
    bucket: niu-mall-backup

# 文件备份
file_backup:
  enabled: true
  schedule: "0 3 * * *"  # 每天凌晨3点
  include:
    - /data/uploads     # 用户上传文件
    - /data/logs        # 日志文件
  exclude:
    - /data/temp        # 临时文件

# 灾难恢复
recovery:
  rto: "4h"             # 恢复时间目标4小时
  rpo: "1h"             # 恢复点目标1小时
  procedures:
    - database_restore
    - service_restart
    - data_validation

9. 开发规范

9.1 代码规范

TypeScript严格模式
ESLint代码检查
Prettier代码格式化

9.2 Git规范

分支管理策略
Commit message规范
Code Review流程

9.3 文档规范

API文档自动化
数据库文档维护
部署文档更新

10. 测试规范

单元测试要求≥80%覆盖率
集成测试要求≥70%覆盖率
E2E测试核心业务流程100%覆盖

11. 附录

11.1 术语表

术语	说明
PRD	产品需求文档
API	应用程序编程接口
JWT	JSON Web Token
RBAC	基于角色的访问控制
CDN	内容分发网络
OSS	对象存储服务

11.2 参考资料

活牛采购智能数字化系统PRD
技术实施方案
NestJS官方文档
MySQL官方文档
Redis官方文档

14 KiB Raw Blame History Unescape Escape

活牛采购智能数字化系统 - 后端API设计文档

1. 概述

1.1 文档目的

1.2 系统架构

1.3 技术选型

2. 统一规范

2.1 响应格式

2.2 分页响应格式

2.3 错误码规范

2.4 认证机制

3. API接口设计

3.1 认证模块

3.1.1 小程序用户登录

3.1.2 获取当前用户信息

3.2 用户管理模块

3.2.1 获取用户列表

3.2.2 获取用户详情

3.3 订单管理模块

3.3.1 创建采购订单

3.3.2 获取订单列表

3.3.3 获取订单详情

3.3.4 更新订单状态

3.4 运输跟踪模块

3.4.1 司机上报位置信息

3.4.2 获取订单运输轨迹

3.5 文件管理模块

3.5.1 统一文件上传接口

3.6 支付管理模块

3.6.1 创建支付订单

3.6.2 支付回调接口

3.6.3 查询支付状态

4. 数据库设计

4.1 用户表 (users)

4.2 订单表 (orders)

4.3 运输跟踪表 (transport_tracks)

4.4 支付表 (payments)

5. 安全设计

5.1 认证授权

5.2 数据安全

5.3 业务安全

6. 性能优化

6.1 数据库优化

6.2 缓存策略

6.3 文件处理

7. 监控告警

7.1 系统监控

7.2 业务监控

7.3 日志管理

8. 部署方案

8.1 开发环境

8.2 生产环境

8.3 备份恢复策略

9. 开发规范

9.1 代码规范

9.2 Git规范

9.3 文档规范

10. 测试规范

11. 附录

11.1 术语表

11.2 参考资料

14 KiB

Raw Blame History