MIGRATED

XiProbe 技术架构 v1.0 · 音响系统测试设备上位机

文档定位

• 产品定位：Xisound L2 层"羲音探针"——音响系统测试设备（XiMic/XiCal 硬件配套）的上位机软件
• 形态演进：Y1 web app（后端代理硬件）→ Y2 Tauri 桌面化（直连串口/USB/CAN 总线）
• P 编号：本文档采用 P11-xiprobe（D0 产品矩阵 V1.1 L2 五件套中列出 XiProbe · 本前端架构体系补齐 P 编号 · DQ-01 已确认）
• 上游：D0 产品矩阵 V1.1 §3.4 L2 五件套 · D3-FE-ARCH-001 §5.5
• 下游：D3-FE-PLAN-009 XiProbe Y1 web 实现 plan

---

1. 产品定位与目标

1.1 产品定位

XiProbe = 羲音探针（Y2H2 首发 · Y3 扩展 Tauri 桌面版）。配套 XiMic（高精度数字麦克风）和 XiCal（多路数字麦采集系统）硬件的上位机软件，用于车载/音响系统的：

• 多通道输出注入：扫频 / 粉噪 / 多音 / 脉冲
• 多通道同步采集：8ch / 16ch / 32ch
• 专业测量分析：THD / SNR / 频响 / 串扰 / 指向性
• 认证报告：AES 17 / ITU-R BS.1116 / GB/T 标准报告

1.2 核心能力

1. Device Manager：硬件设备发现 · 连接 · 通道配置 · 校准数据管理
2. Signal Generator：扫频 / 粉噪 / 白噪 / 多音 / 脉冲 · 自定义 wav
3. Acquisition：多通道同步采集 · 实时电平表 · 波形/频谱双视图
4. Analysis：
   • THD (Total Harmonic Distortion)
   • SNR (Signal-to-Noise Ratio)
   • 频响 (Frequency Response)
   • 串扰 (Channel Crosstalk)
   • 指向性 (Directivity · 仅阵列麦)
   • 阶跃响应 / 脉冲响应
5. Certification Report：按 AES / ITU / GB/T 标准生成 PDF 报告

1.3 目标用户

用户类型	场景	XiProbe 能力
现场测试工程师	车辆交付前验收测量	快速 THD/SNR/频响 自动测试套件
声学实验室 QA	芯片/功放/扬声器认证	AES 17 标准报告 · ITU-R BS.1116
Tier1 / OEM 采购	供应链质量验证	多车型批量测试 · 批量报告归档
Xisound 自家	XiDSP / XiAmp 量产测试	AEC-Q100 规定的 EMC / 电气测试

1.4 版本矩阵

版本	时点	形态	覆盖能力
v0.5 灯塔	Y2Q1	web	基础采集 + 简单分析
v1.0 首发	Y2H2	web	5 大模块完整 + AES 17 标准报告
v1.5	Y3H1	web	多车型矩阵测试 + 批量报告
v2.0 桌面版	Y3H2	Tauri	直连硬件 · 离线完整能力 · 无需后端代理
v2.5	Y4	Tauri + web 双栈	AI 辅助测量（XiMind 驱动）+ 报告解读

1.5 Y1 web vs Y2 Tauri 的形态选择

Y1 web 形态（Y2H2 首发到 Y3H1 主形态）：

• 优点：无需安装 · 跨平台 · 更新快
• 限制：不能直接访问 USB / 串口 → 依赖后端硬件代理服务（probe-agent.exe 在本地 PC 运行 · ws://localhost:7788）
• 适用：实验室有 PC + 硬件代理安装 · 网络稳定

Y2 Tauri 桌面形态（Y3H2+）：

• 优点：直连 USB / 串口 / CAN 总线 · 离线可用 · 低延迟
• 限制：需要安装包 · 跨 OS（Win/Mac/Linux）维护成本
• 适用：现场测试 · 车辆交付现场 · 移动场景 · 大客户私有化

兼容性约束（关键）：Y1 Web 的代码 95%+ 应能直接迁移到 Y2 Tauri（通过抽象硬件访问层 + 环境判断）

---

2. 架构总览

2.1 Y1 web 形态架构

graph TB
    subgraph App["apps/xi-probe (Y1 web)"]
        Router["vue-router"]
        Shell["ProbeLayout"]
        subgraph Modules["5 大功能模块"]
            DevMgr["Device Manager"]
            SigGen["Signal Generator"]
            Acq["Acquisition"]
            Analysis["Analysis"]
            CertRpt["Cert Report"]
        end
    end

    subgraph Packages["packages/"]
        UIKit["@xi/ui-kit<br/>(SpectrumChart/LevelMeter/WaveformChart)"]
        Protocol["@xi/protocol"]
        StoreCore["@xi/store-core"]
        DSPUtils["@xi/dsp-utils<br/>(FFT/THD/SNR/LUFS)"]
        AISDK["@xi/ai-sdk (Y3)"]
    end

    subgraph Agent["本地硬件代理 probe-agent.exe<br/>(Y1 web 模式必需)"]
        Proxy[WebSocket Server<br/>ws://localhost:7788]
        USBDrv[USB Driver]
        SerialDrv[Serial Driver]
    end

    subgraph Hardware["硬件"]
        XiMic[XiMic 数字麦]
        XiCal[XiCal 采集系统 8/16/32ch]
        Target[被测设备 · 喇叭/功放/声学系统]
    end

    App -.WebSocket ws://localhost:7788.-> Proxy
    Proxy --> USBDrv --> XiMic
    Proxy --> SerialDrv --> XiCal
    XiMic --> Target
    XiCal --> Target

    classDef app fill:#FFF4E6,stroke:#D4A574,stroke-width:3px
    classDef module fill:#FFFFFF,stroke:#6B7280,stroke-width:1px
    classDef pkg fill:#F5F2EA,stroke:#6B7280,stroke-width:1px
    classDef agent fill:#F0E6FA,stroke:#9D4EDD,stroke-width:2px
    classDef hw fill:#E6F7FF,stroke:#1890FF,stroke-width:2px
    class App,Router,Shell app
    class DevMgr,SigGen,Acq,Analysis,CertRpt module
    class UIKit,Protocol,StoreCore,DSPUtils,AISDK pkg
    class Proxy,USBDrv,SerialDrv agent
    class XiMic,XiCal,Target hw
    class App,Modules xySgL2; class Packages xySgL4; class Agent xySgL0; class Hardware xySgL1;

2.2 Y2 Tauri 桌面版架构（Y3H2+）

graph TB
    subgraph Tauri["apps/xi-probe + src-tauri (Y2 桌面版)"]
        FE[Vue 3 前端<br/>与 Y1 web 同代码 95%+]
        Rust[Rust 后端<br/>tauri commands]
        HWAbstract["HardwareAdapter<br/>抽象层"]
    end

    subgraph TauriPlugins["Tauri Plugins"]
        PluginUSB["@tauri-apps/plugin-usb"]
        PluginSerial["@tauri-apps/plugin-serialport"]
        PluginShell["@tauri-apps/plugin-shell"]
        PluginFS["@tauri-apps/plugin-fs"]
    end

    subgraph Native["packages/probe-native (新增 · 抽象硬件访问)"]
        Adapter[HardwareAdapter interface]
        WebAdapter[WebSocketAdapter<br/>Y1 web 走 probe-agent]
        TauriAdapter[TauriAdapter<br/>Y2 走 Tauri Plugins]
    end

    FE --> HWAbstract
    HWAbstract --> Adapter
    Adapter -.Y1.-> WebAdapter
    Adapter -.Y2.-> TauriAdapter
    TauriAdapter --> PluginUSB
    TauriAdapter --> PluginSerial

    classDef tauri fill:#FFF4E6,stroke:#D4A574,stroke-width:3px
    classDef plugin fill:#E6F7FF,stroke:#1890FF,stroke-width:2px
    classDef native fill:#F0E6FA,stroke:#9D4EDD,stroke-width:2px
    class FE,Rust,HWAbstract tauri
    class PluginUSB,PluginSerial,PluginShell,PluginFS plugin
    class Adapter,WebAdapter,TauriAdapter native
    class Tauri xySgL4; class TauriPlugins xySgL0; class Native xySgL1;

2.3 技术栈

层	Y1 web	Y2 Tauri
框架	Vue 3.4+	Vue 3.4+ (同)
路由	vue-router 4	vue-router 4 (同)
状态	Pinia 2+	Pinia 2+ (同)
UI	@xi/ui-kit	同
DSP	@xi/dsp-utils	同
硬件访问	probe-agent.exe (Electron/Node) + WebSocket	Tauri Plugins + Rust native
报告生成	jsPDF + html2canvas	同 · 可选 native PDF library
打包	Vite → 静态托管	Tauri CLI → DMG/MSIX/AppImage

---

3. 目录结构（Y1 web · Y2 Tauri 添加 src-tauri/）

apps/xi-probe/
├── src/
│   ├── main.ts
│   ├── App.vue
│   ├── router/
│   │   ├── index.ts          # /devices, /session/:id/{acquire,analyze,report}, /signal-generator
│   │   └── guards.ts
│   ├── layouts/
│   │   └── ProbeLayout.vue
│   ├── views/
│   │   ├── DeviceManagerView.vue
│   │   ├── ProbeSessionLayout.vue
│   │   ├── AcquisitionView.vue
│   │   ├── AnalysisView.vue
│   │   ├── CertificationReportView.vue
│   │   ├── SignalGeneratorView.vue
│   │   └── IntentHandlerView.vue
│   ├── components/
│   │   ├── device/
│   │   │   ├── DeviceCard.vue
│   │   │   ├── ChannelConfig.vue
│   │   │   └── CalibrationPanel.vue
│   │   ├── signal-gen/
│   │   │   ├── SweepGenerator.vue   # 扫频
│   │   │   ├── NoiseGenerator.vue   # 粉噪/白噪
│   │   │   ├── MultiToneGen.vue
│   │   │   └── PulseGen.vue
│   │   ├── acquisition/
│   │   │   ├── ChannelMatrix.vue    # 多通道矩阵显示
│   │   │   ├── LevelMeterArray.vue
│   │   │   └── WaveformViewer.vue
│   │   ├── analysis/
│   │   │   ├── THDAnalyzer.vue
│   │   │   ├── SNRCalculator.vue
│   │   │   ├── FrequencyResponse.vue
│   │   │   ├── CrosstalkMatrix.vue
│   │   │   └── DirectivityPlot.vue
│   │   └── report/
│   │       ├── ReportTemplate.vue
│   │       ├── StandardSelector.vue  # AES/ITU/GB/T
│   │       └── PdfExporter.vue
│   ├── stores/
│   │   ├── useDeviceStore.ts
│   │   ├── useSignalGenStore.ts
│   │   ├── useAcquisitionStore.ts
│   │   ├── useAnalysisStore.ts
│   │   └── useReportStore.ts
│   ├── services/
│   │   ├── hardwareAdapter.ts   # 抽象层 · Y1 连 probe-agent / Y2 连 Tauri
│   │   ├── probeAgentApi.ts     # Y1 web 专用
│   │   └── pdfExport.ts
│   └── types/
│       ├── Device.ts
│       ├── Channel.ts
│       ├── Measurement.ts
│       ├── CertStandard.ts
│       └── Report.ts
├── src-tauri/                   # Y2 添加
│   ├── src/
│   │   ├── main.rs
│   │   ├── usb.rs               # USB 硬件访问
│   │   ├── serial.rs            # 串口访问
│   │   └── can.rs               # CAN 总线（车载场景）
│   ├── Cargo.toml
│   ├── tauri.conf.json
│   └── icons/
├── tests/
├── vite.config.ts
├── tsconfig.json
├── package.json
└── README.md

---

4. 核心模块详细设计

4.1 Device Manager

数据模型：

// types/Device.ts
export interface ProbeDevice {
  id: string
  type: 'xi-mic' | 'xi-cal-8ch' | 'xi-cal-16ch' | 'xi-cal-32ch' | 'third-party'
  vendor: string
  model: string
  serialNumber: string
  firmwareVersion: string
  calibrationData?: CalibrationData       // 出厂校准参数
  connectionState: 'disconnected' | 'connecting' | 'connected' | 'error'
  channels: Channel[]
}

export interface Channel {
  index: number
  label: string                          // 如 "驾驶员位"
  sensitivity: number                    // mV/Pa（麦克风灵敏度）
  gain: number                           // dB（前置放大）
  sampleRate: number                     // 48000 / 96000 / 192000
  bitDepth: 16 | 24 | 32
}

export interface CalibrationData {
  capturedAt: number
  certificate: string                     // 校准证书号
  frequencyResponse: { freqs: number[]; magnitudeDb: number[] }
  phaseResponse?: { freqs: number[]; phaseDeg: number[] }
  thdFloor: number                        // 本底 THD
  noiseFloor: number                      // 本底噪声
}

4.2 Signal Generator

支持信号：

类型	参数	用途
扫频（Sine Sweep）	起始频率 / 结束频率 / 持续时间 / 对数或线性	频响测量
粉噪（Pink Noise）	持续时间 / 幅度	THD / 本底噪声
白噪（White Noise）	持续时间 / 幅度	平坦频谱参考
多音（Multi-Tone）	频率列表 / 幅度	IMD 测量
脉冲（Pulse/Chirp）	脉冲宽度 / 幅度	脉冲响应
自定义 wav	上传 wav 文件	标准 ITU 测试信号

4.3 Acquisition

流程：

sequenceDiagram
    participant UI as AcquisitionView
    participant Store as useAcquisitionStore
    participant HWAdapter as HardwareAdapter
    participant Agent as probe-agent<br/>(Y1) / Tauri (Y2)
    participant HW as XiCal

    UI->>Store: 配置采集(channels, sampleRate, duration)
    UI->>Store: startCapture()
    Store->>HWAdapter: startAcquisition(config)
    HWAdapter->>Agent: WS: {cmd: start-acquisition}
    Agent->>HW: 激活采集
    HW-->>Agent: 多通道 PCM 流
    Agent-->>HWAdapter: 实时流(Float32Array batches)
    HWAdapter-->>Store: 更新 channels[].samples
    Store-->>UI: 实时波形/电平表刷新(60 FPS)

性能要求：

• 16 通道 @ 96kHz · 32-bit Float · 实时显示
• 数据量：16 × 96000 × 4 bytes = 6.1 MB/s
• 缓冲策略：前端 ring buffer 30s 历史 + 可选持续写磁盘

4.4 Analysis

5 大核心指标：

指标	计算方式	用途
THD	测试基频 + 观察谐波分量 + 20·log10(harmonics / fundamental)	扬声器非线性评估
SNR	信号 RMS 与无信号本底 RMS 比值	系统动态范围
频响	扫频响应或白噪/粉噪 FFT · 可选加 ⅓ octave 平滑	系统均衡性
串扰	输入通道 i 的信号漏到其他通道 j 的比例	通道隔离度
指向性	多位置麦阵列测量 · 极坐标绘图	声源方向性

4.5 Certification Report

支持标准：

• AES 17（Recommended Practice - Measurement of Digital Audio Equipment）
• ITU-R BS.1116（主观音质评价 · Ancillary data）
• ITU-R BS.1387（PEAQ · 客观音质指标）
• GB/T 14277-2013（中国音频设备通用规范）
• AEC-Q100（车规可靠性 · 内部）

报告内容：

1. 封面 · 被测设备信息 + 测试环境 + 测试工程师签名
2. 测试环境 · 温度 / 湿度 / 本底噪声 / 设备版本
3. 测量结果 · 每项指标的数据 + 图表 + 与标准阈值对比
4. 合格判定 · 通过 / 警告 / 失败
5. 附录 · 原始数据链接（PCM wav / CSV）

---

5. Y1 web / Y2 Tauri 兼容性设计（关键）

5.1 HardwareAdapter 抽象层

// services/hardwareAdapter.ts
export interface HardwareAdapter {
  discover(): Promise<ProbeDevice[]>
  connect(deviceId: string): Promise<void>
  disconnect(deviceId: string): Promise<void>
  startAcquisition(config: AcquisitionConfig): Promise<AcquisitionSession>
  stopAcquisition(sessionId: string): Promise<void>
  playSignal(signalConfig: SignalConfig): Promise<void>
  stopSignal(): Promise<void>
  readCalibration(deviceId: string): Promise<CalibrationData>
}

// services/webAdapter.ts (Y1)
export class WebSocketAdapter implements HardwareAdapter {
  // 通过 ws://localhost:7788 调用 probe-agent
}

// services/tauriAdapter.ts (Y2)
export class TauriAdapter implements HardwareAdapter {
  // 通过 invoke('discover_devices') 调用 Rust 层
}

// 自动检测环境并注入正确的 adapter
export function createHardwareAdapter(): HardwareAdapter {
  if (window.__TAURI__) return new TauriAdapter()
  else return new WebSocketAdapter()
}

5.2 probe-agent（Y1 专用 · 本地代理服务）

独立项目 tools/probe-agent/（不在 Monorepo 主 app 中）：

• Electron 或 Node.js + pkg 打包
• 用户首次运行 XiProbe web 时提示下载并安装
• 后台服务 · 启动时监听 127.0.0.1:7788
• 定期自动更新（XiProbe 启动时检查版本）

5.3 Y1 → Y2 迁移的工程代价估算

领域	Y1 代码行数	Y2 新增/修改	比例
Vue 前端组件	~5000 行	0	0% 变更
硬件访问抽象层	~200 行	+300 行（新增 TauriAdapter）	60% 新增
Rust Tauri commands	0	+500 行	100% 新增
总计	~5200	+800	15% 新增

结论：Y1 到 Y2 迁移主要是新增 native 层 · 前端基本不改

---

6. 与后端的接口契约（Y1 主要）

6.1 probe-agent 本地 WebSocket 协议

// 命令
ws.send({ cmd: 'discover' })                       // 扫硬件
ws.send({ cmd: 'connect', deviceId: 'xi-cal-001' })
ws.send({ cmd: 'start-acquisition', config: {...}})
ws.send({ cmd: 'play-signal', config: {type: 'sweep', startHz: 20, endHz: 20000, duration: 10}})

// 事件
ws.on('device-list', devices => {...})
ws.on('capture-data', { channel, samples: Float32Array })  // 实时流
ws.on('acquisition-complete', { sessionId, duration })

6.2 云端 API（可选 · 报告归档）

端点	方法	用途
/api/probe/sessions	POST	保存测试 session 到云端
/api/probe/reports	GET	报告列表
/api/probe/calibrations	POST	上传校准数据到云（用于审计）
/api/probe/vehicles/:id	GET	获取某车型的测量历史

---

7. Tauri 分发策略（Y2）

7.1 打包方式

• Windows：MSIX (推荐) 或 MSI · 代码签名证书
• macOS：DMG + Apple Developer 签名 + notarization
• Linux：AppImage / Snap / deb

7.2 更新机制

• Tauri Updater（自带）· 连 GitHub Releases 或自建 update server
• 静默更新 vs 提示更新（默认提示）

7.3 安装包大小估算

• 前端 bundle: ~2MB
• Tauri runtime: ~3MB（vs Electron 80MB · 显著优势）
• Rust native deps: ~5MB
• 总计: ~10MB 单平台

---

8. 测试策略

8.1 单元测试

• Store CRUD + 状态转换
• 硬件代理 Mock 测试（不实际连硬件）
• DSP 计算正确性（与 MATLAB 参考实现对比）

8.2 硬件集成测试

• 连真实 XiMic/XiCal · 自动化脚本跑 AES 17 测试套件
• Y2 Tauri：跨 OS（Win/Mac）硬件兼容性矩阵

8.3 性能基线

• 16ch @ 96kHz 实时采集：CPU < 30%
• FFT 4096 点 × 16 通道：< 20ms
• PDF 报告生成（含 10 张图）：< 10s

---

9. DQ 与风险

9.1 新增 DQ

DQ 编号	问题	建议
DQ-PROBE-01	P 编号确认（DQ-01 遗留）	⭐ 已采用 P11-xiprobe（本文档 doc_id = D2-P11-TECH-001）
DQ-PROBE-02	Y1 probe-agent 分发（下载安装门槛）	v1.0 提供 Win/Mac 签名安装包 · 辅以自动更新
DQ-PROBE-03	实验室场景 vs 现场场景的 UI 差异	v1.0 先做实验室场景 · v2.0 加"现场快测"简化 UI
DQ-PROBE-04	与 XiTune 的边界（调音 vs 测试）	XiTune 主观调音 / XiProbe 客观测量 · 两者可互通数据（导出 measurement 到 XiTune）
DQ-PROBE-05	Y2 Tauri 走哪个 Plugin 生态	优先 Tauri v2 官方 plugin · 缺失的自己写 Rust wrapper

9.2 风险

风险	缓解
probe-agent 被杀毒软件误杀	用官方代码签名证书 · 白名单提交
Y1 → Y2 迁移时 Web API 不同（如 File System Access）	HardwareAdapter 抽象层兜底 · 前端组件 0 改动
硬件驱动兼容性（Win 10/11 · 各硬件厂商 USB chip）	提供标准驱动 + 常见问题 FAQ · 技术支持热线
现场测试环境网络不稳	Y2 Tauri 桌面版完全离线可用 · 数据本地存

---

10. 版本与变更记录

版本	日期	作者	说明
v1.0	2026-05-08	work-cline	初稿 · Y1 web + Y2 Tauri 双形态 · 5 大模块 · HardwareAdapter 抽象层 · AES/ITU 标准报告 · 迁移工程代价估算

---

附录 A · 引用

• D0 产品矩阵 V1.1 §3.4 L2 测试调音层
• D3-FE-ARCH-001 §5.5 XiProbe 概览
• D3-FE-ARCH-005 §3.4 xi-probe 路由
• D3-FE-ARCH-006 §3.1 xi-probe 域名规划
• D3-FE-ARCH-004 PLAN-009