# 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。