系统信息、软件升级与配网
4.1 GET /v1/api/systems/device
公开查询，无参数。响应 data：
{"sn":"SN1234567890","model":"robot-model","version":"3.1.0","device_type":"rk","variant":"standard"}
| 字段 | 类型 | 说明 |
|---|---|---|
sn | string | 业务 SN，识别设备时优先使用 |
model | string | 型号信息 |
version | string | 当前设备软件版本信息；精确软件包版本见 packages |
device_type | string | 当前解析的 Mender 设备类型 |
variant | string | 设备变体信息，取值由身份数据决定 |
4.2 GET /v1/api/systems/health
受保护，无参数。响应字段：
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | 本服务健康标识，正常为 ok |
uptime_seconds | number | 进程运行秒数 |
timestamp | string | 服务端时间 |
provisioning | object，可选 | 配网状态；桥接失败时可能只有 healthy=false, available=false |
{"status":"ok","uptime_seconds":3600,"timestamp":"2026-11-13T08:00:00Z","provisioning":{"healthy":false,"available":false}}
4.3 GET /v1/api/systems/hub
受保护，无参数。返回主机 CPU、内存与日志目录所在磁盘的使用情况。磁盘统计以配置的 server.log_folder 为依据。
| 字段 | 类型 | 单位 / 含义 |
|---|---|---|
hostname | string | 主机名 |
cpu_usage | number | CPU 使用百分比 |
mem_used_mb、mem_total_mb | number | 已用、总内存，MB |
disk_path | string | 实际统计的磁盘路径 |
disk_usage | number | 磁盘使用百分比 |
disk_used_bytes、disk_total_bytes、disk_available_bytes | integer | 磁盘容量，字节 |
disk_status | string | normal、warning、critical、unknown；读取失败时部分 disk_* 容量字段可缺失 |
{"hostname":"orsus-device","cpu_usage":18.5,"mem_used_mb":4096,"mem_total_mb":8192,"disk_path":"/var/log/edge-core","disk_usage":45.0,"disk_used_bytes":45000000000,"disk_total_bytes":100000000000,"disk_available_bytes":55000000000,"disk_status":"normal"}
4.4 GET /v1/api/systems/robot
受保护，无参数。响应 data：
{"robot_type":"adapter-name","connected":true,"battery":85}
robot_type 来自运动控制适配器；connected 为 boolean；battery 保留下游电量结构，可能为数值、数组或 null。运动控制不可达时可返回 robot_type="unknown"、connected=false、battery=null，外层仍为成功，不应把它当成机器人已连接。
4.5 GET /v1/api/systems/software/packages
无参数。返回配置白名单内的软件清单，不是主机上全部软件包。响应 data={packages: SoftwarePackage[], generated_at: string}。
| SoftwarePackage 字段 | 类型 | 说明 |
|---|---|---|
package_name、version、architecture | string | 包名、版本、架构 |
status | string | installed、not_installed、broken、query_failed |
source | string | dpkg 或 direct |
managed | boolean | 是否受软件包管理机制管理 |
revision、build_time、dirty | string、string、boolean | 源码修订、构建时间、构建时是否有未提交改动 |
dpkg_status | string | 原始 dpkg 状态 |
update_modes | string[] | 可用升级方式，由实际软件清单决定 |
runtime | object，可选 | 导航运行时镜像信息，结构见 5.4 |
error | string | 单项查询失败信息 |
{"packages":[{"package_name":"edge-core","version":"3.1.0","architecture":"arm64","status":"installed","source":"direct","managed":false,"revision":"example-revision","build_time":"2026-11-13T00:00:00Z","dirty":false,"dpkg_status":"","update_modes":[],"error":""}],"generated_at":"2026-11-13T08:00:00Z"}
4.6 软件升级目录与任务接口
所有接口遵循 2.3 的业务认证规则，依赖已启用且可访问的升级服务。module 从应用目录获取，并须在设备软件白名单内；不要自行假定包名。
| 方法与路径 | 参数 / 请求 | 响应 data |
|---|---|---|
GET /v1/api/systems/software/applications | 无 | {"applications":[SoftwareApplication]} |
GET /v1/api/systems/software/applications/{module}/updates | path module: string | {"module":"...","current_version":"...","artifacts":[SoftwareArtifact]} |
POST /v1/api/systems/software/applications/{module}/update | path module；JSON 见下表 | SoftwareUpdateJob |
GET /v1/api/systems/software/update-jobs/current | 无 | 当前 SoftwareUpdateJob，无任务时 null |
GET /v1/api/systems/software/update-jobs/{id} | path id：正整数 | SoftwareUpdateJob |
POST /v1/api/systems/software/update-jobs/{id}/cancel | path id：正整数，无请求体 | 取消后的 SoftwareUpdateJob |
升级请求字段：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
artifact_name | string | 是 | 必须使用查询结果中的完整 name |
request_id | string | 否 | 调用方关联请求标识；省略由端侧生成；幂等语义由升级服务决定 |
{"artifact_name":"artifact-from-update-list","request_id":"upgrade-20261113-001"}
SoftwareApplication：
| 字段 | 类型 | 说明 |
|---|---|---|
module、current_version | string | 模块及当前版本 |
latest | SoftwareArtifact / null | 目录中的最新候选 |
update_count | integer | 可用升级包数量 |
SoftwareArtifact：
| 字段 | 类型 | 说明 |
|---|---|---|
name、module、version | string | Artifact 标识、模块、版本 |
device_types | string[] | 适用设备类型 |
payload_type、architecture、created_at | string | 包载荷类型、架构、创建时间 |
available | boolean | 当前可用性 |
container_image、runtime_version | string，可选 | 导航镜像与运行时版本 |
pull_only | boolean，可选 | 仅拉取镜像；不等于已经切换正在运行的导航环境 |
SoftwareUpdateJob：
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | OTA 任务 ID |
module、artifact_name | string | 升级目标 |
state | string | 升级服务状态原样透传；当前 Core 未定义完整枚举 |
deployment_id、request_id | string | 下游部署与调用关联 ID |
created_at | string | 创建时间 |
error_code、error | string | 下游错误代码及文本 |
未知 module、非法 id、Artifact 不匹配：400/1001；任务不存在：404/1002；下游冲突：409/1007；升级服务未启用、Mender 凭据不可用或下游故障：502/1005。取消是否成功取决于下游任务阶段，不能认为 HTTP 成功就撤回了已经安装的软件。
OTA 集成复用设备现有的 Mender 身份与认证路径；客户端无需新增硬件身份上报接口，也不要用 SN 代替认证凭据。
4.7 配网状态与手动窗口
| 方法与路径 | 请求 | 响应 |
|---|---|---|
GET /v1/api/systems/provisioning | 无 | 配网守护进程状态对象 |
POST /v1/api/systems/provisioning/window | 无请求体 | 打开手动广播窗口后的状态 |
DELETE /v1/api/systems/provisioning/window | 无请求体 | 关闭手动广播窗口后的状态 |
这些接口只查询或控制配网广播窗口，不在 HTTP 请求中接收 Wi-Fi SSID/密码。窗口时长由配网服务控制，不提供客户端自定义 duration 字段。
主要状态字段：
| 字段 | 类型 | 说明 |
|---|---|---|
available、advertising、session_active | boolean | 服务可用、正在广播、配网会话活跃 |
state | string | 如 initializing、online_idle、offline_wait、advertising、client_connected、scanning、connecting、ap_active、succeeded、failed |
protocol_version | integer | 配网协议版本 |
advertising_mode、advertising_reasons | string、string[] | 广播模式与原因 |
boot_window_remaining_seconds | integer | 开机窗口剩余秒数，不是所有窗口的统一倒计时 |
bluetooth_adapter、wifi_interface | string | 所用设备接口 |
wifi | object | state、mode、connected，可含 ssid、ip、gateway、can_restore、previous_ssid、internet_reachable、cloud_reachable |
operation | object，可选 | request_id、type、state、started_at、updated_at，可含 result / error |
last_error_code、updated_at | string | 最近错误、采样更新时间 |
桥接服务不可达时为 502/1005；不要将健康接口里的 provisioning.healthy=false 解释为整个 Orsus 进程退出。
4.8 CPU 隔离配置
GET /v1/api/systems/config/cpu-isolation 无参数；PUT /v1/api/systems/config/cpu-isolation 使用以下对象，所有子字段可选，仅修改提供的字段：
{"navigation":{"enabled":true,"cgroup_parent":"business-gs.slice"},"mapping":{"enabled":false,"cgroup_parent":"business-gs.slice"}}
enabled 为 boolean，cgroup_parent 为 string。两接口成功均返回完整的上述配置结构。PUT 会写回配置文件；成功表示配置保存，不保证已运行容器即时重新分配 CPU。当前处理函数没有对现有容器执行重建，应按部署流程让后续启动使用新配置。配置读取或写入失败为 500/1003。