# 轨道对比实验设计器 — 需求与功能说明书 版本: 1.0 状态: 草案（可迭代更新） 范围: 本仓库包含的独立演示版 demo.html 与 React 版本（src/\*） ## 1. 背景与目标 一个用于比较不同轨道（直线、圆弧、摆线、抛物线等）从 A 点到 B 点的滑行时间的交互式可视化工具，源于经典的最速降线（Brachistochrone）问题。面向教学演示、科学实验与数值计算学习。 ## 2. 术语与符号 - A、B 点: 起点与终点的平面直角坐标（像素坐标系）。 - g: 重力加速度，取 9.8 m/s²。 - 像素/米换算: 使用 pixelsPerMeter（默认 50），用于将像素长度映射为米。 - 轨道类型: straight（直线）、circular（圆弧）、cycloid（摆线）、parabolic（抛物线）。 - TrackData: 绘制后返回的轨道结构，用于时间计算与可视化。 ## 3. 目标用户与主要场景 - 物理教师/学生：课堂演示最速降线与不同轨道对比。 - 科学爱好者：交互修改 A/B 坐标并观察结果差异。 - 开发者/研究者：探索不同数值方法与可视化方案。 ### 用户故事 1. 作为用户，我可以输入 A、B 的坐标并点击“更新轨道”，看到多条轨道的曲线与时间对比。 2. 作为用户，我可以勾选/取消不同轨道类型，实时对比它们的总路程与用时。 3. 作为用户，当参数不合理（例如 B 不低于 A、水平距离过小等），我会收到明显的提示。 4. 作为用户，我希望圆弧为“向下凹”的碗状，并满足在 A 点处切线垂直，以便与摆线进行公平比较。 ## 4. 功能清单（Must/Should/May） ### Must（必须） - 坐标设置：输入 A(x,y)、B(x,y)，点击按钮触发一次性更新。 - 轨道选择：直线、圆弧、摆线、抛物线的勾选切换与配色固定。 - 轨道绘制：在 Canvas 上按比例绘制曲线，含坐标网格与标注。 - 时间计算：为每条轨道计算从 A 到 B 的滑行时间；展示结果表格（含总路程、时间、最快标记）。 - 物理校验：B 必须低于 A；水平距离最小阈值；坡度过陡提醒。 - 积分精度：提供积分分辨率倍率（demo.html 已有滑块），影响离散采样密度。 ### Should（应该） - 速度/加速度曲线：可视化速度 v(t) 与加速度 a(t) 的近似变化曲线。 - 自适应分辨率：曲率较大处自动加密采样以保证精度（逐步迭代）。 - 清晰的交互反馈：按钮悬停/点击视觉反馈；错误信息显著且可读。 ### May（可选/后续） - 动画演示小球沿轨道滑行。 - 导出 PNG/SVG 或数据 CSV。 - 多语言切换（中/英）。 - 摩擦力/空气阻力模型、3D 视图等高级功能。 ## 5. 详细需求 ### 5.1 坐标与单位 - 输入范围：不限（合理范围内保持画布可见即可）。 - 坐标单位：画布像素；计算时通过 pixelsPerMeter 转米。 - 方向约定：屏幕 y 轴向下为正；因此“B 低于 A”表示 B.y > A.y。 ### 5.2 轨道绘制与几何约束 - 直线（straight）：A–B 的线段。 - 圆弧（circular）： - 必须为向下凹（下凸）的圆弧。 - 严格通过 A、B 两点。 - 关键约束：A 点处的切线为垂直方向（与 y 轴同向），即圆心与 A 点共水平线（Cy = Ay）。 - 圆心横坐标 Cx = (Bx² − Ax² + (By − Ay)²) / [2 · (Bx − Ax)]，半径 r = |Ax − Cx|。 - 在绘制时选择 A 到 B 的“较短弧段”。 - 摆线（cycloid）：基于起终点构造通过 A、B 的摆线段，满足最速降线特性（现有实现方案保持）。 - 抛物线（parabolic）：使用合理弓高/参数构造，并用数值积分离散为点集。 ### 5.3 物理模型与时间计算 - 常量：g = 9.8 m/s²；像素转米：pixelsPerMeter = 50（可配置）。 - 直线：解析法，沿斜面加速度 a = g·sin(θ)，距离 s，时间 t = sqrt(2s/a)。 - 圆弧：以弧长与局部速度近似/数值积分；当前实现含修正因子（后续以更严格能量+切向分解改进）。 - 摆线与抛物线：采用分段积分（ds / v），v 由能量守恒 v = sqrt(2g·Δh) 得出；采样点从绘制时同步复用。 - 计算输出：每条轨道返回 time（秒）与 distance（像素/同时换算米用于展示）。 ### 5.4 结果展示 - 结果表格： - 列：轨道类型、距离（m/像素）、时间（s）、相对速度/相对用时（可选）。 - 最短时间高亮（⚡）。 - 速度/加速度图（若开启）：曲线图展示 v(t)/a(t) 的近似形态。 ### 5.5 交互与校验 - “更新轨道”按钮：集中提交坐标/轨道类型变更后重绘与重算。 - 校验规则（validatePhysics）： - B.y > A.y，否则提示“终点 B 必须低于起点 A”。 - |Bx − Ax| < 阈值时提示“水平距离太小”。 - 坡度过陡（(By − Ay) / |Bx − Ax| > 阈值）时提示精度风险。 ## 6. 数据结构与接口 ### 6.1 TrackData（绘制函数返回） - 通用字段： - type: 'straight' | 'circular' | 'cycloid' | 'parabolic' - distance: number（像素） - points?: {x:number, y:number}[]（采样点，用于积分/绘图） - 圆弧附加： - radius: number（像素） - center: {x:number, y:number} ### 6.2 组件/函数接口 - draw\*Track(ctx, pointA, pointB, color) → TrackData - calculateTrackTime(trackData, pointA, pointB) → number | null - onResultsChange(results: {trackId, distance, time}[]): 由 TrackCanvas 回传给上层。 ## 7. 非功能需求 - 性能：在常规分辨率与 3 种轨道开启情况下，更新操作在 100ms–500ms 内完成（浏览器中）。 - 可靠性：错误输入有提示，不导致崩溃；超出画布范围时仍能给出合理反馈。 - 可维护性：核心算法与 UI 解耦（utils/_ 与 components/_）。 - 可移植性：demo.html 可单文件直接运行；React 版通过 Vite 启动。 ## 8. 质量保证与验收标准（示例） - 圆弧轨道通过断言： - |dist(A, C) − dist(B, C)| < 1e−6 像素。 - C.y = A.y（误差 < 1 像素）；A 点处切线垂直（绘制时角度检查）。 - 在默认 A(0,10)、B(10,0) 的演示中，摆线时间应最短（允许数值误差）。 - 物理校验触发时显示提示，且不阻止其他轨道的绘制（除非逻辑上不成立）。 ## 9. 项目结构（参考） - demo.html — 独立演示版（含 UI、绘制、计算与结果对比）。 - src/ — React 版本： - components/TrackCanvas.jsx — 绘制与结果生成 - components/ControlPanel.jsx — 参数输入与轨道选择 - components/ResultsTable.jsx — 结果表格 - utils/trackDrawing.js — 轨道算法 - utils/physicsCalculations.js — 时间计算与校验 ## 10. 后续路线（Backlog） - 圆弧时间计算采用更严谨的切向速度积分（替换“修正因子”）。 - 速度/加速度曲线的数值积分与采样一致性优化。 - 轨道方向箭头、动画演示、关键点标注。