jiebanke/backend/docs/商户管理API接口文档.md

# 商户管理API接口文档

## 概述

商户管理模块提供了完整的商户信息管理功能，包括商户的增删改查、统计信息等操作。所有接口均遵循RESTful API设计规范。

## 基础信息

- **基础URL**: `/api/v1/merchants`
- **认证方式**: Bearer Token（部分接口需要管理员权限）
- **数据格式**: JSON
- **字符编码**: UTF-8

## 数据模型

### 商户信息 (Merchant)

```json
{
  "id": 1,
  "name": "示例商户",
  "type": "company",
  "contact_person": "张三",
  "contact_phone": "13800138000",
  "email": "merchant@example.com",
  "address": "北京市朝阳区示例街道123号",
  "description": "这是一个示例商户",
  "status": "active",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | integer | - | 商户ID（系统自动生成） |
| name | string | ✓ | 商户名称 |
| type | string | ✓ | 商户类型：`individual`（个人）、`company`（企业） |
| contact_person | string | ✓ | 联系人姓名 |
| contact_phone | string | ✓ | 联系电话 |
| email | string | - | 邮箱地址 |
| address | string | - | 地址 |
| description | string | - | 商户描述 |
| status | string | - | 状态：`active`（活跃）、`inactive`（非活跃）、`banned`（禁用） |
| created_at | datetime | - | 创建时间 |
| updated_at | datetime | - | 更新时间 |

## 接口列表

### 1. 获取商户列表

**接口地址**: `GET /api/v1/merchants`

**接口描述**: 获取商户列表，支持分页、搜索和筛选

**请求参数**:

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| page | integer | - | 1 | 页码（最小值：1） |
| limit | integer | - | 20 | 每页数量（范围：1-100） |
| keyword | string | - | - | 搜索关键词（匹配商户名称、联系人、电话） |
| status | string | - | - | 状态筛选：`active`、`inactive`、`banned` |
| type | string | - | - | 类型筛选：`individual`、`company` |

**请求示例**:
```http
GET /api/v1/merchants?page=1&limit=20&keyword=示例&status=active&type=company
```

**响应示例**:
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "示例商户",
      "type": "company",
      "contact_person": "张三",
      "contact_phone": "13800138000",
      "email": "merchant@example.com",
      "address": "北京市朝阳区示例街道123号",
      "description": "这是一个示例商户",
      "status": "active",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "请求参数错误",
  "errors": [
    {
      "field": "page",
      "message": "页码必须是正整数"
    }
  ]
}
```

### 2. 获取商户详情

**接口地址**: `GET /api/v1/merchants/{merchantId}`

**接口描述**: 根据商户ID获取商户详细信息

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| merchantId | integer | ✓ | 商户ID |

**请求示例**:
```http
GET /api/v1/merchants/1
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "示例商户",
    "type": "company",
    "contact_person": "张三",
    "contact_phone": "13800138000",
    "email": "merchant@example.com",
    "address": "北京市朝阳区示例街道123号",
    "description": "这是一个示例商户",
    "status": "active",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z",
    "animal_count": 15,
    "order_count": 128
  }
}
```

**错误响应**:
```json
{
  "success": false,
  "message": "商户不存在"
}
```

### 3. 创建商户

**接口地址**: `POST /api/v1/merchants`

**接口描述**: 创建新商户（需要管理员权限）

**认证要求**: Bearer Token + 管理员权限

**请求体**:
```json
{
  "name": "新商户",
  "type": "company",
  "contact_person": "李四",
  "contact_phone": "13900139000",
  "email": "newmerchant@example.com",
  "address": "上海市浦东新区示例路456号",
  "description": "这是一个新商户"
}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | ✓ | 商户名称 |
| type | string | ✓ | 商户类型：`individual`、`company` |
| contact_person | string | ✓ | 联系人姓名 |
| contact_phone | string | ✓ | 联系电话 |
| email | string | - | 邮箱地址（需符合邮箱格式） |
| address | string | - | 地址 |
| description | string | - | 商户描述 |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 2,
    "name": "新商户",
    "type": "company",
    "contact_person": "李四",
    "contact_phone": "13900139000",
    "email": "newmerchant@example.com",
    "address": "上海市浦东新区示例路456号",
    "description": "这是一个新商户",
    "status": "active",
    "created_at": "2024-01-01T12:00:00.000Z",
    "updated_at": "2024-01-01T12:00:00.000Z"
  },
  "message": "商户创建成功"
}
```

### 4. 更新商户信息

**接口地址**: `PUT /api/v1/merchants/{merchantId}`

**接口描述**: 更新商户信息（需要管理员权限）

**认证要求**: Bearer Token + 管理员权限

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| merchantId | integer | ✓ | 商户ID |

**请求体**:
```json
{
  "name": "更新后的商户名称",
  "contact_person": "王五",
  "contact_phone": "13700137000",
  "status": "inactive"
}
```

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | - | 商户名称 |
| type | string | - | 商户类型：`individual`、`company` |
| contact_person | string | - | 联系人姓名 |
| contact_phone | string | - | 联系电话 |
| email | string | - | 邮箱地址 |
| address | string | - | 地址 |
| description | string | - | 商户描述 |
| status | string | - | 状态：`active`、`inactive`、`banned` |

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "更新后的商户名称",
    "type": "company",
    "contact_person": "王五",
    "contact_phone": "13700137000",
    "email": "merchant@example.com",
    "address": "北京市朝阳区示例街道123号",
    "description": "这是一个示例商户",
    "status": "inactive",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T15:30:00.000Z"
  },
  "message": "商户信息更新成功"
}
```

### 5. 删除商户

**接口地址**: `DELETE /api/v1/merchants/{merchantId}`

**接口描述**: 删除商户（需要管理员权限）

**认证要求**: Bearer Token + 管理员权限

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| merchantId | integer | ✓ | 商户ID |

**请求示例**:
```http
DELETE /api/v1/merchants/1
```

**响应示例**:
```json
{
  "success": true,
  "message": "商户删除成功"
}
```

### 6. 获取商户统计信息

**接口地址**: `GET /api/v1/merchants/statistics`

**接口描述**: 获取商户统计信息（需要管理员权限）

**认证要求**: Bearer Token + 管理员权限

**请求示例**:
```http
GET /api/v1/merchants/statistics
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "total": 150,
    "active": 120,
    "inactive": 25,
    "banned": 5,
    "individual": 80,
    "company": 70
  }
}
```

## 错误码说明

| HTTP状态码 | 错误码 | 说明 |
|------------|--------|------|
| 400 | BAD_REQUEST | 请求参数错误 |
| 401 | UNAUTHORIZED | 未授权，需要登录 |
| 403 | FORBIDDEN | 权限不足，需要管理员权限 |
| 404 | NOT_FOUND | 商户不存在 |
| 409 | CONFLICT | 商户信息冲突（如名称重复） |
| 500 | INTERNAL_ERROR | 服务器内部错误 |

## 通用错误响应格式

```json
{
  "success": false,
  "message": "错误描述",
  "code": "ERROR_CODE",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "errors": [
    {
      "field": "字段名",
      "message": "字段错误描述"
    }
  ]
}
```

## 使用示例

### JavaScript (Axios)

```javascript
// 获取商户列表
const getMerchants = async (params = {}) => {
  try {
    const response = await axios.get('/api/v1/merchants', { params });
    return response.data;
  } catch (error) {
    console.error('获取商户列表失败:', error.response.data);
    throw error;
  }
};

// 创建商户
const createMerchant = async (merchantData) => {
  try {
    const response = await axios.post('/api/v1/merchants', merchantData, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('创建商户失败:', error.response.data);
    throw error;
  }
};
```

### cURL

```bash
# 获取商户列表
curl -X GET "http://localhost:3200/api/v1/merchants?page=1&limit=20" \
  -H "Content-Type: application/json"

# 创建商户
curl -X POST "http://localhost:3200/api/v1/merchants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "测试商户",
    "type": "company",
    "contact_person": "测试联系人",
    "contact_phone": "13800138000"
  }'
```

## 注意事项

1. **权限控制**: 创建、更新、删除商户以及获取统计信息需要管理员权限
2. **数据验证**: 所有输入数据都会进行严格验证，确保数据完整性
3. **分页限制**: 列表接口每页最多返回100条记录
4. **搜索功能**: 关键词搜索支持模糊匹配商户名称、联系人和电话
5. **状态管理**: 商户状态变更会影响相关业务功能的可用性
6. **数据关联**: 删除商户前请确保没有关联的动物或订单数据

## 更新日志

- **v1.0.0** (2024-01-01): 初始版本，包含基础的商户管理功能