跳转至

P3.U-autotune-phase1-measure · ADR-11 fork 1 · Phase 1 测量 UI(mock 并行)

Worker:ClaudeC(用户分配)· 部门:前端 (frontend_vue3) 预计:1.5d · 优先级:P1 · 状态:dispatched 隔离:文件隔离(stages/xitune/modes/auto/ 子目录 + components/ 全新 · 不动 stage shell)

🔍 触发与解锁链

  • 触发:ADR-AIOS-11 accepted(2026-05-29 13:46)· 用户拍板 mock 并行模式启动下一阶段(2026-05-29 17:25)
  • 前置就位:useAutoTuningState 4-Phase 状态机骨架(c039075)+ K-shared-meter-dock 6 stub vue(ea5e9e4)
  • 本任务 zombie 后解锁:fork ⅔/4(Phase 2-4 串行)
  • mock 并行说明:fork 5(P5 后端)+ fork 6(P7 sidecar)dispatched 中 · 本任务用 mock 接口先做 UI · 联调时切真接口

任务定义(基于 ADR-AIOS-11 §1.3.1 Phase 1 + §4.1)

按 ADR-11 §1.3.1 Phase 1 测量流程,落地 AutoModePanel.vue 的 Phase 1 子面板:① 目标曲线选择器(平直/Harman 2017/B&K 1974)② 测量节点选择(sink-pre/physical-input)③ log sweep 触发(3-10s 可调 · 默认 5s)④ 多点平均(1-7 点 · 默认 3)⑤ ⅓ oct 平滑 ⑥ FreqResponseChart 实时显示(K-shared-meter-dock read-only 引用)。严守 ADR-07 §1.3.4 三层分工铁律:零数学(FFT/平均/平滑全交 mock P5/P7 端点)。

完整 prompt(直接复制粘贴 worker 终端)

[U-thread] P3.U-autotune-phase1-measure
[部门] 前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies] P3.K-modes-auto(写 · stages/xitune/modes/auto/*)· P0.K-shared-meter-dock(read · K-stub 6 vue 复用)
[隔离] 文件隔离 · 仅写 frontend_vue3/src/stages/xitune/modes/auto/* 子目录(MeasurePanel.vue + components/* + targetCurves.json + composables/*)
       严禁动 stages/xitune/XiTuneStage.vue / drawers / bottom-dock / 其他 modes(reverse / compat / manual)
       严禁动 K-shared-meter-dock 源文件(只 read · 不改 stub)
[优先级] P1 · 1.5d · ADR-11 fork 1 · 解锁 fork 2/3/4 串行
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md(必读 §1.3.1 Phase 1 + §1.3.3 目标曲线 + §1.3.4 节点选择 + §2.2 边界铁律 + §4.1 fork 1 + §5.2 验收)
[业务行为契约引用] ADR-11 §1.3.1 Phase 1 ①~⑤ 6 步流程 · §2.2 三层分工铁律(前端零数学)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-07-p3p4-business-boundary.md(§1.3.4 三层分工铁律 · §2.2.2 Harman 4-Phase 框架)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xitune/modes/auto/useAutoTuningState.ts(状态机骨架 · c039075 · 必读)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xitune/modes/auto/AutoModePanel.vue(占位面板 · 本任务 Phase 1 部分重构)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/test-aux/meter/(K-shared-meter-dock 6 stub vue · ea5e9e4 · FreqResponseChart + MeterNodeSelector read-only 引用)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P3.U-tune-modes-impl--c039075.md(同部门同进程标本 · 仿写格式)

【背景】
ADR-11 已 accepted(2026-05-29 13:46)· P5 fork 5(/api/auto_tune/iterate + /analyze)+ P7 fork 6(targetCurves + 多点平均 + 1/3 oct 平滑算子)dispatched 中 · 用户拍板 mock 并行模式 start fork 1。本任务实施 Phase 1 测量 UI:用户在 AutoModePanel 选目标曲线 + 测量节点 + 扫频参数 → 点击"开始测量"→ 触发 log sweep + 多点平均 + 1/3 oct 平滑 → FreqResponseChart 实时显示当前响应。**前端零数学**:扫频/FFT/平均/平滑全交 P5 → P7 · 本任务用 mock 接口先做 UI 骨架,fork 5/6 zombie 后切真接口。

【执行步骤】

Step 1 · read 已有基础(只读)
- read stages/xitune/modes/auto/useAutoTuningState.ts(idle→measuring→analyzing→optimizing→done/error 状态机)
- read stages/xitune/modes/auto/AutoModePanel.vue(占位面板 · 找到 measuring phase slot)
- read test-aux/meter/FreqResponseChart.vue + MeterNodeSelector.vue(read-only 引用 · 不改)
- read ADR-11 §1.3.1 + §1.3.3 + §1.3.4(锁定 6 步流程 + 3 条曲线 + 节点选择)

Step 2 · 新建 stages/xitune/modes/auto/targetCurves.json
- 内置 3 条曲线(JSON 资源):
  - "flat" · 平直 · 全频段 0dB(31 频段 · 20Hz-20kHz · 1/3 oct 中心频率)
  - "harman-2017" · Harman 2017 · 低频 +6dB · 中频平直 · 高频 -1dB/oct 滚降
  - "bk-1974" · B&K 1974 · 偏明亮 · 低频 +4dB · 中频 0dB · 高频 +2dB
- schema:`{ id, name, description, source, points: [{ freq_hz, gain_db }] }`
- ⚠️ 真实曲线数据可暂用近似值(等 fork 6 P7 zombie 后从 P7 资源拉取覆盖)· **mock 期 placeholder OK**

Step 3 · 新建 stages/xitune/modes/auto/composables/useMeasurement.ts(mock 模式)
- export function useMeasurement() · 封装 Phase 1 测量调度
- 接口契约(等 fork 5 zombie 后切真):
  - `startMeasurement(opts: { targetCurveId, measureNode, sweepDurationSec, averagePoints })`
  - `stopMeasurement()`
  - `currentResponse: Ref<{ freq_hz, level_db }[]>`(频响曲线)· 30fps 节流
  - `progress: Ref<{ phase, currentPoint, totalPoints, elapsedMs }>`
- mock 实现:setInterval 模拟 5s 扫频 + 多点平均 · 输出伪造频响数据(基于 targetCurve 加 ±3dB 随机抖动)
- ⚠️ 留 TODO 标记:`// TODO(fork-5-zombie): 切换为 fetch('/api/auto_tune/measure') + WS /dev-api/meter/stream`

Step 4 · 新建 stages/xitune/modes/auto/components/TargetCurveSelector.vue
- 下拉/卡片选择器 · 列出 3 条 targetCurves
- 预览迷你图(可用 svg 简易折线 · 不调 K-stub · 减少耦合)
- v-model 双向绑定 selectedCurveId

Step 5 · 新建 stages/xitune/modes/auto/components/MeasurementSettings.vue
- 节点选择(MeterNodeSelector read-only 引用 · K-stub)· 默认 'physical-input'
- 扫频时长滑块(3-10s · 默认 5)
- 平均点数选择(1/3/5/7 · 默认 3)
- emit `update:settings` 给父组件

Step 6 · 新建 stages/xitune/modes/auto/components/MeasurePanel.vue(Phase 1 主面板)
- 引入 TargetCurveSelector + MeasurementSettings + useMeasurement
- 引入 FreqResponseChart(K-stub read-only)· 显示 currentResponse + targetCurve overlay
- "开始测量"按钮 · 调 startMeasurement · useAutoTuningState 切 measuring
- 进度条 · 显示 progress.currentPoint / totalPoints
- 测量完成后 emit `phase1-done` payload `{ targetCurve, measuredResponse }` · 父级触发 useAutoTuningState 切 analyzing

Step 7 · 集成 AutoModePanel.vue(改 measuring 阶段 slot)
- 在 measuring phase slot 渲染 MeasurePanel
- 严禁动 idle/analyzing/optimizing/done/error 其他 slot(留 fork 2-4)
- 严禁动 useAutoTuningState 状态机本身(本任务只调 setMeasuring/setAnalyzing 接口)

Step 8 · 单元测试
- targetCurves.json schema 校验测试(3 条曲线 · 31 点结构正确)· 3+ 用例
- useMeasurement.test.ts(mock 模式启动 / 停止 / progress 推进 / currentResponse 更新)· 6+ 用例
- TargetCurveSelector.test.ts(渲染 3 条 · v-model 切换)· 3+ 用例
- MeasurementSettings.test.ts(节点切换 · 滑块联动 · emit settings)· 4+ 用例
- MeasurePanel.test.ts(集成 · 点击开始 → useMeasurement 触发 · phase1-done emit)· 5+ 用例
- test:unit 基线 356/3 → 目标 ≥ 377(+21 用例)

Step 9 · 验收
- npm run typecheck → ✓ exit 0
- npm run build → ✓ 零错误
- npm run test:unit → ≥ 377/3
- 浏览器手动测试:/xitune?mode=auto → 选 Harman 2017 + physical-input + 5s + 3 点 → 点击开始 → 进度推进 → FreqResponseChart 显示 mock 频响 + targetCurve overlay → 测量完成切 analyzing 状态

【验收】

- typecheck/build 全绿 · test:unit ≥ 377/3
- targetCurves.json + useMeasurement + 4 vue 组件 + AutoModePanel measuring slot 集成全部就位
- mock 模式可独立跑通 Phase 1 全流程(无后端依赖)
- TODO(fork-5-zombie) 标记齐全 · 联调切真接口路径清晰
- 不动 stage shell / drawers / bottom-dock / 其他 modes / useAutoTuningState 状态机本体 / K-stub 源文件

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段强制要求)
- e2e 真值:浏览器打开 /xitune?mode=auto → AutoModePanel measuring slot 显示 MeasurePanel → 选 Harman 2017 曲线 + physical-input 节点 + 5s 扫频 + 3 点平均 → 点击"开始测量"→ progress 0→100% 推进 5s → FreqResponseChart 实时刷新(30fps)显示 mock 频响 + Harman targetCurve overlay → 测量完成自动 emit phase1-done → useAutoTuningState 切 analyzing
- 自查清单(5 项必须全过):
  - [ ] 3 条 targetCurves JSON schema 校验通过 · TargetCurveSelector 全部可选
  - [ ] MeasurementSettings 节点/扫频/点数 3 参数 v-model 联动正常
  - [ ] useMeasurement mock 模式 start/stop/progress 正确 · currentResponse 30fps 节流不丢帧
  - [ ] MeasurePanel 集成 FreqResponseChart(K-stub read-only · 不改 K-stub 源文件)
  - [ ] AutoModePanel measuring slot 切换正常 · phase1-done emit 触发状态机切 analyzing
- 失败回退 5 类:
  - ① mock setInterval 内存泄漏(组件 unmount 必须 clearInterval)
  - ② targetCurves.json 加载失败(网络/路径错)→ 降级 fallback flat + 提示
  - ③ K-stub FreqResponseChart 接口变化(read-only 但保护性 try/catch)
  - ④ useAutoTuningState 状态机切换失败(竞态)→ 测量中禁用"开始"按钮
  - ⑤ MeterNodeSelector 节点列表为空 → 默认 physical-input + 提示"K-stub 未就绪"

【commit】
- subject:`feat(P3.U-autotune-phase1-measure/modes-auto): Phase 1 测量 UI · TargetCurve + Settings + MeasurePanel · ADR-11 fork 1 · mock 并行`
- trailer:`[step=9/9] [pid=P3] [uid=U-autotune-phase1-measure] [occupies=P3.K-modes-auto+P0.K-shared-meter-dock(read)] [files=stages/xitune/modes/auto/*+components/*+composables/*+targetCurves.json+tests/*]`

【禁止】
1. ❌ 不动 stages/xitune/XiTuneStage.vue / drawers / bottom-dock / 其他 modes(reverse/compat/manual)
2. ❌ 不改 useAutoTuningState 状态机本体(只调 setMeasuring/setAnalyzing 接口)
3. ❌ 不改 K-shared-meter-dock 源文件(只 read · 不动 stub)
4. ❌ 不实施 Phase 2/3/4(留 fork 2/3/4 串行)
5. ❌ 不在前端做 FFT / 平均 / 平滑(三层分工铁律 · ADR-07 §1.3.4 · 数学全交 P5 → P7)
6. ❌ 不实施自定义曲线导入(决策 2a · 留远景 §11.6)
7. ❌ 不验"typecheck 全绿就 commit"——必须浏览器手动测试 mock 跑通 Phase 1 全流程

解锁链(本任务 zombie 后)

  • ✅ fork 2 P3.U-autotune-phase2-analyze(Phase 2 分析 UI · 1.0d · 串行依赖本任务)
  • ✅ fork 3 P3.U-autotune-phase3-optimize(Phase 3 优化 UI · 1.5d · 串行依赖 fork 2)
  • ✅ fork 4 P3.U-autotune-phase4-apply(Phase 4 应用 UI · 1.0d · 串行依赖 fork 3)
  • ⚠️ 联调依赖:fork 5(P5 后端)+ fork 6(P7 sidecar)zombie 后切真接口(本任务期间 mock)

风险评估

风险 缓解
⚠️ mock 接口与 fork ⅚ 真接口偏差 接口契约写死在 useMeasurement.ts 注释 + ADR-11 §1.3.1 引用 · 联调时 diff 出来即修
⚠️ FreqResponseChart K-stub 接口变化 本任务 read-only 引用 · 加保护性 try/catch · 失败回退 5 类 ③
⚠️ useAutoTuningState 状态机竞态 测量中禁用"开始"按钮 · 失败回退 5 类 ④
⚠️ targetCurves.json 真实数据等 fork 6 mock 期用近似值 + TODO 标记 · 联调时从 P7 拉取覆盖

历史

时间 事件 hash
2026-05-29 17:25 dispatched · ADR-11 fork 1 · 用户拍板方案 A mock 并行 · 与 fork ⅚ 完全并行 (待 stop 时回填)