zhouhui.jiang / test_cursor

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
API接口文档.md 13.5 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）不允许删除
  • 超级管理员状态不允许修改
  • 所有操作都会记录操作日志

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