zhouhui.jiang / test_cursor

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
API接口文档.md 56 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
}

7.9 获取所有产品

接口路径： GET /api/product/all

功能描述： 获取所有启用的产品信息，用于下拉选择

权限要求： 无

请求参数： 无

响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "productId": 1,
      "productCode": "APL-IP15-128G-BK",
      "productName": "iPhone 15|A2848|iPhone|黑色"
    },
    {
      "productId": 2,
      "productCode": "APL-IP15-256G-BK",
      "productName": "iPhone 15|A2848|iPhone|黑色"
    },
    {
      "productId": 3,
      "productCode": "APL-IP15-128G-WH",
      "productName": "iPhone 15|A2848|iPhone|白色"
    }
  ]
}

响应字段说明：

  • 只返回未删除且销售状态为在售的产品
  • 按产品编码升序排列
  • 产品名称格式：产品名称|产品型号|产品类别|产品颜色
  • 主要用于订单管理等模块的下拉选择

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
}

8.9 获取所有经销商

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

功能描述： 获取所有启用的经销商信息，用于下拉选择

权限要求： 无

请求参数： 无

响应示例：

{
  "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-01 10:00:00",
      "createBy": "admin",
      "createTime": "2024-01-01 10:00:00",
      "updateBy": "admin",
      "updateTime": "2024-01-01 10:00:00",
      "delFlag": "0"
    },
    {
      "dealerId": 2,
      "dealerCode": "DL002",
      "dealerName": "上海经销商",
      "creditCode": "91310000123456789Y",
      "dealerLevel": 2,
      "region": "上海",
      "contactPerson": "李四",
      "contactPhone": "13900139000",
      "cooperateStartDate": "2024-02-01",
      "cooperateStatus": 1,
      "businessLicenseUrl": "https://example.com/license2.jpg",
      "cooperationAgreementUrl": "https://example.com/agreement2.pdf",
      "qualificationAuditStatus": 2,
      "auditOpinion": "审核通过",
      "totalRebateAmount": 15000.00,
      "usedRebateAmount": 8000.00,
      "pendingRebateAmount": 7000.00,
      "lastRebateUpdateTime": "2024-02-01 10:00:00",
      "createBy": "admin",
      "createTime": "2024-02-01 10:00:00",
      "updateBy": "admin",
      "updateTime": "2024-02-01 10:00:00",
      "delFlag": "0"
    }
  ]
}

响应字段说明：

  • 只返回未删除且合作状态为正常的经销商
  • 按经销商编码升序排列
  • 主要用于订单管理等模块的下拉选择

数据字典

销售状态（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 HH:mm:ss）
deliveryEndDate String 否 出库结束日期（格式：yyyy-MM-dd HH:mm:ss）

响应示例：

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

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