跳转至

P3.U-autotune-phase1-measure-v2 · ADR-11 v1.2 fork 1 · Phase 1 测量 UI(车载多通道真接口版)

Worker:ClaudeC(用户分配)· 部门:前端 (frontend_vue3) 预计:3.5d · 优先级:P1 · 状态:ready(等 fork 1b zombie 后切真接口) 隔离:stages/xitune/modes/auto/* 子目录全新重写

🔍 触发与解锁链

  • 触发:旧 fork 1(714ace2)产出不合格(aborted-pending)· 用户反馈"DAW 苹果风格 / 30+ 通道 / 4 测试模式 / 后端落盘 / 真接口"+ 拍板 5 决策点(2026-05-29 19:00)
  • 前置就位:useAutoTuningState 状态机(c039075)+ K-shared-meter-dock(ea5e9e4)+ ADR-11 v1.2 §1.3.1+§1.3.4 锁定
  • 本任务 zombie 后解锁:fork ⅔/4(Phase 2-4 串行)
  • 依赖:fork 1b P5.U-autotune-channel-measure(后端 3 端点 vehicle_config + measure_channel + measure_position · 1.5d)

任务定义(基于 ADR-AIOS-11 v1.2 §1.3.1 + §1.3.4)

按 ADR-11 v1.2 §1.3.1 Phase 1 v2 7 步流程,落地 AutoModePanel.vue 重构(DAW 苹果风格 4 Tab 单主窗口)+ 4 测试模式分支 UI:① 车辆配置 Tab(通道数/扬声器位置/截止频率 + P5 后端持久化)② 算法链路 Tab(显示 LeftDock 已实现链路 + 通道映射校验)③ 测量 Tab(4 模式分支:离线导入/手动逐通道/xilink 自动逐路/整体收音 · 每模式 UI 不同 · 主界面频响/相位曲线)④ 计算结果 Tab(ChannelMatrix 可视化)。严守三层分工铁律(前端零数学 · 全交 fork 1b 后端 + P7 算子)。

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

[U-thread] P3.U-autotune-phase1-measure-v2
[部门] 前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies] P3.K-modes-auto(写 · stages/xitune/modes/auto/*)· P0.K-shared-meter-dock(read · K-stub 6 vue 复用)· P5.K-api-routes(read · 等 fork 1b 3 端点)
[隔离] 文件隔离 · 仅写 frontend_vue3/src/stages/xitune/modes/auto/* 子目录
       严禁动 stages/xitune/XiTuneStage.vue / drawers / bottom-dock / 其他 modes(reverse / compat / manual)
       严禁动 K-shared-meter-dock 源文件(只 read · 不改 stub)
       严禁动 useAutoTuningState 状态机本体(只调 setMeasuring/setAnalyzing 接口)
[优先级] P1 · 3.5d · ADR-11 v1.2 fork 1 · 解锁 fork 2/3/4 串行
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md(必读 §1.3.1 v1.2 修订 + §1.3.4 DAW 苹果 UI + §2.2 边界铁律 + §4.1 fork 1)
[业务行为契约引用] ADR-11 v1.2 §1.3.1 Step A-E 7 步 · §1.3.4 4 Tab 单主窗口 · §2.2 三层分工铁律(前端零数学)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md(v1.2)
  - 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 三层分工)
  - 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(全新重写)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/test-aux/meter/(K-shared-meter-dock · ea5e9e4 · FreqResponseChart + PhaseChart + MeterNodeSelector read-only)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P0.U-right-inspector-framework--77b7a50.md(同部门标本 · 多段容器规模)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P3.U-autotune-phase1-measure--714ace2.aborted-pending.md(旧 v1 反例 · 看哪些设计被废弃)

【背景】
ADR-11 v1.1 Phase 1 设计为"单通道 PC 测量假设"· 用户反馈完全不符合车载 30+ 通道真实场景 · 旧 prompt(`714ace2`)mock 单节点产出 aborted-pending。v1.2 修订后:① 7 步流程含车配/链路/测量/结果 4 Tab ② 4 测试模式分支(离线/手动/自动/整体)③ 后端落盘(P5 持久化车配)④ DAW 苹果单主窗口 ⑤ 必须真接口(依赖 fork 1b 3 端点)。本任务严守 ADR-07 §1.3.4 三层分工(前端零数学)。

【执行步骤】

Step 1 · read 已有基础(只读)
- read stages/xitune/modes/auto/useAutoTuningState.ts(状态机 idle→measuring→analyzing→...)
- read stages/xitune/modes/auto/AutoModePanel.vue 旧版(评估保留与重写边界)
- read test-aux/meter/(FreqResponseChart / PhaseChart / MeterNodeSelector · read-only 引用)
- read ADR-11 v1.2 §1.3.1 + §1.3.4(锁 7 步 + 4 Tab + 4 模式)
- read 旧 prompt aborted-pending(看哪些被废弃 · 不再用 mock 单通道)

Step 2 · 新建 stages/xitune/modes/auto/types.ts(车载多通道 schema)
- export interface VehicleConfig { channelCount: number; channels: ChannelConfig[]; }
- export interface ChannelConfig { id: number; label: string; position3D: { x, y, z, angle }; cutoffRange: { lowHz, highHz }; cutoffCurve?: number[]; }
- export interface ChannelMatrix { byChannel: Map<channelId, MeasureResult[]>; byPosition: Map<positionId, MeasureResult[]>; }
- export type MeasureMode = 'offline' | 'manual' | 'auto-xilink' | 'full-cabin'

Step 3 · 新建 stages/xitune/modes/auto/composables/useVehicleConfig.ts(Step A 车配)
- v-model 车配 store(channelCount 1-32 · channels[] 动态)
- saveVehicleConfig() → POST P5 `/api/auto_tune/vehicle_config`(决策 1B 后端落盘)
- loadVehicleConfig(projectId) → GET 同端点
- importPresetVehicle(presetId) → 内置车型预设(.csv 导入扬声器布局)
- ⚠️ 等 fork 1b zombie 切真 · 期间用 mock fetch 占位 + TODO 标记

Step 4 · 新建 stages/xitune/modes/auto/composables/useChannelMeasurement.ts(Step C+D 测量)
- 4 模式调度:
  - offline:导入 .csv/.frd 列表 → 解析 → 写入 ChannelMatrix
  - manual:用户选 channelId → 调 P5 `/api/auto_tune/measure_channel`(决策 5A 真接口 · 等 fork 1b)
  - auto-xilink:e2e 脚本 mute/unmute → 自动遍历 channelId → 调 measure_channel
  - full-cabin:同时发声 → 调 P5 `/api/auto_tune/measure_position`(位置声学合成)
- progress: Ref<{ mode, currentChannel, total, elapsedMs }>· 30fps 节流
- ⚠️ 真接口未就位前用 mock setInterval 占位 + TODO(fork-1b-zombie) 标记

Step 5 · 新建 stages/xitune/modes/auto/components/VehicleConfigTab.vue(Step A UI)
- ChannelCountInput(1-32)· 添加/删除通道
- 通道表格:id / label / position3D 编辑器 / cutoff 范围编辑 + 曲线导入按钮
- "保存到工程文件"按钮 → useVehicleConfig.saveVehicleConfig()
- 导入预设车型下拉(占位 · 后续填实)

Step 6 · 新建 stages/xitune/modes/auto/components/PipelineTab.vue(Step B UI · 仅显示)
- 显示 LeftDock 当前算法链路(read-only · 沿用同手动调音 ADR-07 §1.3.4)
- 通道映射校验:VehicleConfig.channels.length vs 链路输出通道数 · 不一致警告
- 不实施编辑(链路在 LeftDock 已实现)

Step 7 · 新建 stages/xitune/modes/auto/components/MeasurementTab.vue(Step C+D UI · 4 模式分支)
- ModeSelector(4 选 1)· 选模式后渲染对应子面板
- 子面板独立组件:
  - components/measurement-modes/OfflineImportPanel.vue(顺序导入列表 + 文件选择 + 解析进度)
  - components/measurement-modes/ManualPerChannelPanel.vue(通道选择器 + "开始测量" + 主界面 FreqResponseChart + PhaseChart)
  - components/measurement-modes/AutoPerChannelPanel.vue(进度条 + 当前通道 + e2e 脚本日志)
  - components/measurement-modes/FullCabinSweepPanel.vue(单次扫频按钮 + mic 阵列状态)
- 主界面区(中央)· 显示频响 + 相位曲线为主(K-stub FreqResponseChart + PhaseChart)
- **不堆叠多窗口**(决策 4 严守)

Step 8 · 新建 stages/xitune/modes/auto/components/ResultTab.vue(Step E UI)
- ChannelMatrix 可视化(矩阵 / 列表 / 通道筛选)
- "进入 Phase 2"按钮 · 触发 useAutoTuningState.setAnalyzing()
- 离线模式:"保存 .xichannelmatrix"按钮(供联机分析)

Step 9 · 重写 stages/xitune/modes/auto/AutoModePanel.vue(主入口 · DAW 苹果风格)
- Tab Bar(顶部 4 Tab · 苹果风格 · 类似 macOS Settings)
- Tab 切换显示对应组件(VehicleConfigTab / PipelineTab / MeasurementTab / ResultTab)
- 顶部状态条:当前 Phase / 通道数 / 模式
- ⚠️ 严禁动状态机本体(只调接口 setMeasuring/setAnalyzing)

Step 10 · 单元测试
- types.ts schema 校验(VehicleConfig + ChannelConfig + ChannelMatrix)· 4+ 用例
- useVehicleConfig.test.ts(save/load/import + mock fetch)· 6+ 用例
- useChannelMeasurement.test.ts(4 模式 mock + progress + ChannelMatrix 写入)· 8+ 用例
- VehicleConfigTab.test.ts(添加/删除通道 + 保存)· 4+ 用例
- MeasurementTab.test.ts(4 模式切换 + 子面板渲染)· 4+ 用例
- ResultTab.test.ts(矩阵显示 + Phase 2 跳转)· 3+ 用例
- AutoModePanel.test.ts(4 Tab 切换 + 状态条)· 4+ 用例
- test:unit 基线 356/3 → 目标 ≥ 389(+33 用例)

Step 11 · 验收
- npm run typecheck → ✓ exit 0
- npm run build → ✓ 零错误
- npm run test:unit → ≥ 389/3
- 浏览器手动测试:/xitune?mode=auto → 4 Tab 全可切换 → 车配可保存 → 测量 4 模式可选可跑(mock)→ 结果 Tab 可显示 ChannelMatrix → 切 Phase 2

【验收】

- typecheck/build 全绿 · test:unit ≥ 389/3
- 4 Tab(VehicleConfig / Pipeline / Measurement / Result)+ 4 测量模式子面板全部就位
- DAW 苹果风格单主窗口 · 不堆叠多窗口
- 30+ 通道矩阵数据结构完整 · 通道数自由配置
- 真接口 TODO 标记齐全(fork 1b zombie 后切真)
- 不动 stage shell / drawers / bottom-dock / 其他 modes / useAutoTuningState 本体 / K-stub 源文件

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段)
- e2e 真值:浏览器打开 /xitune?mode=auto → AutoModePanel 显示 4 Tab → Tab 1 添加 16 通道 + 编辑位置/截止频率 → 保存(mock POST 成功)→ Tab 2 显示当前链路 + 通道映射 OK → Tab 3 选"手动逐通道"→ 选通道 1 → 点击"开始测量"→ 主界面 FreqResponseChart 显示 mock 频响 + PhaseChart 显示相位 → 测完保存 → Tab 4 ChannelMatrix 显示通道 1 测量结果 → 点击"进入 Phase 2"切状态机
- 自查清单(5 项必须全过):
  - [ ] 4 Tab 全部渲染 · 切换流畅(<100ms)
  - [ ] VehicleConfig 通道数 1-32 自由调 · 保存到 mock 后端成功
  - [ ] 4 测量模式 UI 各不相同 · 子面板独立渲染
  - [ ] 主界面频响/相位曲线为主(不堆叠多窗口)
  - [ ] ChannelMatrix 数据结构正确 · 支持按通道/按位置查询
- 失败回退 5 类:
  - ① 后端不可达(fork 1b 未 zombie)→ mock + 提示 "等 fork 1b 真接口"
  - ② VehicleConfig 通道数超 32 → 限制 + 提示
  - ③ 离线导入文件格式错 → 解析失败 + 友好错误
  - ④ 4 模式切换时上一模式未完成 → 提示确认中断
  - ⑤ ChannelMatrix 大量数据(30+ 通道 * 多组)渲染卡顿 → 虚拟滚动 + 分页

【commit】
- subject:`feat(P3.U-autotune-phase1-measure-v2/modes-auto): Phase 1 v2 4 Tab + 4 模式 + 30+ 通道矩阵 · ADR-11 v1.2 fork 1`
- trailer:`[step=11/11] [pid=P3] [uid=U-autotune-phase1-measure-v2] [occupies=P3.K-modes-auto+P0.K-shared-meter-dock(read)+P5.K-api-routes(read)] [files=stages/xitune/modes/auto/*+components/*+composables/*+types.ts+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. ❌ 不堆叠多窗口(决策 4 · 严守 DAW 苹果单主窗口 + 4 Tab 切换)
7. ❌ 不验"typecheck 全绿就 commit"——必须浏览器手动测试 4 Tab + 4 模式全跑通

解锁链(本任务 zombie 后)

  • ✅ fork 2 P3.U-autotune-phase2-analyze(Phase 2 分析 1.0d 串行)
  • ✅ fork 3 P3.U-autotune-phase3-optimize(Phase 3 优化 1.5d 串行)
  • ✅ fork 4 P3.U-autotune-phase4-apply(Phase 4 应用 1.0d 串行)
  • ⚠️ 联调依赖:fork 1b P5.U-autotune-channel-measure zombie 后切真接口

风险评估

风险 缓解
⚠️ fork 1b 未 zombie · 真接口缺失 mock 模式跑通 UI 骨架 · TODO(fork-1b-zombie) 标记 · 联调切换路径清晰
⚠️ 30+ 通道渲染卡顿 ChannelMatrix 虚拟滚动 + 分页 · 失败回退 5 类 ⑤
⚠️ 4 模式 UI 复杂度爆炸 子面板独立 .vue 文件 · 单文件 ≤ 300 行 · 共用 composable 调度
⚠️ DAW 苹果风格主观 参考 macOS Settings + Logic Pro · 不堆叠 · Tab + 中央主界面 + 侧栏(已 LeftDock)
⚠️ 状态机改动风险 严禁改 useAutoTuningState 本体 · 只调接口

历史

时间 事件 hash
2026-05-29 19:05 ready · ADR-11 v1.2 fork 1 v2 起草 · 用户拍板 5 决策点 · 替代旧 fork 1(714ace2 aborted-pending) (待 stop 时回填)