跳转至

P5.U-autotune-vehicle-config-extend · 后端 VehicleConfig schema 扩展(4/6 座位 + IR 持久化)

Worker:ClaudeB · 后端 / 部门:后端 P5-backend-csharp / 预计:1.0d / 优先级:P0 / 状态:ready

🔍 触发与解锁链

  • 触发:fork 1b(6055025)后端就位后,ADR-AIOS-11 v1.3 修订引入 4/6 座位 IR 矩阵 + 决策 C 混合持久化 · 需扩 VehicleConfig schema + 新增 IR 持久化字段 · 不重写已 zombie 的 8 端点。
  • 解锁条件:本 fork zombie 后,P3.U-autotune-phase1-measure-v3 Tab 1 数据回写车配 + Tab 2 IR 持久化可切真接口(无 mock 阻塞)。

任务定义(基于 ADR-AIOS-11 v1.3)

严格 schema 扩展 · 不重写已有端点:扩 6055025 已落地的 VehicleConfig C# record + 新增 IR 持久化 schema(对齐 §3.5 决策 C 子目录 <project>/autotune/cabin-ir/)。

核心范围: 1. VehicleConfig schema 加 4/6 座位字段:SeatCount: 4 | 6 + Seats: SeatPosition[](driver / passenger / rear-left / rear-right / rear-center-1 / rear-center-2) 2. VehicleConfig channel 行加 hasData 字段:HasMeasureData: bool + ThumbnailSvg: string?(供 Tab 1 回写) 3. IR 持久化 schema(新增 record):CabinIRMatrixRequest / CabinIRMatrixResponse / CabinIRMatrixIndex · 对应 <project>/autotune/cabin-ir/{matrix-index.json, <seat>-<channel>-<mic>-<ts>.json} 4. manifest 索引扩展:.xistudio manifest files.autotune 子节加 cabinIRMatrix: string(指向 matrix-index.json)+ speakerCurves: string[] + outputPresets: string[]

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

[U-thread]: P5.U-autotune-vehicle-config-extend
[部门]: 后端 P5-backend-csharp
[Worker CWD]: d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies]: P5.K-api-routes
[优先级]: P0 · 1.0d
[ADR]: docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md(v1.3)
[业务行为契约引用]: 严格对齐 ADR §3.5 决策 C 持久化 + §3.4.1 Tab 1 hasData 回写 + §3.4.2 Tab 2 IR 矩阵 schema
[参考文档]:
  - ADR-AIOS-11 v1.3 §3.5 持久化策略(子目录约定 + manifest schema)+ §11.9 fork 1c 备案
  - ADR-AIOS-05 §5.2 link by project(大数据走子目录 · 索引走 manifest · 本 fork 沿用思路)
  - 已就位代码(fork 1b 6055025):
    · backend_csharp/Models/AutoTune/VehicleConfig.cs
    · backend_csharp/Models/AutoTune/VehicleConfigRequest.cs
    · backend_csharp/Models/AutoTune/{ChannelMeasureRequest,ChannelMeasureResponse,PositionMeasureRequest,PositionMeasureResponse}.cs
    · backend_csharp/Services/AutoTune/{VehicleConfigService,MultiChannelMeasureService}.cs
    · backend_csharp/Controllers/Dev/AutoTuneController.cs

【背景】
fork 1b(6055025)已落地 8 端点 + 3 record + bridge · 后端基础设施可用。本 fork 严格 schema 扩展 · 不动已落地实现 · 仅:① VehicleConfig 加座位字段 ② channel 行加 hasData/thumbnailSvg ③ 新增 IR 矩阵 record + 持久化 ④ manifest schema 扩展。

P7 synthesize_position 专用端点 + mute 编排 instanceId→DSP 通道映射层留 fork 1c(ADR §11.9)· 本 fork 不碰。

【执行步骤】(5 步)

Step 1 · VehicleConfig schema 扩展(0.2d)
  - 修改 backend_csharp/Models/AutoTune/VehicleConfig.cs
    · 加字段:SeatCount: int(4 或 6 · 默认 4)
    · 加字段:Seats: List<SeatPosition>(枚举:Driver / Passenger / RearLeft / RearRight / RearCenter1 / RearCenter2)
  - 修改 channel 行 record(VehicleConfig 内或子 record):
    · 加字段:HasMeasureData: bool(默认 false)
    · 加字段:ThumbnailSvg: string?(默认 null · Tab 1 回写时填)
  - 兼容性:旧工程文件加载时 · 缺失字段用默认值(SeatCount=4 · Seats=[Driver, Passenger, RearLeft, RearRight] · HasMeasureData=false)

Step 2 · IR 矩阵 schema(0.3d)
  - 新增 backend_csharp/Models/AutoTune/CabinIRMatrixRequest.cs
    · 字段:VehicleConfigVersion / SeatPosition / ChannelId / MicArray: int[] / SweepDuration
  - 新增 backend_csharp/Models/AutoTune/CabinIRMatrixResponse.cs
    · 字段:VehicleConfigVersion / SeatPosition / ChannelId / MicIndex / ImpulseResponse: float[] / SampleRate / MeasuredAt
  - 新增 backend_csharp/Models/AutoTune/CabinIRMatrixIndex.cs
    · 字段:VehicleConfigVersion / Entries: List<{seat,channel,mic,filePath,measuredAt}>(指向各单 IR 文件路径)
  - 不实施新端点(P7 synthesize_position 留 fork 1c)· 仅准备 schema

Step 3 · manifest 索引扩展 + 持久化(0.3d)
  - 修改 backend_csharp/Services/AutoTune/VehicleConfigService.cs(已落地)
    · 扩 SaveAsync:除写 vehicle-config.json 外 · 同步更新 .xistudio manifest files.autotune.vehicleConfig 字段
    · 扩 LoadAsync:从 manifest 索引读路径(原子读 · 防止 manifest/子文件不一致)
  - 新增 backend_csharp/Services/AutoTune/CabinIRPersistenceService.cs
    · SaveIRAsync(CabinIRMatrixResponse): 写 <project>/autotune/cabin-ir/<seat>-<channel>-<mic>-<ts>.json + 更新 matrix-index.json + manifest files.autotune.cabinIRMatrix 字段
    · LoadIndexAsync(): 读 matrix-index.json
  - manifest schema 文档化(注释 + xunit 验证)对齐 ADR §3.5.1 + §3.5.2 子目录约定

Step 4 · xunit 单测扩展(0.2d)
  - 扩 backend_csharp/Tests/Services/AutoTune/VehicleConfigServiceTests.cs(已落地)
    · 加 case:SeatCount=4 + Seats=[...] 加载/保存 round-trip
    · 加 case:旧工程(无 SeatCount 字段)兼容加载用默认值
    · 加 case:hasData + thumbnailSvg 回写后 LoadAsync 字段保留
  - 新增 backend_csharp/Tests/Services/AutoTune/CabinIRPersistenceServiceTests.cs
    · case:SaveIRAsync → 子目录文件存在 + matrix-index.json 含路径 + manifest 索引正确
    · case:LoadIndexAsync round-trip
  - 失败回退 case ≥ 2(子目录创建失败 / manifest 与子文件不一致时报错)

Step 5 · 自查 + commit(0.1d 收尾)
  - dotnet build 全绿(0 warning · 0 error · 已就位 6055025 警告基线参考)
  - dotnet test 不退化(已就位 111 case 基线)+ 新增 case 全过
  - 检查 fork 1c 边界:确认本 fork 未实施 P7 synthesize_position 端点 / mute 编排映射(grep 关键字应为空)
  - commit subject: feat(P5.U-autotune-vehicle-config-extend): extend VehicleConfig schema(SeatCount 4/6 + Seats + hasData) + add CabinIR persistence schema + manifest index sync(decision-C)
  - commit trailer 三元组:[step=5/5] [pid=P5] [uid=U-autotune-vehicle-config-extend] [occupies=P5.K-api-routes] [files=backend_csharp/Models/AutoTune/...,Services/AutoTune/...,Tests/Services/AutoTune/...]

【验收】(stop 前必跑)

形式合规:
  ☐ dotnet build 全绿
  ☐ dotnet test 不退化(基线 111 case)+ 新增 case 全过(预计 +5)
  ☐ 不动 6055025 已落地 4 端点(/api/auto_tune/vehicle_config + measure_channel + measure_position 等)实现
  ☐ 不实施 P7 synthesize_position 端点(grep "synthesize_position" 仅 ADR / 注释中出现 · 不在新代码中)
  ☐ 不实施 mute 编排映射(grep "mute" 仅 6055025 已有占位 log · 无新增逻辑)

业务行为契约(端到端真值 · 必跑):
  ☐ VehicleConfig 加 SeatCount=4 后 SaveAsync → vehicle-config.json + manifest 索引同步落盘
  ☐ 旧工程(无 SeatCount)LoadAsync → 默认 SeatCount=4 · 兼容
  ☐ Tab 1 hasData=true + thumbnailSvg 回写 → LoadAsync 字段保留
  ☐ CabinIR SaveIRAsync → <project>/autotune/cabin-ir/ 子目录 + matrix-index.json + manifest cabinIRMatrix 字段三处一致
  ☐ 失败回退:子目录创建失败 → 抛 IOException + manifest 不更新(原子性)

【commit】
- subject + 三元组 trailer 见 Step 5
- 7 天宽限期内三元组缺失仅 warning · 6/2 起 strict mode 硬拒

【禁止】(6 项红线)
1. ❌ 禁止重写 6055025 已落地 4 端点(/api/auto_tune/vehicle_config + measure_channel + measure_position 等)实现
2. ❌ 禁止实施 P7 `/auto_tune/synthesize_position` 专用端点(留 fork 1c · ADR §11.9 事项 1)
3. ❌ 禁止实施 mute 编排 instanceId→DSP 通道映射层(留 fork 1c · ADR §11.9 事项 2)
4. ❌ 禁止跳过原子性(manifest 与子文件必须同步落盘 · 失败回滚)
5. ❌ 禁止破坏旧工程兼容性(无 SeatCount 字段必须能 LoadAsync 不抛错)
6. ❌ 禁止跳过 xunit 失败回退 case(必须 ≥ 2 个 · 子目录失败 + manifest 不一致)

解锁链(本任务 zombie 后)

  • ✅ P3.U-autotune-phase1-measure-v3 Tab 1 数据回写车配(切真接口)
  • ✅ P3.U-autotune-phase1-measure-v3 Tab 2 IR 矩阵持久化(切真接口)
  • ✅ fork 1c(P5.U-autotune-mute-orchestration + P7.U-autotune-synthesize-endpoint)前置就绪

风险评估

风险 缓解
旧工程文件兼容性破坏 Step 1 显式默认值 + Step 4 兼容 case 验证 + 不改字段名
manifest 与子文件不一致 Step 3 原子写(临时文件 + 重命名)+ Step 4 失败回退 case 验证
误碰 6055025 已落地端点实现 Step 5 自查 grep + dotnet test 111 case 基线不退化
schema 扩展引入未知字段导致前端 fork 1-v3 解析失败 字段全部 nullable 或带默认值 · 前端 mock schema 与本 fork schema 提前对齐

历史

时间 事件 hash
2026-05-30 11:48 dispatched · ADR-11 v1.3 修订完成后立即派发 · 与 fork 1-v3 并行(无前置依赖) —
2026-05-31 08:51 zombie · ClaudeB 完成提交 · VehicleConfig SeatCount 4/6 + Seats + HasMeasureData/ThumbnailSvg + CabinIRMatrix schema + manifest 索引同步 · ADR-11 v1.3 fork 1b-v2 闭环 1ceebfa