# 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` 参数**
```python
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` 参数**
```python
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个数据配置文件
- 结合记忆条目中的经验教训和已知问题