# 剖面盒导出 + 批处理自动检测方案（评估与实施计划）

> **状态**：评估完成（2026-08-05），E4 核心实验已验证，待实施。
> 跟踪：checkbox 标记实施进度。

---

## 1. 背景与目标

生产环境大模型（几十条路径 × 每条小时级）无法直接做全模型动画碰撞检测，目前只能做"指定碰撞对象"模式。

**目标**：非指定碰撞对象模式的任务，通过剖面盒导出缩小模型，在导出的小模型上做动画检测（分钟级），与批处理结合自动化。

---

## 2. 可行性结论

**可行**（E4 实验已证明核心前提）。架构 = 主 NW 批处理 + 副 NW 作为"无头检测 worker" + HTTP 驱动 + 报告 JSON 显式回传。

---

## 3. 已验证前提（含 E4 实验 2026-08-05）

| 前提 | 验证结果 |
|---|---|
| 剖面盒导出真正剔除盒外对象 | ✅ 代码确认（`NwdExportHelper` 用 `ExcludeHiddenItems = true`） |
| 导出后坐标不变 | ✅ 用户经验确认 |
| 多 Navisworks 实例可同时打开 | ✅ E4 实测：主 NW 运行中 `Start-Process Roamer.exe -ArgumentList 模型路径` 创建独立第二实例，两实例并行加载不同模型 |
| 副实例插件正常加载 | ✅ E4 实测：坐标系检测/模型加载事件正常触发 |
| 之前集成测试 Start-Process 失败根因 | ✅ 恢复弹窗拦截（已被 AutoSave 清理方案解决），非多实例/参数问题 |
| 小模型检测快 | ✅ 集成测试验证（57 对象秒级） |
| 对象标识 | ❌ InstanceGuid 大部分为空（用户经验）→ 用树结构索引 PathId |

### E4 实验新发现

| 发现 | 影响 | 对策 |
|---|---|---|
| 副实例打开的导出模型**无 .db** 时插件跳过数据库连接（当前代码不自动建库） | 检测记录/报告无法落副实例库 | 副实例**无头检测**：结果 JSON 回传不依赖 .db；或显式指定库路径（环境变量） |
| HTTP 端口：两实例都绑 18777 冲突 | 副实例测试服务不可用 | 端口隔离：`TestAutomationHttpService` 端口常量改读环境变量（如 `TRANSPORTPLUGIN_TEST_PORT`） |

---

## 4. 架构设计（定稿）

```
主 NW 批处理（非指定碰撞对象模式任务）
 → 1. 路径包围盒 + 膨胀（物体尺寸 + 安全间隙 + 检测容差）
 → 2. 导出局部 NWD（ExcludeHiddenItems=true）+ 导出路径文件（XML/JSON）
      + 记录盒内对象映射表（主模型PathId ↔ 导出模型PathId，含显示名/位置）
 → 3. Process.Start 启动副 Roamer.exe（UseShellExecute，注入 TRANSPORTPLUGIN_TEST_PORT=18778）
      打开导出 NWD
 → 4. 主 NW 轮询 http://127.0.0.1:18778（ping 就绪）
 → 5. HTTP 驱动副实例：import-route-file（路径）→ run-virtual-collision-test（动画参数）
 → 6. 副实例报告 JSON 导出（含 PathId/显示名/位置/碰撞统计）→ 主 NW 读取
 → 7. 主 NW 按映射表写入主库 → 关闭副实例 → 清理临时 .db/导出文件 → 下一条
```

**约束（用户经验）**：
- 大模型每次打开几分钟 → 禁止单 NW 内切文档，必须独立实例
- InstanceGuid 不可用 → 树结构索引（PathId）+ 映射表
- 报告回传必须显式（副实例 .db 主 NW 不读）

---

## 5. 实施清单（checkbox 跟踪）

### E4 完整链路实验（2026-08-05 完成 ✅）

- [x] **E4-1 端口隔离**：`TestAutomationHttpService` 端口改读环境变量 `TRANSPORTPLUGIN_TEST_PORT`（默认 18777）；实测主实例 18777 + 副实例 18778 并行可用
- [x] **E4-2 副实例无头检测**：副实例（导出模型无 .db）PathPlanningManager 仍初始化；import 路径 + 运行动画检测成功（75 帧/15fps×5s，碰撞 1）
- [x] **E4-3 报告 JSON 导出**：`run-virtual-collision-test` report 扩展 `collidedObjects`（碰撞对象名字列表）
- [x] **E4-4 端到端**：主实例 bbox 导出局部 NWD（57 对象）→ 外部启动副实例（18778）→ import 路径 → 动画检测 → 报告 JSON 回传（碰撞对象 25" x 25"）

**E4 结论**：方案全部技术点验证通过，可直接进入正式功能实施（F1-F4）。

### 正式功能

- [x] **F1 批处理状态机**（2026-08-05 完成）：`ExecuteQueueItemAsync` 扩展（非指定碰撞对象 → 导出→副实例检测→回传）；真实物体运动体（层级链匹配）
- [x] **F2 映射表**（2026-08-05 完成）：导出时构建盒内对象映射（chain去根→主PathId），碰撞对象按层级链映射回主模型（实测 4/4）；副实例 report collidedObjects 带 PathId+层级链
- [x] **F3 清理与恢复**（2026-08-05 完成）：副实例进程定位+Kill+WaitForExit、工作目录清理带重试
- [ ] **F4 大模型实测**：真实大模型验证收益（小时级 → 分钟级）

### F1/F2/F3 稳定性修复记录

- UnitsConverter 缓存 NaN 兜底（显式 ActiveDocument.Units，副实例导出 NWD 单位不稳定）
- 副实例数据库时序：IsDatabaseReady 轮询，导入前确保建库（修复路径丢失→检测记录外键失败）
- batch-queue-process 后台化（模态进度条不阻塞 HTTP），轮询数据库状态

---

## 6. 相关现有基础

| 能力 | 位置 |
|---|---|
| 剖面盒导出（bbox 模式） | `SectionBoxExporter` + `/api/test/export-section-box`（T16） |
| 路径导入 | `/api/test/import-route-file` |
| 动画碰撞检测（可配参数） | `/api/test/run-virtual-collision-test`（frameRate/durationSeconds） |
| 检测记录查询 | `/api/test/detection-record` |
| 批处理队列 | `BatchQueueManager` + `/api/test/batch-queue-add`（T14） |
| 启动脚本弹窗处理 | `start-navisworks.ps1`（AutoSave 清理 + 文件关联） |