mcp-system-backend

🚀 系统 API 文档

本系统提供了一系列核心模块的 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,          // 类型（"deposit", "withdrawal", "transfer"）
  amount: Number,        // 金额
  description: String,   // 描述
  status: String,        // 状态（"completed", "failed", "pending"）
  createdAt: Date,
  updatedAt: Date
}