# 机器人控制联调报告

| 项目 | 内容 |
|------|------|
| 文档编号 | TR-01 |
| 文档名称 | 机器人控制联调报告 |
| 版本 | V1.0 |
| 联调阶段 | Alpha 联调 |
| 联调日期 | 2026-08-10 |
| 参与系统 | 设备接入服务 Alpha、状态服务 Alpha、命令服务 Alpha |
| 关联文档 | DOC-08、DOC-09、机器人能力模型 V1.0、控制会话状态机、命令状态机 |

---

## 1. 联调环境

| 项 | 值 |
|----|-----|
| 联调拓扑 | 单机部署（本机 localhost），三服务独立进程 |
| 设备接入服务 | `http://localhost:3010` |
| 状态服务 | `http://localhost:3020` |
| 命令服务 | `http://localhost:3030` |
| 模拟设备 | 巡检机器人 `ROBOT-001`、无人机 `DRONE-001`（脚本模拟心跳/ACK/结果回传） |
| 网络 | 本机回环，无跨机房链路（跨网联调留待 Beta） |

## 2. 联调范围

| 模块 | 范围 | 结论 |
|------|------|------|
| 设备接入 | 注册/查询/心跳/离线判定/注销 | ✅ 通过 |
| 状态服务 | 上报/最新查询/历史/SSE 订阅 | ✅ 通过 |
| 命令服务 | 下发/ACK/结果/取消/重试/超时 | ✅ 通过（含 1 项遗留问题） |
| 跨服务联动 | 离线拦截、能力校验（模拟） | ✅ 通过 |
| 前端对接 | 控制台命令面板（模拟数据） | ⏳ 待前端联调排期 |

## 3. 联调用例执行汇总

### 3.1 设备接入链路（DA-*）

| 用例 | 场景 | 预期 | 实际 | 结果 |
|------|------|------|------|------|
| DA-01 | 注册巡检机器人（含 capabilities） | 201 建档，返回 secret | 建档成功，返回 secret | ✅ |
| DA-02 | 重复注册同一 deviceId | 409 已注册 | 409 已注册 | ✅ |
| DA-03 | 注册非法 type | 400 参数非法 | 400 参数非法 | ✅ |
| DA-04 | 心跳上报 3 次后查在线状态 | online=true | online=true | ✅ |
| DA-05 | 停止心跳 70s 后 | 自动置 offline | 70s 后扫描置 offline | ✅ |
| DA-06 | 注销设备后查询 | 404 不存在 | 404 不存在 | ✅ |

### 3.2 状态链路（ST-*）

| 用例 | 场景 | 预期 | 实际 | 结果 |
|------|------|------|------|------|
| ST-01 | 上报完整状态（位置/电量/模式） | latest 更新 | 更新成功 | ✅ |
| ST-02 | 连续上报 10 条查历史 | 10 条按时间序返回 | 10 条返回 | ✅ |
| ST-03 | SSE 订阅后上报 | 订阅端实时收到推送 | 实时收到 | ✅ |
| ST-04 | 查询未上报设备 | 404 无数据 | 404 无数据 | ✅ |

### 3.3 命令链路（CM-*）

| 用例 | 场景 | 预期 | 实际 | 结果 |
|------|------|------|------|------|
| CM-01 | 下发 move 命令 | SENT，返回 seq | SENT | ✅ |
| CM-02 | 设备 ACK | SENT→ACKED | ACKED | ✅ |
| CM-03 | ACK 后回传 success | ACKED→SUCCEEDED | SUCCEEDED | ✅ |
| CM-04 | 回传 failed | →FAILED，含 errorCode | FAILED | ✅ |
| CM-05 | 下发后不 ACK，超 30s | 自动重试 1 次后仍超时 → TIMEOUT | TIMEOUT（重试 1 次） | ✅ |
| CM-06 | 终态命令手动 retry | TIMEOUT→SENT 重新计时 | SENT | ✅ |
| CM-07 | SENT 态取消 | →CANCELLED | CANCELLED | ✅ |
| CM-08 | 对离线设备下发命令 | 409 设备离线拒绝 | 40902 拒绝 | ✅ |
| CM-09 | 终态命令重复回传结果 | 409 冲突拒绝 | 409 冲突拒绝 | ✅ |

## 4. 问题清单（DEFECT）

| 编号 | 严重级 | 描述 | 状态 |
|------|--------|------|------|
| DEF-001 | 中 | 命令服务对设备接入服务的在线校验依赖 HTTP 同步调用，设备接入服务重启窗口期会降级放行（可接受，Beta 改为事件驱动） | 已知限制 |
| DEF-002 | 低 | 历史状态按设备单文件存储，设备量大时文件增长快；Alpha 限 500 条/设备，Beta 需迁移时序库 | 已知限制 |
| DEF-003 | 低 | 命令 events 中 cancel 分支的 from 字段记录当前状态而非前置状态，审计可读性略差 | 待优化 |

## 5. 性能与稳定性观测

| 指标 | 观测值 | 说明 |
|------|--------|------|
| 命令下发 P95 时延 | 8ms（本机） | 未计设备端执行时间 |
| 状态上报吞吐 | 200 req/s 稳定 | 本机压测，JSON 落盘为瓶颈 |
| SSE 订阅推送时延 | <5ms | 本机 |
| 连续运行 8h | 无崩溃、无内存泄漏 | 三服务均正常 |

## 6. 结论与建议

1. **Alpha 联调结论：通过**，三服务核心链路（注册→心跳→状态→命令→结果）自洽可用，满足控制台 Alpha 演示与开发自测需求。
2. 遗留问题 DEF-001~003 均为已知限制，不影响 Alpha 验收，Beta 排期修复。
3. **建议**：前端控制台联调（⏳）与《越权-冲突-超时测试记录》中安全类用例的自动化脚本在下一迭代补齐。

---

**变更记录**

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| V1.0 | 2026-08-10 | Alpha 联调结果汇总 | 系统组 |