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