132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
# MGT REST API
|
||
|
||
后台用户、应用、角色、权限和部门管理。基础路径：`/rest/mgt`。除匿名接口外均需在 `Authorization` 头直接携带 JWT（不加 `Bearer`）；标记“管理员”的路由还会执行管理员权限检查。
|
||
|
||
## 匿名接口
|
||
|
||
| 方法 | 路径 | 请求类型 | 说明 |
|
||
|---|---|---|---|
|
||
| GET | `/rest/mgt/ping` | 无 | 健康检查 |
|
||
| GET | `/rest/mgt/session` | 无 | Session 演示接口 |
|
||
| POST | `/rest/mgt/login` | `LoginRequest` | 登录并获取 token |
|
||
| POST | `/rest/mgt/refresh` | 当前凭证 | 刷新登录状态 |
|
||
| POST | `/rest/mgt/reset` | `ForgetPwdRequest` | 使用短信验证码重置密码 |
|
||
|
||
## 用户接口
|
||
|
||
| 路径后缀 | 请求类型 | 权限 | 说明 |
|
||
|---|---|---|---|
|
||
| `/user/role` | `FetchBase` | 登录 | 获取用户角色 |
|
||
| `/user/app` | `FetchBase` | 登录 | 获取用户应用 |
|
||
| `/user/pmn` | `FetchBase` | 登录 | 获取用户权限 |
|
||
| `/user/pmn_tree` | `FetchBase` | 登录 | 获取用户权限树 |
|
||
| `/user/create` | `UserRequest` | 管理员 | 创建用户 |
|
||
| `/user/del`、`/user/detail`、`/user/fetch` | `UserRequest` | 管理员 | 删除、详情和查询 |
|
||
| `/user/modify` | `UserRequest` | 管理员 | 修改用户 |
|
||
| `/user/list` | `FetchBase` | 管理员 | 用户列表 |
|
||
| `/user/set_role`、`/user/del_role` | `UserRoleRequest` | 管理员 | 设置或移除角色 |
|
||
| `/user/set_pmn`、`/user/modify_pmn`、`/user/del_pmn` | `AddPmnRequest` | 管理员 | 设置、修改或移除权限 |
|
||
|
||
表内接口均为 POST，完整路径在后缀前加 `/rest/mgt`。
|
||
|
||
## 应用接口
|
||
|
||
全部为管理员 POST 接口，基础路径 `/rest/mgt/app`。
|
||
|
||
| 后缀 | 请求类型 | 说明 |
|
||
|---|---|---|
|
||
| `/create`、`/modify` | `ApplicationRequest` | 创建、修改应用 |
|
||
| `/del`、`/detail`、`/fetch` | `ApplicationRequest` | 删除、详情、查询 |
|
||
| `/user`、`/role`、`/pmn` | `FetchBase` | 获取应用关联用户、角色、权限 |
|
||
|
||
## 角色接口
|
||
|
||
全部为管理员 POST 接口，基础路径 `/rest/mgt/role`。
|
||
|
||
| 后缀 | 请求类型 | 说明 |
|
||
|---|---|---|
|
||
| `/create`、`/modify` | `RoleReq` | 创建、修改角色 |
|
||
| `/del`、`/detail`、`/fetch` | `RoleReq` | 删除、详情、查询 |
|
||
| `/user`、`/app`、`/pmn`、`/pmn_tree` | `FetchBase` | 获取关联对象 |
|
||
| `/set_pmn`、`/modify_pmn`、`/del_pmn` | `AddPmnRequest` | 管理角色权限 |
|
||
|
||
## 权限接口
|
||
|
||
全部为管理员 POST 接口，基础路径 `/rest/mgt/pmn`。
|
||
|
||
| 后缀 | 请求类型 | 说明 |
|
||
|---|---|---|
|
||
| `/create`、`/modify` | `PermissionRequest` | 创建、修改权限或菜单 |
|
||
| `/del`、`/detail`、`/fetch` | `PermissionRequest` | 删除、详情、查询 |
|
||
| `/sort` | `SortPmnRequest[]` | 批量排序 |
|
||
| `/user`、`/role` | `FetchBase` | 获取关联用户或角色 |
|
||
|
||
## 部门接口
|
||
|
||
全部为管理员 POST 接口，基础路径 `/rest/mgt/dpt`。
|
||
|
||
| 后缀 | 请求类型 | 说明 |
|
||
|---|---|---|
|
||
| `/create`、`/modify` | `DptReq` | 创建、修改部门 |
|
||
| `/del`、`/detail`、`/fetch`、`/list`、`/fetch_tree` | `DptReq` | 删除、详情、分页、列表或树 |
|
||
| `/set_pmn`、`/modify_pmn`、`/del_pmn` | `AddPmnRequest` | 管理部门权限 |
|
||
| `/pmn`、`/pmn_tree`、`/user` | `FetchBase` | 获取部门权限、权限树或用户 |
|
||
| `/set_user`、`/del_user` | `DptUserRequest` | 批量移入或移出用户 |
|
||
|
||
## 请求结构
|
||
|
||
### FetchBase
|
||
|
||
`page:int`、`size:int`、`id:uint`、`keyword:string`、`identity:string`、`status:int8`、`workspace:string`。
|
||
|
||
### LoginRequest
|
||
|
||
`account`、`password`、`phone`、`phone_code`、`workspace`、`app_id`、`app_key`，均为字符串。账号密码或手机验证码的有效组合由登录逻辑决定。
|
||
|
||
### ForgetPwdRequest
|
||
|
||
`account`、`code`、`password`、`phone` 均必填；密码至少 6 位。
|
||
|
||
### UserRequest
|
||
|
||
继承 `FetchBase`，增加 `account`、`name`、`password`、`phone`、`email`、`avatar`、`roles`。
|
||
|
||
### UserRoleRequest
|
||
|
||
```json
|
||
{"user_id":1,"role_id":[1,2]}
|
||
```
|
||
|
||
### ApplicationRequest
|
||
|
||
继承 `FetchBase`，增加 `title`、`workspace`、`description`。
|
||
|
||
### RoleReq
|
||
|
||
继承 `FetchBase`，增加 `name`、`description`。
|
||
|
||
### PermissionRequest
|
||
|
||
继承 `FetchBase`，增加 `title`、`title_en`、`code`、`workspace`、`description`、`parent_id`、`menu_path`、`menu_icon`、`type`、`component`、`sort_key`、`order_desc`、`is_web_page`、`is_new_tab`、`is_full`、`hide_menu`、`web_url`。`type` 取值为 `1=菜单`、`2=按钮`。
|
||
|
||
### AddPmnRequest
|
||
|
||
```json
|
||
{"workspace":"default","id":1,"list":[10,11]}
|
||
```
|
||
|
||
### SortPmnRequest
|
||
|
||
```json
|
||
[{"pmn_id":10,"sort_key":1},{"pmn_id":11,"sort_key":2}]
|
||
```
|
||
|
||
### DptReq / DptUserRequest
|
||
|
||
- `DptReq`：继承 `FetchBase`，增加 `name`、`leader_id`、`parent_id`、`tree`。
|
||
- `DptUserRequest`：`dpt_id:uint`、`user_ids:uint[]`，均必填。
|
||
|
||
## 通用响应
|
||
|
||
接口使用 SDK 统一响应包装，常见数据结构包括：登录 `LoginResp`、分页 `{total,data,page,size}`、创建 `{id,identity}`。客户端必须同时判断 HTTP 状态和响应中的业务 code。
|