smart-inspection/docs/开发记录_2026-05_06.md

AGV + 机械臂 移动拍摄平台 — 开发记录

汇总 2026年5-6月期间的所有修复记录和任务总结

---

一、running.html 显示修复 + 任务执行状态实时更新 (2026-05-29 13:10)

目标

修复运行页面两个 bug：

1. 模板中 {{ }} 显示为原始文本（Vue 未挂载）
2. 任务执行过程中状态不更新（始终显示"⏳等待"）

根因分析

问题1：{{ }} 原文显示

• running.js 写有 delimiters: ['[[', ']]']，但 Vue 3 已移除此选项（被静默忽略）
• Vue 3 只认 {{ }}，但模板中混用了 [[ ]] 和 {% raw %}{{ }}{% endraw %}
• 残留的裸 [[ ]]（log、report、errorMsg 等）未被 Jinja2 处理，Vue 也因 delimiters 冲突不解析
• 修复：删除 delimiters 行 → 全部改用 {% raw %}{{ }}{% endraw %} 包裹 Vue 表达式

问题2：状态不更新

• api_mission_state() 每次都从文件初始化 point_status/machine_status 为全 "pending"
• mission_executor.py 完全没有跟踪 point_status 和 machine_status
• 修复：executor 添加状态跟踪 + app.py 从 executor.report 读取实时状态

修改的文件

文件	改动
running.js	删除 delimiters: ['[[', ']]']
running.html	全部 [[ ]] → {% raw %}{{ }}{% endraw %}（14处）
app.py	api_mission_state() 从 ex.report 读取 point_status/machine_status
mission_executor.py	初始化+实时更新 point_status（pending/active/done/skipped）和 machine_status（pending/active/completed）

关键设计

point_status 状态流转：

• pending → active（开始导航到点位） → done（到达） → skipped（空位永不更新）

machine_status 状态流转：

• 初始化全 pending
• 正面扫码开始：status=active, step=正面扫码
• 扫码完成：qr=done/skipped, qr_val=xxx, step=正面拍照
• 正面拍照完成：front=done/skipped, front_cnt++
• 背面拍照开始：step=背面拍照
• 背面拍照完成：back=done/skipped, back_cnt++, status=completed, step=完成

部署状态

• 所有4个文件已通过 scp 部署到 192.168.50.93
• Flask 已重启（PID 3664）
• API 验证通过：point_status 和 machine_status 正常返回
• 本地文件已同步回 workspace

---

二、AGV 蛇形路径关节反转逻辑 (2026-05-29 13:49)

需求理解

蛇形路径行走时，AGV 在不同行到达点位时朝向相反：

• 偶数行(0,2,4...)点位 → AGV 从出发方向来 → 正面/背面朝向 = 标定朝向 → 不反转
• 奇数行(1,3,5...)点位 → AGV 从对面来 → 正面/背面朝向 = 标定朝向的反面 → 反转所有关节角度

修复内容

修改 mission_executor.py：

1. _shoot() 新增 machine_row 参数

def _shoot(self, model, side, row, col, qr_value, machine_row=0):
    invert = (machine_row % 2 == 1)  # 奇数行=反转
    if invert:
        angles = [-a for a in angles]  # 6个关节全部取反

调用处传入 machine_row（正面=pr，背面=pr-1）

2. _scan_qr_with_poses() 新增 machine_row 参数

def _scan_qr_with_poses(self, qr_configs, machine_row=0):
    invert = (machine_row % 2 == 1)
    if invert:
        angles = [-a for a in angles]  # 二维码扫描时也反转

3. 调用处传递 machine_row

• _scan_qr_with_poses(qr_configs, machine_row=pr) — 正面扫码
• _shoot(model, "front", ..., pr) — 正面拍照
• _shoot(model, "back", ..., pr-1) — 背面拍照

部署状态

• Flask PID 20577，AGV IP 192.168.50.93
• 已通过语法检查 ✅ 已部署 ✅

---

三、修复删除机器姿态 404 错误 (2026-05-29)

问题描述

删除机器姿态时出现 404 错误：

/api/mission/poses/m_1778767289/pose_1778767312/undefined

URL 末尾出现 undefined，说明 poseId 参数丢失。

根因分析

JS 中存在两个同名方法 deletePose：

1. 机型姿态 (L457): deletePose(modelId, poseId) → 调用 /api/models/...
2. 机器姿态 (L776): deletePose(machineId, side, poseId) → 调用 /api/mission/poses/...

Vue 方法重载机制导致参数错位，poseId 变成 undefined。

修复方案

将机器姿态方法重命名为 deleteMachinePose，避免命名冲突。

修改文件

• static/js/setting.js L776: deletePose → deleteMachinePose

部署

• setting.js 已部署到 AGV
• setting.html 已部署到 AGV（版本号更新）
• 浏览器需刷新缓存 (Ctrl+F5)

待确认

• 模板中是否有调用 deleteMachinePose 的地方需同步修改

---

四、技术说明文档生成 (2026-06-17)

任务

为 AGV + 机械臂移动拍摄平台项目生成详细的技术说明文档

产出

• 文件: AGV_机械臂_技术说明文档.md (888行, 39.5KB)
• 内容覆盖:
  1. 项目概述（业务目标、核心能力、技术栈）
  2. 系统架构（架构图、核心文件清单）
  3. 硬件环境与网络拓扑（设备清单、参数）
  4. 核心模块详解（GlobalState、MissionExecutorV3、AGVController、ArmClient、Nav2Navigator、QRScanner、ImageUploader）
  5. 通信协议（Flask↔前端、ROS2、TCP Socket、Java后端）
  6. 完整API接口文档（11个分组、98个端点）
  7. 任务执行流程（生命周期、QR扫描流程、拍照流程、错误处理）
  8. 数据配置格式（4种JSON schema）
  9. 部署与运维（启动流程、部署命令、常见问题）
  10. 关键决策与约束（10项架构决策 + 6项已知约束）

数据来源

• 逐文件阅读了全部7个Python源文件（共~4312行代码）
• 读取了4个数据配置文件
• 结合记忆条目中的经验教训和已知问题