demo/docs/API_EXAMPLES.md

# 接口联调示例

## 启动顺序

1. 执行 `src/main/resources/sql/init-auth-schema.sql`
2. 执行 `src/main/resources/sql/init-demo-data.sql`
3. 启动应用
4. 访问 `POST /api/captcha/generate`
5. 使用返回的验证码登录

## 1. 获取验证码

接口:

```http
POST /api/captcha/generate
```

返回示例:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "key": "8f3b8fd4d2cf4d1ca6a4b8cf7ab33f9d",
    "image": "data:image/png;base64,..."
  }
}
```

## 2. 登录

接口:

```http
POST /api/auth/login
Content-Type: application/json
```

请求体:

```json
{
  "username": "admin",
  "password": "admin123",
  "captchaKey": "8f3b8fd4d2cf4d1ca6a4b8cf7ab33f9d",
  "captchaCode": "a8k3"
}
```

返回示例:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "token": "xxxxxx",
    "tokenName": "Authorization",
    "userInfo": {
      "id": 1000000000000000001,
      "username": "admin",
      "nickname": "系统管理员",
      "status": 1,
      "statusDesc": "正常"
    },
    "roles": ["ADMIN"],
    "permissions": [
      "system:user:page",
      "system:role:page",
      "system:menu:list"
    ]
  }
}
```

后续请求头:

```http
Authorization: xxxxxx
```

## 3. 查询当前用户菜单

接口:

```http
POST /api/menu/current
Authorization: xxxxxx
```

## 4. 查询当前用户权限标识

接口:

```http
POST /api/menu/permissions/current
Authorization: xxxxxx
```

## 5. 查询前端下拉字典

查询字典类型:

```http
POST /api/enums/list
```

返回示例:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "enumName": "LogType",
      "enumDesc": "日志类型枚举",
      "displayName": "LogType",
      "className": "com.test.demo.enums.LogType",
      "packageName": "com.test.demo.enums",
      "valueType": "java.lang.String",
      "sourceType": "SYSTEM",
      "builtin": 1,
      "queryPath": "/api/enums/LogType"
    }
  ]
}
```

查询字典项:

```http
POST /api/enums/items/LogType
```

返回示例:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "value": "LOGIN",
      "desc": "登录日志"
    },
    {
      "value": "OPER",
      "desc": "操作日志"
    }
  ]
}
```

## 6. 新增自定义字典类型

接口:

```http
POST /api/enum-manage/type/add
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "enumCode": "PayChannel",
  "enumName": "支付渠道",
  "enumDesc": "支付渠道字典",
  "enabled": 1,
  "sort": 1,
  "remark": "联调新增"
}
```

## 7. 新增自定义字典项

接口:

```http
POST /api/enum-manage/item/add
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "enumCode": "PayChannel",
  "itemValue": "ALIPAY",
  "itemLabel": "支付宝",
  "itemName": "ALIPAY",
  "enabled": 1,
  "sort": 1
}
```

## 8. 启停字典类型

接口:

```http
POST /api/enum-manage/type/enable/2033103240660238338?enabled=0
Authorization: xxxxxx
```

## 9. 启停字典项

接口:

```http
POST /api/enum-manage/item/enable/2033103240752513025?enabled=1
Authorization: xxxxxx
```

## 10. 查询登录日志

接口:

```http
POST /api/log/login/page
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "pageNum": 1,
  "pageSize": 10,
  "username": "admin"
}
```

## 11. 导出登录日志

接口:

```http
POST /api/log/login/export
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "username": "admin",
  "logType": "LOGIN"
}
```

## 12. 查询操作日志

接口:

```http
POST /api/log/oper/page
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "pageNum": 1,
  "pageSize": 10,
  "userName": "admin"
}
```

## 13. 导出操作日志

接口:

```http
POST /api/log/oper/export
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "userName": "admin",
  "logType": "OPER"
}
```

## 14. 查询文件列表

接口:

```http
POST /api/file/list
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "relativeDir": "",
  "recursive": true,
  "pageNum": 1,
  "pageSize": 20
}
```

## 15. 上传文件

接口:

```http
POST /api/file/upload
Authorization: xxxxxx
Content-Type: multipart/form-data
```

参数:

`file`: 文件

## 16. 下载文件

接口:

```http
GET /api/file/download/2026/03/15/demo.xlsx
Authorization: xxxxxx
```

## 17. 预览文件

接口:

```http
GET /api/file/preview/2026/03/15/demo.xlsx
```

## 18. 导入用户

接口:

```http
POST /api/user/import
Authorization: xxxxxx
Content-Type: multipart/form-data
```

参数:

`file`: 用户导入模板

## 19. 导出用户

接口:

```http
POST /api/user/export
Authorization: xxxxxx
Content-Type: application/json
```

请求体:

```json
{
  "username": "admin",
  "pageNum": 1,
  "pageSize": 10
}
```

## 20. 可选签名请求头

如果客户端要启用签名，可附带以下请求头:

```http
X-Timestamp: 1710000000
X-Nonce: random-string
X-Sign: sha256(timestamp + nonce + body + signSecret)
```

签名密钥配置在:

`security.sign.secret`