aiotagro/jiebanke

Fork 0

Files

ylweng 47c816270d 重构动物模型和路由系统，优化查询逻辑并新增商户和促销活动功能

2025-09-22 02:04:07 +08:00

9.9 KiB

Raw Blame History

商户管理API接口文档

概述

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

基础信息

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

数据模型

商户信息 (Merchant)

{
  "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`

请求示例:

GET /api/v1/merchants?page=1&limit=20&keyword=示例&status=active&type=company

响应示例:

{
  "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
  }
}

错误响应:

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

2. 获取商户详情

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

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

路径参数:

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

请求示例:

GET /api/v1/merchants/1

响应示例:

{
  "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
  }
}

错误响应:

{
  "success": false,
  "message": "商户不存在"
}

3. 创建商户

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

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

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

请求体:

{
  "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	-	商户描述

响应示例:

{
  "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

请求体:

{
  "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`

响应示例:

{
  "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

请求示例:

DELETE /api/v1/merchants/1

响应示例:

{
  "success": true,
  "message": "商户删除成功"
}

6. 获取商户统计信息

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

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

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

请求示例:

GET /api/v1/merchants/statistics

响应示例:

{
  "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	服务器内部错误

通用错误响应格式

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

使用示例

JavaScript (Axios)

// 获取商户列表
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

# 获取商户列表
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"
  }'

注意事项

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

更新日志

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

9.9 KiB Raw Blame History Unescape Escape

商户管理API接口文档

概述

基础信息

数据模型

商户信息 (Merchant)

字段说明

接口列表

1. 获取商户列表

2. 获取商户详情

3. 创建商户

4. 更新商户信息

5. 删除商户

6. 获取商户统计信息

错误码说明

通用错误响应格式

使用示例

JavaScript (Axios)

cURL

注意事项

更新日志

9.9 KiB

Raw Blame History