ThinkAdmin/plugin/think-plugs-system/readme.api.md

# 系统管理接口

## 接口标准
- HTTP 入口：`/api/system/{controller}/{action}`
- 适用范围：后台管理接口，默认要求后台登录态或后台 Bearer JWT
- 返回格式：以 JSON 为主，上传选择器等接口可能返回 HTML 或脚本内容
- HTTP 状态码固定返回 `200`
- `code` 统一使用常见业务状态语义：`200` 成功、`401` 未认证/登录过期、`403` 已认证但无权限、`404` 资源不存在、`500` 服务端异常

```jsonc
{
  "code": 200, // 业务状态码
  "info": "ok", // 提示信息
  "data": {}, // 业务数据
  "error": "", // 可选，401/403 等鉴权异常时返回稳定错误标识
  "url": "", // 可选，后续跳转地址
  "wait": 3 // 可选，前端等待秒数
}
```

## 接口列表

### `/api/system/upload/index`
- 说明：输出上传脚本配置

```jsonc
{}
```

### `/api/system/plugs/icon`
- 说明：图标选择器

```jsonc
{}
```

### `/api/system/plugs/script`
- 说明：输出后台前端脚本变量

```jsonc
{}
```

### `/api/system/plugs/optimize`
- 说明：执行数据库优化

```jsonc
{}
```

### `/api/system/system/push`
- 说明：刷新运行发布缓存

```jsonc
{}
```

### `/api/system/system/clear`
- 说明：清理运行缓存与日志缓存

```jsonc
{}
```

### `/api/system/system/debug`
- 说明：切换开发/生产模式

```jsonc
{
  "state": 1 // 1 切换到生产模式，0 切换到开发模式
}
```

### `/api/system/system/config`
- 说明：清理并重建系统配置缓存

```jsonc
{}
```

### `/api/system/queue/start`
- 说明：启动后台监听服务

```jsonc
{}
```

### `/api/system/queue/stop`
- 说明：停止后台监听服务

```jsonc
{}
```

### `/api/system/queue/status`
- 说明：查询监听服务状态

```jsonc
{}
```

### `/api/system/queue/progress`
- 说明：查询队列任务进度

```jsonc
{
  "code": "QUEUE_CODE" // 队列任务编号
}
```

### `/api/system/upload/image`
- 说明：文件选择器或图片库列表

```jsonc
{}
```

### `/api/system/upload/state`
- 说明：创建上传授权或秒传记录

```jsonc
{
  "name": "avatar.png", // 原始文件名
  "hash": "md5-or-sha1", // 文件哈希值
  "extension": "png", // 文件扩展名
  "xext": "png", // 可选，兼容旧字段的扩展名
  "size": 1024, // 文件大小，单位字节
  "mime": "image/png", // 可选，文件 MIME 类型
  "key": "upload/avatar.png", // 存储对象键
  "uptype": "local", // 可选，存储驱动类型
  "safe": 0 // 可选，是否安全文件，0 否，1 是
}
```

### `/api/system/upload/done`
- 说明：确认上传完成并更新文件状态

```jsonc
{
  "id": 1, // 文件记录 ID
  "hash": "md5-or-sha1" // 文件哈希值
}
```

### `/api/system/upload/file`
- 说明：直接上传文件到当前配置的存储驱动

```jsonc
{
  "file": "(binary)", // 表单上传文件本体
  "key": "upload/avatar.png", // 可选，指定存储对象键
  "uptype": "local", // 可选，存储驱动类型
  "safe": 0 // 可选，是否写入安全目录，0 否，1 是
}
```