# FANUC 真机协议 Socket 通信层实现计划

## 上下文

当前 `flyshot-replacement` 项目已完成：
- 三条 FANUC 通信链路的二进制协议编解码（`FanucCommandProtocol`、`FanucStateProtocol`、`FanucJ519Protocol`）
- 抓包样本验证的协议测试（5 个 FanucProtocolTests 全部通过）
- HTTP 兼容层控制器和状态监控页
- 轨迹规划与飞拍触发编排层

**缺失的关键环节**：`FanucControllerRuntime` 仍是纯内存状态桩，没有实际 Socket 通信。`Connect()` 只记录 IP，`ExecuteTrajectory()` 只修改内存变量，`GetJointPositions()` 返回的是上一次写入值而非真实控制器反馈。

## 目标

将 `FanucControllerRuntime` 从内存桩改造为具备真实 FANUC R30iB 通信能力的运行时，使 HTTP 层的每个指令真正下发到控制柜。

## 架构设计

### 分层结构

```
LegacyHttpApiController / StatusController  (HTTP 适配层，保持不动)
    ↓ 调用同步接口
IControllerRuntime / ControllerClientCompatService  (兼容层，保持不动)
    ↓ 调用同步接口
FanucControllerRuntime  (改造：从内存桩 → 委托给三个 Socket 客户端)
    ↓ 内部持有并调度
FanucCommandClient   (TCP 10012，Req/Res 同步命令通道)
FanucStateClient     (TCP 10010，持续接收状态帧后台循环)
FanucJ519Client      (UDP 60015，8ms 周期发送 + 接收响应)
    ↓ 使用现有编解码
FanucCommandProtocol / FanucStateProtocol / FanucJ519Protocol  (已有，不改动)
```

### 关键设计决策

1. **接口保持同步**：`IControllerRuntime` 现有 18 个方法全为同步签名。内部 Socket I/O 采用 `Task` + `.GetAwaiter().GetResult()` 短时间阻塞，或后台线程 + 锁同步状态快照。避免一次性推翻整个兼容层。

2. **三个独立客户端**：每条物理通道一个类，各自管理连接生命周期，便于单独测试和故障定位。

3. **状态通道后台循环**：`FanucStateClient` 内部启动 `Task` 持续 `ReadAsync(90)`，解析状态帧后写入线程安全的 `ControllerStateSnapshot` 缓存。

4. **J519 周期发送器**：`FanucJ519Client` 内部用 `PeriodicTimer` 或 `Task.Delay` 实现约 8ms 周期的发送循环。命令通过线程安全的队列/缓冲区注入。

5. **RVBUSTSM 程序生命周期隐式管理**：`EnableRobot()` 时自动走 `StopProg→Reset→GetProgStatus→StartProg("RVBUSTSM")` 序列（与抓包一致）。`DisableRobot()` 时发送 `StopProg`。

6. **连接顺序**：`Connect()` 按顺序建立三条通道 — 先 TCP 10010（状态），再 TCP 10012（命令），最后 UDP 60015（运动）。

## 实现步骤

### Phase 1: TCP 10012 命令客户端

**新建文件**：`src/Flyshot.Runtime.Fanuc/Protocol/FanucCommandClient.cs`

职责：
- `Connect(string ip, int port = 10012)` — 建立 TcpClient 连接
- `SendCommandAsync(uint messageId, ReadOnlyMemory<byte> body)` — 发送并等待响应
- `SendProgramCommandAsync(uint messageId, string programName)` — 封装程序名命令
- `Disconnect()` — 关闭连接
- 线程安全（单个命令通道同一时间只处理一个请求）

需要封装的具体命令方法：
- `StopProgramAsync(string name)` → `PackProgramCommand(0x2103, name)`
- `ResetRobotAsync()` → `PackEmptyCommand(0x2100)`
- `GetProgramStatusAsync(string name)` → `PackProgramCommand(0x2003, name)`
- `StartProgramAsync(string name)` → `PackProgramCommand(0x2102, name)`
- `GetTcpAsync()` / `SetTcpAsync()` — 待解析请求/响应体格式
- `GetSpeedRatioAsync()` / `SetSpeedRatioAsync()` — 同上
- `GetIoAsync()` / `SetIoAsync()` — 同上

**测试**：`tests/Flyshot.Core.Tests/FanucCommandClientTests.cs`
- 用 `TcpListener` 本地模拟控制器，验证帧收发与解析

### Phase 2: TCP 10010 状态客户端

**新建文件**：`src/Flyshot.Runtime.Fanuc/Protocol/FanucStateClient.cs`

职责：
- `Connect(string ip, int port = 10010)` — 建立 TcpClient 连接
- 内部启动后台 `Task` 循环 `ReadAsync(FanucStateProtocol.StateFrameLength)`
- 每收到一帧调用 `FanucStateProtocol.ParseFrame()`
- 将解析结果写入线程安全的最新状态缓存
- `GetLatestSnapshot()` — 返回最近一次解析的状态帧
- `Disconnect()` — 取消后台循环并关闭连接

**测试**：`tests/Flyshot.Core.Tests/FanucStateClientTests.cs`
- 用 `TcpListener` 本地发送抓包样本 hex，验证后台循环能正确解析

### Phase 3: UDP 60015 J519 运动客户端

**新建文件**：`src/Flyshot.Runtime.Fanuc/Protocol/FanucJ519Client.cs`

职责：
- `Connect(string ip, int port = 60015)` — 创建 UdpClient
- 发送 init packet (`PackInitPacket()`)
- 内部启动发送循环（约 8ms 周期）
- `UpdateCommand(FanucJ519Command command)` — 原子更新下一周期要发送的命令
- `StartMotion()` — 启动发送循环
- `StopMotion()` — 发送 end packet，停止循环
- 接收线程：持续 `ReceiveAsync()` 解析 132B 响应，更新反馈状态
- `Disconnect()` — 清理

**测试**：`tests/Flyshot.Core.Tests/FanucJ519ClientTests.cs`
- 用本地 UDP socket 模拟控制器收发

### Phase 4: 重写 FanucControllerRuntime

**改造文件**：`src/Flyshot.Runtime.Fanuc/FanucControllerRuntime.cs`

将当前内存桩替换为真实运行时：

- 持有三个客户端实例：`FanucCommandClient`、`FanucStateClient`、`FanucJ519Client`
- `Connect(robotIp)` — 顺序连接 10010 → 10012 → 60015
- `EnableRobot(bufferSize)` — 走完整 StartProg 序列（Stop→Reset→Status→Start RVBUSTSM），然后启动 J519
- `DisableRobot()` — 停止 J519，发送 StopProg
- `Disconnect()` — 断开三条通道
- `ExecuteTrajectory(result, finalJointPositions)` — 将规划后的稠密路点通过 J519 逐帧发送
- `StopMove()` — 立即停止 J519 发送循环
- `GetSnapshot()` — 优先从 `FanucStateClient` 读取最新状态；若状态通道未连接，回退到内存值
- `GetJointPositions()` / `GetPose()` / `GetTcp()` / `GetSpeedRatio()` / `GetIo()` — 优先从真实通道读取
- `SetTcp()` / `SetSpeedRatio()` / `SetIo()` — 通过命令通道发送

### Phase 5: 端到端集成测试

**改造/新建测试**：
- `tests/Flyshot.Server.IntegrationTests/LegacyHttpApiCompatibilityTests.cs` — 补充真实连接流程（可用本地模拟器）
- `tests/Flyshot.Core.Tests/FanucControllerRuntimeSocketTests.cs` — 用本地 TCP/UDP 模拟器验证完整链路

**验证命令**：
```bash
cd flyshot-replacement
dotnet build FlyshotReplacement.sln -v minimal
dotnet test tests/Flyshot.Core.Tests/Flyshot.Core.Tests.csproj -v minimal
dotnet test tests/Flyshot.Server.IntegrationTests/Flyshot.Server.IntegrationTests.csproj -v minimal
```

## 风险与回退策略

1. **真机连接风险**：第一版 Socket 实现可能有超时/重连问题。`FanucControllerRuntime` 保留 `_simulationMode` 路径，仿真模式下仍走内存桩。
2. **性能风险**：同步接口内部阻塞 Socket 可能影响 HTTP 并发。若实测有问题，后续将 `IControllerRuntime` 改为 async。
3. **协议字段不完整风险**：TCP 10012 的 `GetTcp`/`SetTcp`/`GetIo`/`SetIo` 请求/响应体格式尚未完全逆向。先实现已知字段，留 TODO 标记待验证。

## 关键文件清单

| 文件 | 动作 |
|------|------|
| `src/Flyshot.Runtime.Fanuc/Protocol/FanucCommandClient.cs` | 新建 |
| `src/Flyshot.Runtime.Fanuc/Protocol/FanucStateClient.cs` | 新建 |
| `src/Flyshot.Runtime.Fanuc/Protocol/FanucJ519Client.cs` | 新建 |
| `src/Flyshot.Runtime.Fanuc/FanucControllerRuntime.cs` | 重写 |
| `tests/Flyshot.Core.Tests/FanucCommandClientTests.cs` | 新建 |
| `tests/Flyshot.Core.Tests/FanucStateClientTests.cs` | 新建 |
| `tests/Flyshot.Core.Tests/FanucJ519ClientTests.cs` | 新建 |
| `tests/Flyshot.Core.Tests/FanucControllerRuntimeSocketTests.cs` | 新建 |

## 下一步验证标准

- `FanucControllerRuntime` 的 `Connect()` 能成功建立三条 TCP/UDP 连接
- `EnableRobot()` 能走完 `RVBUSTSM` 启动序列
- `ExecuteTrajectory()` 能按 8ms 周期通过 J519 发送路点
- `GetSnapshot()` 返回的值来自 TCP 10010 真实状态帧而非内存
- 现有 10 个集成测试和 25 个核心测试仍然通过