zhouhui.jiang / test_cursor

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
API接口文档.md 31.1 KB

Apple ERP 系统 API 接口文档

概述

本文档描述了 Apple ERP 系统的后端 API 接口，包括认证管理、用户管理、角色管理、菜单管理、字典管理、日志管理等模块的接口规范。

基础信息：

  • 基础URL: http://localhost:8083
  • 认证方式: JWT Bearer Token
  • 响应格式: JSON
  • 字符编码: UTF-8

通用响应格式

所有接口都遵循统一的响应格式：

{
  "code": 200,
  "message": "操作成功",
  "data": {}
}

响应字段说明：

  • code: 响应状态码，200表示成功，其他表示失败
  • message: 响应消息
  • data: 响应数据，具体内容根据接口而定

1. 认证管理 (AuthController)

1.1 用户登录

接口路径： POST /api/auth/login

功能描述： 用户登录获取JWT令牌

请求参数：

{
  "username": "admin",
  "password": "123456"
}

响应示例：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin"
  }
}

1.2 刷新令牌

接口路径： POST /api/auth/refresh

功能描述： 使用刷新令牌获取新的访问令牌

请求参数：

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例：

{
  "code": 200,
  "message": "令牌刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "admin"
  }
}

1.3 用户登出

接口路径： POST /api/auth/logout

功能描述： 用户登出清除认证信息和缓存

请求头： Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "登出成功",
  "data": null
}

1.4 获取用户信息

接口路径： GET /api/auth/userinfo

功能描述： 获取当前登录用户的详细信息

请求头： Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "username": "admin",
    "authorities": ["ROLE_ADMIN"]
  }
}

2. 用户管理 (SysUserController)

2.1 获取用户列表

接口路径： GET /api/system/user/list

功能描述： 支持分页查询和条件筛选，包括用户名、真实姓名、手机号、邮箱、状态、创建时间范围等条件

权限要求： sys:user:list

请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Integer | 否 | 页码，默认1 | | pageSize | Integer | 否 | 每页大小，默认10 | | username | String | 否 | 用户名，支持模糊查询 | | realName | String | 否 | 真实姓名，支持模糊查询 | | phone | String | 否 | 手机号，支持模糊查询 | | email | String | 否 | 邮箱，支持模糊查询 | | status | Integer | 否 | 用户状态，0-停用，1-启用 | | startTime | String | 否 | 开始时间，创建时间范围查询的起始时间，格式：yyyy-MM-dd，自动转换为当天00:00:00 | | endTime | String | 否 | 结束时间，创建时间范围查询的结束时间，格式：yyyy-MM-dd，自动转换为当天23:59:59 |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "userId": 1,
        "username": "admin",
        "realName": "管理员",
        "phone": "13800138000",
        "email": "admin@example.com",
        "status": 1,
        "statusText": "正常",
        "roles": [
          {
            "roleId": 1,
            "roleName": "超级管理员"
          }
        ],
        "createTime": "2024-01-01T00:00:00",
        "updateTime": "2024-01-01T00:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 10
  }
}

2.2 获取用户详情

接口路径： GET /api/system/user/{userId}

功能描述： 根据用户ID获取用户的详细信息，包括用户基本资料和分配的角色信息

权限要求： sys:user:query

路径参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userId | Long | 是 | 用户ID |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 1,
    "username": "admin",
    "realName": "管理员",
    "phone": "13800138000",
    "email": "admin@example.com",
    "status": 1,
    "statusText": "正常",
    "roles": [
      {
        "roleId": 1,
        "roleName": "超级管理员"
      }
    ],
    "createTime": "2024-01-01T00:00:00",
    "updateTime": "2024-01-01T00:00:00"
  }
}

2.3 新增用户

接口路径： POST /api/system/user/add

功能描述： 创建新用户，包括用户基本信息和角色分配

权限要求： sys:user:add

请求参数：

{
  "username": "testuser",
  "password": "123456",
  "realName": "测试用户",
  "phone": "13800138001",
  "email": "test@example.com",
  "status": 1,
  "roleIds": [2, 3]
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

2.4 修改用户

接口路径： POST /api/system/user/edit

功能描述： 更新用户基本信息，包括用户资料和角色分配

权限要求： sys:user:edit

请求参数：

{
  "userId": 2,
  "username": "testuser",
  "realName": "测试用户",
  "phone": "13800138001",
  "email": "test@example.com",
  "status": 1,
  "roleIds": [2, 3]
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

2.5 删除用户

接口路径： DELETE /api/system/user/{userIds}

功能描述： 批量删除用户，会同时清理用户角色关联关系

权限要求： sys:user:remove

路径参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userIds | Long[] | 是 | 需要删除的用户ID数组 |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

2.6 重置密码

接口路径： PUT /api/system/user/resetPwd

功能描述： 重置指定用户的登录密码

权限要求： sys:user:resetPwd

请求参数：

{
  "userId": 2,
  "newPassword": "newpassword123"
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

2.7 修改用户状态

接口路径： POST /api/system/user/changeStatus

功能描述： 启用或停用用户账户

权限要求： sys:user:edit

请求参数：

{
  "userId": 2,
  "status": 0
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3. 角色管理 (SysRoleController)

3.1 获取角色列表

接口路径： GET /api/system/role/list

功能描述： 支持分页查询和条件筛选，包括角色名称、角色编码、状态等条件

权限要求： sys:role:list

请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Integer | 否 | 页码，默认1 | | pageSize | Integer | 否 | 每页大小，默认10 | | roleName | String | 否 | 角色名称，支持模糊查询 | | roleCode | String | 否 | 角色编码，支持模糊查询 | | status | Integer | 否 | 角色状态，0-停用，1-启用 |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "roleId": 1,
        "roleCode": "admin",
        "roleName": "超级管理员",
        "status": 1,
        "statusText": "正常",
        "remark": "系统超级管理员",
        "createTime": "2024-01-01T00:00:00",
        "updateTime": "2024-01-01T00:00:00"
      }
    ],
    "total": 1,
    "current": 1,
    "size": 10
  }
}

3.2 获取角色详情

接口路径： GET /api/system/role/{roleId}

功能描述： 根据角色ID获取角色的详细信息，包括角色基本资料和分配的菜单权限

权限要求： sys:role:query

路径参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | roleId | Long | 是 | 角色ID |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "roleId": 1,
    "roleCode": "admin",
    "roleName": "超级管理员",
    "status": 1,
    "statusText": "正常",
    "menuIds": [1, 2, 3, 4, 5],
    "remark": "系统超级管理员",
    "createTime": "2024-01-01T00:00:00",
    "updateTime": "2024-01-01T00:00:00"
  }
}

3.3 新增角色

接口路径： POST /api/system/role/add

功能描述： 创建新角色，包括角色基本信息和菜单权限分配

权限要求： sys:role:add

请求参数：

{
  "roleCode": "testrole",
  "roleName": "测试角色",
  "status": 1,
  "remark": "测试角色描述",
  "menuIds": [1, 2, 3]
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.4 修改角色

接口路径： POST /api/system/role/edit

功能描述： 更新角色基本信息，包括角色资料和菜单权限分配

权限要求： sys:role:edit

请求参数：

{
  "roleId": 2,
  "roleCode": "testrole",
  "roleName": "测试角色",
  "status": 1,
  "remark": "测试角色描述",
  "menuIds": [1, 2, 3]
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.5 删除角色

接口路径： DELETE /api/system/role/{roleIds}

功能描述： 批量删除角色，会同时清理角色与用户、菜单的关联关系

权限要求： sys:role:remove

路径参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | roleIds | Long[] | 是 | 需要删除的角色ID数组 |

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

3.6 修改角色状态

接口路径： POST /api/system/role/changeStatus

功能描述： 启用或停用角色

权限要求： sys:role:edit

请求参数：

{
  "roleId": 2,
  "status": 0
}

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

4. 测试接口 (TestController)

4.1 公开接口测试

接口路径： GET /api/test/public

功能描述： 无需认证的公开接口

响应示例：

{
  "code": 200,
  "message": "公开接口测试成功",
  "data": {
    "message": "这是一个公开接口",
    "timestamp": 1640995200000
  }
}

4.2 认证接口测试

接口路径： GET /api/test/auth

功能描述： 需要JWT令牌认证的接口

请求头： Authorization: Bearer {token}

响应示例：

{
  "code": 200,
  "message": "认证接口测试成功",
  "data": {
    "message": "这是一个需要认证的接口",
    "timestamp": 1640995200000
  }
}

4.3 管理员接口测试

接口路径： GET /api/test/admin

功能描述： 需要ADMIN角色权限的接口

请求头： Authorization: Bearer {token}

权限要求： ROLE_ADMIN

响应示例：

{
  "code": 200,
  "message": "管理员接口测试成功",
  "data": {
    "message": "这是一个需要管理员权限的接口",
    "timestamp": 1640995200000
  }
}

4.4 权限接口测试

接口路径： GET /api/test/permission

功能描述： 需要特定权限的接口

请求头： Authorization: Bearer {token}

权限要求： sys:user:list

响应示例：

{
  "code": 200,
  "message": "权限接口测试成功",
  "data": {
    "message": "这是一个需要特定权限的接口",
    "timestamp": 1640995200000
  }
}

5. 错误码说明

错误码 说明
200 操作成功
400 请求参数错误
401 未认证或认证失败
403 权限不足
404 资源不存在
409 数据冲突（如用户名已存在）
500 服务器内部错误

6. 权限说明

6.1 用户管理权限

  • sys:user:list - 查看用户列表
  • sys:user:query - 查看用户详情
  • sys:user:add - 新增用户
  • sys:user:edit - 修改用户
  • sys:user:remove - 删除用户
  • sys:user:resetPwd - 重置密码

6.2 角色管理权限

  • sys:role:list - 查看角色列表
  • sys:role:query - 查看角色详情
  • sys:role:add - 新增角色
  • sys:role:edit - 修改角色
  • sys:role:remove - 删除角色

6.3 字典管理权限

  • sys:dict:list - 查看字典列表
  • sys:dict:query - 查看字典详情
  • sys:dict:add - 新增字典
  • sys:dict:edit - 修改字典
  • sys:dict:remove - 删除字典

7. 使用说明

7.1 认证流程

  1. 调用登录接口获取JWT令牌
  2. 在后续请求的Header中携带令牌：Authorization: Bearer {token}
  3. 令牌过期时使用刷新令牌获取新令牌
  4. 登出时调用登出接口清除认证信息

7.2 分页查询

所有列表接口都支持分页查询，使用以下参数：

  • pageNum: 页码，从1开始
  • pageSize: 每页大小，建议10-50之间

7.3 数据验证

  • 所有必填字段都会进行验证
  • 字符串长度、邮箱格式等都有相应验证规则
  • 唯一性字段（如用户名、角色编码）会进行重复性检查

7.4 安全限制

  • 超级管理员用户（ID=1）和角色（ID=1）不允许删除
  • 超级管理员状态不允许修改
  • 所有操作都会记录操作日志

7. 产品管理 (ProductInfoController)

7.1 分页查询产品列表

接口路径： GET /api/system/product/list

功能描述： 根据条件分页查询产品列表

权限要求： product:list

请求参数：

参数名 类型 必填 描述 示例
productCode String 否 产品编码 APL-IP15-128G-BK
productName String 否 产品名称 iPhone 15
productModel String 否 产品型号 A2848
productType String 否 产品类别 iPhone
storageCapacity String 否 存储容量 128GB
color String 否 产品颜色 黑色
saleStatus Integer 否 销售状态（0-下架/1-在售/2-预售） 1
rebateFlag Integer 否 是否参与返利（0-否/1-是） 1
minPrice BigDecimal 否 最低价格 1000.00
maxPrice BigDecimal 否 最高价格 10000.00
saleStartDateBegin String 否 销售起始日期开始 2024-01-01
saleStartDateEnd String 否 销售起始日期结束 2024-12-31
saleEndDateBegin String 否 销售终止日期开始 2024-01-01
saleEndDateEnd String 否 销售终止日期结束 2024-12-31
pageNum Integer 否 页码 1
pageSize Integer 否 每页大小 10

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "productId": 1,
        "productCode": "APL-IP15-128G-BK",
        "productName": "iPhone 15",
        "productModel": "A2848",
        "productType": "iPhone",
        "storageCapacity": "128GB",
        "color": "黑色",
        "productImgUrl": "https://example.com/iphone15.jpg",
        "officialPrice": 5999.00,
        "saleStatus": 1,
        "rebateFlag": 1,
        "saleStartDate": "2023-09-15",
        "saleEndDate": "2024-12-31",
        "remark": "iPhone 15 128GB 黑色",
        "createBy": "admin",
        "createTime": "2024-01-15 10:30:00",
        "updateBy": "admin",
        "updateTime": "2024-01-15 10:30:00",
        "delFlag": "0"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}

7.2 获取产品详情

接口路径： GET /api/system/product/{productId}

功能描述： 根据产品ID获取产品详情

权限要求： product:detail

路径参数：

参数名 类型 必填 描述
productId Long 是 产品ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "productId": 1,
    "productCode": "APL-IP15-128G-BK",
    "productName": "iPhone 15",
    "productModel": "A2848",
    "productType": "iPhone",
    "storageCapacity": "128GB",
    "color": "黑色",
    "productImgUrl": "https://example.com/iphone15.jpg",
    "officialPrice": 5999.00,
    "saleStatus": 1,
    "rebateFlag": 1,
    "saleStartDate": "2023-09-15",
    "saleEndDate": "2024-12-31",
    "remark": "iPhone 15 128GB 黑色",
    "createBy": "admin",
    "createTime": "2024-01-15 10:30:00",
    "updateBy": "admin",
    "updateTime": "2024-01-15 10:30:00",
    "delFlag": "0"
  }
}

7.3 新增产品

接口路径： POST /api/system/product

功能描述： 新增产品信息

权限要求： product:add

请求体参数：

参数名 类型 必填 描述
productCode String 是 产品编码
productName String 是 产品名称
productModel String 是 产品型号
productType String 是 产品类别
storageCapacity String 否 存储容量
color String 否 产品颜色
productImgUrl String 否 产品图片URL
officialPrice BigDecimal 否 官方指导价
saleStatus Integer 是 销售状态（0-下架/1-在售/2-预售）
rebateFlag Integer 是 是否参与返利（0-否/1-是）
saleStartDate String 否 销售起始日期
saleEndDate String 否 销售终止日期
remark String 否 产品备注

请求示例：

{
  "productCode": "APL-IP15-128G-BK",
  "productName": "iPhone 15",
  "productModel": "A2848",
  "productType": "iPhone",
  "storageCapacity": "128GB",
  "color": "黑色",
  "productImgUrl": "https://example.com/iphone15.jpg",
  "officialPrice": 5999.00,
  "saleStatus": 1,
  "rebateFlag": 1,
  "saleStartDate": "2023-09-15",
  "saleEndDate": "2024-12-31",
  "remark": "iPhone 15 128GB 黑色"
}

响应示例：

{
  "code": 200,
  "message": "新增产品成功",
  "data": null
}

7.4 修改产品

接口路径： POST /api/product/update

功能描述： 修改产品信息

权限要求： product:edit

请求体参数：

参数名 类型 必填 描述
productId Long 是 产品ID
productCode String 是 产品编码
productName String 是 产品名称
productModel String 是 产品型号
productType String 是 产品类别
storageCapacity String 否 存储容量
color String 否 产品颜色
productImgUrl String 否 产品图片URL
officialPrice BigDecimal 否 官方指导价
saleStatus Integer 是 销售状态（0-下架/1-在售/2-预售）
rebateFlag Integer 是 是否参与返利（0-否/1-是）
saleStartDate String 否 销售起始日期
saleEndDate String 否 销售终止日期
remark String 否 产品备注

请求示例：

{
  "productId": 1,
  "productCode": "APL-IP15-128G-BK",
  "productName": "iPhone 15",
  "productModel": "A2848",
  "productType": "iPhone",
  "storageCapacity": "128GB",
  "color": "黑色",
  "productImgUrl": "https://example.com/iphone15.jpg",
  "officialPrice": 5999.00,
  "saleStatus": 1,
  "rebateFlag": 1,
  "saleStartDate": "2023-09-15",
  "saleEndDate": "2024-12-31",
  "remark": "iPhone 15 128GB 黑色"
}

响应示例：

{
  "code": 200,
  "message": "修改产品成功",
  "data": null
}

7.5 删除产品

接口路径： DELETE /api/system/product/{productId}

功能描述： 根据产品ID删除产品

权限要求： product:delete

路径参数：

参数名 类型 必填 描述
productId Long 是 产品ID

响应示例：

{
  "code": 200,
  "message": "删除产品成功",
  "data": null
}

7.6 批量删除产品

接口路径： POST /api/product/batchDelete

功能描述： 批量删除产品

权限要求： product:delete

请求体参数：

参数名 类型 必填 描述
productIds List 是 产品ID列表

请求示例：

[1, 2, 3]

响应示例：

{
  "code": 200,
  "message": "批量删除产品成功",
  "data": null
}

7.7 修改产品状态

接口路径： POST /api/product/{productId}/status

功能描述： 修改产品销售状态

权限要求： product:edit

路径参数：

参数名 类型 必填 描述
productId Long 是 产品ID

请求参数：

参数名 类型 必填 描述
saleStatus Integer 是 销售状态（0-下架/1-在售/2-预售）

响应示例：

{
  "code": 200,
  "message": "修改产品状态成功",
  "data": null
}

7.8 修改返利标识

接口路径： POST /api/product/{productId}/rebate

功能描述： 修改产品返利标识

权限要求： product:edit

路径参数：

参数名 类型 必填 描述
productId Long 是 产品ID

请求参数：

参数名 类型 必填 描述
rebateFlag Integer 是 返利标识（0-否/1-是）

响应示例：

{
  "code": 200,
  "message": "修改返利标识成功",
  "data": null
}

8. 经销商管理 (DealerInfoController)

8.1 分页查询经销商列表

接口路径： GET /api/dealer/list

功能描述： 根据条件分页查询经销商列表

权限要求： dealer:list

请求参数：

参数名 类型 必填 描述 示例
dealerCode String 否 经销商编码 DL001
dealerName String 否 经销商名称 北京经销商
creditCode String 否 统一社会信用代码 91110000123456789X
dealerLevel Integer 否 经销商等级（1-一级经销商/2-二级经销商） 1
region String 否 所在区域 北京
contactPerson String 否 联系人 张三
contactPhone String 否 联系电话 13800138000
cooperateStatus Integer 否 合作状态（1-正常合作/2-暂停合作/3-终止合作） 1
qualificationAuditStatus Integer 否 资质审核状态（1-待审核/2-审核通过/3-审核不通过） 2
cooperateStartDateStart String 否 合作起始日期开始 2024-01-01
cooperateStartDateEnd String 否 合作起始日期结束 2024-12-31
pageNum Integer 否 页码 1
pageSize Integer 否 每页大小 10

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "dealerId": 1,
        "dealerCode": "DL001",
        "dealerName": "北京经销商",
        "creditCode": "91110000123456789X",
        "dealerLevel": 1,
        "region": "北京",
        "contactPerson": "张三",
        "contactPhone": "13800138000",
        "cooperateStartDate": "2024-01-01",
        "cooperateStatus": 1,
        "businessLicenseUrl": "https://example.com/license.jpg",
        "cooperationAgreementUrl": "https://example.com/agreement.pdf",
        "qualificationAuditStatus": 2,
        "auditOpinion": "审核通过",
        "totalRebateAmount": 10000.00,
        "usedRebateAmount": 5000.00,
        "pendingRebateAmount": 5000.00,
        "lastRebateUpdateTime": "2024-01-15 10:30:00",
        "createBy": "admin",
        "createTime": "2024-01-15 10:30:00",
        "updateBy": "admin",
        "updateTime": "2024-01-15 10:30:00",
        "delFlag": "0"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}

8.2 获取经销商详情

接口路径： GET /api/dealer/{dealerId}

功能描述： 根据经销商ID获取经销商详情

权限要求： dealer:detail

路径参数：

参数名 类型 必填 描述
dealerId Long 是 经销商ID

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "dealerId": 1,
    "dealerCode": "DL001",
    "dealerName": "北京经销商",
    "creditCode": "91110000123456789X",
    "dealerLevel": 1,
    "region": "北京",
    "contactPerson": "张三",
    "contactPhone": "13800138000",
    "cooperateStartDate": "2024-01-01",
    "cooperateStatus": 1,
    "businessLicenseUrl": "https://example.com/license.jpg",
    "cooperationAgreementUrl": "https://example.com/agreement.pdf",
    "qualificationAuditStatus": 2,
    "auditOpinion": "审核通过",
    "totalRebateAmount": 10000.00,
    "usedRebateAmount": 5000.00,
    "pendingRebateAmount": 5000.00,
    "lastRebateUpdateTime": "2024-01-15 10:30:00",
    "createBy": "admin",
    "createTime": "2024-01-15 10:30:00",
    "updateBy": "admin",
    "updateTime": "2024-01-15 10:30:00",
    "delFlag": "0"
  }
}

8.3 新增经销商

接口路径： POST /api/dealer

功能描述： 新增经销商信息

权限要求： dealer:add

请求体参数：

参数名 类型 必填 描述
dealerCode String 是 经销商编码（6-20位大写字母和数字）
dealerName String 是 经销商名称
creditCode String 是 统一社会信用代码
dealerLevel Integer 是 经销商等级（1-一级经销商/2-二级经销商）
region String 是 所在区域
contactPerson String 否 联系人
contactPhone String 否 联系电话
cooperateStartDate String 是 合作起始日期
cooperateStatus Integer 否 合作状态（1-正常合作/2-暂停合作/3-终止合作）
businessLicenseUrl String 否 营业执照URL
cooperationAgreementUrl String 否 合作协议URL
qualificationAuditStatus Integer 否 资质审核状态（1-待审核/2-审核通过/3-审核不通过）
auditOpinion String 否 审核意见

请求示例：

{
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "creditCode": "91110000123456789X",
  "dealerLevel": 1,
  "region": "北京",
  "contactPerson": "张三",
  "contactPhone": "13800138000",
  "cooperateStartDate": "2024-01-01",
  "cooperateStatus": 1,
  "businessLicenseUrl": "https://example.com/license.jpg",
  "cooperationAgreementUrl": "https://example.com/agreement.pdf",
  "qualificationAuditStatus": 1,
  "auditOpinion": ""
}

响应示例：

{
  "code": 200,
  "message": "经销商新增成功",
  "data": null
}

8.4 修改经销商

接口路径： POST /api/dealer/update

功能描述： 修改经销商信息

权限要求： dealer:update

请求体参数：

参数名 类型 必填 描述
dealerId Long 是 经销商ID
dealerCode String 是 经销商编码（6-20位大写字母和数字）
dealerName String 是 经销商名称
creditCode String 是 统一社会信用代码
dealerLevel Integer 是 经销商等级（1-一级经销商/2-二级经销商）
region String 是 所在区域
contactPerson String 否 联系人
contactPhone String 否 联系电话
cooperateStartDate String 是 合作起始日期
cooperateStatus Integer 否 合作状态（1-正常合作/2-暂停合作/3-终止合作）
businessLicenseUrl String 否 营业执照URL
cooperationAgreementUrl String 否 合作协议URL
qualificationAuditStatus Integer 否 资质审核状态（1-待审核/2-审核通过/3-审核不通过）
auditOpinion String 否 审核意见

请求示例：

{
  "dealerId": 1,
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "creditCode": "91110000123456789X",
  "dealerLevel": 1,
  "region": "北京",
  "contactPerson": "张三",
  "contactPhone": "13800138000",
  "cooperateStartDate": "2024-01-01",
  "cooperateStatus": 1,
  "businessLicenseUrl": "https://example.com/license.jpg",
  "cooperationAgreementUrl": "https://example.com/agreement.pdf",
  "qualificationAuditStatus": 2,
  "auditOpinion": "审核通过"
}

响应示例：

{
  "code": 200,
  "message": "经销商修改成功",
  "data": null
}

8.5 删除经销商

接口路径： DELETE /api/dealer/{dealerId}

功能描述： 根据经销商ID删除经销商

权限要求： dealer:delete

路径参数：

参数名 类型 必填 描述
dealerId Long 是 经销商ID

响应示例：

{
  "code": 200,
  "message": "经销商删除成功",
  "data": null
}

8.6 批量删除经销商

接口路径： DELETE /api/dealer/batch

功能描述： 批量删除经销商

权限要求： dealer:batchDelete

请求体参数：

参数名 类型 必填 描述
dealerIds List 是 经销商ID列表

请求示例：

[1, 2, 3]

响应示例：

{
  "code": 200,
  "message": "经销商批量删除成功",
  "data": null
}

8.7 修改经销商合作状态

接口路径： POST /api/dealer/{dealerId}/cooperateStatus/{cooperateStatus}

功能描述： 修改经销商的合作状态

权限要求： dealer:updateStatus

路径参数：

参数名 类型 必填 描述
dealerId Long 是 经销商ID
cooperateStatus Integer 是 合作状态（1-正常合作/2-暂停合作/3-终止合作）

响应示例：

{
  "code": 200,
  "message": "经销商合作状态修改成功",
  "data": null
}

8.8 修改经销商资质审核状态

接口路径： POST /api/dealer/{dealerId}/auditStatus

功能描述： 修改经销商的资质审核状态

权限要求： dealer:audit

路径参数：

参数名 类型 必填 描述
dealerId Long 是 经销商ID

请求参数：

参数名 类型 必填 描述
qualificationAuditStatus Integer 是 资质审核状态（1-待审核/2-审核通过/3-审核不通过）
auditOpinion String 否 审核意见

响应示例：

{
  "code": 200,
  "message": "经销商资质审核状态修改成功",
  "data": null
}

数据字典

销售状态（saleStatus）

值 描述
0 下架
1 在售
2 预售

返利标识（rebateFlag）

值 描述
0 否
1 是

经销商等级（dealerLevel）

值 描述
1 一级经销商
2 二级经销商

合作状态（cooperateStatus）

值 描述
1 正常合作
2 暂停合作
3 终止合作

资质审核状态（qualificationAuditStatus）

值 描述
1 待审核
2 审核通过
3 审核不通过

文档版本： 1.0.0
最后更新： 2025-01-27
维护人员： Apple ERP Team