Initial commit

_bmad-output/planning-artifacts/epics.md

@@ -0,0 +1,212 @@
+---
+stepsCompleted:
+  - ce-brownfield-synthesis-2026-04-06
+inputDocuments:
+  - _bmad-output/planning-artifacts/prd.md
+architecturePresent: false
+uxPresent: false
+workflowType: epics
+---
+
+# chromebox_10th_audio_driver — Epic 与 Story 分解
+
+**作者：** Jack  
+**日期：** 2026-04-06  
+**依据：** [prd.md](./prd.md)（含 §3.1 SC↔FR、附录 A）
+
+**说明：** 当前 **`planning-artifacts/`** 下**无** `architecture.md` / UX；本分解**仅追溯 PRD**。若后续补 **[CA]**，可增 Story 或调整验收中的技术约束。
+
+---
+
+## 概览
+
+将 PRD **FR1–FR9** 与 **NFR1–NFR5** 拆为 **4 个 Epic**、**12 个 Story**，便于 **[SP] Sprint Planning** 生成 `sprint-status.yaml`。
+
+---
+
+## 需求清单（摘自 PRD）
+
+### 功能需求（FR）
+
+| ID | 能力 |
+|----|------|
+| FR1 | 文档索引 |
+| FR2 | Linux HDMI 路线图 |
+| FR3 | 内核诊断补丁可追溯 |
+| FR4 | 构建与验证脚本 |
+| FR5 | 桌面 HDMI 操作说明 |
+| FR6 | 登录自动修复（Kaisa） |
+| FR7 | WirePlumber 片段示例 |
+| FR8 | 对照与导出 |
+| FR9 | BMad 规划链 |
+
+### 非功能需求（NFR）
+
+| ID | 类别 |
+|----|------|
+| NFR1 | 文档语言（简体中文） |
+| NFR2 | 可维护性（大目录不提交约定） |
+| NFR3 | 变更粒度（最小 diff） |
+| NFR4 | 安全与权限（user systemd 优先） |
+| NFR5 | 诚实边界（pro-audio 多 Pro N） |
+
+### UX 设计需求
+
+无（CLI/文档为主）。
+
+### FR 覆盖映射
+
+| Epic | 覆盖的 FR | 覆盖的 NFR（横切） |
+|------|-----------|---------------------|
+| E1 文档与入口 | FR1, FR2, FR9 | NFR1, NFR2, NFR3 |
+| E2 内核诊断与构建 | FR3, FR4 | NFR2, NFR3 |
+| E3 桌面 HDMI 用户态 | FR5, FR6, FR7 | NFR1, NFR4, NFR5 |
+| E4 双树与上游材料 | FR8 | NFR2, NFR3 |
+
+---
+
+## Epic 列表
+
+| ID | 标题 | 目标（一句话） |
+|----|------|----------------|
+| **E1** | 文档入口与 HDMI 叙事 | 读者能从 README/INDEX 到达路线图、OPERATION、PRD。 |
+| **E2** | 内核诊断补丁与构建验证 | 单补丁可检、脚本可跑、文档可跟。 |
+| **E3** | Kaisa 桌面 HDMI（PipeWire / IEC958） | 操作说明 + 片段 + 登录自动修复闭环。 |
+| **E4** | ChromeOS ↔ Ubuntu 对照与上游 | diff/export 与文档入口可发现。 |
+
+---
+
+## Epic 1：文档入口与 HDMI 叙事
+
+**目标：** 满足 **SC1** 与 **FR1、FR2、FR9**；新贡献者 10 分钟内找到 Linux HDMI 主线。
+
+### Story 1.1：INDEX 与 OPERATION/REPRO
+
+作为一名**维护者**，  
+我希望 **INDEX.md** 能链到 **OPERATION** 与 **REPRO**，  
+以便 **不必搜全库**（**FR1**）。
+
+**验收标准：**
+
+- **Given** 仓库根已克隆  
+- **When** 打开 `docs/INDEX.md`  
+- **Then** 存在指向 `OPERATION_PipeWire_Kaisa_HDMI.md` 与 `REPRO_Kaisa_Deb_ProAudio_Manual.md` 的条目  
+
+### Story 1.2：（已收敛）路线图
+
+**状态：** **`Linux_HDMI_Audio_Roadmap.md`** 与 **WORK_PROGRESS** 类长文已删除；**FR2** 以 **OPERATION + REPRO** 为事实源。
+
+### Story 1.3：README 与 PRD / BMad 链
+
+作为一名**产品/维护者**，  
+我希望 **根 README** 指向 **PRD** 与（可选）**epics**，  
+以便 **BMad 规划链**可追溯（**FR9**）。
+
+**验收标准：**
+
+- **Given** `README.md` 为唯一根 README  
+- **When** 查看文档入口表  
+- **Then** 存在指向 `_bmad-output/planning-artifacts/prd.md` 的链接  
+- **And** 可增链至本 `epics.md`（建议与 INDEX 中 BMad 表一致）
+
+---
+
+## Epic 2：（已收敛）内核诊断补丁与自编内核
+
+**状态：** 仓库已移除 **`patches/ubuntu-hwe-6.17/`** 与 **`verify-*` / `ubuntu-hwe-617-build.sh`**；原 **SC2 / FR3 / FR4** 故事**作废**。  
+若需本地 HWE 源码与 ChromiumOS 对照，在本机 **`apt source linux-hwe-6.17`** 后设 **`export UB=…`**，见 **`reference/chromeos-ubuntu-sound-diffs/README.md`**。
+
+---
+
+## Epic 3：Kaisa 桌面 HDMI（PipeWire / IEC958）
+
+**目标：** 满足 **SC3** 与 **FR5、FR6、FR7**；与 **NFR4、NFR5** 一致。
+
+### Story 3.1：OPERATION 覆盖 pro-audio / EBUSY / IEC958 / 全自动
+
+作为一名 **Kaisa 用户**，  
+我希望 **OPERATION_PipeWire_Kaisa_HDMI.md** 说明 **pro-audio**、**`speaker-test -D pulse`**、**IEC958',N** 与 **§4.3 安装器**，  
+以便 **排障不靠口口相传**（**FR5**）。
+
+**验收标准：**
+
+- **Given** 用户使用 PipeWire 桌面会话  
+- **When** 按 §3–§4 操作  
+- **Then** 能区分 **plughw EBUSY** 与 **Pulse 路径**；§4.2 含 **IEC958** 根因；§4.3 含 **install** 命令
+
+### Story 3.2：WirePlumber 片段可复制
+
+作为一名 **Kaisa 用户**，  
+我希望 **`50-kaisa-sof-rt5682-hdmi.conf`** 在仓库内完整且与 OPERATION 路径一致，  
+以便 **复制到 `~/.config/wireplumber/...`**（**FR7**）。
+
+**验收标准：**
+
+- **Given** 文件在 `docs/linux-hdmi/wireplumber/`  
+- **When** 按 OPERATION §2 安装  
+- **Then** `device.name` 与优先级说明在文中有「PCI 变化时如何改」提示（**NFR5** 相关）
+
+### Story 3.3：登录自动恢复（user systemd）
+
+作为一名 **Kaisa 用户**，  
+我希望按 **OPERATION §4.3** 配置 **user systemd**（自建 **`pactl`/`amixer`**），且可 **`disable --now`** 停用，  
+以便 **重启后仍能自动恢复 HDMI**（**FR6**，**NFR4**）。
+
+**验收标准：**
+
+- **Given** 用户会话可用 `systemctl --user`  
+- **When** 按 §4.3 自建单元并 **enable**  
+- **Then** 登录后执行恢复；停用时 **disable** 单元且不删 WirePlumber 片段
+
+---
+
+## Epic 4：双树对照与上游材料
+
+**目标：** 满足 **SC4** 与 **FR8**。
+
+### Story 4.1：双树对照说明与可选输出目录
+
+作为一名**上游贡献者**，  
+我希望 **ChromeOS ↔ Ubuntu** 对照方式与 **可选** diff 输出目录在文档中可查，  
+以便 **投递前自证边界**（**FR8**）。
+
+**验收标准：**
+
+- **Given** 根目录 **`REPO_INDEX.md`** 与 **`reference/chromeos-ubuntu-sound-diffs/README.md`**  
+- **When** 查找 sound/soc 对照  
+- **Then** 说明本机两树路径（**`chromiumos_kernel/v5.15`**、`apt source` 解压目录）及 **`diff -u` / `diff -rq`** 用法  
+- **And** 输出目录 **`reference/chromeos-ubuntu-sound-diffs/`** 有 README（生成物可选、默认 gitignore）
+
+### Story 4.2：双树齐全性（可选）
+
+作为一名**维护者**，  
+我在运行 **`diff`** 前自行确认两棵树路径存在，  
+以便 **不误报空 diff**（**FR8** 质量）。
+
+**验收标准：**
+
+- **Given** 未克隆 `chromiumos_kernel` 或未准备 HWE 解压目录  
+- **When** 尝试对照  
+- **Then** 自行补全树后再 `diff`（无仓库级预检脚本）
+
+---
+
+## 横切 NFR 守门（不单独 Epic）
+
+| NFR | 落实方式 |
+|-----|----------|
+| NFR1 | 上述 Story 验收说明与用户文档保持简体中文。 |
+| NFR2 | Story 2.2、4.2 强调大目录不提交与 clone 约定。 |
+| NFR3 | Code review / 自检：无关文件不混入 PR。 |
+| NFR4 | Story 3.3 明确 user 单元，不强制 root alsactl 为唯一方案。 |
+| NFR5 | Story 3.1、3.2 保持 OPERATION 中「多 Pro N」说明。 |
+
+**PRD 附录 A：** 可作为 Epic 1/2 的 **CI 任务** 或发布前 **checklist**。
+
+---
+
+## 后续
+
+- **[SP] Sprint Planning**：由本文件生成 **`implementation-artifacts/sprint-status.yaml`**。  
+- **[CA]**：若补充 **architecture.md**，可在 **E2/E3** 增加「与架构决策 §X 对齐」验收行。  
+- **[GPC]**：重建 **project-context.md** 时可将本 Epic 列表摘要写入。