🐛 fix(flyshot): 修复输出选择并同步现场配置与文档

- 恢复 use_do 对 DO/RO 的选择，保留拍照脉冲与清零 - 统一直接关节移动与飞拍预移动的规划和运行倍率 - 补充输出选择、预生成队列和点对点倍率回归测试 - 更新 WhP_test 轨迹配置、系统说明和 README - 删除本地 Claude 配置文件验证：构建零警告零错误，定向测试 6 项与集成测试 38 项通过。核心全量 175 项通过、14 项失败，失败项与修改前基线一致。
2026-10-01 19:11:50 +08:00
parent acccb94807
commit abea2d7517
12 changed files with 1228 additions and 372 deletions
--- a/docs/flyshot-system-guide.md
+++ b/docs/flyshot-system-guide.md
@@ -0,0 +1,573 @@
+# 飞拍系统介绍说明与使用教程
+
+## 1. 文档目的
+
+本文档用于说明当前飞拍系统的整体组成、数据流、接口边界和现场使用步骤。文档原稿采用 Markdown 编写，适合后续导入或整理为飞书文档；流程图使用 Mermaid 源码保留，导入飞书时可按需要渲染为图片后插入。
+
+系统当前分为三个主要单元：
+
+| 单元 | 工程位置 | 主要职责 |
+| --- | --- | --- |
+| 上位机单元 | `D:\Dev\Codes\MFD_Solution\FlyShot` | 控制相机、接收 PLC/MES 信息、发起飞拍任务、保存图片、调用 AI 检测、汇总结果并回传 MES/PLC |
+| 飞拍控制单元 | `D:\Dev\Codes\rvbust-code\FlyingShotPkg_3.15_VDA\flyshot-replacement` | 提供 HTTP 控制接口，负责机器人初始化、轨迹上传、ICSP/self-adapt-ICSP 规划、触发时序生成和 FANUC 运动执行 |
+| YOLO AI 识别模块 | 由上位机配置访问 | 接收图片检测请求，完成 AI 推理，返回图片级 OK/NG、原因、参数明细和结果图路径 |
+
+## 2. 系统总览
+
+```mermaid
+flowchart LR
+    PLC["PLC / OPC UA<br/>任务触发、状态反馈"]
+    MES["MES<br/>换型下发、PartProcessed 上报"]
+    PC["上位机单元 FlyShot<br/>WPF 主控程序"]
+    Camera["工业相机<br/>采图与本地存图"]
+    Control["飞拍控制单元<br/>ASP.NET Core HTTP API"]
+    Robot["FANUC 机器人<br/>TCP 10010/10012 + UDP 60015"]
+    AI["YOLO AI 识别模块<br/>HTTP + 文件传输目录"]
+    Storage["本地/远端图片目录<br/>原图、结果图、任务 JSON"]
+    Notify["飞书 / 审核平台 / ClickHouse<br/>异常通知与追溯"]
+
+    PLC <--> PC
+    MES <--> PC
+    PC --> Camera
+    Camera --> PC
+    PC <--> Control
+    Control <--> Robot
+    PC <--> AI
+    PC --> Storage
+    AI --> Storage
+    PC --> Notify
+```
+
+### 2.1 上位机单元
+
+上位机是现场操作和生产流程的核心入口，当前是 WPF MVVM 程序。它负责：
+
+- 初始化相机并注册图像回调。
+- 读取 `appConfig.json`、`Config\TypeData`、`Config\FlyTask` 中的现场配置。
+- 通过 `MpcService` 调用飞拍控制单元 HTTP 接口。
+- 按飞拍任务配置设置相机曝光、增益和拍摄索引。
+- 将图片保存到 `CameraSavePath` 下的任务目录。
+- 通过 `ImageProcessingService` 上传图片到 AI 服务器目录并调用 AI 接口。
+- 将 AI 结果合并回任务对象，保存任务 JSON。
+- 根据结果回写 PLC、发送 MES `PartProcessed`、写入 ClickHouse、必要时发送飞书 NG 报警。
+
+### 2.2 飞拍控制单元
+
+飞拍控制单元是新的 replacement 服务端。它不恢复旧 `50001/TCP+JSON` 网关，而是提供 ASP.NET Core HTTP API。它负责：
+
+- 机器人模型加载与初始化。
+- 轨迹上传、查询、删除。
+- 普通轨迹 `ExecuteTrajectory`。
+- 飞拍轨迹 `ExecuteFlyShotTraj`。
+- 通过 `icsp` 或 `self-adapt-icsp` 生成关节轨迹。
+- 根据 `shot_flags / offset_values / addrs` 生成拍照触发时间轴。
+- 将规划结果转换为 8ms 发送队列，通过 J519 通道控制机器人运动和 IO 脉冲。
+- 提供 `/status.html` 状态页和 `/debug.html` 调试页。
+
+### 2.3 YOLO AI 识别模块
+
+YOLO AI 模块由上位机调用。上位机当前不是直接把所有图片以 multipart 方式传给 AI，而是：
+
+1. 将图片上传到配置的 AI 输入目录。
+2. 构造包含模型版本、配置版本、产品 ID 和图片明细的 JSON 请求。
+3. 调用 `Ai_Model.ApiUrl`。
+4. 根据 AI 响应中的 `SubImgInfo` 下载结果图。
+5. 将图片级结果、原因、参数明细写回任务结果。
+6. 清理远端上传图和结果图。
+
+## 3. 生产主流程
+
+```mermaid
+sequenceDiagram
+    participant PLC as PLC
+    participant PC as 上位机 FlyShot
+    participant CTRL as 飞拍控制单元
+    participant ROBOT as FANUC 机器人
+    participant CAM as 工业相机
+    participant AI as YOLO AI
+    participant MES as MES
+
+    PLC->>PC: StartFlyShotTask 上升沿 + 产品/任务信息
+    PC->>PC: 初始化 WorkStationTask / FlyShotTask
+    PC->>CAM: 注册回调、设置曝光/增益
+    PC->>CTRL: POST /execute_flyshot/
+    CTRL->>ROBOT: move_to_start + J519 飞拍轨迹
+    ROBOT-->>CAM: 轨迹 IO 脉冲触发拍照
+    CAM-->>PC: 图像回调
+    PC->>PC: 保存原图并加入待处理队列
+    PC->>AI: 上传图片 + 发送 AI 请求
+    AI-->>PC: 返回 OK/NG、原因、结果图路径
+    PC->>PC: 下载结果图并汇总任务结果
+    PC-->>PLC: TaskCompleted / TaskResult / WorkStationResult
+    PC->>MES: PartProcessed 结果报文
+```
+
+## 4. 关键配置
+
+### 4.1 上位机配置
+
+上位机配置文件：
+
+- 基础配置：`D:\Dev\Codes\MFD_Solution\FlyShot\appConfig.json`
+- 调试覆盖：`D:\Dev\Codes\MFD_Solution\FlyShot\appConfig.Debug.json`
+
+常用配置项：
+
+| 配置路径 | 示例值 | 说明 |
+| --- | --- | --- |
+| `MesConfig.EnableMes` | `true` | 是否启用 MES 通信 |
+| `MesConfig.ServerIp` / `ServerPort` | `174.34.82.193` / `55065` | MES 服务地址 |
+| `MesConfig.LineNo` / `ProcessNo` / `StatNo` | `6958` / `993002` / `9930` | MES 位置上下文 |
+| `MesConfig.TelegramFolder` | `D:\MesTelegram` | MES 报文保存目录 |
+| `CameraIp` / `LocalIp` | `192.168.11.11` / `192.168.11.188` | 工业相机与本机网卡地址 |
+| `CameraSavePath` | `D:\Images\flyShot` | 飞拍原图、结果图和任务 JSON 保存根目录 |
+| `MPC.MpcInterfaceIp` | `192.168.11.12` | 飞拍控制单元 HTTP 地址 |
+| `MPC.MpcInterfacePort` | `9001` | 上位机调用的飞拍控制单元端口 |
+| `MPC.RobotName` | `LR_Mate_200iD_7L` | 机器人型号/名称 |
+| `MPC.RobotIp` | `192.168.10.11` | FANUC 控制柜 IP |
+| `Ai_Model.ApiUrl` | `http://127.0.0.1:8124/corebg` | AI HTTP 接口地址 |
+| `Ai_Model.AI_Model_Version` | `PEU` | AI 模型版本 |
+| `Ai_Model.AI_configVersion` | `peu_20241011` | AI 配置版本 |
+| `Ai_Model.ai_upload_path` | `/mnt/d/ai_images/ai-feed` | AI 输入图片目录 |
+| `Ai_Model.ai_result_path` | `/mnt/d/ai_images` | AI 结果图片目录 |
+| `FileTransfer.DefaultService` | `Primary` | 当前使用的文件传输服务 |
+| `PLC.EnablePlc` | `true` | 是否启用 PLC 通信 |
+| `PLC.OpcUaServer` | `opc.tcp://174.34.178.68:4840` | OPC UA 服务地址 |
+
+> 注意：如果飞拍控制单元实际监听端口是 `5000`，上位机的 `MPC.MpcInterfacePort` 需要同步改为 `5000`，或通过反向代理/部署配置把控制单元暴露为 `9001`。
+
+### 4.2 飞拍控制单元配置
+
+飞拍控制单元配置文件：
+
+- `D:\Dev\Codes\rvbust-code\FlyingShotPkg_3.15_VDA\flyshot-replacement\src\Flyshot.Server.Host\appsettings.json`
+
+常用配置项：
+
+| 配置路径 | 示例值 | 说明 |
+| --- | --- | --- |
+| `ControllerClientCompat.AutoInit.RobotName` | `FANUC_LR_Mate_200iD_7L` | 服务启动自动初始化的机器人名称 |
+| `ControllerClientCompat.AutoInit.RobotIp` | `192.168.10.11` | 服务启动自动连接的机器人 IP |
+| `Kestrel.Endpoints.Http.Url` | `http://0.0.0.0:5000` | HTTP 服务监听地址 |
+| `Swagger.Enabled` | `true` | 是否启用 Swagger 和调试接口 |
+| `Cors.AllowedOrigins` | `*` | 允许跨域调用的来源 |
+
+## 5. 飞拍控制单元 HTTP 接口
+
+### 5.1 初始化机器人
+
+推荐使用聚合初始化接口：
+
+```http
+POST /init_mpc_robot
+Content-Type: application/json
+
+{
+  "robot_name": "FANUC_LR_Mate_200iD_7L",
+  "robot_ip": "192.168.10.11"
+}
+```
+
+内部执行顺序：
+
+1. `SetUpRobot`：加载机器人模型和关节限制。
+2. `Connect`：建立 FANUC 状态、命令、J519 三条通道。
+3. `EnableRobot(8)`：启动机器人程序和运动循环。
+
+也可以拆分调用：
+
+```text
+POST /setup_robot/?robot_name=FANUC_LR_Mate_200iD_7L
+POST /connect_robot/?ip=192.168.10.11
+GET  /enable_robot/?buffer_size=8
+```
+
+### 5.2 上传飞拍轨迹
+
+```http
+POST /upload_flyshot/
+Content-Type: application/json
+
+{
+  "name": "UTTC_MS11",
+  "waypoints": [[0, 0, 0, 0, 0, 0]],
+  "shot_flags": [true],
+  "offset_values": [0],
+  "addrs": [[1, 3]]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | string | 飞拍轨迹名称，上位机执行时使用 |
+| `waypoints` | number[][] | 机器人关节路径点 |
+| `shot_flags` | bool[] | 每个路径点是否拍照 |
+| `offset_values` | number[] | 拍照触发偏移周期 |
+| `addrs` | number[][] | 拍照触发 IO 地址组 |
+
+### 5.3 执行飞拍轨迹
+
+上位机 `MpcService.ExecuteFlyShot` 当前默认发送：
+
+```http
+POST /execute_flyshot/
+Content-Type: application/json
+
+{
+  "name": "UTTC_MS11",
+  "move_to_start": true,
+  "method": "icsp",
+  "save_traj": false,
+  "use_cache": false,
+  "wait": false
+}
+```
+
+字段说明：
+
+| 字段 | 推荐值 | 说明 |
+| --- | --- | --- |
+| `name` | 轨迹名称 | 必须已上传或存在于控制单元缓存 |
+| `move_to_start` | `true` | 执行前先移动到规划起点，避免第一帧目标突变 |
+| `method` | `icsp` 或 `self-adapt-icsp` | 轨迹规划方法 |
+| `save_traj` | `false` | 是否保存本次规划轨迹 |
+| `use_cache` | `false` 或 `true` | 是否复用缓存轨迹 |
+| `wait` | `false` 或 `true` | 是否等待整条轨迹完成后再返回 |
+
+### 5.4 常用调试接口
+
+| 接口 | 方法 | 用途 |
+| --- | --- | --- |
+| `/healthz` | GET | 服务健康检查 |
+| `/status.html` | GET | 浏览器状态页 |
+| `/debug.html` | GET | 浏览器接口调试页 |
+| `/api/status/snapshot` | GET | 当前兼容层和运行时状态快照 |
+| `/robot_info/` | GET | 查询机器人信息 |
+| `/set_speedRatio/` | POST | 设置速度倍率 |
+| `/list_flyShotTraj/` | GET | 查询可执行飞拍轨迹名称 |
+| `/delete_flyshot/` | POST | 删除飞拍轨迹 |
+| `/stop_move/` | GET | 停止当前运动 |
+| `/disable_robot/` | GET | 禁用机器人 |
+| `/disconnect_robot/` | POST | 断开机器人连接 |
+
+## 6. 上位机使用教程
+
+### 6.1 启动前检查
+
+1. 确认工业相机、机器人控制柜、AI 服务、PLC、MES 网络可达。
+2. 检查上位机 `appConfig.json`：
+   - `CameraIp` 和 `LocalIp` 是否匹配现场网段。
+   - `CameraSavePath` 是否存在或可创建。
+   - `MPC.MpcInterfaceIp` / `MpcInterfacePort` 是否指向飞拍控制单元。
+   - `Ai_Model.ApiUrl` 是否指向 YOLO AI 接口。
+   - `FileTransfer` 是否能访问 AI 上传和结果目录。
+3. 检查飞拍控制单元是否启动：
+   - 浏览器访问 `http://<控制单元IP>:<端口>/healthz`。
+   - 浏览器访问 `http://<控制单元IP>:<端口>/status.html`。
+4. 检查机器人程序、控制柜状态和安全围栏。
+
+### 6.2 上位机启动流程
+
+```mermaid
+flowchart TD
+    A["启动 FlyShot 上位机"] --> B["读取 appConfig.json"]
+    B --> C["初始化 MES<br/>可按 EnableMes 关闭"]
+    B --> D["初始化相机"]
+    B --> E["查询飞拍控制单元轨迹列表"]
+    E --> F["设置机器人速度倍率<br/>默认 0.5"]
+    D --> G["确认系统状态栏无关键 NG"]
+    F --> G
+    G --> H["等待手动或 PLC 触发任务"]
+```
+
+启动后，上位机会执行：
+
+- 初始化 MES 连接。
+- 初始化相机。
+- 查询飞拍控制单元中的飞拍任务列表。
+- 设置机器人速度倍率。
+- 创建或检查图片保存目录。
+
+### 6.3 手动执行飞拍任务
+
+适用于调试、首件验证和现场排查。
+
+1. 打开上位机。
+2. 确认相机初始化成功。
+3. 确认飞拍任务列表已加载。
+4. 输入或扫码产品标识。
+5. 选择飞拍任务名称。
+6. 点击手动开始。
+7. 上位机执行：
+   - 初始化工位任务。
+   - 注册相机回调。
+   - 调用飞拍控制单元 `/execute_flyshot/`。
+   - 接收相机回调并保存图片。
+   - 批量调用 AI 检测。
+   - 汇总 OK/NG。
+   - 保存任务 JSON。
+   - 如有 NG，打开人工复判界面并发送通知。
+
+### 6.4 PLC 自动执行飞拍任务
+
+适用于正式生产。
+
+PLC 通过 OPC UA 写入任务触发信号，上位机收到 `StartFlyShotTask` 上升沿后执行任务。
+
+PLC 输入给 PC 的核心信号：
+
+| 信号 | 说明 |
+| --- | --- |
+| `StartFlyShotTask` | 飞拍任务启动，上升沿触发 |
+| `WorkStationId` | 工位号 |
+| `FlyShotTaskName` | 飞拍任务名称 |
+| `CurrentTaskIndex` | 当前任务序号 |
+| `TotalTaskCount` | 当前工位任务总数 |
+| `ProductTypeNo` | 产品型号 |
+| `ProductIdentifier` | 产品唯一标识 |
+| `ProductBatch` | 产品批次 |
+| `ResetSystem` | 系统重置信号 |
+
+PC 回写给 PLC 的核心信号：
+
+| 信号 | 说明 |
+| --- | --- |
+| `TaskCompleted` | 当前任务完成 |
+| `TaskResult` | 当前任务结果，true=OK，false=NG |
+| `CompletedTaskIndex` | 已完成任务序号 |
+| `TaskProcessingTime` | 当前任务耗时 |
+| `WorkStationCompleted` | 工位所有任务是否完成 |
+| `WorkStationResult` | 工位总结果 |
+| `SystemReady` | 系统是否就绪 |
+| `SystemBusy` | 系统是否忙碌 |
+| `ErrorCode` | 错误码 |
+| `ErrorMessage` | 错误信息 |
+| `PcHeartbeat` | PC 心跳 |
+
+### 6.5 图片和结果保存规则
+
+上位机会基于 `CameraSavePath` 生成任务目录：
+
+```text
+{CameraSavePath}\{yyyyMMdd}\{TypeNo-TypeVar}\{ProductIdentifier}\{FlyShotName}\
+```
+
+任务目录内通常包含：
+
+| 内容 | 说明 |
+| --- | --- |
+| 原始图片 | 相机回调保存的图片 |
+| `result` 子目录 | AI 下载后的结果图 |
+| `flyShotTask@...json` | 单个飞拍任务详情 |
+| `WorkStationTask@...json` | 工位任务汇总 |
+
+AI 结果图命名会带上检测结果，例如：
+
+```text
+原图名@OK.jpeg
+原图名@NG.jpeg
+```
+
+## 7. YOLO AI 识别流程
+
+```mermaid
+flowchart TD
+    A["相机回调保存原图"] --> B["上位机收集待处理图片"]
+    B --> C["达到 BatchSize 或采集结束"]
+    C --> D["上传原图到 Ai_Model.ai_upload_path"]
+    D --> E["构造 AiProcessRequestModel"]
+    E --> F["POST Ai_Model.ApiUrl"]
+    F --> G["解析 ProductResult / SubImgInfo / FailureModes"]
+    G --> H["从 Ai_Model.ai_result_path 下载结果图"]
+    H --> I["写回 ImageProcessOutcome"]
+    I --> J["更新 UI 与任务结果"]
+    J --> K["清理 AI 远端临时文件"]
+```
+
+### 7.1 AI 请求结构
+
+AI 请求的典型结构：
+
+```json
+{
+  "ai_modelVersion": "PEU",
+  "ai_configVersion": "peu_20241011",
+  "key": "empty",
+  "product_id": "20250228121929",
+  "sub_img_info": [
+    {
+      "index": 1,
+      "view": "pipe",
+      "object": "spring",
+      "image_path": "000001_161008_1.jpeg",
+      "ai_image_path": null,
+      "ai_result": null,
+      "ai_reason": null,
+      "ai_param_list:": {}
+    }
+  ]
+}
+```
+
+字段说明：
+
+| 字段 | 说明 |
+| --- | --- |
+| `ai_modelVersion` | AI 模型版本，对应上位机 `Ai_Model.AI_Model_Version` |
+| `ai_configVersion` | AI 配置版本，对应上位机 `Ai_Model.AI_configVersion` |
+| `product_id` | 本次 AI 任务 ID，通常由时间戳生成 |
+| `sub_img_info[].index` | 图片序号 |
+| `sub_img_info[].view` | 视角，例如 `pipe`、`surface`、`connector` |
+| `sub_img_info[].object` | 检测对象，例如 `spring`、`top`、`side` |
+| `sub_img_info[].image_path` | 上传到 AI 输入目录后的图片文件名 |
+
+### 7.2 AI 响应处理
+
+上位机按 `index` 将 AI 响应和原图对应起来，主要读取：
+
+| 字段 | 说明 |
+| --- | --- |
+| `ProductResult` | 产品级检测结果 |
+| `ErrorInfo` | AI 处理错误信息 |
+| `AiFailureModel` | AI 不良模式集合 |
+| `SubImgInfo[].AiResult` | 单张图片结果，`OK` 视为 OK，其他非空值视为 NG |
+| `SubImgInfo[].AiReason` | 单张图片 NG 原因 |
+| `SubImgInfo[].AiParamList` | AI 参数明细 |
+| `SubImgInfo[].AiImagePath` | AI 结果图远端路径 |
+
+## 8. MES 交互说明
+
+### 8.1 换型下发
+
+上位机启动或手动换型时，会根据 `MesConfig.TypeNo` 和 `MesConfig.TypeVar` 发送 `DataDownloadRequired`。
+
+主要用途：
+
+- 获取或刷新当前型号配置。
+- 更新本地 `TypeNo` / `TypeVar`。
+- 加载对应 `Config\TypeData` 文件。
+
+### 8.2 结果上报
+
+飞拍任务完成后，上位机会发送 `PartProcessed`。
+
+上报内容包括：
+
+- 产品唯一标识。
+- 产品型号和变体。
+- 工位结果，`1=OK`，`2=NG`。
+- 图片相对路径。
+- 每张图片的 AI 结果和人工复判结果。
+- 汇总后的 NIO bits。
+
+## 9. 常见使用场景
+
+### 9.1 首次联调
+
+1. 启动飞拍控制单元。
+2. 访问 `/healthz` 确认服务正常。
+3. 访问 `/status.html` 查看模型和机器人状态。
+4. 调用 `/init_mpc_robot` 初始化机器人。
+5. 调用 `/list_flyShotTraj/` 确认可用轨迹。
+6. 启动上位机。
+7. 检查上位机日志中相机、MPC、MES、PLC 状态。
+8. 使用手动模式执行一次飞拍任务。
+9. 检查图片目录、AI 结果图、任务 JSON 和 MES/PLC 反馈。
+
+### 9.2 正式生产
+
+1. 启动飞拍控制单元并确认状态正常。
+2. 启动上位机并确认系统就绪。
+3. PLC 写入产品和任务信息。
+4. PLC 触发 `StartFlyShotTask` 上升沿。
+5. 上位机执行飞拍、AI 检测和结果汇总。
+6. 上位机回写 PLC 当前任务和工位结果。
+7. 上位机发送 MES `PartProcessed`。
+8. PLC 根据 `WorkStationCompleted` 和 `WorkStationResult` 决定后续流程。
+
+### 9.3 离线排查 AI
+
+1. 准备一组本地图片。
+2. 在上位机调试页面或相关调试入口选择图片。
+3. 确认 `Ai_Model.ApiUrl`、`ai_upload_path`、`ai_result_path` 正确。
+4. 执行 AI 请求。
+5. 检查 AI 响应、结果图下载、上位机日志和远端文件清理情况。
+
+## 10. 故障排查
+
+```mermaid
+flowchart TD
+    A["发现任务失败或结果异常"] --> B{"失败阶段"}
+    B -->|相机无图| C["检查 CameraIp / LocalIp / 相机连接 / 触发源 / 曝光增益"]
+    B -->|控制单元失败| D["检查 /healthz /status.html / MpcInterfaceIp / 端口 / 机器人状态"]
+    B -->|机器人报警| E["检查 FANUC 控制柜 / RVBUSTSM / J519 通道 / 安全状态"]
+    B -->|AI 无结果| F["检查 Ai_Model.ApiUrl / 文件传输目录 / AI 服务日志 / 结果图路径"]
+    B -->|PLC 不触发| G["检查 OPC UA 地址 / ActiveProfile / StartFlyShotTask 上升沿 / SystemReady"]
+    B -->|MES 失败| H["检查 EnableMes / ServerIp / ServerPort / TelegramFolder / 报文响应"]
+    C --> I["查看上位机日志和图片目录"]
+    D --> I
+    E --> I
+    F --> I
+    G --> I
+    H --> I
+```
+
+### 10.1 相机问题
+
+| 现象 | 排查点 |
+| --- | --- |
+| 无图像回调 | 相机 IP、本机网卡、相机初始化、回调注册 |
+| 图片曝光异常 | 飞拍点位配置中的曝光和增益 |
+| 图片保存失败 | `CameraSavePath` 权限、磁盘空间、路径是否存在 |
+
+### 10.2 飞拍控制单元问题
+
+| 现象 | 排查点 |
+| --- | --- |
+| 上位机无法连接 MPC | `MPC.MpcInterfaceIp` / `MpcInterfacePort` 是否指向控制单元 |
+| `/execute_flyshot/` 失败 | 轨迹是否已上传、机器人是否初始化、`method` 是否支持 |
+| 机器人不运动 | `/status.html` 状态、FANUC 通道、使能状态、控制柜报警 |
+| 轨迹执行后无拍照 | `shot_flags`、`offset_values`、`addrs`、J519 IO 脉冲 |
+
+### 10.3 AI 问题
+
+| 现象 | 排查点 |
+| --- | --- |
+| AI 请求失败 | `Ai_Model.ApiUrl`、AI 服务是否启动、HTTP 是否可达 |
+| AI 找不到图片 | `ai_upload_path`、文件传输服务、远端目录权限 |
+| 结果图下载失败 | `ai_result_path`、`AiImagePath`、SFTP/SMB/LOCAL 配置 |
+| 结果和图片错位 | 检查 AI 响应中的 `index` 是否和请求一致 |
+
+### 10.4 PLC/MES 问题
+
+| 现象 | 排查点 |
+| --- | --- |
+| PLC 不触发任务 | `PLC.EnablePlc`、OPC UA 地址、变量映射、上升沿保持时间 |
+| PLC 反馈不更新 | 输出变量是否可写、`SystemBusy/SystemReady` 状态 |
+| MES 连接失败 | `MesConfig.EnableMes`、IP、端口、防火墙 |
+| MES 报文异常 | `TelegramFolder` 下保存的 XML 报文和响应 |
+
+## 11. 交付与飞书整理建议
+
+建议后续整理为飞书文档时采用以下方式：
+
+1. 以本文档 Markdown 作为源稿。
+2. 将 Mermaid 流程图渲染为 PNG 或 SVG 图片后插入飞书。
+3. 保留接口表、配置表和操作步骤，适合现场培训。
+4. 如果需要正式发布版本，可再从 Markdown 生成 Word，再导入飞书云文档。
+5. 每次接口、配置或流程变更后，优先更新 Markdown 源稿，再同步飞书版本。
+
+建议拆分飞书目录：
+
+```text
+飞拍系统说明
+├─ 1. 系统总览
+├─ 2. 生产主流程
+├─ 3. 上位机使用教程
+├─ 4. 飞拍控制单元使用教程
+├─ 5. YOLO AI 接口说明
+├─ 6. PLC 与 MES 交互
+└─ 7. 常见问题排查
+```
--- a/docs/use-do-output-selection.md
+++ b/docs/use-do-output-selection.md
@@ -0,0 +1,14 @@
+# 飞拍 DO / RO 输出选择
+
+`RobotConfig.json` 的 `robot.use_do` 用于选择飞拍输出类型：
+
+- `true`：使用 DO，J519 `writeIoType=2`。
+- `false`：使用 RO，J519 `writeIoType=9`。
+
+两种模式都根据 `shot_flags / offset_values / addr` 生成触发事件，保持 `io_keep_cycles` 的脉冲保持与清零行为。`use_do=false` 不再关闭拍照触发。
+
+触发时间轴将输出选择固化到每个事件中；FANUC 运行时根据事件选择写入类型，触发帧和清零帧使用相同类型。未携带输出选择的已有事件默认使用 DO，普通无触发运动保持原行为。
+
+本次不修改配置中的 `addr`，不增加 RO 点位范围校验，现场点位由调用方自行调试。手动 HTTP `SetIo` 仍使用显式 `io_type`。
+
+验证覆盖配置到事件的传递，以及 DO / RO 两种模式下的 J519 脉冲与清零。软件测试不代表末端接线和真实相机触发已完成验收。