# API文档

## 1. 概述

本文档描述了 Crawlful Hub 系统的API接口，包括认证、用户、商品、订单、财务等模块的接口规范。所有API接口都遵循RESTful设计原则，使用JSON格式进行数据交换。

## 2. 基础信息

### 2.1 API版本

当前API版本：v1

### 2.2 基础URL

```
https://api.crawlful.com/v1
```

### 2.3 认证方式

系统使用JWT（JSON Web Token）进行认证，在请求头中添加`Authorization`字段：

```
Authorization: Bearer <token>
```

### 2.4 响应格式

所有API响应都遵循以下格式：

```json
{
  "success": true,
  "data": {...},
  "error": null
}
```

- `success`：布尔值，表示请求是否成功
- `data`：请求成功时返回的数据
- `error`：请求失败时返回的错误信息

### 2.5 错误码

| 错误码 | 描述 | HTTP状态码 |
|-------|------|------------|
| 40001 | 参数错误 | 400 |
| 40101 | 未授权 | 401 |
| 40301 | 禁止访问 | 403 |
| 40401 | 资源不存在 | 404 |
| 50001 | 服务器内部错误 | 500 |

## 3. 认证接口

### 3.1 登录

**请求**：
- 方法：POST
- 路径：/auth/login
- 内容类型：application/json
- 请求体：

```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "1",
      "username": "user",
      "email": "user@example.com",
      "role": "OPERATOR"
    }
  },
  "error": null
}
```

### 3.2 注册

**请求**：
- 方法：POST
- 路径：/auth/register
- 内容类型：application/json
- 请求体：

```json
{
  "username": "user",
  "email": "user@example.com",
  "password": "password123",
  "role": "OPERATOR"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "userId": "1"
  },
  "error": null
}
```

### 3.3 刷新令牌

**请求**：
- 方法：POST
- 路径：/auth/refresh
- 内容类型：application/json
- 请求体：

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "error": null
}
```

## 4. 用户接口

### 4.1 获取用户列表

**请求**：
- 方法：GET
- 路径：/users
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - role：角色筛选
  - search：搜索关键词

**响应**：

```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": "1",
        "username": "user1",
        "email": "user1@example.com",
        "role": "OPERATOR",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

### 4.2 获取用户详情

**请求**：
- 方法：GET
- 路径：/users/{id}

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "1",
    "username": "user1",
    "email": "user1@example.com",
    "role": "OPERATOR",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  },
  "error": null
}
```

### 4.3 创建用户

**请求**：
- 方法：POST
- 路径：/users
- 内容类型：application/json
- 请求体：

```json
{
  "username": "user1",
  "email": "user1@example.com",
  "password": "password123",
  "role": "OPERATOR",
  "tenantId": "1"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "userId": "1"
  },
  "error": null
}
```

### 4.4 更新用户

**请求**：
- 方法：PUT
- 路径：/users/{id}
- 内容类型：application/json
- 请求体：

```json
{
  "username": "user1",
  "email": "user1@example.com",
  "role": "MANAGER"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

### 4.5 删除用户

**请求**：
- 方法：DELETE
- 路径：/users/{id}

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

### 4.6 批量创建用户

**请求**：
- 方法：POST
- 路径：/users/batch
- 内容类型：application/json
- 请求体：

```json
{
  "users": [
    {
      "username": "user1",
      "email": "user1@example.com",
      "password": "password123",
      "role": "OPERATOR",
      "tenantId": "1"
    },
    ...
  ]
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "createdIds": ["1", "2", ...]
  },
  "error": null
}
```

## 5. 商品接口

### 5.1 获取商品列表

**请求**：
- 方法：GET
- 路径：/products
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - category：分类筛选
  - status：状态筛选
  - search：搜索关键词

**响应**：

```json
{
  "success": true,
  "data": {
    "products": [
      {
        "id": "1",
        "name": "Product 1",
        "price": 99.99,
        "stock": 100,
        "category": "Electronics",
        "status": "ACTIVE"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

### 5.2 获取商品详情

**请求**：
- 方法：GET
- 路径：/products/{id}

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "1",
    "name": "Product 1",
    "price": 99.99,
    "stock": 100,
    "category": "Electronics",
    "status": "ACTIVE",
    "description": "Product description",
    "images": ["image1.jpg", "image2.jpg"]
  },
  "error": null
}
```

### 5.3 创建商品

**请求**：
- 方法：POST
- 路径：/products
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Product 1",
  "price": 99.99,
  "stock": 100,
  "category": "Electronics",
  "description": "Product description",
  "images": ["image1.jpg", "image2.jpg"]
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "productId": "1"
  },
  "error": null
}
```

### 5.4 更新商品

**请求**：
- 方法：PUT
- 路径：/products/{id}
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Product 1 Updated",
  "price": 109.99,
  "stock": 150
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

### 5.5 删除商品

**请求**：
- 方法：DELETE
- 路径：/products/{id}

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

## 6. 订单接口

### 6.1 获取订单列表

**请求**：
- 方法：GET
- 路径：/orders
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - status：状态筛选
  - startDate：开始日期
  - endDate：结束日期

**响应**：

```json
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "1",
        "orderNumber": "ORD-2023-0001",
        "totalAmount": 199.98,
        "status": "PENDING",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

### 6.2 获取订单详情

**请求**：
- 方法：GET
- 路径：/orders/{id}

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "1",
    "orderNumber": "ORD-2023-0001",
    "totalAmount": 199.98,
    "status": "PENDING",
    "createdAt": "2023-01-01T00:00:00Z",
    "items": [
      {
        "productId": "1",
        "name": "Product 1",
        "quantity": 2,
        "price": 99.99
      }
    ],
    "customer": {
      "name": "Customer 1",
      "email": "customer1@example.com",
      "address": "123 Main St"
    }
  },
  "error": null
}
```

### 6.3 创建订单

**请求**：
- 方法：POST
- 路径：/orders
- 内容类型：application/json
- 请求体：

```json
{
  "customer": {
    "name": "Customer 1",
    "email": "customer1@example.com",
    "address": "123 Main St"
  },
  "items": [
    {
      "productId": "1",
      "quantity": 2
    }
  ]
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "orderId": "1",
    "orderNumber": "ORD-2023-0001"
  },
  "error": null
}
```

### 6.4 更新订单状态

**请求**：
- 方法：PUT
- 路径：/orders/{id}/status
- 内容类型：application/json
- 请求体：

```json
{
  "status": "SHIPPED"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

### 6.5 取消订单

**请求**：
- 方法：POST
- 路径：/orders/{id}/cancel

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

## 7. 财务接口

### 7.1 获取财务报表

**请求**：
- 方法：GET
- 路径：/finance/reports
- 查询参数：
  - startDate：开始日期
  - endDate：结束日期
  - type：报表类型（daily, monthly, yearly）

**响应**：

```json
{
  "success": true,
  "data": {
    "report": {
      "totalSales": 10000.00,
      "totalExpenses": 5000.00,
      "netProfit": 5000.00,
      "transactions": [
        {
          "date": "2023-01-01",
          "amount": 1000.00,
          "type": "SALE"
        },
        ...
      ]
    }
  },
  "error": null
}
```

### 7.2 获取结算记录

**请求**：
- 方法：GET
- 路径：/finance/settlements
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - status：状态筛选

**响应**：

```json
{
  "success": true,
  "data": {
    "settlements": [
      {
        "id": "1",
        "amount": 5000.00,
        "status": "COMPLETED",
        "createdAt": "2023-01-01T00:00:00Z",
        "completedAt": "2023-01-02T00:00:00Z"
      },
      ...
    ],
    "total": 10
  },
  "error": null
}
```

### 7.3 发起结算

**请求**：
- 方法：POST
- 路径：/finance/settlements
- 内容类型：application/json
- 请求体：

```json
{
  "amount": 5000.00,
  "method": "BANK_TRANSFER"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "settlementId": "1"
  },
  "error": null
}
```

## 8. 店铺接口

### 8.1 获取店铺列表

**请求**：
- 方法：GET
- 路径：/shops
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - platform：平台筛选
  - status：状态筛选

**响应**：

```json
{
  "success": true,
  "data": {
    "shops": [
      {
        "id": "1",
        "name": "Shop 1",
        "platform": "Amazon",
        "status": "ACTIVE",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 10
  },
  "error": null
}
```

### 8.2 获取店铺详情

**请求**：
- 方法：GET
- 路径：/shops/{id}

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "1",
    "name": "Shop 1",
    "platform": "Amazon",
    "status": "ACTIVE",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z",
    "config": {
      "apiKey": "api_key",
      "apiSecret": "api_secret"
    }
  },
  "error": null
}
```

### 8.3 添加店铺

**请求**：
- 方法：POST
- 路径：/shops
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Shop 1",
  "platform": "Amazon",
  "config": {
    "apiKey": "api_key",
    "apiSecret": "api_secret"
  }
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "shopId": "1"
  },
  "error": null
}
```

### 8.4 更新店铺

**请求**：
- 方法：PUT
- 路径：/shops/{id}
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Shop 1 Updated",
  "config": {
    "apiKey": "new_api_key",
    "apiSecret": "new_api_secret"
  }
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

### 8.5 删除店铺

**请求**：
- 方法：DELETE
- 路径：/shops/{id}

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

## 9. 部门接口

### 9.1 获取部门列表

**请求**：
- 方法：GET
- 路径：/departments

**响应**：

```json
{
  "success": true,
  "data": {
    "departments": [
      {
        "id": "1",
        "name": "Department 1",
        "parentId": null,
        "userCount": 10
      },
      ...
    ]
  },
  "error": null
}
```

### 9.2 获取部门详情

**请求**：
- 方法：GET
- 路径：/departments/{id}

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "1",
    "name": "Department 1",
    "parentId": null,
    "userCount": 10,
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-01T00:00:00Z"
  },
  "error": null
}
```

### 9.3 创建部门

**请求**：
- 方法：POST
- 路径：/departments
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Department 1",
  "parentId": null,
  "description": "Department description"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "departmentId": "1"
  },
  "error": null
}
```

### 9.4 更新部门

**请求**：
- 方法：PUT
- 路径：/departments/{id}
- 内容类型：application/json
- 请求体：

```json
{
  "name": "Department 1 Updated",
  "parentId": "2",
  "description": "Updated department description"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

### 9.5 删除部门

**请求**：
- 方法：DELETE
- 路径：/departments/{id}

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

### 9.6 设置部门负责人

**请求**：
- 方法：PUT
- 路径：/departments/{id}/manager
- 内容类型：application/json
- 请求体：

```json
{
  "userId": "1"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

## 10. 订阅接口

### 10.1 获取套餐列表

**请求**：
- 方法：GET
- 路径：/subscriptions/plans

**响应**：

```json
{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "1",
        "name": "Free",
        "price": 0,
        "features": ["5 shops", "100 products"]
      },
      {
        "id": "2",
        "name": "Basic",
        "price": 99,
        "features": ["20 shops", "1000 products"]
      },
      ...
    ]
  },
  "error": null
}
```

### 10.2 获取当前订阅

**请求**：
- 方法：GET
- 路径：/subscriptions/current

**响应**：

```json
{
  "success": true,
  "data": {
    "subscription": {
      "id": "1",
      "planId": "2",
      "planName": "Basic",
      "startDate": "2023-01-01T00:00:00Z",
      "endDate": "2023-02-01T00:00:00Z",
      "status": "ACTIVE"
    }
  },
  "error": null
}
```

### 10.3 切换套餐

**请求**：
- 方法：POST
- 路径：/subscriptions/switch
- 内容类型：application/json
- 请求体：

```json
{
  "planId": "3"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "subscriptionId": "2"
  },
  "error": null
}
```

### 10.4 获取使用量统计

**请求**：
- 方法：GET
- 路径：/subscriptions/usage
- 查询参数：
  - startDate：开始日期
  - endDate：结束日期

**响应**：

```json
{
  "success": true,
  "data": {
    "usage": {
      "aiCalls": 100,
      "shops": 5,
      "storage": 1024,
      "apiCalls": 1000
    }
  },
  "error": null
}
```

## 11. 数据接口

### 11.1 导出数据

**请求**：
- 方法：GET
- 路径：/data/export
- 查询参数：
  - type：数据类型（users, products, orders, etc.）
  - format：导出格式（csv, excel）
  - startDate：开始日期
  - endDate：结束日期

**响应**：
- 类型：文件下载

### 11.2 导入数据

**请求**：
- 方法：POST
- 路径：/data/import
- 内容类型：multipart/form-data
- 请求体：
  - file：数据文件
  - type：数据类型（users, products, orders, etc.）

**响应**：

```json
{
  "success": true,
  "data": {
    "importedCount": 100,
    "failedCount": 0
  },
  "error": null
}
```

## 12. 日志接口

### 12.1 获取操作日志

**请求**：
- 方法：GET
- 路径：/logs/operations
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - user：操作人
  - action：操作类型
  - startDate：开始日期
  - endDate：结束日期

**响应**：

```json
{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "userId": "1",
        "username": "user1",
        "action": "CREATE_USER",
        "details": "Created user user2",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

### 12.2 获取登录日志

**请求**：
- 方法：GET
- 路径：/logs/logins
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - user：用户
  - ip：IP地址
  - startDate：开始日期
  - endDate：结束日期

**响应**：

```json
{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "userId": "1",
        "username": "user1",
        "ip": "192.168.1.1",
        "status": "SUCCESS",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

### 12.3 获取异常日志

**请求**：
- 方法：GET
- 路径：/logs/exceptions
- 查询参数：
  - page：页码，默认1
  - pageSize：每页数量，默认10
  - type：异常类型
  - startDate：开始日期
  - endDate：结束日期

**响应**：

```json
{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "1",
        "type": "API_ERROR",
        "message": "Invalid API key",
        "stack": "Error: Invalid API key\n    at ...",
        "createdAt": "2023-01-01T00:00:00Z"
      },
      ...
    ],
    "total": 100
  },
  "error": null
}
```

## 13. 系统接口

### 13.1 获取系统信息

**请求**：
- 方法：GET
- 路径：/system/info

**响应**：

```json
{
  "success": true,
  "data": {
    "system": {
      "version": "1.0.0",
      "status": "RUNNING",
      "uptime": "7 days 12 hours 34 minutes"
    }
  },
  "error": null
}
```

### 13.2 获取系统配置

**请求**：
- 方法：GET
- 路径：/system/config

**响应**：

```json
{
  "success": true,
  "data": {
    "config": {
      "systemName": "Crawlful Hub",
      "timezone": "UTC",
      "language": "en"
    }
  },
  "error": null
}
```

### 13.3 更新系统配置

**请求**：
- 方法：PUT
- 路径：/system/config
- 内容类型：application/json
- 请求体：

```json
{
  "systemName": "Crawlful Hub",
  "timezone": "UTC",
  "language": "en"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true
  },
  "error": null
}
```

## 15. 店铺管理接口

### 15.1 获取我的店铺列表

**请求**：
- 方法：GET
- 路径：/api/shops/my-shops
- 认证：需要登录

**响应**：

```json
{
  "success": true,
  "data": [
    {
      "id": "shop_1",
      "tenantId": "tenant_1",
      "name": "TikTok店铺A",
      "platform": "TIKTOK",
      "platformAccountId": "account_1",
      "departmentId": "dept_1_1",
      "status": "ACTIVE",
      "lastSyncAt": "2026-03-29T10:00:00Z",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-29T10:00:00Z"
    }
  ],
  "error": null
}
```

### 15.2 获取店铺详情

**请求**：
- 方法：GET
- 路径：/api/shops/:id
- 认证：需要店铺成员权限

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "shop_1",
    "tenantId": "tenant_1",
    "name": "TikTok店铺A",
    "platform": "TIKTOK",
    "platformAccountId": "account_1",
    "departmentId": "dept_1_1",
    "status": "ACTIVE",
    "config": {},
    "lastSyncAt": "2026-03-29T10:00:00Z",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-03-29T10:00:00Z"
  },
  "error": null
}
```

### 15.3 创建店铺

**请求**：
- 方法：POST
- 路径：/api/shops
- 认证：需要店铺拥有者权限
- 内容类型：application/json
- 请求体：

```json
{
  "name": "TikTok店铺A",
  "platform": "TIKTOK",
  "platformAccountId": "account_1",
  "departmentId": "dept_1_1",
  "config": {}
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "shop_1",
    "name": "TikTok店铺A",
    "platform": "TIKTOK",
    "status": "INACTIVE",
    "createdAt": "2026-03-29T10:00:00Z"
  },
  "error": null
}
```

### 15.4 更新店铺信息

**请求**：
- 方法：PUT
- 路径：/api/shops/:id
- 认证：需要店铺拥有者权限
- 内容类型：application/json
- 请求体：

```json
{
  "name": "TikTok店铺A（更新）",
  "departmentId": "dept_1_2"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "shop_1",
    "name": "TikTok店铺A（更新）",
    "platform": "TIKTOK",
    "status": "ACTIVE",
    "updatedAt": "2026-03-29T10:30:00Z"
  },
  "error": null
}
```

### 15.5 刷新店铺授权

**请求**：
- 方法：POST
- 路径：/api/shops/:id/refresh-auth
- 认证：需要店铺拥有者权限

**响应**：

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "授权已刷新"
  },
  "error": null
}
```

### 15.6 删除店铺

**请求**：
- 方法：DELETE
- 路径：/api/shops/:id
- 认证：需要店铺拥有者权限

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

### 15.7 获取店铺成员列表

**请求**：
- 方法：GET
- 路径：/api/shops/:shopId/members
- 认证：需要店铺成员权限

**响应**：

```json
{
  "success": true,
  "data": [
    {
      "id": "member_1",
      "shopId": "shop_1",
      "userId": "user_1",
      "userName": "李主管",
      "userEmail": "manager@crawlful.com",
      "role": "admin",
      "permissions": ["product:read", "product:write", "order:read"],
      "assignedBy": "user_admin",
      "assignedAt": "2026-03-20T10:00:00Z",
      "createdAt": "2026-03-20T10:00:00Z",
      "updatedAt": "2026-03-20T10:00:00Z"
    }
  ],
  "error": null
}
```

### 15.8 获取用户拥有的店铺

**请求**：
- 方法：GET
- 路径：/api/shops/user/:userId/shops
- 认证：需要管理员权限或用户本人

**响应**：

```json
{
  "success": true,
  "data": [
    {
      "id": "member_1",
      "shopId": "shop_1",
      "userId": "user_1",
      "role": "admin",
      "permissions": ["product:read", "product:write"],
      "assignedAt": "2026-03-20T10:00:00Z"
    }
  ],
  "error": null
}
```

### 15.9 添加店铺成员

**请求**：
- 方法：POST
- 路径：/api/shop-members
- 认证：需要店铺拥有者权限
- 内容类型：application/json
- 请求体：

```json
{
  "shopId": "shop_1",
  "userId": "user_2",
  "role": "operator",
  "permissions": ["product:read", "product:write", "order:read"],
  "assignedBy": "user_1"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "member_2",
    "shopId": "shop_1",
    "userId": "user_2",
    "role": "operator",
    "permissions": ["product:read", "product:write", "order:read"],
    "assignedBy": "user_1",
    "assignedAt": "2026-03-29T11:00:00Z",
    "createdAt": "2026-03-29T11:00:00Z"
  },
  "error": null
}
```

### 15.10 移除店铺成员

**请求**：
- 方法：DELETE
- 路径：/api/shop-members/:shopId/:userId
- 认证：需要店铺拥有者权限

**响应**：

```json
{
  "success": true,
  "data": null,
  "error": null
}
```

### 15.11 更新成员角色和权限

**请求**：
- 方法：PUT
- 路径：/api/shop-members/:shopId/:userId
- 认证：需要店铺拥有者权限
- 内容类型：application/json
- 请求体：

```json
{
  "role": "admin",
  "permissions": ["product:read", "product:write", "product:delete", "order:read", "order:write"]
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "id": "member_1",
    "shopId": "shop_1",
    "userId": "user_1",
    "role": "admin",
    "permissions": ["product:read", "product:write", "product:delete", "order:read", "order:write"],
    "updatedAt": "2026-03-29T11:30:00Z"
  },
  "error": null
}
```

### 15.12 获取店铺统计信息

**请求**：
- 方法：GET
- 路径：/api/shops/stats
- 认证：需要登录

**响应**：

```json
{
  "success": true,
  "data": {
    "total": 10,
    "active": 8,
    "inactive": 1,
    "expired": 1,
    "error": 0
  },
  "error": null
}
```

---

## 16. 集成与扩展接口

### 16.1 SSO集成

**请求**：
- 方法：GET
- 路径：/integrations/sso/login
- 查询参数：
  - provider：身份提供商（google, microsoft, etc.）
  - redirect_uri：回调地址

**响应**：
- 类型：重定向到身份提供商登录页面

### 16.2 LDAP/AD集成

**请求**：
- 方法：POST
- 路径：/integrations/ldap/test
- 内容类型：application/json
- 请求体：

```json
{
  "url": "ldap://example.com",
  "bindDn": "cn=admin,dc=example,dc=com",
  "bindPassword": "password",
  "baseDn": "ou=users,dc=example,dc=com"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "connected": true,
    "userCount": 100
  },
  "error": null
}
```

### 16.3 Webhook管理

**请求**：
- 方法：POST
- 路径：/webhooks
- 内容类型：application/json
- 请求体：

```json
{
  "url": "https://example.com/webhook",
  "events": ["user.created", "user.updated", "tenant.created"],
  "secret": "secret_key"
}
```

**响应**：

```json
{
  "success": true,
  "data": {
    "webhookId": "1"
  },
  "error": null
}
```

---

本文档会定期更新，以反映系统的最新API接口。