使用说明

MCP系统后端

物料收集点（MCP）系统的强大后端系统，用于管理合作伙伴、提货、订单和钱包交易。

概述

该服务器为MCP系统实现RESTful API，允许合作伙伴管理、提货计划、订单处理和钱包交易。它是用Node.js、Express和MongoDB构建的。

目录结构

server/
├── config/             # Configuration files
│   └── db.js           # Database connection configuration
├── controllers/        # Route controllers
│   ├── authController.js      # Authentication logic
│   ├── orderController.js     # Order management
│   ├── partnerController.js   # Partner management
│   ├── pickupController.js    # Pickup scheduling
│   └── walletController.js    # Wallet operations
├── middleware/         # Express middleware
│   └── auth.js         # Authentication & authorization middleware
├── models/             # MongoDB data models
│   ├── Order.js        # Order schema
│   ├── Partner.js      # Partner schema
│   ├── Pickup.js       # Pickup schema
│   ├── Transaction.js  # Transaction schema
│   ├── User.js         # User schema
│   └── Wallet.js       # Wallet schema
├── routes/             # API routes
│   ├── auth.js         # Authentication routes
│   ├── order.js        # Order management routes
│   ├── partner.js      # Partner management routes
│   ├── pickup.js       # Pickup scheduling routes
│   └── wallet.js       # Wallet operation routes
├── scripts/            # Utility scripts
│   └── seed.js         # Database seeding script
├── .env                # Environment variables
├── package.json        # Project dependencies and scripts
└── server.js           # Main application entry point

设置

安装依赖项:
```
npm install
```
设置环境变量: 创建一个 .env 根目录中的文件，包含以下变量：
```
PORT=5000
MONGO_URI=mongodb://localhost:27017/mcp-system
JWT_SECRET=your_jwt_secret
```
运行开发服务器:
```
npm run dev
```
为数据库添加种子 （可选）：
```
npm run seed
```

API终点

所有API回复均遵循标准格式：

{
  "success": true|false,
  "message": "Description of the result",
  "data": { /* Response data object */ }
}

认证

注册新用户

端点: POST /api/auth/register

请求正文:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "securePassword123",
  "phone":"6201693634",
  "role": "user"
}

响应:

{
  "success": true,
  "message": "Registration successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "_id": "60d21b4667d0d8992e610c85",
      "name": "John Doe",
      "email": "john@example.com",
      "phone":"6201693634",
    }
  }
}

伙伴

注册合作伙伴

端点: POST /api/partners/register

请求正文:

{
  "name": "EcoRecycle Inc",
  "email": "contact@ecorecycle.com",
  "password": "securePassword123",
  "role": "MCP"
}

响应:

{
  "success": true,
  "message": "Partner registered successfully",
  "data": {
    "partner": {
      "_id": "60d21b4667d0d8992e610c85",
      "name": "EcoRecycle Inc",
      "email": "contact@ecorecycle.com",
      "role": "MCP",
      "walletBalance": 0
    }
  }
}

获取合作伙伴详细信息

端点: GET /api/partners/:id

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应:

{
  "success": true,
  "data": {
    "partner": {
      "_id": "60d21b4667d0d8992e610c85",
      "name": "EcoRecycle Inc",
      "email": "contact@ecorecycle.com",
      "role": "MCP",
      "walletBalance": 500,
      "createdAt": "2023-04-05T14:30:45.123Z"
    }
  }
}

拾音器

创建提货

端点: POST /api/pickups/create

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

访问：仅限MCP合作伙伴

请求正文:

{
  "title": "Weekly Recyclables Pickup",
  "description": "Collection of plastic and paper materials",
  "address": "123 Green St, Eco City",
  "date": "2023-04-10T09:00:00.000Z",
  "assignedTo": "60d21b4667d0d8992e610c86",
  "commission": 50
}

响应:

{
  "success": true,
  "message": "Pickup created successfully",
  "data": {
    "pickup": {
      "_id": "60d21b4667d0d8992e610c87",
      "title": "Weekly Recyclables Pickup",
      "description": "Collection of plastic and paper materials",
      "address": "123 Green St, Eco City",
      "date": "2023-04-10T09:00:00.000Z",
      "status": "pending",
      "assignedTo": "60d21b4667d0d8992e610c86",
      "commission": 50,
      "createdAt": "2023-04-05T16:30:22.789Z"
    }
  }
}

取我的皮卡

端点: GET /api/pickups/my

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

访问：任何经过身份验证的用户

响应:

{
  "success": true,
  "data": {
    "pickups": [
      {
        "_id": "60d21b4667d0d8992e610c87",
        "title": "Weekly Recyclables Pickup",
        "description": "Collection of plastic and paper materials",
        "address": "123 Green St, Eco City",
        "date": "2023-04-10T09:00:00.000Z",
        "status": "pending",
        "assignedTo": "60d21b4667d0d8992e610c86",
        "commission": 50,
        "createdAt": "2023-04-05T16:30:22.789Z"
      }
    ]
  }
}

更新取货状态

端点: PUT /api/pickups/:id/status

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求正文:
```
{
  "status": "completed"
}
```

响应:

{
  "success": true,
  "message": "Pickup status updated successfully",
  "data": {
    "pickup": {
      "_id": "60d21b4667d0d8992e610c87",
      "status": "completed",
      "updatedAt": "2023-04-10T14:25:10.789Z"
    }
  }
}

过滤器拾音器

端点: GET /api/pickups/filter

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

访问：仅限MCP合作伙伴
查询参数:
- status：按状态筛选（待定、已完成、失败）
- date：按日期筛选

响应:

{
  "success": true,
  "data": {
    "pickups": [
      {
        "_id": "60d21b4667d0d8992e610c87",
        "title": "Weekly Recyclables Pickup",
        "description": "Collection of plastic and paper materials",
        "address": "123 Green St, Eco City",
        "date": "2023-04-10T09:00:00.000Z",
        "status": "completed",
        "assignedTo": "60d21b4667d0d8992e610c86",
        "commission": 50,
        "createdAt": "2023-04-05T16:30:22.789Z"
      }
    ]
  }
}

订单

创建订单

端点: POST /api/orders/create

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求正文:

{
  "items": [
    {
      "product": "Recycled Paper",
      "quantity": 20,
      "price": 5.50
    }
  ],
  "shippingAddress": "789 Client St, Client City",
  "paymentMethod": "wallet"
}

响应:

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order": {
      "_id": "60d21b4667d0d8992e610c88",
      "orderNumber": "ORD-20230405-001",
      "items": [
        {
          "product": "Recycled Paper",
          "quantity": 20,
          "price": 5.50,
          "total": 110
        }
      ],
      "totalAmount": 110,
      "shippingAddress": "789 Client St, Client City",
      "paymentMethod": "wallet",
      "status": "pending",
      "createdAt": "2023-04-05T17:15:33.123Z"
    }
  }
}

获取我的订单

端点: GET /api/orders/my

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应:

{
  "success": true,
  "data": {
    "orders": [
      {
        "_id": "60d21b4667d0d8992e610c88",
        "orderNumber": "ORD-20230405-001",
        "items": [
          {
            "product": "Recycled Paper",
            "quantity": 20,
            "price": 5.50,
            "total": 110
          }
        ],
        "totalAmount": 110,
        "status": "pending",
        "createdAt": "2023-04-05T17:15:33.123Z"
      }
    ]
  }
}

钱包

获取我的钱包

端点: GET /api/wallet/balance

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应:

{
  "success": true,
  "data": {
    "balance": 1250.75
  }
}

向钱包充值

端点: POST /api/wallet/deposit

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

请求正文:

{
  "amount": 500,
  "paymentMethod": "credit_card"
}

响应:

{
  "success": true,
  "message": "Deposit successful",
  "data": {
    "transaction": {
      "_id": "60d21b4667d0d8992e610c90",
      "type": "deposit",
      "amount": 500,
      "description": "Wallet deposit via credit card",
      "createdAt": "2023-04-06T14:25:10.789Z"
    },
    "balance": 1750.75
  }
}

交易历史记录

端点: GET /api/wallet/transactions

标头:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应:

{
  "success": true,
  "data": {
    "transactions": [
      {
        "_id": "60d21b4667d0d8992e610c90",
        "type": "deposit",
        "amount": 500,
        "description": "Wallet deposit via credit card",
        "createdAt": "2023-04-06T14:25:10.789Z"
      },
      {
        "_id": "60d21b4667d0d8992e610c91",
        "type": "withdrawal",
        "amount": 110,
        "description": "Payment for order ORD-20230405-001",
        "createdAt": "2023-04-05T17:30:45.123Z"
      }
    ]
  }
}

身份验证流程

注册/登录:
- 用户或合作伙伴使用各自的端点注册或登录
- 服务器使用JWT令牌进行响应
令牌使用情况:
- 在所有受保护请求的Authorization标头中包含令牌：
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
基于角色的访问:
- 某些端点根据用户角色受到限制
- 系统支持“MCP”和“皮卡伙伴”等角色
- 未经授权的访问尝试将被拒绝，并显示403错误

数据模型

用户

{
  name: String,         // User's full name
  email: String,        // User's email (unique)
  password: String,     // Hashed password
  role: String,         // Role for authorization
  status: String,       // 'ACTIVE', 'INACTIVE'
  createdAt: Date,
  updatedAt: Date
}

搭档

{
  name: String,          // Partner name
  email: String,         // Contact email (unique)
  password: String,      // Hashed password
  role: String,          // 'MCP', 'PickupPartner'
  walletBalance: Number, // Current wallet balance
  createdAt: Date,
  updatedAt: Date
}

拾取

{
  title: String,         // Pickup title
  description: String,   // Pickup description
  address: String,       // Pickup location
  date: Date,            // Scheduled date and time
  status: String,        // 'pending', 'completed', 'failed'
  assignedTo: ObjectId,  // Reference to User/Partner
  commission: Number,    // Commission amount
  createdAt: Date,
  updatedAt: Date
}

订单

{
  orderNumber: String,   // Formatted order number
  items: [{
    product: String,     // Product name
    quantity: Number,    // Quantity
    price: Number,       // Price per unit
    total: Number        // Calculated total
  }],
  totalAmount: Number,   // Order total
  shippingAddress: String, // Delivery address
  paymentMethod: String, // Payment method
  status: String,        // 'pending', 'processing', 'completed', 'cancelled'
  createdAt: Date,
  updatedAt: Date
}

交易

{
  type: String,          // 'deposit', 'withdrawal', 'transfer'
  amount: Number,        // Transaction amount
  description: String,   // Transaction description
  status: String,        // 'completed', 'failed', 'pending'
  createdAt: Date
}

错误处理

所有API端点返回标准化错误响应：

{
  "success": false,
  "message": "Error message describing what went wrong",
  "error": {
    "details": "Additional error details (development mode only)"
  }
}

常见错误代码

400:错误请求-输入无效
401：未经授权-需要身份验证
403：禁止-用户缺乏权限
404：未找到-资源不存在
500：内部服务器错误-服务器端错误

环境变量

PORT -服务器端口（默认值：5000）
MONGO_URI -MongoDB连接字符串
JWT_SECRET -JWT身份验证密钥
NODE_ENV -环境（开发、生产）

数据库

该系统使用MongoDB作为其数据库。通过Mongoose使用环境变量中指定的连接字符串建立连接。

型号包括：

用户：用于身份验证和用户信息
合作伙伴：材料收集合作伙伴和取货合作伙伴
取货：预定材料取货
订单：订单处理
交易：金融交易记录

使用说明

MCP系统后端

目录

概述

目录结构

设置

API终点

认证

注册新用户

登录

伙伴

注册合作伙伴

获取合作伙伴详细信息

拾音器

创建提货

取我的皮卡

更新取货状态

过滤器拾音器

订单

创建订单

获取我的订单

钱包

获取我的钱包

向钱包充值

交易历史记录

身份验证流程

数据模型

用户

搭档

拾取

订单

交易

错误处理

常见错误代码

环境变量

数据库

相关 MCP

交易平台MCP服务

Tradovate交易协议服务器

MetaTrader 5 MCP服务器

支付协议服务器

快递100寄快递 MCP

POS系统中间件服务