系统 API 文档

概述

本系统包括以下核心模块：

1. 用户管理（User Management）
2. 合作伙伴管理（Partner Management）
3. 上门取货管理（Pickup Management）
4. 订单处理（Order Processing）
5. 交易记录管理（Transaction Record Management）

用户注册与登录

注册接口

请求方式: POST
路径: /api/v1/auth/register

请求参数:

• name: 用户姓名
• email: 用户邮箱 (必须唯一)
• password: 用户密码
• role: 用户角色（可选，默认为 "user"）

登录接口

请求方式: POST
路径: /api/v1/auth/login

请求参数:

• email: 用户邮箱
• password: 用户密码

合伙伙伴管理

创建合作伙伴

请求方式: POST
路径: /api/v1/partners

请求参数:

• name: 合伙企业名称
• email: 联系邮箱 (必须唯一)
• password: 合伙人密码
• role: 角色（"MCP" 或 "PickupPartner"）

上门取货管理

创建上门取货任务

请求方式: POST
路径: /api/v1/pickups

请求参数:

• title: 取货标题
• description: 取货描述
• address: 取货地址
• date: 计划日期和时间
• status: 状态（"pending", "completed", "failed"）
• assignedTo: 负责人ID（用户或合作伙伴）

订单处理

创建订单

请求方式: POST
路径: /api/v1/orders

请求参数:

• orderNumber: 订单号
• items: 订单项数组，包含：
  • product: 商品名称
  • quantity: 数量
  • price: 单价
  • total: 总价
• totalAmount: 订单总额
• shippingAddress: 运输地址
• paymentMethod: 支付方式
• status: 状态（"pending", "processing", "completed", "cancelled"）

交易记录管理

创建交易记录

请求方式: POST
路径: /api/v1/transactions

请求参数:

• type: 类型（"deposit", "withdrawal", "transfer"）
• amount: 金额
• description: 描述
• status: 状态（"completed", "failed", "pending"）

授权流程

1. 注册/登录:

   • 用户或合作伙伴通过相应端点进行注册或登录
   • 服务器返回 JWT 令牌

2. 令牌使用:

   • 在所有受保护的请求中包含令牌，格式如下：

   Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   

3. 基于角色的访问控制:

   • 部分端点根据用户角色进行限制
   • 系统支持的角色包括 "MCP" 和 "PickupPartner"
   • 未授权的访问尝试将被拒绝，返回 403 错误

数据模型

用户（User）

{
  name: String,         // 用户姓名
  email: String,        // 用户邮箱 (唯一)
  password: String,     // 加密密码
  role: String,         // 授权角色
  status: String,       // 'ACTIVE', 'INACTIVE'
  createdAt: Date,
  updatedAt: Date
}

合作伙伴（Partner）

{
  name: String,          // 合伙企业名称
  email: String,         // 联系邮箱 (唯一)
  password: String,      // 加密密码
  role: String,          // 'MCP', 'PickupPartner'
  walletBalance: Number, // 当前钱包余额
  createdAt: Date,
  updatedAt: Date
}

上门取货（Pickup）

{
  title: String,         // 取货标题
  description: String,   // 取货描述
  address: String,       // 取货地址
  date: Date,            // 计划日期和时间
  status: String,        // 'pending', 'completed', 'failed'
  assignedTo: ObjectId,  // 负责人引用（用户/合作伙伴）
  createdAt: Date,
  updatedAt: Date
}

订单（Order）

{
  orderNumber: String,   // 订单号
  items: Array,          // 订单项数组，包含：
    - product: String   // 商品名称
    - quantity: Number  // 数量
    - price: Number     // 单价
    - total: Number     // 总价
  totalAmount: Number,   // 订单总额
  shippingAddress: String,// 运输地址
  paymentMethod: String,// 支付方式
  status: String,        // 状态（"pending", "processing", "completed", "cancelled"）
  createdAt: Date,
  updatedAt: Date
}

交易记录（Transaction）

{
  type: String,          // 类型（"