扫描、语义建图与运动服务

13.1 统一状态 ServiceStatus

字段	类型	说明
`status`	string	running / stopped / degraded / unknown
`detail`	object	下游详情，随服务和设备版本变化

{"status":"running","detail":{}}

状态查询会把不可达归一化为 unknown/degraded 等结果，外层 code=0 不等于所有服务就绪。

GET /v1/api/services/status 无参数，返回 {"scan":ServiceStatus,"semantic":ServiceStatus,"motion":ServiceStatus}，三个状态并行查询。

接口	参数 / 请求	响应 data
`GET /v1/api/services/scan/status`	无	ServiceStatus
`POST /v1/api/services/scan/start`	无请求体	下游启动结果对象
`POST /v1/api/services/scan/stop`	无请求体	下游停止结果对象
`POST /v1/api/services/scan/{name}/start`	path name：部署支持的子服务名；无请求体	下游结果对象
`POST /v1/api/services/scan/{name}/stop`	同上	下游结果对象

子服务名从服务详情和部署配置确认，不能把任意 systemd 服务名当成此接口参数。可选 rtk-lio-fusion 的状态放在 detail 中，不参与扫描整体状态判断。调用失败通常 502/1005；结果对象具体字段由下游返回，不固定为 null。

接口	参数 / 请求	响应 data
`GET /v1/api/services/semantic/health`	无	下游 HTTP 控制服务健康对象
`GET /v1/api/services/semantic/status`	无	ServiceStatus
`POST /v1/api/services/semantic/start`	可省略或 `{"map_name":"office_1f"}`	下游启动结果
`POST /v1/api/services/semantic/stop`	无请求体	下游停止结果

map_name 为 string，建议显式绑定地图，避免落入部署默认语义集合。health 只证明控制 HTTP 服务能响应，不证明向量库、扫描或算法都健康。下游参数错误映射 400/1001；冲突 409/1007；其他失败 502/1005，可在 data 保留原始下游诊断。

接口	参数 / 请求	响应 data
`GET /v1/api/services/motion/status`	无	ServiceStatus
`GET /v1/api/services/motion/adapters`	无	`{"enabled_adapter_types":["adapter-name"]}`
`POST /v1/api/services/motion/start`	`{"adapter_type":"adapter-name"}`，非空 string 必填	下游结果对象
`POST /v1/api/services/motion/stop`	无请求体	下游结果对象
`GET /v1/api/services/motion/system_info`	无	当前适配器能力与系统信息
`POST /v1/api/services/motion/trigger`	query motion_id 必填；无请求体	下游动作结果
`GET /v1/api/services/motion/mqtt_config`	无	MQTT 遥控连接配置

system_info 常含 active_adapter、state、system_info；动作目录从返回对象的 system_info.motions[*].id 按实际嵌套结构读取。适配器类型与动作 ID 由部署决定，本文不提供所有机器人通用的固定列表。

motion_id 仅允许 [A-Za-z0-9_]+：

curl -sS -X POST -H "Authorization: Bearer $ORSUS_TOKEN" \
  "$ORSUS_ORIGIN/v1/api/services/motion/trigger?motion_id=action_from_system_info"

缺失/格式非法或下游明确参数错误：400/1001；其他下游故障通常 502/1005。motion/start 与 motion/stop 当前在收到下游错误对象时仍可能外层 code=0，并把错误对象放入 data；必须检查下游结果字段，再查询 motion/status 确认。

mqtt_config 字段：

该接口只返回连接配置，不定义速度遥控的完整消息协议；不要推导出不存在的 REST 速度接口。凭据无需展示或记录到普通应用日志。