effekt-interface/.agents/RBAC_API.md

RBAC / 用户 / 菜单管理接口文档

本文档基于当前已落地代码整理，适合直接给前端联调使用。

1. 通用说明

1.1 响应结构

成功：

{
  "success": true,
  "code": 20000,
  "message": "",
  "data": {}
}

失败：

{
  "success": false,
  "code": 40009,
  "message": "具体错误信息",
  "data": null
}

1.2 错误码使用习惯

code	说明
20000	成功
40009	创建类失败 / 参数校验失败
40011	详情查询失败
40012	更新 / 删除 / 分配失败

1.3 当前实现注意事项

• 用户密码字段当前直接写入 password_hash，还未做真正加密
• 分配类接口均为覆盖式保存
• 当前密码字段是占位实现，后续建议替换为真实 hash

---

2. 角色管理

2.1 角色列表

• 方法：GET
• 路径：/role/list

请求参数：

参数名	类型	必填	说明
keyword	string	否	角色名称模糊搜索
status	int	否	1启用 0禁用
pageNo	int	否	页码，默认1
pageSize	int	否	每页条数，默认20

返回 data：

{
  "list": [
    {
      "id": 1,
      "code": "admin",
      "name": "超级管理员",
      "description": "系统内置超级管理员",
      "status": 1,
      "is_system": 1,
      "created_by": 1,
      "created_time": "2025-01-01 10:00:00",
      "updated_time": "2025-01-01 10:00:00"
    }
  ],
  "total": 1
}

2.2 角色详情

• 方法：GET
• 路径：/role/detail

请求参数：

参数名	类型	必填	说明
roleId	int	是	角色ID

返回：单个角色对象。

2.3 创建角色

• 方法：POST
• 路径：/role/create

请求体：

{
  "code": "test_manager",
  "name": "测试经理",
  "description": "测试经理角色",
  "status": 1,
  "isSystem": 0,
  "createdBy": 1
}

返回：

{
  "id": 2
}

2.4 更新角色

• 方法：POST
• 路径：/role/update

请求体：

{
  "roleId": 2,
  "name": "高级测试经理",
  "description": "升级后的测试经理角色"
}

返回：

{
  "id": 2
}

2.5 删除角色

• 方法：POST
• 路径：/role/delete

请求体：

{
  "roleId": 2
}

返回：

{
  "id": 2
}

---

3. 权限管理

3.1 权限列表

• 方法：GET
• 路径：/permission/list

请求参数：

参数名	类型	必填	说明
keyword	string	否	权限名称模糊搜索
module	string	否	模块名
status	int	否	状态
pageNo	int	否	页码
pageSize	int	否	每页条数

返回 data：

{
  "list": [
    {
      "id": 1,
      "code": "user:create",
      "name": "创建用户",
      "module": "user",
      "action": "create",
      "description": "创建用户权限",
      "status": 1,
      "created_time": "2025-01-01 10:00:00",
      "updated_time": "2025-01-01 10:00:00"
    }
  ],
  "total": 1
}

3.2 权限详情

• 方法：GET
• 路径：/permission/detail
• 参数：permissionId

3.3 创建权限

• 方法：POST
• 路径：/permission/create

请求体：

{
  "code": "user:create",
  "name": "创建用户",
  "module": "user",
  "action": "create",
  "description": "创建用户权限",
  "status": 1
}

3.4 更新权限

• 方法：POST
• 路径：/permission/update

3.5 删除权限

• 方法：POST
• 路径：/permission/delete

---

4. 菜单管理

4.1 菜单树

• 方法：GET
• 路径：/menu/tree

请求参数：

参数名	类型	必填	说明
status	int	否	状态过滤

返回 data：

[
  {
    "id": 1,
    "parent_id": 0,
    "name": "系统管理",
    "code": "system",
    "type": 1,
    "path": "/system",
    "component": "Layout",
    "icon": "setting",
    "permission_code": null,
    "sort": 1,
    "visible": 1,
    "status": 1,
    "created_time": "2025-01-01 10:00:00",
    "updated_time": "2025-01-01 10:00:00",
    "children": [
      {
        "id": 2,
        "parent_id": 1,
        "name": "用户管理",
        "code": "user_manage",
        "type": 2,
        "path": "/system/user",
        "component": "system/user/index",
        "icon": "user",
        "permission_code": "user:list",
        "sort": 1,
        "visible": 1,
        "status": 1,
        "children": []
      }
    ]
  }
]

4.2 菜单详情

• 方法：GET
• 路径：/menu/detail
• 参数：menuId

4.3 创建菜单

• 方法：POST
• 路径：/menu/create

请求体：

{
  "parentId": 1,
  "name": "角色管理",
  "code": "role_manage",
  "type": 2,
  "path": "/system/role",
  "component": "system/role/index",
  "icon": "peoples",
  "permissionCode": "role:list",
  "sort": 2,
  "visible": 1,
  "status": 1
}

4.4 更新菜单

• 方法：POST
• 路径：/menu/update

4.5 删除菜单

• 方法：POST
• 路径：/menu/delete

---

5. 角色权限分配

5.1 查询角色权限

• 方法：GET
• 路径：/role/permission/list
• 参数：roleId

返回：

{
  "permissionIds": [1, 2, 3]
}

5.2 分配角色权限

• 方法：POST
• 路径：/role/permission/assign

请求体：

{
  "roleId": 2,
  "permissionIds": [1, 2, 3, 4]
}

返回：

{
  "id": 2
}

---

6. 角色菜单分配

6.1 查询角色菜单

• 方法：GET
• 路径：/role/menu/list
• 参数：roleId

返回：

{
  "menuIds": [1, 2, 3, 4]
}

6.2 分配角色菜单

• 方法：POST
• 路径：/role/menu/assign

请求体：

{
  "roleId": 2,
  "menuIds": [1, 2, 10, 11]
}

返回：

{
  "id": 2
}

---

7. 用户管理

7.1 用户列表

• 方法：GET
• 路径：/user/list

请求参数：

参数名	类型	必填	说明
keyword	string	否	用户名模糊搜索
status	int	否	状态
pageNo	int	否	页码
pageSize	int	否	每页条数

返回 data：

{
  "list": [
    {
      "id": 1,
      "username": "admin",
      "real_name": "管理员",
      "mobile": "13800000000",
      "email": "admin@test.com",
      "avatar": "",
      "status": 1,
      "last_login_time": "2025-01-01 10:00:00",
      "created_by": 1,
      "created_time": "2025-01-01 10:00:00",
      "updated_time": "2025-01-01 10:00:00",
      "role_ids": [1, 2],
      "role_names": ["管理员", "测试经理"]
    }
  ],
  "total": 1
}

7.2 用户详情

• 方法：GET
• 路径：/user/detail
• 参数：userId

返回会额外包含：

{
  "role_ids": [1, 2]
}

7.3 创建用户

• 方法：POST
• 路径：/user/create

请求体：

{
  "username": "zhangsan",
  "password": "123456",
  "realName": "张三",
  "mobile": "13800001111",
  "email": "zhangsan@test.com",
  "avatar": "",
  "status": 1,
  "createdBy": 1
}

返回：

{
  "id": 3
}

7.4 更新用户

• 方法：POST
• 路径：/user/update

7.5 删除用户

• 方法：POST
• 路径：/user/delete

---

8. 用户角色分配

8.1 查询用户角色

• 方法：GET
• 路径：/user/role/list
• 参数：userId

返回：

{
  "roleIds": [1, 2]
}

8.2 分配用户角色

• 方法：POST
• 路径：/user/role/assign

请求体：

{
  "userId": 10,
  "roleIds": [2, 3]
}

响应：

{
  "id": 10
}

---

9. 认证接口

9.1 注册

• 方法：POST
• 路径：/auth/register

请求体：

{
  "username": "zhangsan",
  "password": "123456",
  "realName": "张三",
  "mobile": "13800001111",
  "email": "zhangsan@test.com",
  "avatar": "",
  "createdBy": 1
}

请求参数说明：

参数名	类型	必填	说明
username	string	是	登录用户名
password	string	是	登录密码，当前直接写入 password_hash
realName	string	否	真实姓名
mobile	string	否	手机号
email	string	否	邮箱
avatar	string	否	头像
createdBy	int	否	创建人

成功返回：

{
  "id": 11
}

失败场景：

• username、password 为必传参数
• 用户名已存在！

9.2 登录

• 方法：POST
• 路径：/auth/login

请求体：

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

请求参数说明：

参数名	类型	必填	说明
username	string	是	登录用户名
password	string	是	登录密码

成功返回 data：

{
  "id": 11,
  "username": "zhangsan",
  "real_name": "张三",
  "mobile": "13800001111",
  "email": "zhangsan@test.com",
  "avatar": "",
  "status": 1,
  "last_login_time": null,
  "created_by": 1,
  "created_time": "2025-01-01 10:00:00",
  "updated_time": "2025-01-01 10:00:00",
  "role_ids": [2, 3]
}

失败场景：

• username、password 为必传参数
• 用户名或密码错误！
• 用户已禁用！

登录成功额外返回：

字段	类型	说明
token	string	登录令牌，存入 Redis
token_type	string	固定为 Bearer
expires_in	int	token 过期时间，单位秒，当前为 7200
refresh_threshold_seconds	int	自动续期阈值，单位秒，当前为 1800
refresh_mechanism	string	刷新机制说明

当前 token 机制：

• token 存储位置：Redis
• Redis key 前缀：effekt:token:
• token 过期时间：7200 秒（2小时）
• 刷新机制：访问任意需要登录的接口时，如果 token 剩余有效期小于 1800 秒，则自动续期到完整 2 小时
• 请求头支持：
  • accessToken
  • accesstoken
  • Authorization: Bearer <token>

当前登录接口已返回 token、过期时间和刷新机制说明。

---

10. 一组联调示例

9.1 创建角色

POST /role/create
Content-Type: application/json

{
  "code": "tester",
  "name": "测试人员",
  "description": "普通测试角色",
  "status": 1,
  "isSystem": 0
}

9.2 创建权限

{
  "code": "case:list",
  "name": "查看用例列表",
  "module": "case",
  "action": "list",
  "description": "查看测试用例列表",
  "status": 1
}

9.3 创建菜单

{
  "parentId": 1,
  "name": "权限管理",
  "code": "permission_manage",
  "type": 2,
  "path": "/system/permission",
  "component": "system/permission/index",
  "icon": "lock",
  "permissionCode": "permission:list",
  "sort": 3,
  "visible": 1,
  "status": 1
}

9.4 给角色分配权限

{
  "roleId": 5,
  "permissionIds": [1, 2, 3, 4]
}

9.5 给角色分配菜单

{
  "roleId": 5,
  "menuIds": [1, 2, 8, 9]
}

9.6 创建用户

{
  "username": "lisi",
  "password": "123456",
  "realName": "李四",
  "mobile": "13800002222",
  "email": "lisi@test.com",
  "status": 1
}

10.7 给用户分配角色

{
  "userId": 10,
  "roleIds": [5]
}

10.8 注册

{
  "username": "new_user",
  "password": "123456",
  "realName": "新用户",
  "mobile": "13800009999",
  "email": "new_user@test.com"
}

10.9 登录

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

10.10 鉴权说明

请求受保护接口时，请在请求头中携带以下任意一种：

accessToken: <token>

或

accesstoken: <token>

或

Authorization: Bearer <token>

当前机制：

• token 存 Redis
• 默认有效期：2 小时
• 剩余有效期小于 30 分钟时，访问受保护接口会自动续期
• 注册、登录接口不需要 token
• 其他接口已逐步接入登录鉴权与权限限制

---

11. 当前初始化 SQL 已包含的业务菜单

已补入以下可直接录入的菜单数据：

系统管理

• system 系统管理
• role_manage 角色管理
• user_manage 用户管理
• permission_manage 权限管理
• menu_manage 菜单管理

测试平台

• test_platform 测试平台
• product_manage 产品管理
• project_manage 项目管理
• case_manage 用例管理
• plan_manage 测试计划
• report_manage 测试报告

造数工具

• data_tools 造数工具
• data_builder_manage 数据库造数
• data_factory_manage 造数工厂

如果后续你要，我可以继续补：

1. Swagger/OpenAPI 版本
2. Apifox / Postman 导入版
3. 初始化权限菜单角色的更完整种子数据