Skip to content

APIDocument.md

Latest commit

 

History

History
806 lines (481 loc) · 15.2 KB

APIDocument.md

File metadata and controls

806 lines (481 loc) · 15.2 KB

CIMS API 文档

概述

CIMS 提供四个独立端口的 API 服务：

端口 名称 用途
27041 Client API ClassIsland 客户端获取配置和资源
27042 Management API 用户认证、账户管理、资源管理、客户端控制
27043 Admin API 超级管理员全局用户/账户/系统管理
27044 gRPC Cyrene_MSP 协议（注册、命令推送、心跳）

Client API :27041

GET /

服务状态检测。

响应

{"message": "CIMS Client API 运行中"}

GET /api/v1/client/{client_uid}/manifest

获取客户端配置清单。

参数 位置 类型 必填 说明
client_uid path string ✅ 客户端唯一标识

响应 — Manifest JSON，包含各资源类型的名称列表。

GET /api/v1/client/{resource_type}

获取指定资源（302 重定向到令牌下载地址）。

参数 位置 类型 必填 说明
resource_type path string ✅ 合法值: ClassPlan, TimeLayout, Subjects, Policy, DefaultSettings, Components, Credentials
name query string ✅ 资源文件名

GET /get

通过令牌获取资源 JSON 内容。

参数 位置 类型 必填 说明
token query string ✅ 一次性资源访问令牌

响应 — 资源 JSON 内容。

GET /api/v1/management-config

获取 ManagementPreset 引导配置。

参数 位置 类型 必填 说明
class_identity query string ❌ 班级标识（匹配预注册客户端）

响应

{
  "IsManagementEnabled": true,
  "ManagementServerKind": 1,
  "ManagementServer": "https://{slug}.example.com",
  "ManagementServerGrpc": "grpc://{slug}.example.com",
  "ClassIdentity": "",
  "PreRegisteredLabel": "三年一班",
  "ManifestUrlTemplate": ""
}

Management API :27042

所有端点（除 /user/apply 和 /user/auth）需要 Authorization: Bearer {token} 请求头。

Token 管理

POST /token/refresh

刷新当前会话令牌。

响应

{"token": "新的会话令牌"}

POST /token/verify

验证令牌有效性。

响应

{"valid": true, "user_id": "uuid"}

POST /token/deactivate

注销当前令牌（登出）。

响应

{"status": "success", "message": "已登出"}

用户

POST /user/apply

申请注册新用户。注册后进入 Pending 状态，需管理员审核。

请求体

{
  "email": "user@example.com",
  "password": "至少12位密码",
  "username": "可选",
  "display_name": "可选"
}

POST /user/auth

用户登录，获取会话令牌。

请求体

{"email": "user@example.com", "password": "密码"}

响应（正常） — {"token": "会话令牌"}

响应（需 2FA） — {"requires_2fa": true, "temp_token": "临时令牌"}

GET /user/availability/mail

检查邮箱是否可用（未被占用）。无需认证。

参数 位置 类型 必填 说明
value query string ✅ 待检查的邮箱地址

响应 — {"available": true|false}

GET /user/availability/username

检查用户名是否可用（未被占用、非系统保留且格式合法）。无需认证。

参数 位置 类型 必填 说明
value query string ✅ 待检查的用户名（3-64位）

响应 — {"available": true|false, "reason": "不可用原因(可选)"}

GET /user/info

获取当前用户信息。

响应 — UserOut

2FA (TOTP) /user/2fa/totp/...

POST /user/2fa/totp/enable

启用 TOTP。返回密钥和恢复码。

POST /user/2fa/totp/confirm

确认绑定（提交首次 TOTP 码）。

请求体 — {"code": "123456"}

POST /user/2fa/totp/disable

禁用 TOTP。

请求体 — {"password": "当前密码"}

POST /user/2fa/totp/verify

登录时验证 TOTP。

请求体 — {"temp_token": "临时令牌", "code": "123456"}

响应 — {"token": "正式会话令牌"}

POST /user/2fa/totp/recover

使用恢复码登录。

请求体 — {"temp_token": "临时令牌", "recovery_code": "恢复码"}

用户信息 /user/info/...

GET /user/info/

获取用户信息（同 GET /user/info）。

POST /user/info/email

修改邮箱。

请求体 — {"email": "new@example.com"}

POST /user/info/username

修改用户名。

请求体 — {"username": "new_username"}

POST /user/info/password/change

修改密码（需旧密码）。

请求体 — {"old_password": "旧密码", "new_password": "至少12位新密码"}

POST /user/info/password/reset

重置密码（自助流程）。

账户管理

GET /account/availability/slug

检查账户 URL 标识 (Slug) 是否可用。需登录。

参数 位置 类型 必填 说明
value query string ✅ 待检查的 Slug（3-64位）

响应 — {"available": true|false, "reason": "不可用原因(可选)"}

GET /account/list

列出当前用户有权访问的所有账户。

响应 — AccountOut[]

POST /account/search

搜索账户。

参数 位置 类型 说明
q query string 搜索关键字

POST /account/apply

申请创建新账户。

请求体 — {"name": "学校名称", "slug": "可选"}

DELETE /account/{account_id}

删除/停用账户。

GET /account/{account_id}/info

获取账户详情。

响应 — AccountOut

POST /account/{account_id}/info/slug

修改账户 slug。

请求体 — {"slug": "new-slug-name"}

资源管理 /account/{account_id}/{resource_type}/...

GET /{resource_type}/list

列出所有资源文件名。

POST /{resource_type}/search

搜索资源。

POST /{resource_type}/create

创建资源。

POST /{resource_type}/upload

上传资源。

DELETE /{resource_type}/{resource_id}

删除资源。

POST /{resource_type}/{resource_id}/rename

重命名资源。

POST /{resource_type}/{resource_id}

覆盖写入资源。

GET /{resource_type}/{resource_id}

下载资源。

当前实现仍使用 ?name= 查询参数模式而非路径参数：

  • GET /{resource_type}/create?name={name} — 创建空资源
  • GET /{resource_type}/token?name={name} — 签发访问令牌
  • PUT|POST /{resource_type}/write?name={name} — 覆盖写入
  • PATCH /{resource_type}/update?name={name} — 增量合并更新
  • GET|DELETE /{resource_type}/delete?name={name} — 删除资源

客户端管理 /account/{account_id}/client/...

GET /client/list

列出已注册客户端 UID。

GET /client/search

搜索客户端。

GET /client/{client_id}

查询客户端注册详情及在线状态。

响应

{
  "uid": "client-uid",
  "name": "client-id",
  "mac": "AA:BB:CC:DD:EE:FF",
  "status": "online",
  "registered_at": "2026-01-01T00:00:00Z"
}

DELETE /client/{client_id}

删除客户端。

POST /client/{client_id}/rename

重命名客户端。

GET /client/{client_id}/status

获取客户端在线状态。

POST /client/{client_id}/disconnect

断开客户端连接。

POST /client/{client_id}/disable

禁用客户端。

POST /client/{client_id}/enable

启用客户端。

POST /client/{client_id}/config

修改客户端使用的档案组。

POST /client/{client_id}/command/restart

重启客户端应用。

POST /client/{client_id}/command/update-data

强制客户端同步最新数据。

POST /client/{client_id}/command/send-notification

发送通知。

请求体

{
  "title": "标题",
  "content": "内容",
  "icon": "info",
  "tts": false,
  "urgent": false
}

GET /client/{client_id}/command/get-config

请求客户端上报运行时配置。

参数 位置 类型 说明
config_type query int 配置类型枚举

配对码管理 /account/{account_id}/pairing/...

GET /pairing/list

列出配对码。

GET /pairing/search

搜索配对码。

POST /pairing/{pairing_id}/reject

拒绝配对码。

POST /pairing/{pairing_id}/approve

批准配对码。

POST /pairing/enable

启用配对码功能。

POST /pairing/disable

禁用配对码功能。

预注册客户端 /account/{account_id}/pre-registration/...

GET /pre-registration/list

列出预注册客户端。

GET /pre-registration/search

搜索预注册客户端。

GET /pre-registration/{pre_reg_id}

获取预注册客户端信息。

DELETE /pre-registration/{pre_reg_id}

删除预注册客户端。

POST /pre-registration/{pre_reg_id}/rename

重命名预注册客户端。

POST /pre-registration/{pre_reg_id}/enable

启用预注册客户端。

POST /pre-registration/{pre_reg_id}/disable

禁用预注册客户端。

GET /pre-registration/{pre_reg_id}/ManagementPreset.json

下载引导配置。

POST /pre-registration/{pre_reg_id}/config

修改预注册客户端使用的档案组。

POST /pre-registration/create

创建预注册客户端。

请求体 — {"label": "三年一班", "class_identity": "3-1"}

访问控制 /account/{account_id}/access/...

GET /access/list

列出具权用户。

GET /access/search

搜索具权用户。

GET /access/{user_id}

获取具权用户信息。

DELETE /access/{user_id}

移除成员（204 No Content）。

POST /access/{user_id}/rename

重命名具权用户。

POST /access/{user_id}

修改具权用户的权限。

请求体 — {"role_in_account": "admin"}

邀请 /account/{account_id}/invitation/...

GET /invitation/list

列出邀请列表。

POST /invitation/create

创建邀请。

请求体

{
  "role_in_account": "member",
  "max_uses": 1,
  "expires_at": "2026-12-31T23:59:59Z"
}

GET /invitation/search

搜索邀请。

DELETE /invitation/{invitation_id}

删除邀请。

POST /invitation/{invitation_id}/rename

重命名邀请。

GET /invitation/{invitation_id}

获取邀请信息。

批量操作

POST /account/bulk

执行批量资源操作。

请求体

{
  "operations": [
    {
      "action": "write",
      "resource_type": "ClassPlan",
      "name": "文件名",
      "payload": {}
    }
  ]
}
action 说明
create 创建资源
write 覆盖写入
update 增量合并
delete 删除资源

Admin API :27043

所有端点需要超级管理员认证（Authorization: Bearer {admin_secret}）。

用户管理

GET /user/list

分页查询所有用户。

参数 位置 类型 说明
offset query int 偏移量（默认 0）
limit query int 条数（默认 20）

响应 — UserOut[]

GET /user/search

搜索用户。

参数 位置 类型 说明
q query string 搜索关键字

POST /user/create

直接创建用户（跳过审核）。

请求体

{
  "email": "user@example.com",
  "password": "至少12位密码",
  "username": "可选",
  "display_name": "可选"
}

GET /user/{user_id}

获取用户信息。

响应 — UserOut

POST /user/{user_id}

修改用户信息。

请求体

{
  "display_name": "新名称",
  "role_code": "normal",
  "is_active": true,
  "can_create_account": true
}

DELETE /user/{user_id}

删除用户。

POST /user/{user_id}/rename

重命名用户。

请求体 — {"name": "新用户名"}

POST /user/{user_id}/password/reset

重置用户密码（无需旧密码）。

请求体 — {"new_password": "至少12位新密码"}

POST /user/{user_id}/password/change

修改用户密码（需验证旧密码）。

请求体 — {"old_password": "旧密码", "new_password": "新密码"}

用户 2FA 管理

POST /user/{user_id}/2fa/enable

为用户启用 TOTP。

POST /user/{user_id}/2fa/disable

禁用用户 TOTP。

POST /user/{user_id}/2fa/verify

验证用户 TOTP。

POST /user/{user_id}/2fa/reset

重置用户 TOTP 密钥。

用户审核

GET /user/pending/list

列出待审核用户。

参数 位置 类型 说明
offset query int 偏移量（默认 0）
limit query int 条数（默认 50）

POST /user/pending/approve/{user_id}

批准用户注册。

POST /user/pending/reject/{user_id}

拒绝用户注册。

账户管理

GET /account

列出所有账户（跨租户）。复用 Management API 的 /account 接口，但具备所有权限。允许 ?role={user_id} 以某个用户身份操作。

响应 — AccountOut[]

系统设置

GET /settings

获取所有系统设置。

响应 — 键值对 JSON。

POST /settings

修改系统设置。

仅允许以下 key：registration_open, require_approval, max_accounts_per_user, default_role, motd。

请求体 — 键值对 JSON。

批量操作

POST /bulk

执行批量资源操作（同 Management API /account/bulk）。

gRPC :27044

ClientRegister

客户端注册。

请求 — ClientRegisterCsReq

字段 类型 说明
uid string 客户端唯一标识
client_id string 客户端 ID
mac string MAC 地址
ip string IP 地址
pairing_code string 配对码

响应 — ClientRegisterScRsp

字段 类型 说明
RetCode enum 返回码（Success/Fail）
ServerPublicKey bytes 服务器公钥

ClientCommand (双向流)

命令通道。

客户端发送 — ClientCommandDeliverCsReq（命令响应 / Ping）

服务端推送 — ClientCommandDeliverScRsp

字段 类型 说明
RetCode enum 返回码
Type enum 命令类型 (RestartApp, DataUpdated, SendNotification, GetClientConfig)
Payload bytes Protobuf 序列化的命令负载

HeartBeat

心跳保活。客户端定期发送心跳，服务端回复确认。

通用数据模型

UserOut

{
  "id": "uuid",
  "username": "user_a1b2c3d4",
  "email": "user@example.com",
  "display_name": "显示名称",
  "role_code": "normal",
  "is_active": true,
  "can_create_account": false,
  "created_at": "2026-01-01T00:00:00Z"
}

AccountOut

{
  "id": "uuid",
  "name": "账户名称",
  "slug": "org-a1b2c3d4",
  "api_key": "API密钥",
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z"
}

StatusResponse

{
  "status": "success|error",
  "message": "操作结果描述"
}