跳转至

P0.U-measurement-rms-fft-phase · ADR-12 Phase 2 #5 · RMS+FFT+Phase 真业务 + 端到端真值首落地

Worker:TBD(用户分配 · 建议 ClaudeA 主战场)· 部门:前端 (frontend_vue3) 预计:2.0d · 优先级:P1 · 状态:dispatched 隔离:文件隔离(widgets/{rms,fft,phase}/* + test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue 升级 · 与 #6/#7 正交)

🔍 触发与解锁链

  • 触发:2026-05-29 19:48 ADR-12 Phase 1 全栈闭环(a7df354)→ Phase 2 #5/#6/#7 解锁
  • 前置就位:
  • 前端容器层:DashboardCanvas + WidgetContainer + 4 套 Preset 切换(a7df354)
  • 前端 types:7 类 MeterFrame schema(9fc31c4)+ NodeFactory + LeftDock(6050959)+ Inspector 6 段(77b7a50)
  • 后端中转:7 toolKind 路由 + 30fps/tool/client 限流(48cf0ba)
  • sidecar 算:5 new endpoints + multi-channel(153a109)
  • 本任务 zombie 后解锁:Phase 3 #10 engine-session-snapshots · ADR-12 §3 业务契约首次 e2e 真值跑通
  • 用户期待:⭐ 首次端到端真值闭环(注入 1kHz 正弦 → RMSMeter 显示 -20±1dB · SpectrumChart 显示峰值 1000±50Hz · PhaseChart 0° 参考稳定)

任务定义(基于 ADR-AIOS-12 §3.1 + §3.2 + §3.4)

按 ADR-12 §3.1 RMS Meter Node + §3.2 FFT Analyzer Node + §3.4 Phase Meter Node 各 5 项契约,填实容器层(a7df354)中 RMS/FFT/Phase 三类 widget 的真实业务行为。仅升级现有 6 stub(test-aux/meter/RMSMeter.vue + SpectrumChart.vue + PhaseChart.vue · ea5e9e4)+ 新增 widgets/{rms,fft,phase}/ 业务壳 · 不动 #6 widgets/{transfer,waveform}/* 与 #7 widgets/{electrical,recorder}/。

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

[U-thread] P0.U-measurement-rms-fft-phase
[部门] 前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies] P0.K-shared-meter-dock(写) · P0.K-shared-types(read) · P4.K1-page-layout(read)
[隔离] 文件隔离 · 仅写:
       - frontend_vue3/src/stages/xitest/dashboard/widgets/{rms,fft,phase}/*(全新)
       - frontend_vue3/src/test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue(stub→真业务升级 · 仅这 3 个文件)
       - frontend_vue3/src/stores/xiTestWorkspaceStore.ts(只读引用 · #2 actions 已实施)
       - tests/* 新增
       严禁动 widgets/{transfer,waveform,electrical,recorder}/*(留 #6/#7)· 严禁动 stages/xitest/modes/*(P4.U3 ceecccf 实装)
[优先级] P1 · 2.0d · ADR-12 Phase 2 #5 · ⭐ 首次端到端真值闭环
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(必读 §3.1 + §3.2 + §3.4 + §2.11)
[业务行为契约引用] ADR-AIOS-12 §3.1 RMS Meter + §3.2 FFT Analyzer + §3.4 Phase Meter · 5 项契约 × 3 类(① 输入输出 schema · ② 收敛判据 · ③ 失败回退 5 类 · ④ 用户操作流 5 步 · ⑤ 端到端真值 e2e)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(主 ADR · §3.1/3.2/3.4 必读)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/types/measurement-node.ts(MeasurementNode 7 子能力 schema · 9fc31c4)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/types/meter-frame-rms.ts + meter-frame-fft.ts + meter-frame-phase.ts(7 类 MeterFrame · 9fc31c4 落地 · 字段单位 Hz/dBFS/° · noiseFloorDb / averagedCount)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xitest/dashboard/{DashboardCanvas,WidgetContainer,WorkspacePresetSwitcher}.vue(a7df354 · 容器层就位 · 本任务在 WidgetContainer 内挂 widget 业务)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue(ea5e9e4 · 6 stub 之 3 · 本任务升级为真业务)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stores/xiTestWorkspaceStore.ts(#2 actions 已实施 · 本任务 read-only 引用 measurementNodes/widgets/loadPreset)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/backend_csharp/Services/Meter/MeterTapService.cs(P5 48cf0ba · 7 toolKind 路由 · 本任务 WS 消费 toolKind=rms/fft/phase)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P0.U-widget-workspace-framework--a7df354.md(同 ADR · #2 标本 · 严格仿写 frontmatter + 8 段格式)

【背景】
ADR-12 Phase 1 容器层全闭环(`a7df354` 等 5 fork)· Phase 2 #5 是首个填实"widget 内部真实业务行为"的任务 · 注入信号(generator/loopback)→ 后端 MeterTapService 路由 toolKind=rms/fft/phase → sidecar pysidecar 算 fft/phase → WS 帧推回前端 → RMSMeter/SpectrumChart/PhaseChart 渲染 + Inspector 元信息 · 本任务 zombie 后用户首次看到"注入 1kHz 正弦 → 三 widget 真实跳数"端到端真值。

【执行步骤】

Step 1 · read 已有基础(只读 · 必做)
- read ADR-AIOS-12 §3.1 RMS Meter Node + §3.2 FFT Analyzer Node + §3.4 Phase Meter Node 5 项契约全文
- read types/{measurement-node, meter-frame-rms, meter-frame-fft, meter-frame-phase}.ts 字段定义 + 单位
- read stages/xitest/dashboard/{DashboardCanvas, WidgetContainer}.vue 容器接口(props.widget · slot 注入点)
- read test-aux/meter/{RMSMeter, SpectrumChart, PhaseChart}.vue 当前 stub(ea5e9e4)
- read stores/xiTestWorkspaceStore.ts 当前 actions(loadPreset/addWidget/removeWidget)

Step 2 · 升级 RMSMeter.vue(stub → 真业务)
- 订阅 WS 帧(toolKind=rms · 30fps)· 渲染 RMS dB + peak hold + averagedCount + noiseFloorDb
- 字段对齐 ADR §3.1 ① 输入输出契约(rmsDb / peakDbHold / decimateFactor / windowMs · 单位 dBFS/ms)
- 收敛判据 §3.1 ②:测量稳定 ≥ 25 帧后显示"稳定"标志 · RMS 抖动 < 0.5dB
- 失败回退 §3.1 ③:WS 断/通道断/后端崩溃/配置错/帧倒序 5 类 · UI 表现(灰底 + 错误标签)+ 自动重连

Step 3 · 升级 SpectrumChart.vue(stub → 真业务)
- 订阅 WS 帧(toolKind=fft · 30fps)· 渲染 fftBins[] + freqAxisHz[] + 峰值标记
- 字段对齐 ADR §3.2 ① 输入输出契约(fftSize / window / averaging / freqAxisHz · 单位 Hz/dBFS)
- 收敛判据 §3.2 ②:峰值频率定位精度 ± 50Hz @ 1kHz 单频 · averagedCount ≥ 16
- 失败回退 §3.2 ③ 5 类同上 · 配置错(fftSize 非 2^N)显式 toast

Step 4 · 升级 PhaseChart.vue(stub → 真业务)
- 订阅 WS 帧(toolKind=phase · 30fps)· 渲染 phaseDeg[] + freqAxisHz[] + 0° 参考线
- 字段对齐 ADR §3.4 ① 输入输出契约(refChannel / measureChannel / phaseDeg · 单位 °)
- 收敛判据 §3.4 ②:相干性 > 0.7 区间显示实线 · < 0.7 显示虚线 · 0° 参考稳定 ± 5°
- 失败回退 §3.4 ③ 5 类 · 单通道断时降级显示"参考通道丢失"

Step 5 · 新建 widgets/{rms,fft,phase}/*(business shell · 包装 stub 升级版)
- widgets/rms/RmsWidget.vue(WidgetContainer 内层 · 接 props: DashboardWidget · 内嵌升级版 RMSMeter + Inspector 元信息按钮)
- widgets/fft/FftWidget.vue(同上 · 内嵌 SpectrumChart)
- widgets/phase/PhaseWidget.vue(同上 · 内嵌 PhaseChart)
- 在 stages/xitest/dashboard/DashboardCanvas.vue widget 路由表注册 type='rms-meter'/'fft-analyzer'/'phase-meter' → 对应 Widget 组件(WidgetContainer 内 dynamic component)

Step 6 · 单元测试 + 端到端真值 ⭐
- 新增 rms-widget.test.ts / fft-widget.test.ts / phase-widget.test.ts(WS mock 帧 + 字段渲染 + 收敛标志)
- 新增 vitest 端到端真值脚本(注入 1kHz 正弦 -20dBFS · 断言 RMSMeter 显示 -20±1dB · SpectrumChart 显示峰值 1000±50Hz · PhaseChart 0° 参考稳定 ± 5°)
- test:unit 基线 356/3 → 目标 ≥ 380(+24 用例)

【验收】

形式合规(必要不充分):
- npm run typecheck → ✓ exit 0
- npm run build → ✓ 零错误
- npm run test:unit → ≥ 380/3
- 三 stub 升级 + 三 widget 业务壳 + dynamic component 注册

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段强制要求 · 不可仅"typecheck 全绿就 commit")

ADR §3.1/3.2/3.4 5 项契约自查清单:
- [ ] ① 输入输出契约:三 widget 字段对齐 ADR(单位 Hz/dBFS/° · noiseFloorDb/averagedCount/windowMs 物理元信息显示)
- [ ] ② 收敛判据:RMS 抖动 < 0.5dB · FFT 峰值 ± 50Hz · Phase 相干性 > 0.7 实线 / < 0.7 虚线
- [ ] ③ 失败回退 5 类:WS 断 + 单通道断 + 后端崩溃 + 配置不合法 + 数据帧倒序 · 各有 UI 表现 + 恢复路径
- [ ] ④ 用户操作流 5 步:打开 /xitest?mode=realtime → 切 Tuning Preset → 注入 1kHz 正弦 → 观察 3 widget 实时跳数 → 快照对比
- [ ] ⑤ 端到端真值 e2e:vitest 真值脚本注入 1kHz 正弦 -20dBFS → 断言 RMS -20±1dB / FFT 峰值 1000±50Hz / Phase 0°±5°(stable for ≥ 25 frames)

【commit】
- subject:`feat(P0.U-measurement-rms-fft-phase/widgets): RMS+FFT+Phase 三 widget 真业务 + e2e 真值 · ADR-12 Phase 2 #5`
- trailer:`[step=6/6] [pid=P0] [uid=U-measurement-rms-fft-phase] [occupies=P0.K-shared-meter-dock+P0.K-shared-types+P4.K1] [files=stages/xitest/dashboard/widgets/{rms,fft,phase}/*+test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue+tests/*]`

【禁止】
1. ❌ 不动 widgets/{transfer,waveform,electrical,recorder}/*(留 #6/#7)
2. ❌ 不动 stages/xitest/modes/*(P4.U3 ceecccf 实装的 regression/realtime mode)
3. ❌ 不动 dashboard 容器层(DashboardCanvas / WidgetContainer / WorkspacePresetSwitcher · #2 a7df354 已就位 · 仅 read)
4. ❌ 不嵌入完整 Vue SFC 骨架(.clinerules v1.6 §prompt 内容硬约束)· worker 自决具体实现风格
5. ❌ 不绑定 CPU(本 prompt frontmatter worker: TBD · 用户分配 worker/worktree)
6. ❌ 不与 ADR-11 P3 fork 冲突(P3 改 stages/xitune/* · 本任务改 stages/xitest/*)
7. ❌ 不验"typecheck 全绿就 commit"——必须按 ADR §3 5 项契约自查 + e2e 真值脚本(1kHz 注入断言)
8. ❌ 不实施 transfer_function / group_delay / thd 等 sidecar 高级端点(留 #6 transfer-waveform · #7 electrical-recorder · 本任务仅消费 toolKind=rms/fft/phase)

解锁链(本任务 zombie 后)

  • ✅ ADR-12 §3 业务行为契约首次 e2e 真值跑通(.clinerules v1.8 §业务行为契约必填段标杆落地)
  • ✅ 解锁 Phase 3 #10 P0.U-engine-session-snapshots(LeftDock § Engine + Session + Snapshots)
  • ✅ 与并行派发的 #6(transfer+waveform)+ #7(electrical+recorder)合流后 ADR-12 §3 7 类全实施

风险评估

风险 缓解
⚠️ 30fps WS 帧渲染卡顿 requestAnimationFrame 节流 · canvas/svg 取舍参考现有 SpectrumChart 风格 · Phase 3 性能调优可补
⚠️ FFT 峰值频率定位精度依赖 fftSize 默认 fftSize=4096 @ 48kHz → 频率分辨率 ~11.7Hz · ± 50Hz 断言留足余量 · ADR §3.2 默认配置
⚠️ Phase 相干性低区间易闪烁 用 EMA 平滑 + 实线/虚线渐变 · 不要硬切换(参考 ADR §3.4 ②)
⚠️ stub 升级可能影响现有 modes/realtime 调用方 RMSMeter/SpectrumChart/PhaseChart 保持 props 向后兼容 · 现有 modes/realtime 调用不破坏(回归测试覆盖)

历史

时间 事件 hash
2026-05-30 08:35 dispatched · ADR-12 Phase 2 #5 解锁 · #2 zombie(a7df354)Phase 1 全闭环后即派 —