> **摘要**：本文深度记录了开源项目 Kt-Notepad 从传统 View 体系向全 Jetpack Compose 架构迁移的完整历程。我们将深入探讨 **单向数据流架构的设计**、**Android 分区存储（Scoped Storage）的攻坚**、**遗留数据的无缝迁移策略**以及**桌面级键盘快捷键的支持**。这不仅是一次代码的重写，更是一次对现代 Android 开发最佳实践的深度探索。
---
🚀一、架构重塑：单向数据流与 Compose 的协奏曲
1.1 告别 Fragment，拥抱纯粹的 Compose
在 Kt-Notepad 2.0 中，我们做出了一个大胆的决定：**完全移除 Fragment，构建纯 Compose 应用**。
传统的 Android 开发中，页面导航往往依赖于 `FragmentManager` 或 `Jetpack Navigation`，这在处理简单的状态切换时显得过于厚重。为了追求极致的轻量化和对“多窗口模式”（Multi-pane）的完美支持，我们在 `NotepadComposeApp.kt` 中设计了一套基于 **Sealed Class** 的轻量级状态导航系统。
// 导航状态定义：简洁而强大
sealed class NavState {
object Empty : NavState() // 空状态（如平板右侧未选中时）
data class View(val id: Long) : NavState() // 查看模式
data class Edit(val id: Long? = null) : NavState() // 编辑模式
}
任何时刻，UI 的显示内容仅由 `navState` 这一单一信源决定。这种设计使得我们在处理**平板双栏布局**时游刃有余：
- **手机模式**：`navState` 变化时，通过 `AnimatedVisibility` 进行全屏页面的切换动画。
- **平板模式**：左侧始终显示列表，右侧根据 `navState` 动态渲染 `ViewNoteContent` 或 `EditNoteContent`。
1.2 真正的数据驱动 UI (Unidirectional Data Flow)
在 `NotepadViewModel` 中，我们摒弃了传统的 `LiveData`，全面转向 `KeyFlow` 与 `StateFlow`。所有的用户操作（点击、输入）都被视为 **Action**，而所有的界面更新都主要依赖于 **State** 的快照。
这解决了传统 MVVM 中常见的“状态不一致”痛点。例如，在多选模式下删除笔记，UI 会自动响应该笔记从 `notes` 列表中消失的变化，无需手动通知 Adapter 刷新。
---
🛠️ 二、核心难题攻坚：驾驭 Android 分区存储 (Scoped Storage)
随着 Android 10/11 引入分区存储（Scoped Storage），传统的文件读写方式（直接访问 `/sdcard`）已不再也被允许。对于一款支持 **导入/导出** 功能的记事本应用，这是最大的技术挑战之一。
我们引入了“导入导出大师”模块 —— `ArtVandelay`（致敬 Seinfeld），并结合 `FSAF (File System Access Framework)` 库，优雅地解决了这一难题。
### 2.1 抽象化的文件交互接口
在 `ArtVandelay.kt` 中，我们将文件操作抽象为统一的接口，屏蔽了底层 `ContentResolver` 和 `Uri` 的复杂性：
```kotlin
interface ArtVandelay {
fun importNotes(...)
fun exportNotes(...)
fun exportSingleNote(
metadata: NoteMetadata,
filenameFormat: FilenameFormat, // 支持多种文件名格式
saveExportedNote: (OutputStream) -> Unit
)
}
```
2.2 灵活的导出策略
为了满足不同用户的需求，我们实现了高度定制化的导出逻辑。特别是在处理**文件名生成**时，我们需要确保文件名的合法性以及用户自定义格式的准确性（如 `TitleOnly` 或 `TimestampAndTitle`）：
```kotlin
private fun generateFilename(metadata: NoteMetadata, format: FilenameFormat): String {
val timestamp = dateFormat.format(metadata.date)
// 智能截断文件名，防止超出文件系统限制 (255字节)，并预留时间戳空间
return when(format) {
TitleOnly -> metadata.title.take(245)
TimestampAndTitle -> "${timestamp}_${metadata.title.take(245 - (timestamp.length + 1))}"
// ...
} + ".txt"
}
```
这一设计不仅保证了兼容性，更体现了我们在细节处理上的严谨。
---
💾 三、数据迁移的艺术：一场“无感”的手术
从旧版本的 **基于文件存储 + SharedPreferences** 迁移到新版本的 **Room 数据库 + DataStore**，就好比在飞机飞行过程中更换引擎。任何一点差错都会导致用户长年积累的笔记丢失，这是 absolutely unacceptable 的。
我们在 `DataMigrator.kt` 中设计了一套严密的迁移机制：
1. **原子性检测**：利用 `migration_complete` 标记文件，确保迁移逻辑只执行一次。
2. **Legacy 数据清洗**：
- 扫描 `filesDir`，过滤掉非数字命名的文件（旧版笔记以时间戳命名）。
- 读取文件内容，提取首行作为标题，构建 `NoteMetadata`。
- 将内容插入 SQLDelight 生成的数据库接口。
3. **配置项迁移**：
- 使用 `SharedPreferencesMigration` 将旧配置无缝迁移至 Jetpack DataStore。
- 甚至处理了复杂的格式转换，例如将旧的 `Theme` 字符串拆解为新的 `ColorScheme` 和 `FontType`。
```kotlin
// DataMigrator.kt 核心逻辑片段
override suspend fun migrate() = withContext(Dispatchers.IO) {
if (!notesMigrationComplete.exists()) {
// ... 遍历文件，解析，插入数据库 ...
with(database) {
noteMetadataQueries.insert(metadata)
noteContentsQueries.insert(contents)
}
File(context.filesDir, filename).delete() // 只有在数据库插入成功后才删除源文件
}
}
```
这种防御性的编程方式，确保了用户更新应用后，能立即看到熟悉的数据以全新的面貌呈现。
---
🎨 四、创新与体验：打造 Android 平台的“桌面级”体验
4.1 硬件键盘的一等公民待遇
很多 Android 应用都忽视了外接键盘体验，但 Kt-Notepad 旨在涵盖 Chromebook 和平板用户。我们在 `KeyboardShortcuts.kt` 中实现了完整的快捷键映射：
- `Ctrl + N`：新建笔记
- `Ctrl + S`：保存
- `Ctrl + E`：进入编辑模式
- `Ctrl + D`：删除笔记
这使得专业用户可以双手不离键盘完成所有核心操作，极大提升了生产力。
4.2 极致的 RTL (Right-to-Left) 支持
为了服务全球用户，我们在 `RtlTextWrapper` 中不仅仅是依赖系统的自动镜像，而是针对文本编辑场景做了深度适配，确保阿拉伯语或希伯来语用户在混排英文时，光标移动和文本对齐完全符合直觉。
---
🌟 总结
Kt-Notepad 2.0 的重构不仅仅是技术的堆砌，更是对 **Clean Architecture**、**Modern Android Development (MAD)** 理念的一次完整实践。
- **架构上**，我们证明了 Compose + StateFlow 在处理复杂状态应用时的优越性。
- **技术上**，我们攻克了 Scoped Storage 和数据迁移等底层难题。
- **体验上**，我们通过细节打磨（动画、快捷键、无障碍支持），让一款开源应用拥有了商业软件的质感。
我们相信，好的代码不仅是用来运行的，更是用来阅读和传承的。希望 Kt-Notepad 的源码能为 Android 开发者社区带来新的灵感。
