# 集成测试覆盖补充计划

> **跟踪文档**：记录集成测试的覆盖现状与待补充测试，后续按此文档跟踪完成情况。
> 状态：`- [ ]` 待办 · `- [x]` 完成（勾选时注明日期与提交）

---

## 1. 背景

- 集成测试框架：MSTest + `NavisworksTestAutomationClient`（HTTP `127.0.0.1:18777` ↔ 插件内 `TestAutomationHttpService`，请求经 UI 线程走真实业务链路）
- 运行方式：
  - 部署+启动：`./build-and-deploy.bat` → `./start-navisworks.bat`（默认模型 Floor2_mobile_yup.nwd，英尺单位）
  - 集成测试：`vstest NavisworksTransport.UnitTests.dll /TestCaseFilter:"TestCategory=NavisworksIntegration"`（单测已排除此分类）
- 依赖：标准测试路径由插件自动导入（`resources/auto-test-routes.xml` → `EnsureAutoTestRoutesImported`）

## 2. 现有覆盖（已完成 ✅）

| 测试 | 文件 | 覆盖点 |
|---|---|---|
| Ground/Hoisting/Rail 虚拟物体碰撞 | `VirtualCollisionAutomationTests.cs` | 虚拟物体 + 三类路径完整动画/碰撞流程（断言 Finished、检测记录 ID、报告存在） |
| Ground 自动路径规划 | `AutoPathGridGenerationAutomationTests.cs` | AutoPlanPath + 网格验证（默认参数/Shortest/畅通场景） |
| JSON/XML 路径导入 | `PathImportValidityAutomationTests.cs` | 导入 → Rail 属性映射 → 长度计算（文档单位换算）→ 切换 → 动画可用性 |

## 3. 待补充测试

### P0 高风险区（AGENTS.md 标注高风险：真实物体姿态链 / 动画逐帧状态）

- [x] **T01 真实物体 Ground 动画与姿态**（2026-08-04，`RealObjectAnimationAutomationTests`）
  - 验证：`select-animated-object` 选真实物体 → 生成动画 → 断言物体实际位置/姿态（fragment 代表姿态、平面姿态链）
  - 实现：`run-virtual-collision-test?useVirtualObject=false&animatedObjectPath=0/0/660/0`（42" Diameter）
- [x] **T02 真实物体 Hoisting 动画与姿态**（2026-08-04，`RealObjectAnimationAutomationTests`）
  - 验证：真实物体吊装路径动画（起吊/平移/下降三段姿态）
  - 实现：`animatedObjectPath=0/0/769/0`（25" x 25"，Hoisting 路径上）
- [x] **T03 真实物体 Rail 动画与姿态**（2026-08-04，`RealObjectAnimationAutomationTests`）
  - 验证：真实物体空轨路径（canonical → rail pose 链、角度修正不污染 0° 基线）
  - 实现：`animatedObjectPath=0/0/660/0`（42" Diameter）
- [x] **T04 动画逐帧状态验证**（2026-08-04，`AnimationFrameProbeAutomationTests`）
  - 验证：动画中途/结束时物体位置沿路径移动（起点=路径起点、逐帧插值、终点=路径终点）；Ground 平面链 yaw 正确
  - 实现：`probe-animation-frames` 端点（生成动画后 SeekToProgress 取跟踪位置）；Ground 起点/终点 XZ 匹配 + 高度恒定，Hoisting 吊装剖面（起吊→悬挂→下降）+ 水平平移

### P1 功能面缺失

- [x] **T05 Free 自由路径动画**（2026-08-04，`FreePathAutomationTests`）— 第 4 类路径完整流程 + 逐帧位置精确匹配路径点（物体中心=路径点，XYZ 全匹配）
- [x] **T06 碰撞结果内容验证**（2026-08-04，`CollisionReportAssertions`）— 报告结构/路径关联/数据一致性断言，接入虚拟+真实物体测试
- [x] **T07 自动路径障碍绕行**（2026-08-04，`AutoPathObstacleDetourAutomationTests`）— 构造跨越大半模型的起终点（直线 11.0m），断言规划路径 blocked=0 且长度 11.57m > 直线距离（成功绕行）
- [x] **T08 自动路径多策略**（2026-08-04，同测试类）— Shortest/Straightest 策略参数回传正确 + 均规划出有效路径
- [x] **T09 网格诊断断言**（2026-08-04，`RouteGridDiagnosticsAutomationTests`）— 网格参数/路径点覆盖/段数量一致性（可通行性为诊断信息不作硬断言）
- [x] **T10 路径持久化/检测记录**（2026-08-04，`DetectionRecordPersistenceAutomationTests`）— 检测记录从数据库重载：关联路径、动画参数（15fps/5s）、虚拟物体模式一致

### P2 需新增服务端端点

- [x] **T11 路径编辑**（2026-08-04，`PathEditingAutomationTests`）— 删除路径点/更新位置/正交化/去环（RemovePathPoint 仅处理 3D 标记，真删点走 PathRoute.RemovePoint）
- [x] **T12 路径导出**（2026-08-04，`ExportImportRoundTripAutomationTests`）— XML/JSON 导出→导入回环属性一致
- [x] **T13 动画播放控制**（2026-08-04，`AnimationPlaybackControlAutomationTests`）— prepare→start→pause 验证→resume→finished
- [x] **T14 批量任务队列**（2026-08-04，`BatchQueueAutomationTests`）— 队列添加/计数递增（轻量版，不执行批量动画）
- [x] **T15 路径分析**（2026-08-04，`PathAnalysisAutomationTests`）— 评分结构验证；顺带修复产品 bug（CollisionResults 表已废弃导致路径分析 no such table）
- [x] **T16 剖面盒导出**（2026-08-04，`SectionBoxExportAutomationTests`）— 指定包围盒模式导出 NWD（对象数/文件大小/隐藏节点），不依赖 UI 剖面盒状态

## 4. 测试服务支撑能力

| 端点 | 状态 | 用途 |
|---|---|---|
| ping / status / routes / selection | ✅ | 健康检查、状态、路径列表、选择集 |
| select-route / select-default-route | ✅ | 切换路径（自动测试_ 前缀自动导入） |
| **select-animated-object** | ✅ 已实现 | 真实物体选择（T01-T03 已用） |
| **list-model-items** | ✅ 已实现 | 枚举模型物体（DisplayName/PathId/包围盒中心/祖先链，动态解析真实物体） |
| run-virtual-collision-test / run-ground-collision-test | ✅ | 虚拟/真实物体碰撞流程（useVirtualObject=false + animatedObjectPath + frameRate/durationSeconds 加速） |
| probe-animation-frames | ✅ | 动画逐帧位置/yaw 探针（T04，SeekToProgress） |
| **detection-record** | ✅ 已实现 | 检测记录持久化查询（T10） |
| run-auto-path / analyze-auto-path-grid / route-grid-diagnostics | ✅ | 自动路径（strategy）+ 网格诊断（T07/T08/T09） |
| **export-debug-snapshot** | ✅ 已实现 | 动画调试快照（trackedState/boundingBox） |
| import-route-file | ✅ | 路径导入验证 |
| export-route-file | ✅ 已实现 | 路径导出（T12） |
| edit-route | ✅ 已实现 | 路径编辑 remove-point/update-point/orthogonalize/remove-loops（T11） |
| animation-playback-control | ✅ 已实现 | 播放控制序列（T13） |
| batch-queue-add | ✅ 已实现 | 批量队列添加（T14） |
| analyze-path | ✅ 已实现 | 路径分析评分（T15） |
| export-section-box | ✅ 已实现 | 剖面盒导出 NWD（bbox/activeView 模式，T16） |
| 其余待扩展 | — | 批量执行、TimeLiner 集成等后续迭代补充 |

## 5. 完成记录

| 日期 | 提交 | 完成项 |
|---|---|---|
| 2026-08-02 | `43df07c` | 集成测试标准路径自动导入机制（前置基础） |
| 2026-08-02 | `c9c29c7` | 路径导入验证迁入集成测试（PathImportValidity） |
| 2026-08-02 | `5bdfa82` | AGENTS.md 单位原则强化（测试断言按文档单位换算） |
| 2026-08-04 | `b5cfcbf` | T01-T03 真实物体动画（RealObjectAnimationAutomationTests，服务端支持 useVirtualObject=false + animatedObjectPath/InstanceGuid 校验） |
| 2026-08-04 | `8f477c0` | T04 动画逐帧状态验证（AnimationFrameProbeAutomationTests，probe-animation-frames 端点） |
| 2026-08-04 | `44214ba` | T05/T06 + 基础修复（Free 路径、报告断言、动态解析、串行锁、脚本、加速 15fps/5s） |
| 2026-08-04 | 待提交 | T07-T10（障碍绕行、多策略、网格诊断、持久化）+ GetDetectionRecordById + detection-record 端点；P0+P1 完成，18/18 |
| 2026-08-04 | 待提交 | T11-T15（路径编辑/导出/播放控制/批量队列/路径分析）+ 服务端 5 端点 + 产品 bug 修复（PathDatabase CollisionResults→CollisionReports、RemovePoint 链路）；P0+P1+P2 全部完成，集成测试 24/24，完整集 74.6s |
| 2026-08-04 | 待提交 | T16 剖面盒导出（SectionBoxExportAutomationTests + export-section-box 端点，bbox 模式），25/25 |