📝 docs(architecture): 制定多平台修正与稳定板保护计划

[ZhaoXingPeng]

结论

本 PR 提交多平台重构的架构修正与可恢复基线计划，供当前和后续开发分支作为前置约束。请 Reviewer 重点确认：VoiceLife PCB 与 SparkBot 是否被正确建模为同级板型，以及 PlatformAssembly、事件单写者与显示 Adapter 的边界是否足以避免新板适配继续侵入 Runtime。

Refs #94

变更

• 将 main@0bc930d 固定为 VoiceLife PCB 的首个可恢复基线，并定义每个受影响 Profile 的真机回归、可刷写产物和回退门禁；
• 明确 VoiceLife PCB 与 SparkBot 是同级 Profile/Adapter：两者都可以独立修改和演进，发布时只需记录相对上一已验证版本的变化并保留回退产物；
• 定义构建期 Profile/manifest、PlatformAssembly、能力模型与 InteractionEventLoop 的演进路径；
• 明确点阵 SSD1306 与 SparkBot 彩屏是不同 PresentationPort Adapter：Runtime 仅提交 DisplaySnapshot，图片/GIF 受逻辑 asset_id、资源清单、许可证、哈希和内存预算约束；
• 复核 ESP-IDF、Zephyr、SLSA 公开规范，以及现有 🏗️ refactor(architecture): 重建 VoiceLife 可迁移架构主干 #92、🎙️ feat: 建立可插拔语音会话与 Provider 契约 #106、✨ feat(voice): 接入 ESP32-S3 Linx WSS Transport #108、✨ feat(voice): 建立 ESP32-S3 PCM/I2S 板级探针 #110、🏗️ refactor(voice): 接入 voicelife-pcb 纯 I2S PCM Profile #112、✨ feat(voice): 接入 Profile 驱动的 ESP32-S3 PCM Audio Port #114、✨ feat(timing): 建立定时任务服务契约与注册骨架 #122、✨ feat(im): 建立 voicelife_im 上报通道并纳入主机测试与架构门禁 #168、✨ feat(im): 建立设备侧动作通道并在强提醒窗口建立 SSE 动作流 #170、✨ feat(im): PostgreSQL 持久化与重启恢复（#128） #172、✨ feat(timing): 建立共享 occurrence 规划器 #209、📝 docs(architecture): 收敛日程、调度与动作模块边界 #217、✨ feat(board): 实现小智式板端交互状态机 #222、✨ feat(storage): 搭建 SQLite 日程持久化链路 #224、🐛 fix(board): 无声修复与状态机完善（裸 PCM/24kHz/控制队列） #229、🐛 fix(board): 交互修复/音量满幅/队列背压 + 热点配网（替代断网错误） #230、📝 docs(board): 制定 ESP-SparkBot 适配执行计划 #232 的演进关系；
• 记录已关闭的 ✨ feat(display): 完成小智式牛牛屏幕适配 #226 仅涉及旧 SSD1306 点阵屏，不是 SparkBot 彩屏或素材的开发基线。

明确未包含：

• 不新增 Runtime、板卡、显示或音频实现；
• 不移动、提交或授权使用其他工作树中未跟踪的 SparkBot 素材；
• 不创建基线 tag、发布固件、修改现有板卡 Profile，或修改其他 Issue/PR。

架构与兼容

文档提出的接口为后续 Design Issue/骨架 PR 的评审边界，尚未引入生产代码。实际实施必须先完成可编译的 PlatformAssembly、PresentationPort 与事件循环骨架，并逐边界迁移。

main@0bc930d 是 VoiceLife PCB 的可恢复对照点，不是对 GPIO、I2S、Codec、SSD1306 或交互行为的永久冻结。任何板型的行为变更都需要新的 Profile/固件身份、差异说明、真机证据和可刷回上一产物的步骤。

验证

• git diff --check
• ./scripts/check_architecture.sh
• ctest --test-dir build-host --output-on-failure：44/44 通过
• python3 scripts/firmware.py validate：3 个 ESP32-S3 Profile 通过
• ESP-IDF 固件构建：当前 shell 未提供 idf.py
• 真机回归：本 PR 不改固件，后续受影响 Profile 的实现 PR 必须提供

证据：docs/architecture/multi-platform-correction-plan.md 包含公开规范链接、PR 对照、资源/内存/回退门禁与验收标准。

TDD 记录

• RED：不涉及；本 PR 只新增架构审查文档。
• GREEN：不涉及；复跑现有架构、主机和 Profile 门禁确认基线未受影响。
• REFACTOR：不涉及。

风险与回退

风险是将文档误作已完成的多平台实现，或把彩屏素材、LVGL 和板级条件继续写入 runtime.cc。本 PR 保持 Draft 且不应合并；正式实现按 Issue 拆分为骨架、VoiceLife PCB 显示 Adapter、彩屏资源清单与 SparkBot Adapter 等小 PR。

回退方式：关闭本 Draft PR 或回退单独的文档提交，不影响 main、任一板型固件或其他开发工作树。

Review 清单

• Issue [Design] 重建 VoiceLife 可迁移架构主干与工程基线 #94 的架构边界、迁移路径和门禁均有对应章节
• 没有提交凭据、设备备份、用户隐私、构建产物或未跟踪素材
• 外部规范和上游实现均记录为参考，不直接迁移第三方代码
• 文档与当前 main@0bc930d、已关闭 ✨ feat(display): 完成小智式牛牛屏幕适配 #226 和 📝 docs(board): 制定 ESP-SparkBot 适配执行计划 #232 的实际范围一致
• AI 用于资料核查和文档初稿；结论、架构取舍和验证结果已人工复核

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!