makemd/docs/02_API_Documentation.md

# API 文档

## 1. 认证 API

### 1.1 注册用户

**路径**: `/v1/auth/register`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| email | string | 是 | 邮箱 |
| role | string | 是 | 角色 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 1.2 用户登录

**路径**: `/v1/auth/login`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

## 2. 用户 API

### 2.1 创建用户

**路径**: `/v1/user`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
| email | string | 是 | 邮箱 |
| role | string | 是 | 角色 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 2.2 获取用户列表

**路径**: `/v1/user`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "ADMIN",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 2.3 获取用户详情

**路径**: `/v1/user/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 用户 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "ADMIN",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 2.4 更新用户

**路径**: `/v1/user/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 用户 ID |
| username | string | 否 | 用户名 |
| password | string | 否 | 密码 |
| email | string | 否 | 邮箱 |
| role | string | 否 | 角色 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "ADMIN",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 2.5 删除用户

**路径**: `/v1/user/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 用户 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

## 3. 商品 API

### 3.1 创建商品

**路径**: `/v1/product`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| title | string | 是 | 商品标题 |
| description | string | 否 | 商品描述 |
| mainImage | string | 否 | 商品主图 |
| platform | string | 否 | 平台 |
| platformProductId | string | 否 | 平台商品 ID |
| price | double | 否 | 价格 |
| costPrice | double | 否 | 成本价格 |
| quantity | int | 否 | 数量 |
| status | string | 否 | 状态 |
| phash | string | 否 | 图片哈希 |
| semanticHash | string | 否 | 语义哈希 |
| vectorEmbedding | string | 否 | 向量嵌入 |
| attributes | string | 否 | 属性 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 3.2 获取商品列表

**路径**: `/v1/product`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| platform | string | 否 | 平台 |
| status | string | 否 | 状态 |
| page | int | 否 | 页码，默认 1 |
| size | int | 否 | 每页数量，默认 10 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "商品标题",
      "description": "商品描述",
      "mainImage": "图片 URL",
      "platform": "平台",
      "platformProductId": "平台商品 ID",
      "price": 100.00,
      "costPrice": 80.00,
      "quantity": 100,
      "status": "ACTIVE",
      "phash": "图片哈希",
      "semanticHash": "语义哈希",
      "vectorEmbedding": "向量嵌入",
      "attributes": "属性",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "page": 1,
  "size": 10
}
```

### 3.3 获取商品详情

**路径**: `/v1/product/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 商品 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "商品标题",
    "description": "商品描述",
    "mainImage": "图片 URL",
    "platform": "平台",
    "platformProductId": "平台商品 ID",
    "price": 100.00,
    "costPrice": 80.00,
    "quantity": 100,
    "status": "ACTIVE",
    "phash": "图片哈希",
    "semanticHash": "语义哈希",
    "vectorEmbedding": "向量嵌入",
    "attributes": "属性",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 3.4 更新商品

**路径**: `/v1/product/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 商品 ID |
| title | string | 否 | 商品标题 |
| description | string | 否 | 商品描述 |
| mainImage | string | 否 | 商品主图 |
| platform | string | 否 | 平台 |
| platformProductId | string | 否 | 平台商品 ID |
| price | double | 否 | 价格 |
| costPrice | double | 否 | 成本价格 |
| quantity | int | 否 | 数量 |
| status | string | 否 | 状态 |
| phash | string | 否 | 图片哈希 |
| semanticHash | string | 否 | 语义哈希 |
| vectorEmbedding | string | 否 | 向量嵌入 |
| attributes | string | 否 | 属性 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "商品标题",
    "description": "商品描述",
    "mainImage": "图片 URL",
    "platform": "平台",
    "platformProductId": "平台商品 ID",
    "price": 100.00,
    "costPrice": 80.00,
    "quantity": 100,
    "status": "ACTIVE",
    "phash": "图片哈希",
    "semanticHash": "语义哈希",
    "vectorEmbedding": "向量嵌入",
    "attributes": "属性",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 3.5 删除商品

**路径**: `/v1/product/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 商品 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 3.6 商品清洗与本地化

**路径**: `/v1/product/{id}/wash-and-localize`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 商品 ID |
| tenantId | string | 是 | 租户 ID |
| targetMarket | string | 是 | 目标市场 |
| targetLang | string | 是 | 目标语言 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "商品标题 (Localized for 目标市场)",
    "description": "商品描述 (Localized for 目标市场)",
    "targetMarket": "目标市场",
    "targetLang": "目标语言",
    "status": "LOCALIZED"
  }
}
```

### 3.7 商品套利分析

**路径**: `/v1/product/{id}/analyze-arbitrage`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 商品 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "productId": 1,
    "price": 100.00,
    "costPrice": 80.00,
    "profitMargin": 20.0,
    "arbitrageOpportunity": true
  }
}
```

## 4. 订单 API

### 4.1 创建订单

**路径**: `/v1/order`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| shopId | string | 否 | 店铺 ID |
| platform | string | 否 | 平台 |
| platformOrderId | string | 否 | 平台订单 ID |
| status | string | 否 | 状态 |
| totalAmount | double | 否 | 总金额 |
| currency | string | 否 | 货币 |
| customerInfo | string | 否 | 客户信息 |
| items | string | 否 | 商品列表 |
| shippingAddress | string | 否 |  shipping 地址 |
| trackingNumber | string | 否 | 跟踪号 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 4.2 获取订单列表

**路径**: `/v1/order`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| platform | string | 否 | 平台 |
| status | string | 否 | 状态 |
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "shopId": "店铺 ID",
      "platform": "平台",
      "platformOrderId": "平台订单 ID",
      "status": "PENDING",
      "totalAmount": 100.00,
      "currency": "USD",
      "customerInfo": "客户信息",
      "items": "商品列表",
      "shippingAddress": "shipping 地址",
      "trackingNumber": "跟踪号",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 4.3 获取订单详情

**路径**: `/v1/order/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "shopId": "店铺 ID",
    "platform": "平台",
    "platformOrderId": "平台订单 ID",
    "status": "PENDING",
    "totalAmount": 100.00,
    "currency": "USD",
    "customerInfo": "客户信息",
    "items": "商品列表",
    "shippingAddress": "shipping 地址",
    "trackingNumber": "跟踪号",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 4.4 更新订单

**路径**: `/v1/order/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| status | string | 否 | 状态 |
| totalAmount | double | 否 | 总金额 |
| currency | string | 否 | 货币 |
| customerInfo | string | 否 | 客户信息 |
| items | string | 否 | 商品列表 |
| shippingAddress | string | 否 |  shipping 地址 |
| trackingNumber | string | 否 | 跟踪号 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "shopId": "店铺 ID",
    "platform": "平台",
    "platformOrderId": "平台订单 ID",
    "status": "PENDING",
    "totalAmount": 100.00,
    "currency": "USD",
    "customerInfo": "客户信息",
    "items": "商品列表",
    "shippingAddress": "shipping 地址",
    "trackingNumber": "跟踪号",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 4.5 删除订单

**路径**: `/v1/order/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 4.6 订单状态流转

**路径**: `/v1/order/{id}/transition`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| status | string | 是 | 目标状态 |
| reason | string | 否 | 流转原因 |

**返回格式**:
```json
{
  "success": true
}
```

### 4.7 批量更新订单

**路径**: `/v1/order/batch-update`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| orderIds | array | 是 | 订单 ID 列表 |
| updates | object | 是 | 更新内容 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "successCount": 1,
    "failureCount": 0,
    "totalCount": 1
  }
}
```

### 4.8 批量审核订单

**路径**: `/v1/order/batch-audit`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| orderIds | array | 是 | 订单 ID 列表 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "successCount": 1,
    "failureCount": 0,
    "totalCount": 1
  }
}
```

### 4.9 批量发货

**路径**: `/v1/order/batch-ship`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| orderIds | array | 是 | 订单 ID 列表 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "successCount": 1,
    "failureCount": 0,
    "totalCount": 1
  }
}
```

### 4.10 标记订单异常

**路径**: `/v1/order/{id}/exception`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| reason | string | 是 | 异常原因 |

**返回格式**:
```json
{
  "success": true
}
```

### 4.11 自动改派订单

**路径**: `/v1/order/{id}/auto-reroute`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 4.12 重试异常订单

**路径**: `/v1/order/{id}/retry`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 4.13 取消订单

**路径**: `/v1/order/{id}/cancel`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| reason | string | 是 | 取消原因 |

**返回格式**:
```json
{
  "success": true
}
```

### 4.14 申请退款

**路径**: `/v1/order/{id}/refund`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| reason | string | 是 | 退款原因 |
| amount | double | 是 | 退款金额 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "refundId": "REFUND_1234567890"
  }
}
```

### 4.15 审批退款

**路径**: `/v1/order/{id}/refund/approve`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| approved | boolean | 是 | 是否批准 |
| note | string | 否 | 审批备注 |

**返回格式**:
```json
{
  "success": true
}
```

### 4.16 申请售后

**路径**: `/v1/order/{id}/after-sales`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| type | string | 是 | 售后类型 |
| reason | string | 是 | 售后原因 |
| items | array | 是 | 售后商品列表 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "afterSalesId": "AFTER_SALES_1234567890"
  }
}
```

### 4.17 处理售后

**路径**: `/v1/order/{id}/after-sales/process`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |
| action | string | 是 | 处理动作 |
| note | string | 否 | 处理备注 |

**返回格式**:
```json
{
  "success": true
}
```

### 4.18 完成订单

**路径**: `/v1/order/{id}/complete`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 订单 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 4.19 获取订单统计

**路径**: `/v1/order/stats`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "totalOrders": 100,
    "pendingOrders": 20,
    "shippedOrders": 50,
    "completedOrders": 30
  }
}
```

## 5. 支付 API

### 5.1 创建支付

**路径**: `/v1/payment`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| orderId | long | 否 | 订单 ID |
| paymentMethod | string | 否 | 支付方式 |
| amount | double | 否 | 金额 |
| currency | string | 否 | 货币 |
| status | string | 否 | 状态 |
| transactionId | string | 否 | 交易 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 5.2 获取支付列表

**路径**: `/v1/payment`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| orderId | long | 否 | 订单 ID |
| status | string | 否 | 状态 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "orderId": 1,
      "paymentMethod": "credit_card",
      "amount": 100.00,
      "currency": "USD",
      "status": "COMPLETED",
      "transactionId": "TXN_1234567890",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 5.3 获取支付详情

**路径**: `/v1/payment/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 支付 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "orderId": 1,
    "paymentMethod": "credit_card",
    "amount": 100.00,
    "currency": "USD",
    "status": "COMPLETED",
    "transactionId": "TXN_1234567890",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 5.4 更新支付

**路径**: `/v1/payment/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 支付 ID |
| paymentMethod | string | 否 | 支付方式 |
| amount | double | 否 | 金额 |
| currency | string | 否 | 货币 |
| status | string | 否 | 状态 |
| transactionId | string | 否 | 交易 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "orderId": 1,
    "paymentMethod": "credit_card",
    "amount": 100.00,
    "currency": "USD",
    "status": "COMPLETED",
    "transactionId": "TXN_1234567890",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 5.5 删除支付

**路径**: `/v1/payment/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 支付 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

## 6. 物流 API

### 6.1 创建物流

**路径**: `/v1/logistics`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| orderId | long | 否 | 订单 ID |
| shippingMethod | string | 否 | 物流方式 |
| trackingNumber | string | 否 | 跟踪号 |
| carrier | string | 否 | 物流公司 |
| status | string | 否 | 状态 |
| estimatedDeliveryDate | string | 否 | 预计送达日期 |
| actualDeliveryDate | string | 否 | 实际送达日期 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 6.2 获取物流列表

**路径**: `/v1/logistics`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| orderId | long | 否 | 订单 ID |
| status | string | 否 | 状态 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "orderId": 1,
      "shippingMethod": "standard",
      "trackingNumber": "TRK_1234567890",
      "carrier": "UPS",
      "status": "DELIVERED",
      "estimatedDeliveryDate": "2024-01-10T00:00:00.000Z",
      "actualDeliveryDate": "2024-01-09T00:00:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-09T00:00:00.000Z"
    }
  ]
}
```

### 6.3 获取物流详情

**路径**: `/v1/logistics/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 物流 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "orderId": 1,
    "shippingMethod": "standard",
    "trackingNumber": "TRK_1234567890",
    "carrier": "UPS",
    "status": "DELIVERED",
    "estimatedDeliveryDate": "2024-01-10T00:00:00.000Z",
    "actualDeliveryDate": "2024-01-09T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-09T00:00:00.000Z"
  }
}
```

### 6.4 更新物流

**路径**: `/v1/logistics/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 物流 ID |
| shippingMethod | string | 否 | 物流方式 |
| trackingNumber | string | 否 | 跟踪号 |
| carrier | string | 否 | 物流公司 |
| status | string | 否 | 状态 |
| estimatedDeliveryDate | string | 否 | 预计送达日期 |
| actualDeliveryDate | string | 否 | 实际送达日期 |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "orderId": 1,
    "shippingMethod": "standard",
    "trackingNumber": "TRK_1234567890",
    "carrier": "UPS",
    "status": "DELIVERED",
    "estimatedDeliveryDate": "2024-01-10T00:00:00.000Z",
    "actualDeliveryDate": "2024-01-09T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-09T00:00:00.000Z"
  }
}
```

### 6.5 删除物流

**路径**: `/v1/logistics/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 物流 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```

## 7. 监控 API

### 7.1 获取系统健康状态

**路径**: `/v1/monitoring/health`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "status": "UP",
    "components": {
      "database": {
        "status": "UP"
      },
      "cache": {
        "status": "UP"
      }
    }
  }
}
```

### 7.2 获取性能指标

**路径**: `/v1/monitoring/metrics`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "jvm": {
      "memory": {
        "used": 1024,
        "total": 2048
      }
    },
    "system": {
      "cpu": {
        "usage": 0.5
      }
    }
  }
}
```

### 7.3 获取服务状态

**路径**: `/v1/monitoring/services`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "authService": {
      "status": "UP"
    },
    "productService": {
      "status": "UP"
    },
    "orderService": {
      "status": "UP"
    }
  }
}
```

### 7.4 获取数据库状态

**路径**: `/v1/monitoring/database`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "status": "UP",
    "connections": {
      "active": 5,
      "max": 10
    }
  }
}
```

### 7.5 获取缓存状态

**路径**: `/v1/monitoring/cache`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "status": "UP",
    "keys": 100
  }
}
```

### 7.6 获取系统统计信息

**路径**: `/v1/monitoring/stats`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "data": {
    "requests": {
      "total": 1000,
      "success": 990,
      "error": 10
    }
  }
}
```

### 7.7 Ping 测试

**路径**: `/v1/monitoring/ping`

**方法**: `GET`

**返回格式**:
```json
{
  "success": true,
  "message": "Pong",
  "timestamp": 1234567890
}
```

## 8. 告警 API

### 8.1 创建告警

**路径**: `/v1/alerts`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| alertType | string | 否 | 告警类型 |
| severity | string | 否 | 严重程度 |
| message | string | 否 | 告警消息 |
| status | string | 否 | 状态 |
| source | string | 否 | 告警来源 |
| threshold | string | 否 | 阈值 |
| actualValue | string | 否 | 实际值 |

**返回格式**:
```json
{
  "success": true,
  "alertId": 1
}
```

### 8.2 获取告警列表

**路径**: `/v1/alerts`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| status | string | 否 | 状态 |
| severity | string | 否 | 严重程度 |
| alertType | string | 否 | 告警类型 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenantId": "租户 ID",
      "alertType": "system",
      "severity": "high",
      "message": "系统异常",
      "status": "ACTIVE",
      "source": "monitoring",
      "threshold": "90%",
      "actualValue": "95%",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "resolvedAt": null
    }
  ]
}
```

### 8.3 获取告警详情

**路径**: `/v1/alerts/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 告警 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "tenantId": "租户 ID",
    "alertType": "system",
    "severity": "high",
    "message": "系统异常",
    "status": "ACTIVE",
    "source": "monitoring",
    "threshold": "90%",
    "actualValue": "95%",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "resolvedAt": null
  }
}
```

### 8.4 解决告警

**路径**: `/v1/alerts/{id}/resolve`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 告警 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "message": "Alert resolved successfully"
}
```

### 8.5 更新告警状态

**路径**: `/v1/alerts/{id}/status`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 告警 ID |
| tenantId | string | 是 | 租户 ID |
| status | string | 是 | 新状态 |

**返回格式**:
```json
{
  "success": true,
  "message": "Alert status updated successfully"
}
```

### 8.6 获取告警统计

**路径**: `/v1/alerts/stats`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| startDate | string | 是 | 开始日期 |
| endDate | string | 是 | 结束日期 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "totalAlerts": 10,
    "severityStats": {
      "high": 2,
      "medium": 5,
      "low": 3
    },
    "statusStats": {
      "ACTIVE": 3,
      "RESOLVED": 7
    },
    "typeStats": {
      "system": 5,
      "application": 3,
      "database": 2
    },
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}
```

### 8.7 检查阈值

**路径**: `/v1/alerts/check-thresholds`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "message": "Thresholds checked successfully"
}
```

## 9. 审计 API

### 9.1 获取审计日志列表

**路径**: `/v1/audit`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| shopId | string | 否 | 店铺 ID |
| userId | long | 否 | 用户 ID |
| action | string | 否 | 操作类型 |
| resourceType | string | 否 | 资源类型 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenantId": "租户 ID",
      "shopId": "店铺 ID",
      "userId": 1,
      "action": "create",
      "resourceType": "product",
      "resourceId": "1",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0",
      "details": "创建商品",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 9.2 获取审计日志详情

**路径**: `/v1/audit/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 审计日志 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "tenantId": "租户 ID",
    "shopId": "店铺 ID",
    "userId": 1,
    "action": "create",
    "resourceType": "product",
    "resourceId": "1",
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0",
    "details": "创建商品",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

## 10. 配置 API

### 10.1 创建配置

**路径**: `/v1/config`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 否 | 租户 ID |
| shopId | string | 否 | 店铺 ID |
| configKey | string | 是 | 配置键 |
| configValue | string | 是 | 配置值 |
| configType | string | 否 | 配置类型 |
| description | string | 否 | 配置描述 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1
  }
}
```

### 10.2 获取配置列表

**路径**: `/v1/config`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 否 | 租户 ID |
| shopId | string | 否 | 店铺 ID |
| configType | string | 否 | 配置类型 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenantId": "租户 ID",
      "shopId": "店铺 ID",
      "configKey": "api_key",
      "configValue": "value",
      "configType": "string",
      "description": "API 密钥",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

### 10.3 获取配置详情

**路径**: `/v1/config/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 配置 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "tenantId": "租户 ID",
    "shopId": "店铺 ID",
    "configKey": "api_key",
    "configValue": "value",
    "configType": "string",
    "description": "API 密钥",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 10.4 更新配置

**路径**: `/v1/config/{id}`

**方法**: `PUT`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 配置 ID |
| configValue | string | 否 | 配置值 |
| configType | string | 否 | 配置类型 |
| description | string | 否 | 配置描述 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "tenantId": "租户 ID",
    "shopId": "店铺 ID",
    "configKey": "api_key",
    "configValue": "new_value",
    "configType": "string",
    "description": "API 密钥",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-02T00:00:00.000Z"
  }
}
```

### 10.5 删除配置

**路径**: `/v1/config/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | long | 是 | 配置 ID |

**返回格式**:
```json
{
  "success": true
}
```

### 10.6 根据键获取配置

**路径**: `/v1/config/key/{key}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| key | string | 是 | 配置键 |
| tenantId | string | 否 | 租户 ID |
| shopId | string | 否 | 店铺 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "tenantId": "租户 ID",
    "shopId": "店铺 ID",
    "configKey": "api_key",
    "configValue": "value",
    "configType": "string",
    "description": "API 密钥",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

## 11. 数据 API

### 11.1 导入数据

**路径**: `/v1/data/import`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| dataType | string | 是 | 数据类型 |
| data | array | 是 | 数据列表 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "importedCount": 10,
    "failedCount": 0
  }
}
```

### 11.2 导出数据

**路径**: `/v1/data/export`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| dataType | string | 是 | 数据类型 |
| filters | object | 否 | 过滤条件 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "数据 1"
    }
  ]
}
```

### 11.3 同步数据

**路径**: `/v1/data/sync`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| source | string | 是 | 数据源 |
| target | string | 是 | 目标 |
| filters | object | 否 | 过滤条件 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "syncedCount": 10,
    "failedCount": 0
  }
}
```

## 12. 报表 API

### 12.1 生成报表

**路径**: `/v1/report/generate`

**方法**: `POST`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| reportType | string | 是 | 报表类型 |
| startDate | string | 是 | 开始日期 |
| endDate | string | 是 | 结束日期 |
| filters | object | 否 | 过滤条件 |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "reportId": "REPORT_1234567890",
    "url": "http://example.com/report/REPORT_1234567890"
  }
}
```

### 12.2 获取报表列表

**路径**: `/v1/report`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| tenantId | string | 是 | 租户 ID |
| reportType | string | 否 | 报表类型 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**返回格式**:
```json
{
  "success": true,
  "data": [
    {
      "id": "REPORT_1234567890",
      "reportType": "sales",
      "startDate": "2024-01-01",
      "endDate": "2024-01-31",
      "createdAt": "2024-02-01T00:00:00.000Z",
      "url": "http://example.com/report/REPORT_1234567890"
    }
  ]
}
```

### 12.3 获取报表详情

**路径**: `/v1/report/{id}`

**方法**: `GET`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 报表 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true,
  "data": {
    "id": "REPORT_1234567890",
    "reportType": "sales",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "createdAt": "2024-02-01T00:00:00.000Z",
    "url": "http://example.com/report/REPORT_1234567890"
  }
}
```

### 12.4 删除报表

**路径**: `/v1/report/{id}`

**方法**: `DELETE`

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| id | string | 是 | 报表 ID |
| tenantId | string | 是 | 租户 ID |

**返回格式**:
```json
{
  "success": true
}
```