# 等底等高的圆柱与圆锥体积关系（V锥=⅓V柱）｜开发文档

## 1. 目标概述
本页面服务知识点“等底等高的圆柱与圆锥体积关系（V锥=⅓V柱）”，所属单元“圆柱与圆锥”，目标是把教学方案中的关键动作数字化：虚拟实验型：用户控制倒沙动画，每倒一次计数。可切换等底等高/不等底等高模式对比。不等时系统提示⅓不再成立。

## 2. 建议技术形态
- 前端单页交互页面
- Canvas / SVG / DOM 动画混合实现
- 以浏览器本地状态为主，不依赖复杂后端

## 3. 页面状态结构
建议至少包含：
- `sceneState`：主场景当前状态
- `controlState`：当前控件值
- `resultState`：是否完成、是否正确、当前提示
- `highlightState`：当前高亮对象、说明文本
- `historyState`：是否需要记录操作步骤与次数

## 4. 核心事件流 / 状态机
1. 页面初始化 -> 加载默认场景。
2. 用户操作控件 -> 更新场景状态。
3. 引擎重绘或刷新主可视区域。
4. 判定逻辑执行 -> 输出反馈。
5. 用户可继续调整 / 重置 / 进入下一次尝试。

## 5. 关键组件拆分
- `KnowledgeHeader`
- `VisualizationStage`
- `ControlPanel`
- `FeedbackPanel`
- `SummaryPanel`
- 如为实验/动画场景，可补 `TimelineController` 或 `StepController`

## 6. 数据结构建议
```ts
interface PageModel {
  seq: string;
  unit: string;
  topic: string;
  name: string;
  interactionType: string;
  priority: string;
}

interface InteractionState {
  step: number;
  params: Record<string, number | string | boolean>;
  selection?: string[];
  isCorrect?: boolean;
  feedbackText?: string;
}
```

## 7. 埋点 / 日志建议
- 页面进入
- 首次操作
- 参数调整次数 / 拖拽次数
- 提交判定次数
- 首次答对耗时
- 常见错误类型

## 8. 风险点与实现注意事项
- 风险一：只做动画播放会削弱交互价值，必须保留用户操作入口。
- 风险二：视觉表达过复杂会影响课堂使用效率，需要控制信息密度。
- 风险三：判定逻辑不能只判断最终值，必要时要关注关键步骤。
- 风险四：小学生场景下，拖拽、点击热区要足够大，反馈要直接。

## 9. 与教学内容的对应
- 现有讲解方法：①倒沙子/水实验：等底等高圆锥往圆柱倒3次正好装满；②单独演示不等底等高时⅓不成立的反例。
- 可吸收的教学设计：先猜需要倒几次，再做实验验证。特别强调必须等底等高——单独演示不等底等高的反例，打破误解。
- 建议交互落点：虚拟实验型：用户控制倒沙动画，每倒一次计数。可切换等底等高/不等底等高模式对比。不等时系统提示⅓不再成立。

## 10. 开发建议
- 先做单知识点闭环版本，再考虑模板化复用。
- 优先保证“主过程可见 + 操作可重复 + 反馈清楚”。
- 代码结构尽量抽象出可复用的动画层、控制层、反馈层，便于后续同类知识点复用。