你说得完全对。上一版确实是把 `frpc-console` 的文档骨架“迁移”过来了，而不是为清听重新设计的。现在我们来彻底扭转这个方向。

核心变化：**不再围绕“工程体系”组织文档，而是围绕“一首歌的生命路径”来组织**。每个文档回答一个具体的、用户视角的问题，而不是抽象的技术模块。

---

## 清听 (QingTing) 文档体系（最终版）

### 📁 目录结构

```
qingting/
│
├── README.md
│
├── docs/
│   ├── getting-started.md
│   ├── architecture.md
│   ├── playback.md
│   ├── metadata.md
│   ├── android.md
│   ├── storage.md
│   └── decisions.md
│
├── lib/
├── android/
├── assets/
└── pubspec.yaml
```

**只有 7 个文档 + 1 个 README。**

---

### 📄 各文档定位

| 文档 | 回答的问题 | 风格 |
|:---|:---|:---|
| **README.md** | 清听是什么？为什么做它？怎么快速体验？ | 产品入口，克制，有信条 |
| **getting-started.md** | 怎么把代码跑起来？ | 开发者上手，不含架构 |
| **architecture.md** | 整体怎么组织的？核心原则是什么？ | 架构总览，哲学融入其中 |
| **playback.md** | **一首歌是怎么被播放出来的？** | **核心文档，完整链路** |
| **metadata.md** | 歌曲信息是怎么被认识的？ | 诚实说明当前能力与局限 |
| **android.md** | 它怎么成为一个真正的 Android 播放器？ | 平台能力，面向使用者 |
| **storage.md** | 远程数据和本地状态怎么共存？ | 数据策略，区别于普通播放器 |
| **decisions.md** | 为什么最终选了这些方案？ | 设计记录，每问三部分 |

---

### ✍️ 各文档内容

---

#### 1. `README.md` —— 入口

```markdown
# 清听 QingTing

[![Flutter](https://img.shields.io/badge/Flutter-3.x-blue)](https://flutter.dev)
[![Platform](https://img.shields.io/badge/Platform-Android-green)](https://android.com)

**让远程音乐，像本地音乐一样可靠。**

清听是一个面向 Android 的 WebDAV 音乐播放器。

它解决的事情很简单：

> **让存储在 WebDAV 服务器上的音频文件，获得稳定、连续、可控的本地级播放体验。**

## ✨ 能力

- WebDAV 流式播放，无需下载
- 后台播放，退出应用不停
- 通知中心、锁屏、耳机控制
- 元数据读取与 SQLite 缓存
- 通知栏封面图

## 🚀 快速开始

```bash
# 克隆
git clone https://your-repo/qingting.git
cd qingting

# 获取依赖
flutter pub get

# 运行
flutter run
```

详细步骤：[Getting Started →](./docs/getting-started.md)

## 📖 文档

- [整体架构](./docs/architecture.md) —— 系统怎么组织的
- [播放链路](./docs/playback.md) —— 一首歌从点击到喇叭
- [元数据](./docs/metadata.md) —— 歌曲信息怎么被认识
- [Android 集成](./docs/android.md) —— 怎么成为 Android 播放器
- [存储策略](./docs/storage.md) —— 远程与本地如何共存
- [设计决策](./docs/decisions.md) —— 为什么选了这些方案

---

> 最好的播放器，是当你开始听歌之后，就再也感觉不到它技术细节的那一个。
```

---

#### 2. `docs/architecture.md` —— 架构总览（哲学融入）

```markdown
# 整体架构

> *“代码定义它如何工作，架构定义它如何活着。”*

---

## 四条原则

清听的设计围绕四个原则展开，它们共同指向同一个目标：**播放体验的完整性**。

### 1. 播放优先

Metadata 识别失败，不能阻塞播放。
封面加载失败，不能阻塞播放。
数据库异常，不能阻塞播放。

播放是主路径，其他一切都是旁路。

### 2. 状态是事实，UI 只是观察者

播放状态只有一个事实源：`AudioService`。

UI、通知中心、锁屏都只观察这个状态，不拥有它。

### 3. 异步结果必须验证身份

切歌后，上一首歌的元数据请求如果才返回，必须丢弃。

通过 `_playbackGeneration` 为每次切歌分配唯一身份。

### 4. 平台边界显式接入

Android 特有功能（FileProvider、前台服务）通过 `MethodChannel` 显式调用，不依赖第三方插件的封装。

---

## 分层结构

```
┌─────────────────────────────────────────┐
│              UI Layer                   │
│  PlayerPage / MiniPlayer / Playlist    │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│           AudioService                  │
│  队列 · 状态 · 模式 · generation       │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│       AudioPlayerHandler               │
│  MediaSession · PlaybackState · 系统回调│
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         MetadataService                 │
│  读取 · 标准化 · 缓存 · 封面           │
└─────────────────────────────────────────┘
```

---

## 数据流向

```
用户点击歌曲
    ↓
设置队列 → 更新索引
    ↓
加载 WebDAV URL
    ↓
media_kit 播放
    ↓
发布 PlaybackState
    ↓
UI 更新 / 通知更新
```

元数据加载是旁路，不阻塞上述流程。
```

---

#### 3. `docs/playback.md` —— 播放链路（核心文档）

```markdown
# 播放链路

> *“一首歌从点击到喇叭出声，中间发生了什么？”*

这是清听最核心的文档。它描述的是整个播放系统如何协同工作，让用户获得连续、可靠的聆听体验。

---

## 总览

```
User Action
    ↓
Queue Management
    ↓
Current Index
    ↓
Generation (防漂移)
    ↓
WebDAV URL
    ↓
media_kit
    ↓
Playback State
    ↓
AudioService → UI / Notification
```

---

## 队列与索引

```dart
class AudioService {
  List<Song> _queue = [];
  int _currentIndex = -1;
  List<int> _shuffledIndices = [];
  int _shuffledIndex = -1;
}
```

- `setQueue(queue, index)`：设置队列并开始播放
- `next()` / `previous()`：根据当前模式（顺序/随机/单曲循环）计算下一首

---

## Generation 机制（防漂移）

这是清听处理异步竞态的关键设计。

```dart
int _playbackGeneration = 0;

void _playCurrent() {
  _playbackGeneration++;  // 每次切歌递增
  _loadMetadataForCurrentSong(_playbackGeneration);
}

void _loadMetadataForCurrentSong(int generation) async {
  final data = await fetchMetadata();
  if (_playbackGeneration != generation) return;  // 丢弃过期结果
  applyMetadata(data);
}
```

**场景：**

```
歌曲 A → 请求元数据（gen=1）
用户切到歌曲 B → gen=2，请求元数据
歌曲 A 的元数据返回 → gen=1 ≠ 2 → 丢弃
歌曲 B 的元数据返回 → gen=2 = 2 → 应用
```

---

## PlaybackState 发布

```dart
playbackState.add(PlaybackState(
  controls: [skipToPrevious, playPause, skipToNext],
  playing: playing,
  position: _currentPosition,
  updateTime: DateTime.now(),
  systemActions: {MediaAction.seek},
));
```

- `systemActions` 必须包含 `seek`，通知栏进度条才能拖动
- 使用 `playPause` 而非分离的 `play`/`pause`
- 每 500ms 节流发布，平衡性能与流畅度

---

## 完整时序

```mermaid
sequenceDiagram
    participant User
    participant UI
    participant AudioService
    participant media_kit
    participant MetadataService

    User->>UI: 点击歌曲
    UI->>AudioService: setQueue(queue, index)
    AudioService->>AudioService: _currentIndex = index
    AudioService->>AudioService: _playbackGeneration++
    AudioService->>media_kit: 加载 WebDAV URL
    media_kit-->>AudioService: 开始播放
    AudioService->>AudioService: 发布 PlaybackState
    AudioService-->>UI: 状态更新

    par 旁路加载
        AudioService->>MetadataService: 请求元数据(携带 generation)
        MetadataService-->>AudioService: 返回
        AudioService->>AudioService: 校验 generation
        AudioService-->>UI: 更新歌曲信息
    end
```
```

---

#### 4. `docs/metadata.md` —— 元数据

```markdown
# 元数据

> *“歌曲信息是怎么被认识的？”*

---

## 数据来源

```
WebDAV 音频文件
    │
    ├── ID3 标签 (MP3)
    ├── Vorbis 注释 (OGG/FLAC)
    └── MP4 原子 (M4A)
```

---

## 读取流程

```
1. 检查内存缓存 → 命中则返回
2. 检查 SQLite → 命中则反序列化
3. 下载文件头部 (~1MB) 到临时目录
4. audio_metadata_reader 提取标签
5. MetadataNormalizer 标准化
6. 字段缺失时 fallback 到文件名/路径
7. 写入 SQLite 和内存缓存
8. 异步提取封面图
```

---

## 标准化与 Fallback

```dart
class MetadataNormalizer {
  String normalizeTitle(String? tag, String filename) {
    return tag?.isNotEmpty == true ? tag! : _extractFromFilename(filename);
  }

  String normalizeArtist(String? tag, String? album, String path) {
    return tag?.isNotEmpty == true ? tag! : _extractFromPath(path);
  }
}
```

优先级：**标签 > 文件名 > 路径推断**

---

## 封面图处理

```
artwork bytes (内存)
    ↓
保存到 /data/.../artworks/{md5(id)}.jpg
    ↓
通过 MethodChannel 调用 FileProvider
    ↓
content:// URI
    ↓
MediaItem.artUri → 通知中心
```

---

## 当前状态与未来

**已实现：**
- 一次读取 + fallback
- SQLite 持久化
- 封面图提取与推送

**计划中（渐进式识别）：**
- 5% 快速探测 (title/artist)
- 70% 完整探测 (album/genre/year)
- 100% 最终确认
- 置信度与校验次数记录
```

---

#### 5. `docs/android.md` —— Android 集成

```markdown
# Android 集成

> *“它怎么成为一个真正的 Android 播放器？”*

---

## 与系统的关系

```
Flutter (Dart)
    │
    ├── audio_service (桥接层)
    │
    ▼
Android MediaSession
    │
    ├── 通知中心 (播放/暂停/上一首/下一首/进度条)
    ├── 锁屏控制
    ├── 耳机按钮 (播放/暂停/切歌)
    └── Android Auto (预留)
```

---

## MediaSession 契约

清听遵循 Android 媒体应用的契约规范：

| 要求 | 清听实现 |
|:---|:---|
| 声明 `MediaAction.seek` | `systemActions` 中包含 |
| 使用 `playPause` 统一控制 | 不分离 play/pause |
| 正确更新 `updateTime` | 每次发布同步更新 |
| 前台服务 | 播放时启动 Foreground Service |

---

## 通知中心控制

| 控制 | 实现 |
|:---|:---|
| 播放/暂停 | `MediaAction.playPause` → `click(MediaButton.media)` |
| 上一首/下一首 | `MediaAction.skipToPrevious/Next` |
| 进度拖动 | `systemActions: {seek}` + `Handler.seek()` |
| 封面图 | `MediaItem.artUri = content://...` |

---

## FileProvider（封面图推送）

Android 10+ 禁止 `file://` 跨应用传递。

```
flutter_file_provider (不采用)
    ↓
MethodChannel: com.lxh.qingting_player/file_provider
    ↓
Kotlin: FileProvider.getUriForFile()
    ↓
content:// URI
```

**为什么不用插件？** 维护状态不确定，兼容性问题。显式边界更可控。

---

## 后台播放

```dart
await AudioService.start(
  backgroundTaskEntrypoint: _audioPlayerTaskEntrypoint,
  androidNotificationOngoing: false,
  androidStopForegroundOnPause: false,
);
```

- `ongoing: false`：暂停时不显示“正在运行”
- `stopForegroundOnPause: false`：暂停时仍保留前台状态，快速恢复
```

---

#### 6. `docs/storage.md` —— 存储策略

```markdown
# 存储策略

> *“远程数据和本地状态怎么共存？”*

---

## 两类数据

```
远程数据 (WebDAV)
    │
    ├── 音频文件 (流式播放，不缓存)
    └── 目录结构 (浏览用)
    │
本地数据 (设备存储)
    │
    ├── 元数据 (SQLite)
    ├── 封面图 (文件系统)
    └── 播放状态 (内存)
```

---

## 为什么不缓存音频文件？

- WebDAV 存储通常较大，本地存储有限
- 流式播放已足够，无需额外下载
- 版权/存储空间考量

> **只缓存“关于歌曲的信息”，不缓存歌曲本身。**

---

## SQLite 表结构

### songs

| 字段 | 说明 |
|:---|:---|
| `song_key` | WebDAV 路径 (唯一标识) |
| `title` | 歌曲标题 |
| `artist` | 艺术家 |
| `album` | 专辑 |
| `artwork_path` | 封面图本地路径 |
| `confidence` | 置信度 (预留) |
| `validation_count` | 校验次数 (预留) |

### metadata_cache

| 字段 | 说明 |
|:---|:---|
| `song_key` | 关联 songs |
| `cache_path` | 缓存文件路径 (预留) |
| `cache_created_at` | 创建时间 |

---

## 缓存策略

| 数据 | 缓存位置 | 有效期 |
|:---|:---|:---|
| 元数据 | SQLite | 永久 (除非 WebDAV 文件变更) |
| 封面图 | 文件系统 | 永久 |
| 播放进度 | 内存 | 会话级 |
| 队列 | 内存 | 会话级 |

> 元数据缓存的失效策略：当前以 `song_key` (WebDAV 路径) 为唯一标识，文件变更后重新读取。

---

## 文件目录

```
/data/data/com.lxh.qingting_player/
├── app_flutter/
│   ├── artworks/
│   │   └── {md5(id)}.jpg
│   └── temp/
│       └── metadata_*.tmp
└── databases/
    └── qingting.db
```
```

---

#### 7. `docs/decisions.md` —— 设计决策

```markdown
# 设计决策

> *“为什么最终选了这些方案？”*

每个决策三段：**问题 → 决策 → 原因**

---

## 为什么用 media_kit 而不是 just_audio？

**问题：** 需要稳定支持 WebDAV 流式播放和 MediaSession 集成。

**决策：** 选用 `media_kit`。

**原因：** `media_kit` 基于 libmpv，对流式 HTTP 支持更好，与 `audio_service` 集成更紧密。`just_audio` 虽社区更大，但对 MediaSession 的支持需要额外桥接。

---

## 为什么用 playPause 而非 play / pause 分离？

**问题：** 通知中心按钮状态偶尔错乱。

**决策：** 统一使用 `MediaAction.playPause`。

**原因：** Android MediaSession 对分离 action 的映射有特定逻辑，`playPause` 是系统原生支持的统一控制方式。

---

## 为什么不用 flutter_file_provider？

**问题：** 需要向通知中心传递 `content://` URI。

**决策：** 通过 `MethodChannel` 调用 Kotlin 侧原生 `FileProvider`。

**原因：** `flutter_file_provider` 插件维护状态不确定，Android 版本兼容性问题。显式平台边界更可控。

---

## 为什么引入 generation 机制？

**问题：** 切歌后，上一首歌的元数据返回会覆盖当前歌曲信息。

**决策：** 每次切歌递增 `_playbackGeneration`，异步回调校验身份。

**原因：** 防御性编程，处理异步竞态。这是清听保证 UI 状态永远属于当前歌曲的关键机制。

---

## 为什么用 SQLite？

**问题：** 需要持久化元数据，支持快速检索。

**决策：** 使用 `sqflite`。

**原因：** 边缘设备不需要 PostgreSQL；单文件备份复制即迁移；零配置零维护。

---

## 为什么进度更新节流到 500ms？

**问题：** 进度回调 (100ms/次) 导致频繁 UI 重建和通知刷新。

**决策：** 每 500ms 发布一次进度变化。

**原因：** 人眼对 500ms 的进度变化已足够流畅，在性能和体验之间取得平衡。
```

---

### ✅ 这套文档体系的特征

1. **沿着“一首歌的生命路径”组织** —— 从点击、播放、元数据、Android 集成到存储，自然连贯
2. **哲学融入架构，不单独成立文件** —— `architecture.md` 第一节讲原则，不做独立的 `philosophy.md`
3. **`playback.md` 是绝对核心** —— 清听最有价值的文档，讲述完整链路
4. **诚实区分已实现和计划中** —— `metadata.md` 明确标注当前状态与未来
5. **`decisions.md` 保持简洁** —— 每问三部分：问题 → 决策 → 原因，不加 ADR 编号
6. **没有“文档体系”的仪式感** —— 只有 7 个文档，每个回答一个具体问题

---

### 与 frpc-console 文档的差异

| 方面 | frpc-console | 清听 |
|:---|:---|:---|
| 核心主线 | 部署与长期运行 | 播放链路 |
| 关键文档 | `deployment-engine.md` | `playback.md` |
| 哲学位置 | 独立 `philosophy.md` | 融入 `architecture.md` |
| 平台文档 | `edge-node.md` (硬件边界) | `android.md` (系统边界) |
| 文档数量 | 10+ | 7 |
| 文档命名 | 抽象命名 (engineering-philosophy) | 直白命名 (playback, metadata) |

---

> **frpc-console**：这是一个系统应该如何被长期运行。
>
> **清听**：这是一个播放器应该如何让用户忘记系统正在运行。

两个项目共享同一套工程哲学，但拥有各自独立的文档骨架。