# 机器人智慧服务系统 · 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。

## 启动

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

## 快速联调（PowerShell 示例）

```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
```