web-Iot/services/SERVICES.md

机器人智慧服务系统 · Alpha 服务说明

机器人智慧服务系统后端 Alpha 三服务 + 配套文档，位于本仓库 services/ 与 docs/。

服务一览

服务	目录	端口	职责	数据文件
设备接入服务 Alpha	services/device-access	3010	设备注册/心跳/在线管理	data/devices.json
状态服务 Alpha	services/status	3020	状态上报/查询/历史/SSE 订阅	data/status.json
命令服务 Alpha	services/command	3030	命令下发/ACK/结果/超时重试	data/commands.json

技术栈：Node.js + Express + 本地 JSON 文件（替代数据库）。依赖：express / cors / uuid。

启动

# 三个服务分别启动（首次需先安装依赖）
cd services\device-access; npm install; npm start
cd services\status;        npm install; npm start
cd services\command;       npm install; npm start

快速联调（PowerShell 示例）

# 1. 注册设备
Invoke-RestMethod -Method Post -Uri http://localhost:3010/api/devices/register -ContentType 'application/json' -Body '{"deviceId":"ROBOT-001","type":"inspection_robot","name":"巡检机器人1号","capabilities":["cap.move","cap.rotate","cap.photo","cap.patrol","cap.charging","cap.emergency_stop"]}'

# 2. 心跳保活
Invoke-RestMethod -Method Post -Uri http://localhost:3010/api/devices/ROBOT-001/heartbeat

# 3. 上报状态
Invoke-RestMethod -Method Post -Uri http://localhost:3020/api/status/report -ContentType 'application/json' -Body '{"deviceId":"ROBOT-001","position":{"x":10,"y":5,"z":0,"yaw":90},"battery":85,"mode":"patrol","speed":1.2}'

# 4. 下发命令
$cmd = Invoke-RestMethod -Method Post -Uri http://localhost:3030/api/commands -ContentType 'application/json' -Body '{"deviceId":"ROBOT-001","type":"move","params":{"direction":"forward","distance":3,"speed":0.8}}'
$cmd.data.id

# 5. 设备 ACK + 回传结果
Invoke-RestMethod -Method Post -Uri http://localhost:3030/api/commands/<命令ID>/ack -ContentType 'application/json' -Body '{"executing":true}'
Invoke-RestMethod -Method Post -Uri http://localhost:3030/api/commands/<命令ID>/result -ContentType 'application/json' -Body '{"status":"success"}'

文档索引（docs/）

文档	说明
DOC-08-设备数据字典-V1.0草案.md	设备类型/属性/状态模型/传感器点表/告警编码
DOC-09-控制命令字典-V1.0草案.md	命令通用结构/命令类型/优先级/错误码
机器人能力模型-V1.0.md	能力分层/定义表/设备能力矩阵/校验规则
控制会话状态机.md	会话状态/迁移表/互斥抢占规则
命令状态机.md	命令状态/迁移表/超时重试/事件审计
机器人控制联调报告.md	Alpha 联调用例汇总/问题清单/结论
越权-冲突-超时测试记录.md	越权/冲突/超时三类 21 用例记录

三服务调用关系

控制台 / 前端
   │  REST + SSE
   ▼
设备接入服务(3010) ◄── 心跳/注册 ── 设备（机器人/无人机/桩/网关/传感器）
状态服务(3020)     ◄── 状态上报 ── 设备
命令服务(3030)     ── 命令下发 ──► 设备（经设备接入服务校验在线）
   │
   └── 校验设备在线: GET http://localhost:3010/api/devices/:id/online