API接口文档.md 65.4 KB

Raw Blame History Permalink



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. 首页仪表板 (DashboardController)


1.1 获取首页统计数据

接口路径： GET /api/dashboard/stats

功能描述： 获取首页仪表板的统计数据，包括今日订单、待出库、待开票、销售额等信息

请求头：

Authorization: Bearer <JWT_TOKEN>


响应示例：

{
  "code": 200,
  "message": "获取统计数据成功",
  "data": {
    "todayOrderCount": 23,
    "pendingDeliveryCount": 8,
    "pendingInvoiceCount": 5,
    "todaySalesAmount": 125680.50,
    "onlineUserCount": 156,
    "systemStatus": "正常运行",
    "systemVersion": "v1.0.0"
  }
}


错误响应示例：

{
  "code": 500,
  "message": "获取统计数据失败: 数据库连接异常",
  "data": null
}


响应字段说明：


todayOrderCount: 今日订单数量

pendingDeliveryCount: 待出库数量

pendingInvoiceCount: 待开票数量

todaySalesAmount: 今日销售额

onlineUserCount: 在线用户数

systemStatus: 系统状态

systemVersion: 系统版本


2. 认证管理 (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",
    "realName": "系统管理员",
    "roles": [
      {
        "roleId": 1,
        "roleCode": "ADMIN",
        "roleName": "系统管理员",
        "status": 1,
        "statusText": "正常",
        "remark": "系统管理员角色",
        "createBy": "admin",
        "createTime": "2024-01-01T00:00:00",
        "updateBy": "admin",
        "updateTime": "2024-01-01T00:00:00"
      }
    ],
    "authorities": [
      {
        "authority": "ROLE_ADMIN"
      }
    ]
  }
}


响应字段说明：


username: 用户名

realName: 真实姓名

roles: 用户角色列表


roleId: 角色ID

roleCode: 角色编码

roleName: 角色名称

status: 角色状态（0-停用/1-启用）

statusText: 角色状态文本描述

remark: 备注

createBy: 创建者

createTime: 创建时间

updateBy: 更新者

updateTime: 更新时间


authorities: 用户权限列表（Spring Security权限对象）


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 认证流程


调用登录接口获取JWT令牌
在后续请求的Header中携带令牌：Authorization: Bearer {token}

令牌过期时使用刷新令牌获取新令牌
登出时调用登出接口清除认证信息


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. 分页查询订单列表

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

请求方法： GET

权限要求： order:list

请求参数：


参数名
类型
必填
描述
示例


orderNo
String
否
订单编号
ORD-2024-001


dealerCode
String
否
经销商编码
APL-DLR-001


dealerName
String
否
经销商名称
北京经销商


deliveryStatus
Integer
否
出库状态（0-未出库/1-已出库）
1


invoiceStatus
Integer
否
开票状态（0-未开票/1-已开票）
1


rebateCalcFlag
Integer
否
返利计算状态（0-未计算/1-已计算）
1


dataSource
String
否
数据来源
ERP系统


verifyStatus
Integer
否
数据验证状态（0-待验证/1-验证通过/2-验证失败）
1


orderStartDate
String
否
订单开始日期
2024-01-01T00:00:00


orderEndDate
String
否
订单结束日期
2024-12-31T23:59:59


minAmount
BigDecimal
否
金额最小值
1000.00


maxAmount
BigDecimal
否
金额最大值
100000.00


pageNum
Integer
是
页码
1


pageSize
Integer
是
每页大小
10


响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "orderId": 1,
        "orderNo": "ORD-2024-001",
        "dealerCode": "APL-DLR-001",
        "dealerName": "北京经销商",
        "orderDate": "2024-01-15T10:30:00",
        "totalAmount": 119980.00,
        "rebateAmount": 5999.00,
        "deliveryStatus": 1,
        "invoiceStatus": 1,
        "rebateCalcFlag": 1,
        "dataSource": "ERP系统",
        "verifyStatus": 1,
        "uploadTime": "2024-01-15T10:35:00",
        "createBy": "admin",
        "createTime": "2024-01-15T10:30:00",
        "updateBy": "",
        "updateTime": "2024-01-15T10:30:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}


2. 获取订单详情

接口路径： GET /api/order/{orderId}

请求方法： GET

权限要求： order:detail

路径参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "orderId": 1,
    "orderNo": "ORD-2024-001",
    "dealerCode": "APL-DLR-001",
    "dealerName": "北京经销商",
    "orderDate": "2024-01-15T10:30:00",
    "totalAmount": 119980.00,
    "rebateAmount": 5999.00,
    "deliveryStatus": 1,
    "invoiceStatus": 1,
    "rebateCalcFlag": 1,
    "dataSource": "ERP系统",
    "verifyStatus": 1,
    "uploadTime": "2024-01-15T10:35:00",
    "createBy": "admin",
    "createTime": "2024-01-15T10:30:00",
    "updateBy": "",
    "updateTime": "2024-01-15T10:30:00",
    "orderItems": [
      {
        "itemId": 1,
        "orderId": 1,
        "orderNo": "ORD-2024-001",
        "productCode": "APL-IP15-128G-BK",
        "productName": "iPhone 15 128GB 黑色",
        "productSpec": "128GB/黑色",
        "productType": "手机",
        "unitPrice": 5999.00,
        "quantity": 20,
        "itemAmount": 119980.00,
        "rebateRate": 0.05,
        "rebateAmount": 5999.00,
        "createBy": "admin",
        "createTime": "2024-01-15T10:30:00",
        "updateBy": "",
        "updateTime": "2024-01-15T10:30:00"
      }
    ]
  }
}


3. 新增订单

接口路径： POST /api/order

请求方法： POST

权限要求： order:add

请求体参数：


参数名
类型
必填
描述


orderNo
String
是
订单编号


dealerCode
String
是
经销商编码


dealerName
String
是
经销商名称


orderDate
String
是
订单创建日期


totalAmount
BigDecimal
是
订单总金额


rebateAmount
BigDecimal
否
订单返利金额


deliveryStatus
Integer
否
出库状态（0-未出库/1-已出库）


invoiceStatus
Integer
否
开票状态（0-未开票/1-已开票）


rebateCalcFlag
Integer
否
返利计算状态（0-未计算/1-已计算）


dataSource
String
否
数据来源


verifyStatus
Integer
否
数据验证状态（0-待验证/1-验证通过/2-验证失败）


uploadTime
String
否
数据上传时间


orderItems
Array
是
订单明细列表


订单明细参数：


参数名
类型
必填
描述


productCode
String
是
产品编码


productName
String
是
产品名称


productSpec
String
否
产品规格


productType
String
否
产品类别


unitPrice
BigDecimal
是
产品单价


quantity
Integer
是
订购数量


itemAmount
BigDecimal
否
明细金额


rebateRate
BigDecimal
否
返利比例


rebateAmount
BigDecimal
否
返利金额


请求示例：

{
  "orderNo": "ORD-2024-001",
  "dealerCode": "APL-DLR-001",
  "dealerName": "北京经销商",
  "orderDate": "2024-01-15T10:30:00",
  "totalAmount": 119980.00,
  "rebateAmount": 5999.00,
  "deliveryStatus": 0,
  "invoiceStatus": 0,
  "rebateCalcFlag": 0,
  "dataSource": "ERP系统",
  "verifyStatus": 0,
  "orderItems": [
    {
      "productCode": "APL-IP15-128G-BK",
      "productName": "iPhone 15 128GB 黑色",
      "productSpec": "128GB/黑色",
      "productType": "手机",
      "unitPrice": 5999.00,
      "quantity": 20,
      "itemAmount": 119980.00,
      "rebateRate": 0.05,
      "rebateAmount": 5999.00
    }
  ]
}


响应示例：

{
  "code": 200,
  "message": "新增订单成功",
  "data": null
}


4. 修改订单

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

请求方法： POST

权限要求： order:edit

请求体参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


orderNo
String
是
订单编号


dealerCode
String
是
经销商编码


dealerName
String
是
经销商名称


orderDate
String
是
订单创建日期


totalAmount
BigDecimal
是
订单总金额


rebateAmount
BigDecimal
否
订单返利金额


deliveryStatus
Integer
否
出库状态（0-未出库/1-已出库）


invoiceStatus
Integer
否
开票状态（0-未开票/1-已开票）


rebateCalcFlag
Integer
否
返利计算状态（0-未计算/1-已计算）


dataSource
String
否
数据来源


verifyStatus
Integer
否
数据验证状态（0-待验证/1-验证通过/2-验证失败）


uploadTime
String
否
数据上传时间


orderItems
Array
是
订单明细列表


响应示例：

{
  "code": 200,
  "message": "修改订单成功",
  "data": null
}


5. 删除订单

接口路径： DELETE /api/order/{orderId}

请求方法： DELETE

权限要求： order:delete

路径参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


响应示例：

{
  "code": 200,
  "message": "删除订单成功",
  "data": null
}


6. 批量删除订单

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

请求方法： POST

权限要求： order:delete

请求体参数：


参数名
类型
必填
描述


-
Array
是
订单ID列表


请求示例：

[1, 2, 3]


响应示例：

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


7. 修改订单出库状态

接口路径： POST /api/order/{orderId}/deliveryStatus

请求方法： POST

权限要求： order:edit

路径参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


请求参数：


参数名
类型
必填
描述


deliveryStatus
Integer
是
出库状态（0-未出库/1-已出库）


响应示例：

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


8. 修改订单开票状态

接口路径： POST /api/order/{orderId}/invoiceStatus

请求方法： POST

权限要求： order:edit

路径参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


请求参数：


参数名
类型
必填
描述


invoiceStatus
Integer
是
开票状态（0-未开票/1-已开票）


响应示例：

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


9. 修改订单返利计算状态

接口路径： POST /api/order/{orderId}/rebateCalcFlag

请求方法： POST

权限要求： order:edit

路径参数：


参数名
类型
必填
描述


orderId
Long
是
订单ID


请求参数：


参数名
类型
必填
描述


rebateCalcFlag
Integer
是
返利计算状态（0-未计算/1-已计算）


响应示例：

{
  "code": 200,
  "message": "修改返利计算状态成功",
  "data": null
}


出库管理接口


1. 分页查询出库列表

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

请求方法： GET

权限要求： delivery:list

请求参数：


参数名
类型
必填
描述


pageNum
Integer
是
页码，从1开始


pageSize
Integer
是
每页大小


deliveryNo
String
否
出库单编号


dealerCode
String
否
经销商编码


dealerName
String
否
经销商名称


orderNo
String
否
关联订单编号


deliveryStatus
Integer
否
出库状态（0-未出库/1-已出库）


warehouseCode
String
否
出库仓库编码


dataSource
String
否
数据来源


deliveryStartDate
String
否
出库开始日期（格式：yyyy-MM-dd HHss）


deliveryEndDate
String
否
出库结束日期（格式：yyyy-MM-dd HHss）


响应示例：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "records": [
      {
        "deliveryId": 1,
        "deliveryNo": "DL202501270001",
        "dealerCode": "DL001",
        "dealerName": "北京经销商",
        "orderNo": "ORD202501270001",
        "deliveryDate": "2025-01-27 10:00:00",
        "deliveryStatus": 1,
        "warehouseCode": "WH001",
        "dataSource": "系统录入",
        "uploadTime": "2025-01-27 09:30:00",
        "createBy": "admin",
        "createTime": "2025-01-27 09:30:00",
        "updateBy": "admin",
        "updateTime": "2025-01-27 10:00:00",
        "deliveryItems": [
          {
            "deliveryItemId": 1,
            "deliveryId": 1,
            "deliveryNo": "DL202501270001",
            "orderNo": "ORD202501270001",
            "productCode": "P001",
            "productName": "iPhone 15",
            "deliveryQty": 10,
            "deliveryPrice": 5999.00,
            "deliveryAmount": 59990.00,
            "createBy": "admin",
            "createTime": "2025-01-27 09:30:00",
            "updateBy": "admin",
            "updateTime": "2025-01-27 10:00:00"
          }
        ]
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}


2. 获取出库详情

接口路径： GET /api/delivery/{deliveryId}

请求方法： GET

权限要求： delivery:detail

路径参数：


参数名
类型
必填
描述


deliveryId
Long
是
出库单ID


响应示例：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "deliveryId": 1,
    "deliveryNo": "DL202501270001",
    "dealerCode": "DL001",
    "dealerName": "北京经销商",
    "orderNo": "ORD202501270001",
    "deliveryDate": "2025-01-27 10:00:00",
    "deliveryStatus": 1,
    "warehouseCode": "WH001",
    "dataSource": "系统录入",
    "uploadTime": "2025-01-27 09:30:00",
    "createBy": "admin",
    "createTime": "2025-01-27 09:30:00",
    "updateBy": "admin",
    "updateTime": "2025-01-27 10:00:00",
    "deliveryItems": [
      {
        "deliveryItemId": 1,
        "deliveryId": 1,
        "deliveryNo": "DL202501270001",
        "orderNo": "ORD202501270001",
        "productCode": "P001",
        "productName": "iPhone 15",
        "deliveryQty": 10,
        "deliveryPrice": 5999.00,
        "deliveryAmount": 59990.00,
        "createBy": "admin",
        "createTime": "2025-01-27 09:30:00",
        "updateBy": "admin",
        "updateTime": "2025-01-27 10:00:00"
      }
    ]
  }
}


3. 新增出库

接口路径： POST /api/delivery

请求方法： POST

权限要求： delivery:add

请求体：

{
  "deliveryNo": "DL202501270001",
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "orderNo": "ORD202501270001",
  "deliveryDate": "2025-01-27 10:00:00",
  "deliveryStatus": 0,
  "warehouseCode": "WH001",
  "dataSource": "系统录入",
  "uploadTime": "2025-01-27 09:30:00",
  "deliveryItems": [
    {
      "productCode": "P001",
      "productName": "iPhone 15",
      "deliveryQty": 10,
      "deliveryPrice": 5999.00,
      "deliveryAmount": 59990.00
    }
  ]
}


响应示例：

{
  "code": 200,
  "message": "新增出库单成功",
  "data": null
}


4. 修改出库

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

请求方法： POST

权限要求： delivery:edit

请求体：

{
  "deliveryId": 1,
  "deliveryNo": "DL202501270001",
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "orderNo": "ORD202501270001",
  "deliveryDate": "2025-01-27 10:00:00",
  "deliveryStatus": 1,
  "warehouseCode": "WH001",
  "dataSource": "系统录入",
  "uploadTime": "2025-01-27 09:30:00",
  "deliveryItems": [
    {
      "deliveryItemId": 1,
      "productCode": "P001",
      "productName": "iPhone 15",
      "deliveryQty": 15,
      "deliveryPrice": 5999.00,
      "deliveryAmount": 89985.00
    }
  ]
}


响应示例：

{
  "code": 200,
  "message": "修改出库单成功",
  "data": null
}


5. 删除出库

接口路径： DELETE /api/delivery/{deliveryId}

请求方法： DELETE

权限要求： delivery:delete

路径参数：


参数名
类型
必填
描述


deliveryId
Long
是
出库单ID


响应示例：

{
  "code": 200,
  "message": "删除出库单成功",
  "data": null
}


6. 批量删除出库

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

请求方法： POST

权限要求： delivery:delete

请求体：

[1, 2, 3]


响应示例：

{
  "code": 200,
  "message": "批量删除出库单成功",
  "data": null
}


7. 修改出库状态

接口路径： POST /api/delivery/{deliveryId}/deliveryStatus

请求方法： POST

权限要求： delivery:edit

路径参数：


参数名
类型
必填
描述


deliveryId
Long
是
出库单ID


请求参数：


参数名
类型
必填
描述


deliveryStatus
Integer
是
出库状态（0-未出库/1-已出库）


响应示例：

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


发票管理接口


1. 分页查询发票列表

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

请求方法： GET

权限要求： invoice:list

请求参数：


参数名
类型
必填
描述


pageNum
Integer
是
页码，从1开始


pageSize
Integer
是
每页大小


invoiceNo
String
否
发票编号


orderNo
String
否
关联订单编号


deliveryNo
String
否
关联出库单编号


dealerCode
String
否
经销商编码


dealerName
String
否
经销商名称


invoiceStatus
Integer
否
发票状态（0-未开票/1-已开票）


dataSource
String
否
数据来源


invoiceStartDate
String
否
开票开始日期（格式：yyyy-MM-dd）


invoiceEndDate
String
否
开票结束日期（格式：yyyy-MM-dd）


minAmount
BigDecimal
否
金额最小值


maxAmount
BigDecimal
否
金额最大值


响应示例：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "records": [
      {
        "invoiceId": 1,
        "invoiceNo": "INV202501270001",
        "orderNo": "ORD202501270001",
        "deliveryNo": "DL202501270001",
        "dealerCode": "DL001",
        "dealerName": "北京经销商",
        "totalAmount": 67890.00,
        "invoiceDate": "2025-01-27",
        "invoiceStatus": 1,
        "taxRate": 13.00,
        "dataSource": "系统录入",
        "uploadTime": "2025-01-27 09:30:00",
        "createBy": "admin",
        "createTime": "2025-01-27 09:30:00",
        "updateBy": "admin",
        "updateTime": "2025-01-27 10:00:00",
        "invoiceItems": [
          {
            "invoiceItemId": 1,
            "invoiceId": 1,
            "invoiceNo": "INV202501270001",
            "orderNo": "ORD202501270001",
            "productCode": "P001",
            "productName": "iPhone 15",
            "invoiceQty": 10,
            "unitPriceNoTax": 5309.73,
            "amountNoTax": 53097.30,
            "taxAmount": 6902.70,
            "createBy": "admin",
            "createTime": "2025-01-27 09:30:00",
            "updateBy": "admin",
            "updateTime": "2025-01-27 10:00:00"
          }
        ]
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}


2. 获取发票详情

接口路径： GET /api/invoice/{invoiceId}

请求方法： GET

权限要求： invoice:detail

路径参数：


参数名
类型
必填
描述


invoiceId
Long
是
发票ID


响应示例：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "invoiceId": 1,
    "invoiceNo": "INV202501270001",
    "orderNo": "ORD202501270001",
    "deliveryNo": "DL202501270001",
    "dealerCode": "DL001",
    "dealerName": "北京经销商",
    "totalAmount": 67890.00,
    "invoiceDate": "2025-01-27",
    "invoiceStatus": 1,
    "taxRate": 13.00,
    "dataSource": "系统录入",
    "uploadTime": "2025-01-27 09:30:00",
    "createBy": "admin",
    "createTime": "2025-01-27 09:30:00",
    "updateBy": "admin",
    "updateTime": "2025-01-27 10:00:00",
    "invoiceItems": [
      {
        "invoiceItemId": 1,
        "invoiceId": 1,
        "invoiceNo": "INV202501270001",
        "orderNo": "ORD202501270001",
        "productCode": "P001",
        "productName": "iPhone 15",
        "invoiceQty": 10,
        "unitPriceNoTax": 5309.73,
        "amountNoTax": 53097.30,
        "taxAmount": 6902.70,
        "createBy": "admin",
        "createTime": "2025-01-27 09:30:00",
        "updateBy": "admin",
        "updateTime": "2025-01-27 10:00:00"
      }
    ]
  }
}


3. 新增发票

接口路径： POST /api/invoice

请求方法： POST

权限要求： invoice:add

请求体：

{
  "invoiceNo": "INV202501270001",
  "orderNo": "ORD202501270001",
  "deliveryNo": "DL202501270001",
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "totalAmount": 67890.00,
  "invoiceDate": "2025-01-27",
  "invoiceStatus": 0,
  "taxRate": 13.00,
  "dataSource": "系统录入",
  "uploadTime": "2025-01-27 09:30:00",
  "invoiceItems": [
    {
      "productCode": "P001",
      "productName": "iPhone 15",
      "invoiceQty": 10,
      "unitPriceNoTax": 5309.73,
      "amountNoTax": 53097.30,
      "taxAmount": 6902.70
    }
  ]
}


响应示例：

{
  "code": 200,
  "message": "新增发票成功",
  "data": null
}


4. 修改发票

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

请求方法： POST

权限要求： invoice:edit

请求体：

{
  "invoiceId": 1,
  "invoiceNo": "INV202501270001",
  "orderNo": "ORD202501270001",
  "deliveryNo": "DL202501270001",
  "dealerCode": "DL001",
  "dealerName": "北京经销商",
  "totalAmount": 67890.00,
  "invoiceDate": "2025-01-27",
  "invoiceStatus": 1,
  "taxRate": 13.00,
  "dataSource": "系统录入",
  "uploadTime": "2025-01-27 09:30:00",
  "invoiceItems": [
    {
      "invoiceItemId": 1,
      "productCode": "P001",
      "productName": "iPhone 15",
      "invoiceQty": 15,
      "unitPriceNoTax": 5309.73,
      "amountNoTax": 79645.95,
      "taxAmount": 10353.05
    }
  ]
}


响应示例：

{
  "code": 200,
  "message": "修改发票成功",
  "data": null
}


5. 删除发票

接口路径： DELETE /api/invoice/{invoiceId}

请求方法： DELETE

权限要求： invoice:delete

路径参数：


参数名
类型
必填
描述


invoiceId
Long
是
发票ID


响应示例：

{
  "code": 200,
  "message": "删除发票成功",
  "data": null
}


6. 批量删除发票

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

请求方法： POST

权限要求： invoice:delete

请求体：

[1, 2, 3]


响应示例：

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


7. 修改发票状态

接口路径： POST /api/invoice/{invoiceId}/invoiceStatus

请求方法： POST

权限要求： invoice:edit

路径参数：


参数名
类型
必填
描述


invoiceId
Long
是
发票ID


请求参数：


参数名
类型
必填
描述


invoiceStatus
Integer
是
发票状态（0-未开票/1-已开票）


响应示例：

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


8. 导出发票数据

接口路径： POST /api/invoice/export

请求方法： POST

权限要求： invoice:export

请求参数： 同发票查询接口参数

响应： 返回Excel文件流


八、数据导出接口


1. 订单数据导出

接口路径： POST /order/export

请求方法： POST

权限要求： order:export

请求参数： 同订单查询接口参数

响应： 返回Excel文件流，文件名格式：订单数据_yyyyMMdd_HHmmss.xlsx


2. 出库数据导出

接口路径： POST /api/delivery/export

请求方法： POST

权限要求： delivery:export

请求参数： 同出库查询接口参数

响应： 返回Excel文件流，文件名格式：出库数据_yyyyMMdd_HHmmss.xlsx


3. 发票数据导出

接口路径： POST /api/invoice/export

请求方法： POST

权限要求： invoice:export

请求参数： 同发票查询接口参数

响应： 返回Excel文件流，文件名格式：发票数据_yyyyMMdd_HHmmss.xlsx


4. 异常工单数据导出

接口路径： POST /api/exception-workorder/export

请求方法： POST

权限要求： exception:workorder:export

请求参数： 同异常工单查询接口参数

响应： 返回Excel文件流，文件名格式：异常工单数据_yyyyMMdd_HHmmss.xlsx


12. 异常工单管理 (ExceptionWorkorderController)


12.1 分页查询异常工单列表

接口路径： GET /api/exception-workorder/list

功能描述： 根据条件分页查询异常工单列表

请求头：

Authorization: Bearer <JWT_TOKEN>


请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| workorderNo | String | 否 | 工单编号（模糊查询） |
| orderNo | String | 否 | 关联订单号（模糊查询） |
| dealerCode | String | 否 | 经销商编码 |
| dealerName | String | 否 | 经销商名称（模糊查询） |
| workorderStatus | Integer | 否 | 工单状态（1-待处理/2-处理中/3-已解决/4-已关闭） |
| exceptionType | Integer | 否 | 异常类型（1-逻辑验证异常/2-源头验证异常/3-交叉验证异常） |
| severityLevel | Integer | 否 | 严重程度（1-高/2-中/3-低） |
| handlerUser | String | 否 | 处理人（模糊查询） |
| startTime | String | 否 | 创建开始时间（yyyy-MM-dd HHss） |
| endTime | String | 否 | 创建结束时间（yyyy-MM-dd HHss） |
| pageNum | Integer | 是 | 页码，默认1 |
| pageSize | Integer | 是 | 每页大小，默认10 |

权限要求： exception:workorder:list

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "workorderId": 1,
        "workorderNo": "EW202501290001",
        "orderNo": "ORD202501290001",
        "dealerCode": "D001",
        "dealerName": "北京经销商",
        "exceptionType": 1,
        "exceptionTypeName": "逻辑验证异常",
        "severityLevel": 1,
        "severityLevelName": "高",
        "workorderStatus": 1,
        "workorderStatusName": "待处理",
        "createTime": "2025-01-29 10:00:00",
        "expectCompleteTime": "2025-01-30 18:00:00",
        "handlerUser": "张三",
        "exceptionDesc": "订单金额与产品单价不匹配",
        "handleSuggest": "请核实订单明细",
        "dataSource": "系统自动生成",
        "createBy": "system",
        "updateBy": null,
        "updateTime": null,
        "workorderLogs": []
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}


12.2 获取异常工单详情

接口路径： GET /api/exception-workorder/{workorderId}

功能描述： 根据工单ID获取异常工单详细信息，包含处理日志

请求头：

Authorization: Bearer <JWT_TOKEN>


路径参数：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| workorderId | Long | 是 | 工单ID |

权限要求： exception:workorder:detail

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "workorderId": 1,
    "workorderNo": "EW202501290001",
    "orderNo": "ORD202501290001",
    "dealerCode": "D001",
    "dealerName": "北京经销商",
    "exceptionType": 1,
    "exceptionTypeName": "逻辑验证异常",
    "severityLevel": 1,
    "severityLevelName": "高",
    "workorderStatus": 2,
    "workorderStatusName": "处理中",
    "createTime": "2025-01-29 10:00:00",
    "expectCompleteTime": "2025-01-30 18:00:00",
    "handlerUser": "张三",
    "exceptionDesc": "订单金额与产品单价不匹配",
    "handleSuggest": "请核实订单明细",
    "dataSource": "系统自动生成",
    "createBy": "system",
    "updateBy": "张三",
    "updateTime": "2025-01-29 11:00:00",
    "workorderLogs": [
      {
        "logId": 1,
        "workorderId": 1,
        "workorderNo": "EW202501290001",
        "handleUser": "张三",
        "handleTime": "2025-01-29 11:00:00",
        "beforeStatus": 1,
        "beforeStatusName": "待处理",
        "afterStatus": 2,
        "afterStatusName": "处理中",
        "handleOpinion": "开始处理此工单",
        "attachUrl": null,
        "createBy": "张三",
        "createTime": "2025-01-29 11:00:00"
      }
    ]
  }
}


12.3 新增异常工单

接口路径： POST /api/exception-workorder

功能描述： 创建新的异常工单

请求头：

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json


请求体：

{
  "workorderNo": "EW202501290002",
  "orderNo": "ORD202501290002",
  "dealerCode": "D002",
  "dealerName": "上海经销商",
  "exceptionType": 2,
  "severityLevel": 2,
  "workorderStatus": 1,
  "expectCompleteTime": "2025-01-30 18:00:00",
  "handlerUser": "李四",
  "exceptionDesc": "经销商信息不完整",
  "handleSuggest": "请补充经销商详细信息",
  "dataSource": "手动创建"
}


权限要求： exception:workorder:add

响应示例：

{
  "code": 200,
  "message": "新增异常工单成功",
  "data": null
}


12.4 更新异常工单

接口路径： PUT /api/exception-workorder

功能描述： 更新异常工单信息

请求头：

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json


请求体：

{
  "workorderId": 1,
  "workorderNo": "EW202501290001",
  "orderNo": "ORD202501290001",
  "dealerCode": "D001",
  "dealerName": "北京经销商",
  "exceptionType": 1,
  "severityLevel": 1,
  "workorderStatus": 2,
  "expectCompleteTime": "2025-01-30 18:00:00",
  "handlerUser": "张三",
  "exceptionDesc": "订单金额与产品单价不匹配",
  "handleSuggest": "请核实订单明细并联系客户确认",
  "dataSource": "系统自动生成"
}


权限要求： exception:workorder:edit

响应示例：

{
  "code": 200,
  "message": "更新异常工单成功",
  "data": null
}


12.5 更新工单状态

接口路径： POST /api/exception-workorder/status

功能描述： 更新异常工单状态并记录处理日志

请求头：

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json


请求体：

{
  "workorderId": 1,
  "workorderStatus": 3,
  "handlerUser": "张三",
  "handleOpinion": "问题已解决，客户确认无误",
  "attachUrl": "http://example.com/attachment.pdf"
}


权限要求： exception:workorder:edit

响应示例：

{
  "code": 200,
  "message": "更新工单状态成功",
  "data": null
}


12.6 删除异常工单

接口路径： DELETE /api/exception-workorder/{workorderId}

功能描述： 根据工单ID逻辑删除异常工单

请求头：

Authorization: Bearer <JWT_TOKEN>


路径参数：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| workorderId | Long | 是 | 工单ID |

权限要求： exception:workorder:delete

响应示例：

{
  "code": 200,
  "message": "删除异常工单成功",
  "data": null
}


12.7 批量删除异常工单

接口路径： DELETE /api/exception-workorder/batch

功能描述： 根据工单ID列表批量逻辑删除异常工单

请求头：

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json


请求体：

[1, 2, 3]


权限要求： exception:workorder:delete

响应示例：

{
  "code": 200,
  "message": "批量删除异常工单成功",
  "data": null
}


12.8 批量更新工单状态

接口路径： POST /api/exception-workorder/batch-status

功能描述： 批量更新异常工单状态

请求头：

Authorization: Bearer <JWT_TOKEN>


请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| workorderIds | String | 是 | 工单ID列表，逗号分隔 |
| workorderStatus | Integer | 是 | 工单状态 |
| handlerUser | String | 是 | 处理人 |

权限要求： exception:workorder:edit

响应示例：

{
  "code": 200,
  "message": "批量更新工单状态成功",
  "data": null
}


12.9 获取异常工单统计信息

接口路径： GET /api/exception-workorder/stats

功能描述： 获取异常工单的统计信息

请求头：

Authorization: Bearer <JWT_TOKEN>


权限要求： exception:workorder:list

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "workorderNo": "total",
      "workorderId": 10,
      "exceptionType": 3,
      "severityLevel": 2,
      "workorderStatus": 4,
      "handlerUser": 1,
      "exceptionDesc": 5,
      "handleSuggest": 3,
      "dataSource": 2
    }
  ]
}


12.10 导出异常工单数据

接口路径： POST /api/exception-workorder/export

功能描述： 根据查询条件导出异常工单数据到Excel

请求头：

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json


请求体： 同异常工单查询接口参数（可选，为空时导出所有数据）

权限要求： exception:workorder:export

响应： 返回Excel文件流，文件名格式：异常工单数据_yyyyMMdd_HHmmss.xlsx

导出字段：


工单ID
工单编号
工单类型（异常类型名称）
严重程度（严重程度名称）
工单状态（工单状态名称）
问题描述
处理人
创建人
创建时间
更新时间


文档版本： 1.0.0

最后更新： 2025-01-29

维护人员： Apple ERP Team