From 454590ae2605d9dc95dc8ee4be8a415b2dcafc6e Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Tue, 4 Aug 2026 16:42:05 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E9=9B=86=E6=88=90?=
 =?UTF-8?q?=E6=B5=8B=E8=AF=95=E8=A6=86=E7=9B=96=E8=A1=A5=E5=85=85=E8=AE=A1?=
 =?UTF-8?q?=E5=88=92=E8=B7=9F=E8=B8=AA=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 记录现有集成测试覆盖（6 个测试）与核心功能缺口（15 项待补，分 P0/P1/P2 优先级）
- P0 高风险区：真实物体动画（Ground/Hoisting/Rail）、动画逐帧状态验证
- P1 功能面：Free 路径、碰撞内容验证、自动路径障碍绕行/多策略、网格诊断、持久化
- P2 需新增端点：路径编辑/导出、播放控制、批量任务、路径分析
- 附带测试服务端点支撑能力清单与完成记录表（checkbox 跟踪）
---
 ...26-08-02-integration-test-coverage-plan.md | 76 +++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 doc/working/2026-08-02-integration-test-coverage-plan.md

diff --git a/doc/working/2026-08-02-integration-test-coverage-plan.md b/doc/working/2026-08-02-integration-test-coverage-plan.md
new file mode 100644
index 0000000..e222479
--- /dev/null
+++ b/doc/working/2026-08-02-integration-test-coverage-plan.md
@@ -0,0 +1,76 @@
+# 集成测试覆盖补充计划
+
+> **跟踪文档**：记录集成测试的覆盖现状与待补充测试，后续按此文档跟踪完成情况。
+> 状态：`- [ ]` 待办 · `- [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 标注高风险：真实物体姿态链 / 动画逐帧状态）
+
+- [ ] **T01 真实物体 Ground 动画与姿态**
+  - 验证：`select-animated-object` 选真实物体 → 生成动画 → 断言物体实际位置/姿态（fragment 代表姿态、平面姿态链）
+  - 支撑：服务端 `select-animated-object` 端点已实现（按名称/选择集）；`export-debug-snapshot` 返回 trackedState/geometryState/boundingBox
+- [ ] **T02 真实物体 Hoisting 动画与姿态**
+  - 验证：真实物体吊装路径动画（起吊/平移/下降三段姿态）
+- [ ] **T03 真实物体 Rail 动画与姿态**
+  - 验证：真实物体空轨路径（canonical → rail pose 链、角度修正不污染 0° 基线）
+- [ ] **T04 动画逐帧状态验证**
+  - 验证：动画中途/结束时物体位置沿路径移动、姿态符合预期（起点=路径起点、逐帧插值、终点=路径终点）；Ground 平面链 yaw 正确
+  - 支撑：`export-debug-snapshot` trackedState（position/yaw/quaternion）+ boundingBox
+
+### P1 功能面缺失
+
+- [ ] **T05 Free 自由路径动画** — 第 4 类路径（任意多点，路径点即物体中心）完整流程 + 姿态（保持原始姿态、平面旋转）
+- [ ] **T06 碰撞结果内容验证** — 现有 Rail 测试断言 `totalCollisions > 0`、碰撞对象数、截图数；Ground 断言 0 碰撞（权威结果）
+- [ ] **T07 自动路径障碍绕行** — 构造起终点之间有障碍物的场景，断言规划路径成功绕行（blockedSampleCount==0 且路径非直线）
+- [ ] **T08 自动路径多策略** — `run-auto-path` strategy 参数（Shortest/Straightest）对比：路径长度/转弯数差异断言
+- [ ] **T09 网格诊断断言** — `route-grid-diagnostics` 端点：网格参数（cellSize、origin）、路径点所在网格可通行性
+- [ ] **T10 路径持久化/检测记录** — 检测记录 ID 从数据库重新加载断言（CollisionReports/DetectionRecords 表存在）
+
+### P2 需新增服务端端点
+
+- [ ] **T11 路径编辑** — 增删路径点、更新点位置（`RemovePathPoint`/`UpdatePathPointWithConstraints`/`UpdatePointPosition`）、正交化、去矩形环
+- [ ] **T12 路径导出** — ExportPath（XML/JSON 导出 → 再导入回环验证）
+- [ ] **T13 动画播放控制** — Pause/Resume/Stop/Reset 中途控制（当前只测自动跑完）
+- [ ] **T14 批量任务队列** — AddToBatchQueue 批量执行（BatchQueueManager）
+- [ ] **T15 路径分析** — PathAnalysisService（效率/安全评分）与 TimeLiner 集成
+
+## 4. 测试服务支撑能力
+
+| 端点 | 状态 | 用途 |
+|---|---|---|
+| ping / status / routes / selection | ✅ | 健康检查、状态、路径列表、选择集 |
+| select-route / select-default-route | ✅ | 切换路径（自动测试_ 前缀自动导入） |
+| **select-animated-object** | ✅ 已实现未用 | 真实物体选择（P0 测试用） |
+| run-virtual-collision-test / run-ground-collision-test | ✅ | 虚拟/真实物体碰撞流程 |
+| analyze-auto-path-grid / run-auto-path | ✅ | 自动路径规划（已支持 strategy） |
+| **route-grid-diagnostics** | ✅ 已实现未用 | 网格诊断（T09 用） |
+| **export-debug-snapshot** | ✅ 已实现未用 | 动画逐帧状态（T04 用） |
+| import-route-file | ✅ | 路径导入验证 |
+| 路径编辑 / 导出 / 播放控制 / 批量任务 | ❌ 需新增 | T11-T15 |
+
+## 5. 完成记录
+
+| 日期 | 提交 | 完成项 |
+|---|---|---|
+| 2026-08-02 | `43df07c` | 集成测试标准路径自动导入机制（前置基础） |
+| 2026-08-02 | `c9c29c7` | 路径导入验证迁入集成测试（PathImportValidity） |
+| 2026-08-02 | `5bdfa82` | AGENTS.md 单位原则强化（测试断言按文档单位换算） |