docs(huoshan): 同步 Crank/Slider 控制器文档至 04/06/实现指南

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-13 16:58:40 +08:00
parent 880da10797
commit 83f3fb68dc
4 changed files with 55 additions and 4 deletions
@@ -10,7 +10,7 @@

 | 类型 | 变更 |
 |------|------|
-| 文档 | （待补充） |
+| 文档 | 销售系统控制器（CrankController、SliderController）实现细节同步至 04_implementation、06_sales_deep、实现指南 |
 | 功能 | （待补充） |

 ---
@@ -79,3 +79,48 @@

 `Assets/Scripts/MiniGame/HuoShan/Waveform/`  
 详见 `README_WaveformSetup.md`。
+
+---
+
+## 销售系统控制器（实现版）
+
+位于 `Assets/Scripts/MiniGame/HuoShan/SalesSystem/`。
+
+### CrankController（发条控制器）
+
+**功能**：拖拽旋转、最大 260°、缓慢回位、触发事件。支持沿环轨道移动或原地旋转。
+
+| 配置项 | 类型 | 默认 | 说明 |
+|--------|------|------|------|
+| maxRotationAngle | float | 260 | 最大旋转角度（度）|
+| returnDuration | float | 3 | 回位时长（秒），与滑片滑动时长匹配 |
+| triggerAngle | float | 240 | 触发事件的最小角度 |
+| autoReturn | bool | true | 是否自动返回初始位置 |
+| ringCenter | Transform | - | 环中心；不填则原地旋转 |
+| ringRadius | float | 0 | 环半径，0 则从初始位置自动计算 |
+
+**事件**：`onCrankComplete`（到顶松开）、`onCrankRotate(float)`（0–1 标准化）、`onCrankStartDrag`。
+
+**公共方法**：`ResetCrank()`、`RotateTo(angle, duration)`、`GetNormalizedRotation()`、`GetCurrentAngle()`、`ReturnDuration`。
+
+### SliderController（滑片控制器）
+
+**功能**：仅通过 Yarn/代码控制，不接受玩家直接交互。滑片沿圆环滑动，等离子体发光段从起始到当前位置，滑片位置驱动波形参数。
+
+| 配置项 | 类型 | 默认 | 说明 |
+|--------|------|------|------|
+| ringCenter | Transform | - | 圆环中心 |
+| outerRadius | float | 2 | 外环半径（滑片轨迹）|
+| innerRadius | float | 1.5 | 内环半径（等离子体弧线）|
+| slideAngleRange | float | 360 | 滑动弧度范围（度）|
+| segmentCount | int | 12 | 离散段数量，用于 `slide_to_segment` |
+| plasmaAffectsWaveform | bool | true | 等离子体发光是否影响波形参数 |
+
+**事件**：`onSliderPositionChanged(float)`（0–1 标准化）。
+
+**公共方法**：`SlideTo(angle, duration)`、`SlideToNormalized(pos, duration)`、`SlideToSegment(index, duration)`、`GetCurrentAngle()`、`GetNormalizedPosition()`、`ResetPosition()`、`GetCurrentSegment()`。
+
+### 联动关系
+
+- 发条 `returnDuration` 与滑片滑动时长建议一致（如 3 秒），实现「发条回位 ≈ 滑片到位」的节奏。
+- 滑片位置驱动 `WaveformRenderer.SetClarity()`、`SetClarityPosition()`。
@@ -209,6 +209,8 @@
 |------|-------------|
 | 波形屏幕 | `Assets/Scripts/MiniGame/HuoShan/Waveform/`（WaveformDetector、WaveformRenderer、WaveformYarnCommand）|
 | 销售系统 | `Assets/Scripts/MiniGame/HuoShan/SalesSystem/` |
+| 发条控件 | `CrankController.cs`：拖拽 260°、回位、沿环轨道/原地旋转、onCrankComplete |
+| 滑片控件 | `SliderController.cs`：Yarn 驱动滑动、等离子体弧线、波形联动（SetClarity/SetClarityPosition）|
 | 主管理器 | `SalesManager.cs`：打开/关闭 SaleView、相机注册 |
 | 美术 | `Assets/Resources/Art/Fix/Huoshan/SellSystem/`（步进模式.psb 等）|
 | 维修框架 | `FixStateMachine` 中销售系统视图的打开/关闭 |
@@ -219,7 +221,7 @@
 ## 待补充（开发中填写）

 - [ ] 波形屏幕：扫描模式↔步进模式的切换流程是否需显式 UI 区分
- [ ] 步进 UI 布局与操作方式（点击 / 滑动 / 键盘）
+- [x] 步进 UI 布局与操作方式：发条拖拽（CrankController）、滑片由 Yarn 驱动（SliderController）已实现
 - [ ] 转换器视觉与交互控件
 - [ ] 治疗记录面板的打开方式（按钮 / 自动弹出）
 - [ ] 调节失败的具体反馈形式
@@ -199,11 +199,15 @@
 | 类型 | 路径 | 说明 |
 |------|------|------|
 | 销售管理器 | `Assets/Scripts/MiniGame/HuoShan/SalesSystem/SalesManager.cs` | SaleView 显示/隐藏 |
+| 发条控制器 | `Assets/Scripts/MiniGame/HuoShan/SalesSystem/CrankController.cs` | 拖拽 260°、回位、触发 onCrankComplete；沿环轨道或原地旋转 |
+| 滑片控制器 | `Assets/Scripts/MiniGame/HuoShan/SalesSystem/SliderController.cs` | Yarn/代码驱动滑片、等离子体弧线、波形联动；无玩家直接交互 |
 | 波形检测器 | `Assets/Scripts/MiniGame/HuoShan/Waveform/WaveformDetector.cs` | 波形屏 |
-| 波形渲染 | `Assets/Scripts/MiniGame/HuoShan/Waveform/WaveformRenderer.cs` | 波形绘制 |
+| 波形渲染 | `Assets/Scripts/MiniGame/HuoShan/Waveform/WaveformRenderer.cs` | 波形绘制；滑片通过 SetClarity/SetClarityPosition 驱动 |
 | 维修状态机 | `Assets/Scripts/FixSystemNew/FixStateMachine.cs` | SalesState 进入/退出 |
 | 资源索引 | `Docs/HuoShan/core/05_resources.md` | 路径与资产映射 |

+*发条/滑片详细配置与 API 见 `04_implementation.md` 销售系统控制器。*
+
 ---

 ## 流程关系示意
@@ -248,5 +252,5 @@ flowchart TB
 ## 待确认 / 可后续补充

 - 治疗记录（步骤 8）与「信息面板显示表达模块拒绝」（步骤 9）是否同一面板不同内容
- 发条与滑片精确参数：260°、归位速度、滑片角速度等
+- ~~发条与滑片精确参数~~：已实现。发条 260°、returnDuration 可配（默认 3s）；滑片 slideAngleRange、segmentCount 可配；见 CrankController/SliderController
 - 异常段的弧度/角度定义