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
}