docs: design movementtest readme restructure

2026-08-11 17:38:54 +08:00
parent c18315e31e
commit 569de5f13c
1 changed files with 72 additions and 0 deletions
@@ -0,0 +1,72 @@
+# MovementTest README 完整结构重构设计
+
+## 背景
+
+`ClumsyPilot/ParkrobTrajplanner/tarjplanner_movementtest/README.md` 已经说明 EM 轨迹观察会话的只读边界、规划模式、配置和可视化，但章节组织、中英文一致性以及当前目录文件覆盖度仍弱于 `CoarsePath/README.md`。本次更新以粗路径 README 的阅读路径为参照，不机械复制其术语，而是按 MovementTest 的观察、闭环测试、诊断和停止职责重新组织内容。
+
+## 目标
+
+- 让读者先理解模块职责和安全边界，再理解文件、数据流、配置、操作和故障诊断。
+- 用完整文件树覆盖目标目录当前源码，包括观察入口、闭环入口、控制轨迹适配器、规划截止时间和各类诊断/快照/可视化组件。
+- 明确只读观察模式与闭环测试的能力边界，避免把诊断控制意图误认为可直接下发的硬件命令。
+- 根据当前源码核实入口名称、字段、默认值、报告路径、停止行为和可视化行为。
+- 仅修改目标 README，不修改其他源码或用户已有变更。
+
+## 不在范围内
+
+- 不改变规划、观察、控制或可视化行为。
+- 不新增 MovementTest 入口、配置字段或测试代码。
+- 不重构 `CoarsePath`、`PathSmoothing`、`EMPlanner` 或 `TrajectoryExecution` 文档。
+- 不清理、恢复或提交工作区内与本任务无关的改动。
+
+## 文档结构
+
+README 按以下阅读顺序重构：
+
+1. 模块定位与安全声明。
+2. 模块说明：列出上游规划模块、执行模块和当前宿主的职责边界。
+3. 文件结构：逐项覆盖目标目录当前文件及职责。
+4. 运行数据流：分别呈现只读观察链路和闭环测试链路，明确二者共享与分离的部分。
+5. 运行状态与停止：说明启动、运行、取消、故障和资源清理行为。
+6. 坐标与单位：统一解释世界坐标、参考路径坐标、时间和运动学量。
+7. 最小使用示例：以 UI 操作和关键配置为主，不虚构独立公共 API。
+8. 会话冻结、规划周期与轨迹发布：说明完整方向段和滚动模式。
+9. 详细操作指南：准备目标与障碍物、启动、检查状态、观察图层、停止。
+10. 网页看板与可选 Painter：说明端口、令牌、刷新、交互和异常隔离。
+11. 报告与诊断：说明报告位置、主要状态和诊断用途。
+12. 常见错误：覆盖定位/速度读取、目标或障碍物、规划失败、可视化和误用控制意图。
+13. 当前限制：陈述现有模式的能力边界，不把未来设想写成已实现功能。
+
+## 文件结构覆盖原则
+
+文件树以磁盘上的实际文件为准，至少显式包含：
+
+- `MovementTest.TrajectoryObservationTest.cs`
+- `MovementTest.EmClosedLoopTest.cs`
+- `EmControlTrajectoryAdapter.cs`
+- `TrajectoryObservationPlanningDeadline.cs`
+- `TrajectoryObservationPipeline.cs`
+- `TrajectoryObservationContracts.cs`
+- `TrajectoryObservationDiagnostics.cs`
+- `TrajectoryObservationSegmentTracker.cs`
+- 静态与动态快照构建器
+- 运动学图表、交接分析、呈现、可视化发布和报告写入组件
+
+相近文件可以在树中逐项列出；正文可按职责分组解释，避免重复。
+
+## 内容约束
+
+- 以中文为主，保留必要的类型名、字段名、状态枚举和界面标识。
+- 保留 `OBSERVE_ONLY: no chassis command is sent.` 等具有运行识别价值的原始状态文本。
+- 参数表区分 MovementTest UI 默认值和契约默认值。
+- 所有命令、路径、入口和配置名称必须能从当前 README 或源码中找到依据。
+- 闭环测试涉及真实控制能力时，以源码中的安全前置条件、停止策略和命令出口为依据，避免沿用只读观察模式的绝对表述。
+- 不使用容易过时的实现细节替代稳定的使用契约。
+
+## 验证方式
+
+- 将文件树与目标目录的实际文件列表逐项比对。
+- 用源码搜索核实两个 UI 入口、配置字段、报告路径、停止/清理逻辑和安全状态文本。
+- 检查 Markdown 标题层级、代码块、表格和相对链接。
+- 扫描 `TODO`、`TBD`、占位文本和相互矛盾的安全描述。
+- 使用 `git diff --check` 并确认最终变更只包含目标 README；规格文档单独提交。