FlyShotHost/README.md

Flyshot Replacement

基于 .NET 8 的跨平台飞拍服务端重写项目。

当前目标：

• 以新的 ASP.NET Core HTTP API 作为唯一上层接口
• 重写轨迹生成、触发时序和 FANUC 实时控制链路
• 提供 Web 状态监控页面
• 在 Windows 和 Linux 上运行完整后台服务

说明：

• 这是长期运行的无头后台服务，不是 GUI 桌面程序。
• 第一版仅面向当前现场组合，后续再扩展机型与控制柜适配。
• 当前仓库不再恢复旧 50001/TCP+JSON 监听入口；旧 ControllerClient 逆向资料只作为接口语义参考，不作为运行时目标。
• 宿主只保留 ASP.NET Core HTTP 控制器层，以及其后端 Flyshot.ControllerClientCompat 兼容服务。
• ExecuteTrajectory 与 ExecuteFlyShotTraj 已经接入 Planning + Triggering + Runtime 链路；Web 状态页已通过 /status 和 /api/status/snapshot 暴露当前兼容层与运行时状态。
• Flyshot.Core.Planning 的 ICSP / self-adapt-icsp 轨迹已经完成旧系统导出轨迹对齐；doubles 仍未实现。
• Flyshot.Runtime.Fanuc 已固化 10010 / 10012 / 60015 基础协议帧编解码。10010 状态通道以 j519 协议.pcap 和 Rvbust/uttc-20260428/20260428.pcap 真机抓包确认为 90B 固定帧。
• 2026-04-28 UTTC 抓包确认：UDP 60015 命令 target[0..5] 为关节角度制 deg，JointDetialTraj.txt 为弧度制 rad，speed_ratio=0.7 体现为 UDP 下发时间轴约 1.427730x 拉伸；2026-04-30 实体机确认 speed_ratio 不影响生成的 JointTraj.txt 规划时长，当前实际生成约 7.4s 轨迹。
• 2026-04-30 本机 50001/TCP+JSON 抓包确认：ExecuteFlyShotTraj(save_traj=true,use_cache=false) 请求只显式携带规划方法、保存、缓存和等待参数，不携带 JointLimits / acc_limit / jerk_limit / velocity / acceleration / jerk。因此旧系统不可见的有效规划限制不再继续假设来自公开链路，新系统按 replacement-only 内部参数限制规划加速度。
• 真机 Socket 客户端已具备基础连接、程序启停、速度倍率/TCP/IO 参数命令和 J519 状态包驱动发送能力；稠密轨迹下发已按 speed_ratio 做执行时间缩放，并已用 0.5/0.7/1.0 三份 UTTC 抓包固化 J519 golden tests。真实 R30iB 全流程现场联调仍需执行。
• MoveJoint 已按 2026042802-mvpoint*.pcap 复刻为点到点临时轨迹：当前关节到目标关节的关节空间直线，五次 smoothstep 起停，按 status=15 运动窗口复现 40/55/77 点，并由 J519 层完成 rad -> deg 下发。
• 单程序只对应一台机器人，上传/删除/恢复飞拍轨迹统一读写运行目录 Config/RobotConfig.json，不再创建独立轨迹存储文件。

单位约定总览：

• 规划层、JointDetialTraj.txt 和运行时内部关节轨迹，默认按弧度制 rad 理解。
• UDP 60015 J519 命令 target[0..5] 和响应关节反馈按角度制 deg 理解；运行时下发前必须显式执行 rad -> deg 转换。
• TCP 10010 状态通道是混合单位：pose[0..2] 更像 mm，pose[3..5] 更像 deg，joint_or_ext[0..5] 当前现场抓包更支持按 rad 理解。
• 不要把“关节角”默认当成统一单位；在规划、状态监控和 J519 执行三条链路之间必须明确标注 rad/deg。

当前现场主链路的单位流转可简化为：

位置	内容	当前更可信单位
规划输入 / 轨迹算法	关节角	rad
JointDetialTraj.txt / JointTraj.txt	关节角	rad
运行时下发前内部轨迹	关节角	rad
UDP 60015 命令 target[0..5]	关节目标	deg
UDP 60015 响应 Joint	关节反馈	deg
TCP 10010 pose[0..2]	X/Y/Z	mm
TCP 10010 pose[3..5]	姿态角	deg
TCP 10010 joint_or_ext[0..5]	关节状态	更像 rad
TCP 10010 joint_or_ext[6..8]	扩展轴槽位	当前样本为 0

TCP 10010 的正式字段表、样例帧和已确认/待确认说明见 docs/fanuc-10010-state-frame.md。

开发约定：

• 建议从 flyshot-replacement/ 根目录启动 IDE、终端和 Codex 会话。
• 当前仓库内的 @ 引用主要覆盖本仓库文件；引用父目录资料时，请直接写相对路径，如 ../analysis/ICSP_algorithm_reverse_analysis.md。
• 父目录中的 analysis/、FlyingShot/、RobotController/、RPS/ 主要作为逆向参考资料和样本来源，新实现默认只落地在当前仓库。

当前已完成：

• 初始化独立仓库
• 创建 dotnet 8 解决方案骨架
• 打通最小宿主与 /healthz
• 建立领域模型与模块边界
• 落地配置兼容与机器人模型解析
• 落地 ICSP / self-adapt-icsp 轨迹规划与飞拍触发时间轴
• 完成 ICSP 轨迹导出结果与旧系统对齐
• 将 ExecuteTrajectory / ExecuteFlyShotTraj 接入 FANUC 运行时链路
• 落地 Web 状态页
• 落地浏览器内 OpenAPI 自动驱动的接口调试页（/debug），与 Swagger:Enabled 同步可见
• 固化 10010 / 10012 / 60015 FANUC 基础协议帧编解码，确认 10010 状态帧为 90B
• 使用本地 TCP/UDP 模拟器覆盖命令通道、状态通道和 J519 基础收发
• 补齐 Get/SetSpeedRatio、Get/SetTCP、Get/SetIO 真机命令体与响应解析
• 保留新 HTTP 接口路线，明确不再实现旧 50001/TCP+JSON 网关
• 将飞拍轨迹持久化收敛到运行目录 Config/RobotConfig.json

剩余 Todo：

1. 配置与测试基线

   • 修正 ConfigCompatibilityTests 当前样本路径漂移：Rvbust/EOL10_EAU_0/RobotConfig.json 不再包含 001，应改用稳定样本或更新断言。
   • 将 RobotConfig.json 中的 use_do、io_keep_cycles、acc_limit、jerk_limit、adapt_icsp_try_num 全部贯通到规划和执行链路。
   • 将上传飞拍轨迹统一保存到运行目录 Config/RobotConfig.json 的 flying_shots 节点。
   • 为新 HTTP API 补一份当前现场调用顺序文档，替代旧 ControllerClient 工作流：见 docs/fanuc-field-runtime-workflow.md。

2. 轨迹规划

   • 补齐 ICSP 最终 global_scale > 1.0 失败判定，避免未收敛轨迹被当作有效结果执行。
   • 将 self-adapt-icsp 的补点次数改为使用配置中的 adapt_icsp_try_num。
   • 新增 replacement-only 的 planning_acceleration_scale 规划加速度校准参数，用于复现旧服务端公开链路中抓不到的保守 effective limits；该参数只影响规划结果，不影响运行时 speed_ratio。
   • 如果现场仍需要 method="doubles"，实现 TrajectoryDoubleS 等价规划；否则在 HTTP 文档中明确标为不支持。
   • 把已完成对齐的旧系统轨迹样本固化为 golden tests，防止后续重构破坏轨迹一致性。
   • 将 Rvbust/uttc-20260428/Data/JointDetialTraj.txt 固化为 J519 golden 样本：输入为 rad，下发为 deg，并按 speed_ratio 拉伸时间轴；覆盖 2026042802-0.5/0.7/1.pcap。
   • 补齐飞拍 save_traj / SaveTrajInfo 的规划结果导出，将关节关键点、稠密关节轨迹、笛卡尔关键点、稠密笛卡尔轨迹和 ShotEvents 写入 Config/Data/<name>。

3. FANUC TCP 10012 命令通道

   • 补齐 GetSpeedRatio / SetSpeedRatio 真机命令体与响应解析。
   • 补齐 GetTCP / SetTCP 真机命令体与响应解析。
   • 补齐 GetIO / SetIO 真机命令体与响应解析。
   • 所有命令响应必须检查 result_code，失败时返回可诊断错误，而不是只更新本地缓存。

4. FANUC TCP 10010 状态通道

   • 用 j519 协议.pcap 和 Rvbust/uttc-20260428/20260428.pcap 中的 90B 真机状态帧扩充状态解析测试样本。
   • 明确 pose[6]、joint_or_ext[9]、尾部状态字的字段语义，并映射到 ControllerStateSnapshot。
   • 补充 TCP 10010 正式字段表与已确认/待确认说明：见 docs/fanuc-10010-state-frame.md。
   • 补充断线清理和异常帧拒绝测试。
   • 补充状态通道超时和重连策略，超时后标记陈旧状态并按退避策略自动重连。

5. FANUC UDP 60015 J519 运动链路

   • 重新确认 J519 发送节拍与 FanucControllerRuntime 稠密轨迹循环的职责边界：FanucJ519Client 收到机器人 UDP status 后按该 status sequence 回发命令，FanucControllerRuntime 只按轨迹时间更新下一帧命令内容。
   • 执行时将规划输出 rad 转为 J519 deg 目标，并按当前 speed_ratio 调整 8ms 发送索引/时间尺度：第 k 个 J519 目标采样 t_traj = k * 0.008 * speed_ratio，包数为 floor(duration / (0.008 * speed_ratio)) + 1。
   • 补齐 accept_cmd、received_cmd、sysrdy、rbt_inmotion 状态位解析与启动前闭环检查；若已有 J519 响应且 accept_cmd/sysrdy 未就绪，则拒绝稠密轨迹执行。
   • 校验序号递增、状态包 sequence 校准、响应滞后、丢包、停止包和最后一帧语义：UTTC golden tests 覆盖连续 seq、无重复 seq、响应滞后 2 到 8 帧、lastData=0；J519 客户端测试覆盖收到 status 后按 status sequence 回发命令和 type 2 状态输出停止包。
   • 将飞拍 IO 触发的 write_io_type/index/mask/value 与现场控制柜实际 IO 地址逐项对齐；UTTC golden tests 确认 17 个触发点对应 17 个 UDP IO set 脉冲、17 个 clear 帧，mask 集合为 10/12/14。
   • 将 MoveJoint 从单点最终目标改为临时 PTP 稠密轨迹：按 status=15 运动窗口统计，speed=1 抓包 40 点，speed=0.7 抓包 55 点，speed=0.5 抓包 77 点，路径为关节空间直线 + smoothstep 进度。
   • ExecuteFlyShotTraj(move_to_start=true) 复用临时 PTP 稠密轨迹移动到规划起点，并等待运行时完成后再启动飞拍轨迹，避免第一帧 J519 目标突变导致控制柜报警。
   • ExecuteFlyShotTraj(wait=true) 等待正式飞拍轨迹执行完成后再返回；HTTP /execute_flyshot/ 已接入旧抓包中的 wait 字段，默认值为 true。

6. 真机联调与运行安全

   • 在真实 R30iB + RVBUSTSM 程序上验证 Connect -> EnableRobot -> ExecuteFlyShotTraj -> StopMove -> DisableRobot -> Disconnect 全流程。
   • 实体机复核运行速度对轨迹生成时间的影响：speed_ratio 不影响 IsFlyshotTrajectoryValid / SaveTrajectoryInfo 生成的 JointTraj.txt 规划时长，当前实际生成约 7.4s 轨迹；运行阶段仅 J519 下发时长和包数按 speed_ratio 拉伸，UTTC_MS11 参考值为约 7.4s 与 10.56s。
   • 增加急停、伺服未就绪、程序未启动、网络断开、控制柜拒收命令等故障路径处理。
   • 给 HTTP 执行接口增加运行互斥、执行中拒绝重复轨迹、取消和超时控制。
   • 增加运行日志、协议摘要日志和状态快照导出，便于现场排查。

7. 发布与部署

   • 固化 Windows / Linux 启动脚本和 systemd 服务配置。
   • 补充生产配置模板、端口说明和现场部署检查表。
   • 给 Web 状态页增加程序状态和最近报警显示；J519 状态位已通过快照和状态页显示。