一、用途 room-kmp-setup 整理的是在 Kotlin 多平台项目中搭建一个跨 Android、JVM/桌面和 iOS 共享的 Room 数据库所需的工程配置。它适用于希望数据库代码只写一份、而非各平台分别维护的场景。
二、主要能力与结构 数据库类、实体、DAO 和类型转换器放在 commonMain。每个平台只通过一个 expect 函数提供 RoomDatabase.Builder，资料给出的形式为 expect fun getDatabaseBuilder(converters: Converters): RoomDatabase.Builder<MusicDatabase>。驱动和查询调度器在共享依赖注入点一次性设置：setDriver(BundledSQLiteDriver()) 与 setQueryCoroutineContext(Dispatchers.IO)，避免各平台不一致。 三个 actual 的差异仅在 databaseBuilder 的重载：JVM 与 iOS 传入绝对文件路径作为 name，Android 传入 context、数据库类和裸文件名。
三、已知陷阱
- 注解处理器需按目标逐一声明，例如 kspAndroid、kspJvm、kspIosArm64、kspIosSimulatorArm64 各一条；漏掉一个目标时源码能编译通过，但链接阶段会因缺少生成的数据库实现而失败。
- 注册在 builder 上的迁移、addCallback、破坏性回退策略和 open-helper 调整只存在于写了它们的平台 actual 中。资料中的代码库把手写迁移和重建触发器的 onOpen 回调只放在 Android actual，JVM 与 iOS 不会获得这些行为，也没有任何警告。建议把共享内容放入 common 扩展，actual 只保留路径处理。
- expect 签名是各平台交集，无法接收 Android Context，因此 Android actual 通过服务定位器获取；这要求容器在数据库单例创建前已持有 Context，构建策略为急切初始化时需先注册 Context。
- 必须通过 room { schemaDirectory("$projectDir/schemas") } 导出 schema 并提交每个 <version>.json；生成迁移依赖对两个导出 schema 做差异比较，删除旧文件不会破坏构建，但会破坏仍停留在该版本用户的升级路径。
- bundled 驱动按 CPU 架构提供原生切片，缺一个切片就会使整个目标失败。资料给出审计命令：解压对应 sqlite-bundled-jvm 版本的 JAR，列出 natives/ 目录。需先确定实际构建版本，因为 Gradle 缓存中可能包含多个历史版本。资料提到某个版本缺少 Windows ARM 切片，而该仓库锁定的 2.7.0 版本缺少 osx_x64（Intel Mac）切片，说明应针对自己的版本重新运行审计。
- 驱动选择与原生链接配置在不同文件中：iOS framework 可能声明 linkerOpts.add("-lsqlite3")，而共享 DI 安装的是 bundled 驱动。两者互不提及，应在注入点记录日志或断点确认运行时实际使用的驱动。
- 类型转换器通过构造函数注入，是数据库的依赖；其所需依赖（如 JSON 格式、时钟）必须在数据库创建前可构造，注册为独立的急切创建单例可使顺序显式化。
四、验证方式 资料建议在仓库根目录运行命令：从 gradle/libs.versions.toml 读取 sqlite 版本并审计对应 JAR 的 natives 切片；用 grep 检查 addMigrations/addCallback 是否只出现在 Android actual；用 grep 检查 ksp 声明列表与声明目标列表是否一一对应。手工验证则是在桌面与 iOS 构建的注入点记录实际驱动。
五、限制 资料仅覆盖上述平台的 Room 配置与审计方法，未提供其他平台、其他数据库或完整示例工程的信息；具体版本行为需按实际锁定版本复核。