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

- 更新页面布局，优化导航栏和面包屑导航 - 重新组织页面内容，突出公司使命和价值观 - 添加发展历程和核心团队介绍 - 更新合作伙伴展示方式 - 调整页脚内容，增加社交媒体链接
2025-09-10 20:09:58 +08:00
parent 59cfe620fe
commit a9209b9c75
38 changed files with 10067 additions and 1989 deletions
--- a/docs/后端API设计文档.md
+++ b/docs/后端API设计文档.md
@@ -0,0 +1,560 @@
+# 活牛采购智能数字化系统 - 后端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官方文档