# 05-API接口契约

BasePath: `/api`
端口: `8080`

## 全局约定

### 响应格式
```json
{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000}
```

### 错误码
| 范围 | 含义 |
|---|---|
| 200 | 成功 |
| 400xx | 客户端参数错误 |
| 401xx | 认证/授权错误 |
| 403xx | 权限不足 |
| 404xx | 资源不存在 |
| 500xx | 服务端内部错误 |

### 鉴权

除登录接口（`POST /api/auth/login`）外，所有接口要求 `Authorization: Bearer <accessToken>` 请求头。token 由 `POST /api/auth/login` 签发，HS256，有效期 2 小时；过期返回 `40101`，前端需用 refreshToken 换新或重新登录。

### 分页参数

- 入参（query）：`pageNum`（≥1，默认 1）、`pageSize`（1~100，默认 20）、`keyword`（可选模糊查询）、`sort`（可选，形如 `field,asc|desc`）。
- 出参（data）：`{ "total": 0, "list": [], "pageNum": 1, "pageSize": 20 }`。

## 接口清单

（各模块接口段落见下方，由 `downstream-gen` 按 REQ 填入）

---

## module_mod 模块管理

### REQ-MOD-001 模块新增

- **Method**: POST
- **Path**: `/api/modules`
- **Auth**: 需要
- **Permission**: `MOD:CREATE`
- **请求**: JSON body：`sDisplayType`（必填，枚举：手机端 / 前端业务 / 系统配置 / 接口）、`sProcedureName`（必填，唯一）、`sModuleType`（必填）、`sManageDeptEn`（必填）、`bShowPermission`（可选，默认 false）、`sModuleNameZh`（必填）、`iParentId`（可选）、`iSortOrder`（可选，默认 0）
- **响应**: `data.iIncrement` 新模块主键 + 完整模块对象（VO）

#### 错误码
- `40010` — 参数缺失或格式错误
- `40911` — `sProcedureName` 已存在（唯一性冲突）
- `40411` — `iParentId` 指向的父模块不存在或已删除

---

### REQ-MOD-002 模块修改

- **Method**: PUT
- **Path**: `/api/modules/{id}`
- **Auth**: 需要
- **Permission**: `MOD:UPDATE`
- **请求**: 路径参数 `id` = `iIncrement`；JSON body 同新增（`sProcedureName` 不可改），未提供字段保持原值
- **响应**: `data` = 更新后的模块 VO

#### 错误码
- `40010` — 参数缺失或格式错误
- `40421` — 模块不存在或已删除
- `40921` — 同级名称冲突或不能将自身/后代设为父模块
- `40911` — `sProcedureName` 冲突（如尝试修改）

---

### REQ-MOD-003 模块删除

- **Method**: DELETE
- **Path**: `/api/modules/{id}`
- **Auth**: 需要
- **Permission**: `MOD:DELETE`
- **请求**: 路径参数 `id` = `iIncrement`
- **响应**: `data` = `{ "iIncrement": <id>, "bDeleted": 1 }`（软删除标记）

#### 错误码
- `40421` — 模块不存在或已被删除
- `40912` — 存在子模块或外部业务引用，禁止删除（响应附 `data.references`）

---

### REQ-MOD-004 模块查询

- **Method**: GET
- **Path**: `/api/modules`
- **Auth**: 需要
- **Permission**: `MOD:READ`
- **请求**: query 参数 `keyword`（可选，对 `sModuleNameZh` 模糊匹配）；返回完整树而非分页
- **响应**: `data` = 模块树数组，节点结构：`{ iIncrement, sModuleNameZh, sDisplayType, sManageDeptEn, iParentId, iSortOrder, children: [] }`

#### 错误码
- `40010` — `keyword` 长度超限

---

## module_usr 用户管理

### REQ-USR-001 用户新增

- **Method**: POST
- **Path**: `/api/users`
- **Auth**: 需要
- **Permission**: `USR:CREATE`
- **请求**: JSON body：`sUserNo`（必填）、`sUserName`（必填）、`iStaffId`（可选）、`sUserType`（必填）、`sLanguage`（必填）、`bCanModifyDocs`（可选，默认 false）、`permissionCategoryIds`（数组，对应 REQ-USR-001 表 2 选中行写入 `tUserPermission`）；密码不在请求中传，后端使用初始密码 `666666` 经 BCrypt 哈希后落库
- **响应**: `data.iIncrement` 新用户主键 + 用户 VO（不含密码哈希）

#### 错误码
- `40020` — 参数缺失或格式错误
- `40921` — `sUserName` 或 `sUserNo` 唯一性冲突
- `40421` — `iStaffId` 不存在或已软删除
- `40422` — `permissionCategoryIds` 含不存在的权限分类

---

### REQ-USR-002 用户修改

- **Method**: PUT
- **Path**: `/api/users/{id}`
- **Auth**: 需要
- **Permission**: `USR:UPDATE`
- **请求**: 路径参数 `id` = `iIncrement`；JSON body 同新增（`sUserNo` 不可改）；`permissionCategoryIds` 重新覆盖当前权限关联（先删后插）
- **响应**: `data` = 更新后的用户 VO

#### 错误码
- `40020` — 参数缺失或格式错误
- `40431` — 用户不存在或已软删除
- `40931` — `sUserName` 唯一性冲突
- `40331` — 当前操作员无权变更目标角色

---

### REQ-USR-003 用户查询

- **Method**: GET
- **Path**: `/api/users`
- **Auth**: 需要
- **Permission**: `USR:READ`
- **请求**: query 参数：`pageNum` / `pageSize`（标准分页）、`queryField`（枚举：`username` / `staffname` / `userno` / `department` / `usertype` / `deleted` / `lastLoginDate` / `createdBy`）、`matchType`（`contains` / `notContains` / `equals`）、`queryValue`（可空）
- **响应**: `data` = `PageResult<UserListVO>`，VO 字段：`iIncrement`、`sUserName`、`sStaffName`（join `tStaff`）、`sUserNo`、`sDepartment`（join `tStaff`）、`sUserType`、`sLanguage`、`bDeleted`、`tLastLoginDate`、`sCreatedBy`、`tCreateDate`

#### 错误码
- `40020` — `queryField` / `matchType` 非枚举值
- `40021` — `pageSize` 超出 1~100

---

### REQ-USR-004 用户登录

- **Method**: POST
- **Path**: `/api/auth/login`
- **Auth**: 不需要
- **Permission**: 无
- **请求**: JSON body：`sUserName`（必填）、`sPassword`（必填，明文，HTTPS 传输）、`sVersion`（必填，枚举：`standard`）
- **响应**: `data` = `{ "accessToken": "...", "refreshToken": "...", "expiresIn": 7200, "user": { "iIncrement", "sUserNo", "sUserName", "sUserType", "sLanguage" } }`；登录成功同时回写 `tUser.tLastLoginDate`

#### 错误码
- `40101` — 用户名或密码错误（统一提示，不区分原因）
- `40102` — 账号已禁用 / 已软删除
- `40301` — 账号被临时锁定（响应附 `data.cooldownSeconds` 剩余秒数）
- `40020` — 参数缺失或格式错误