# 活牛采购智能数字化系统 - 后端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 响应格式
```json
{
  "code": 200,
  "message": "成功",
  "data": {},
  "timestamp": 1643097600000
}
```

### 2.2 分页响应格式
```json
{
  "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 <token>

## 3. API接口设计

### 3.1 认证模块

#### 3.1.1 小程序用户登录
- **URL**: POST /api/auth/mini-program/login
- **请求参数**:
  ```json
  {
    "phone": "13800138000",
    "code": "123456",
    "miniProgramType": "client"
  }
  ```
- **响应数据**:
  ```json
  {
    "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
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "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
- **请求参数**:
  ```json
  {
    "page": 1,
    "limit": 10,
    "userType": "client"
  }
  ```
- **响应数据**: 分页用户列表

#### 3.2.2 获取用户详情
- **URL**: GET /api/users/{id}
- **请求参数**: 无
- **响应数据**: 用户详细信息

### 3.3 订单管理模块

#### 3.3.1 创建采购订单
- **URL**: POST /api/orders
- **请求参数**:
  ```json
  {
    "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
- **请求参数**:
  ```json
  {
    "status": "pending",
    "page": 1,
    "limit": 10
  }
  ```
- **响应数据**: 分页订单列表

#### 3.3.3 获取订单详情
- **URL**: GET /api/orders/{id}
- **请求参数**: 无
- **响应数据**: 订单详细信息

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

### 3.4 运输跟踪模块

#### 3.4.1 司机上报位置信息
- **URL**: POST /api/transport/tracks
- **请求参数**:
  ```json
  {
    "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
- **请求参数**:
  ```json
  {
    "file": "文件二进制数据",
    "type": "cattle_video",
    "businessId": "order_123",
    "description": "装车过程视频"
  }
  ```
- **响应数据**:
  ```json
  {
    "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
- **请求参数**:
  ```json
  {
    "orderId": 123,
    "amount": 355000,
    "paymentType": "wechat",
    "paymentMethod": "mini_program"
  }
  ```
- **响应数据**:
  ```json
  {
    "paymentId": 1,
    "paymentNo": "pay_123456",
    "amount": 355000
  }
  ```

#### 3.6.2 支付回调接口
- **URL**: POST /api/payments/{id}/callback
- **请求参数**:
  ```json
  {
    "paymentId": "pay_123456",
    "status": "success",
    "paidAmount": 355000,
    "paidTime": "2024-01-25 15:30:00"
  }
  ```
- **响应数据**: 回调处理结果

#### 3.6.3 查询支付状态
- **URL**: GET /api/payments/{id}/status
- **请求参数**: 无
- **响应数据**:
  ```json
  {
    "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 开发环境
```yaml
# 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 生产环境
```yaml
# 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 备份恢复策略
```yaml
# 数据库备份
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 参考资料
1. 活牛采购智能数字化系统PRD
2. 技术实施方案
3. NestJS官方文档
4. MySQL官方文档
5. Redis官方文档