数据库系统与 Room

// 继承 SQLiteOpenHelper，管理名为 "app.db" 的数据库
class AppDatabaseHelper(
    context: Context // 需要 Context 来定位数据库文件路径
) : SQLiteOpenHelper(
    context,        // 上下文，用于获取 /data/data/<pkg>/databases/ 路径
    "app.db",       // 数据库文件名
    null,           // CursorFactory，通常传 null 使用默认实现
    1               // 数据库版本号，首次发布为 1
) {
 
    // 数据库文件首次创建时回调（整个应用生命周期内通常只执行一次）
    override fun onCreate(db: SQLiteDatabase) {
        // 执行原始 SQL 建表语句
        // TEXT 对应 Kotlin 的 String 类型
        // INTEGER 对应 Kotlin 的 Int/Long 类型
        // PRIMARY KEY AUTOINCREMENT 表示自增主键
        db.execSQL(
            """
            CREATE TABLE user (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                name TEXT NOT NULL,
                email TEXT,
                created_at INTEGER NOT NULL
            )
            """.trimIndent()
        )
    }
 
    // 数据库版本号发生变化时回调（oldVersion < newVersion 时触发）
    override fun onUpgrade(
        db: SQLiteDatabase, // 当前数据库实例
        oldVersion: Int,     // 数据库文件中记录的旧版本号
        newVersion: Int      // 构造函数中传入的新版本号
    ) {
        // 简单粗暴的策略：删表重建（生产环境不推荐，会丢失用户数据）
        db.execSQL("DROP TABLE IF EXISTS user")
        // 重新走 onCreate() 建表流程
        onCreate(db)
    }
}

-- 创建用户表，展示常见约束的使用
CREATE TABLE IF NOT EXISTS user (
    -- INTEGER PRIMARY KEY 在 SQLite 中即为 rowid 的别名
    -- AUTOINCREMENT 保证 id 严格递增，即使删除旧行后也不会复用 id
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    -- NOT NULL 约束：该列不允许为空
    name TEXT NOT NULL,
    -- UNIQUE 约束：该列值在全表中不允许重复
    email TEXT UNIQUE,
    -- DEFAULT 约束：插入时未指定该列则使用默认值
    age INTEGER DEFAULT 0,
    -- CHECK 约束：插入/更新时检查条件是否满足
    status INTEGER CHECK(status IN (0, 1, 2)),
    -- 外键引用（需要额外开启 PRAGMA foreign_keys = ON）
    department_id INTEGER REFERENCES department(id)
);
 
-- 创建索引以加速按 email 的查询（B-Tree 索引）
CREATE INDEX idx_user_email ON user(email);
 
-- 创建复合索引（多列联合索引，遵循最左前缀匹配原则）
CREATE INDEX idx_user_name_age ON user(name, age);

// 获取数据库实例（通常在后台线程中执行）
val db = helper.writableDatabase
 
// ========== INSERT 插入 ==========
// 方式一：使用 ContentValues（Framework 推荐方式，防 SQL 注入）
val values = ContentValues().apply {
    // put() 方法会根据值类型自动选择正确的绑定方式
    put("name", "张三")          // TEXT 类型
    put("email", "zs@test.com") // TEXT 类型
    put("created_at", System.currentTimeMillis()) // INTEGER 类型
}
// insert() 返回新插入行的 rowid，失败返回 -1
// 第二个参数 nullColumnHack：当 values 为空时，指定一个列名用 NULL 填充
val newRowId = db.insert(
    "user",      // 表名
    null,        // nullColumnHack，通常传 null
    values       // 要插入的列-值映射
)
 
// 方式二：使用原始 SQL（灵活但需自行防注入）
db.execSQL(
    // 使用 ? 占位符进行参数绑定，避免 SQL 注入攻击
    "INSERT INTO user (name, email, created_at) VALUES (?, ?, ?)",
    // 参数数组，按顺序替换 ? 占位符
    arrayOf("李四", "ls@test.com", System.currentTimeMillis())
)
 
// ========== SELECT 查询 ==========
// query() 方法提供了结构化的查询参数
val cursor = db.query(
    "user",                          // FROM 表名
    arrayOf("id", "name", "email"),  // SELECT 的列（null 表示 *）
    "age > ? AND status = ?",        // WHERE 子句（用 ? 占位）
    arrayOf("18", "1"),              // WHERE 参数值（全部为 String 类型）
    null,                            // GROUP BY
    null,                            // HAVING
    "created_at DESC",               // ORDER BY
    "20"                             // LIMIT
)
 
// ========== UPDATE 更新 ==========
val updateValues = ContentValues().apply {
    put("name", "王五")   // 要更新的列和新值
    put("age", 25)        // 可同时更新多列
}
// update() 返回受影响的行数
val affectedRows = db.update(
    "user",          // 表名
    updateValues,    // 新值
    "id = ?",        // WHERE 条件
    arrayOf("1")     // WHERE 参数
)
 
// ========== DELETE 删除 ==========
// delete() 返回被删除的行数
val deletedRows = db.delete(
    "user",          // 表名
    "status = ?",    // WHERE 条件（传 null 则删除全表数据）
    arrayOf("0")     // WHERE 参数
)

val db = helper.writableDatabase
 
// beginTransaction() 开启一个 EXCLUSIVE 事务
// 内部执行 SQL: BEGIN EXCLUSIVE
db.beginTransaction()
try {
    // --- 事务体：在这里执行所有数据库操作 ---
 
    // 插入第一条记录
    db.execSQL(
        "INSERT INTO user (name, email, created_at) VALUES (?, ?, ?)",
        arrayOf("用户A", "a@test.com", System.currentTimeMillis())
    )
    // 插入第二条记录
    db.execSQL(
        "INSERT INTO user (name, email, created_at) VALUES (?, ?, ?)",
        arrayOf("用户B", "b@test.com", System.currentTimeMillis())
    )
 
    // 标记事务成功（必须在 endTransaction() 之前调用）
    // 如果不调用此方法，endTransaction() 会执行 ROLLBACK 而非 COMMIT
    db.setTransactionSuccessful()
} catch (e: Exception) {
    // 发生异常时不调用 setTransactionSuccessful()
    // endTransaction() 会自动回滚
    Log.e("DB", "事务执行失败，即将回滚", e)
} finally {
    // endTransaction() 检查是否调用过 setTransactionSuccessful()
    // 是 → 执行 COMMIT; 否 → 执行 ROLLBACK
    db.endTransaction()
}

// 使用 KTX 扩展函数，内部自动管理 begin/setSuccessful/end
// 如果 lambda 正常返回则 COMMIT，抛出异常则 ROLLBACK
db.transaction {
    // this 即 SQLiteDatabase 实例，可以直接调用 execSQL / insert 等方法
    execSQL(
        "INSERT INTO user (name, email, created_at) VALUES (?, ?, ?)",
        arrayOf("用户C", "c@test.com", System.currentTimeMillis())
    )
    execSQL(
        "INSERT INTO user (name, email, created_at) VALUES (?, ?, ?)",
        arrayOf("用户D", "d@test.com", System.currentTimeMillis())
    )
    // 无需手动调用 setTransactionSuccessful()，lambda 正常结束即代表成功
}

// 执行原始 SQL 查询，返回 Cursor
// rawQuery 的第二个参数是绑定参数数组，防止 SQL 注入
val cursor: Cursor = db.rawQuery(
    "SELECT id, name, email, created_at FROM user WHERE age > ?",
    arrayOf("18") // 参数值始终为 String 类型，SQLite 内部按亲和性转换
)
 
// 使用 Kotlin 的 use {} 扩展函数（等价于 try-finally + close）
// use {} 会在 lambda 结束后自动调用 cursor.close()
cursor.use { c ->
    // getColumnIndexOrThrow() 通过列名获取列索引
    // 相比 getColumnIndex()，它在列名不存在时抛出异常而非返回 -1
    val idIndex = c.getColumnIndexOrThrow("id")           // 列索引 0
    val nameIndex = c.getColumnIndexOrThrow("name")       // 列索引 1
    val emailIndex = c.getColumnIndexOrThrow("email")     // 列索引 2
    val createdAtIndex = c.getColumnIndexOrThrow("created_at") // 列索引 3
 
    // moveToNext() 将游标移动到下一行
    // 首次调用时从"第 -1 行"（即起始位置 Before First）移动到第 0 行
    // 如果没有更多行则返回 false，循环结束
    while (c.moveToNext()) {
        // 根据列索引和数据类型调用对应的 get 方法
        val id = c.getLong(idIndex)            // 读取 INTEGER 类型为 Long
        val name = c.getString(nameIndex)      // 读取 TEXT 类型为 String
        // 注意：如果该列可能为 NULL，应先用 isNull() 检查
        val email = if (c.isNull(emailIndex)) {
            null                               // 列值为 NULL 时返回 null
        } else {
            c.getString(emailIndex)            // 列值不为 NULL 时正常读取
        }
        val createdAt = c.getLong(createdAtIndex) // 时间戳存为 INTEGER
 
        // 此处可将数据封装为实体对象
        Log.d("DB", "User: id=$id, name=$name, email=$email")
    }
    // while 循环结束意味着游标已遍历完所有行
    // use {} 会在此处自动调用 c.close() 释放资源
}

┌───────────────────────────────────────────────────────────┐
│                     SQLiteCursor                          │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  mQuery: "SELECT id, name... WHERE age > ?"        │  │
│  │  mPosition: 3  (当前游标指向第 3 行)                  │  │
│  │  mCount: 1000  (总结果行数)                          │  │
│  └─────────────────────────────────────────────────────┘  │
│                          │                                │
│                          ▼                                │
│  ┌─────────────────────────────────────────────────────┐  │
│  │             CursorWindow (2MB 共享内存)               │  │
│  │  ┌───────┬────────┬─────────┬────────────────────┐  │  │
│  │  │ Row 0 │ Row 1  │  Row 2  │  Row 3 ← 当前位置  │  │  │
│  │  ├───────┼────────┼─────────┼────────────────────┤  │  │
│  │  │ Row 4 │ Row 5  │  Row 6  │  ...               │  │  │
│  │  ├───────┼────────┼─────────┼────────────────────┤  │  │
│  │  │  ...  │ Row N  │ (空闲)  │  (空闲)             │  │  │
│  │  └───────┴────────┴─────────┴────────────────────┘  │  │
│  │  ↑ 一次加载尽可能多的行，直到填满 2MB              ↑  │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  当 moveToPosition() 超出已加载范围时：                     │
│  → 重新执行查询                                            │
│  → 清空 CursorWindow                                      │
│  → 从目标位置开始重新填充                                   │
└───────────────────────────────────────────────────────────┘

// 使用 @Entity 标注，表名默认取类名 "User"（可通过 tableName 自定义）
@Entity(tableName = "users")
data class User(
    // @PrimaryKey 标记主键列；autoGenerate = true 表示自增
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
 
    // @ColumnInfo 可自定义列名；不写则默认使用字段名
    @ColumnInfo(name = "user_name")
    val name: String,
 
    // Kotlin 的 Int 类型自动映射为 SQLite 的 INTEGER
    val age: Int,
 
    // Kotlin 的 String? 表示该列允许 NULL
    val email: String? = null
)

-- Room 编译期自动生成的建表语句（开发者无需手写）
CREATE TABLE IF NOT EXISTS `users` (
    `id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
    `user_name` TEXT NOT NULL,
    `age` INTEGER NOT NULL,
    `email` TEXT
);

// @Dao 标注的接口，Room 会自动生成其实现类（命名规则：类名_Impl）
@Dao
interface UserDao {
 
    // @Insert 注解：Room 自动生成 INSERT INTO users VALUES(...) 语句
    // onConflict 指定主键冲突时的策略，REPLACE 表示覆盖旧数据
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUser(user: User)
 
    // @Query 注解：直接书写 SQL，Room 在编译时验证语法和表名/列名
    // 返回值 Flow<List<User>> 表示数据变化时自动推送新列表
    @Query("SELECT * FROM users WHERE age > :minAge ORDER BY user_name")
    fun getUsersOlderThan(minAge: Int): Flow<List<User>>
 
    // @Delete 注解：Room 根据主键匹配删除对应行
    @Delete
    suspend fun deleteUser(user: User)
}

// Entity 中定义的列名是 "user_name"
@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Long,
    @ColumnInfo(name = "user_name") val name: String
)
 
@Dao
interface UserDao {
    // 错误：SQL 中使用了 "username" 而不是 "user_name"
    @Query("SELECT * FROM users WHERE username = :name")
    fun findByName(name: String): User?
}

// 自定义返回类型，包含 Entity 中不存在的字段
data class UserSummary(
    val id: Long,
    val name: String,
    val address: String  // users 表中没有 address 列
)
 
@Dao
interface UserDao {
    // Room 会警告：UserSummary 中的 address 字段无法从查询结果中填充
    @Query("SELECT id, user_name AS name FROM users")
    fun getAllSummaries(): List<UserSummary>
}

@Dao
interface UserDao {
    // 错误：SQL 中有 :minAge 和 :maxAge 两个参数，但方法签名只提供了 minAge
    @Query("SELECT * FROM users WHERE age BETWEEN :minAge AND :maxAge")
    fun findUsersInAgeRange(minAge: Int): List<User>
}

// ============ KAPT 方式（旧，逐步被淘汰）============
plugins {
    // 启用 kapt 插件
    id("kotlin-kapt")
}
dependencies {
    // Room 注解处理器通过 kapt 配置
    kapt("androidx.room:room-compiler:2.6.1")
}
 
// ============ KSP 方式（推荐）============
plugins {
    // 启用 ksp 插件，版本需与 Kotlin 版本匹配
    id("com.google.devtools.ksp") version "1.9.21-1.0.15"
}
dependencies {
    // Room 注解处理器通过 ksp 配置
    ksp("androidx.room:room-compiler:2.6.1")
}

// version = 1 表示这是数据库的第一个版本
// entities 数组列出所有参与建表的 Entity 类
@Database(
    entities = [User::class, Order::class],
    version = 1,                               // 当前 Schema 版本
    exportSchema = true                         // 是否导出 Schema JSON 文件
)
abstract class AppDatabase : RoomDatabase() {
    // 声明 DAO 的抽象获取方法，Room 在 _Impl 中实现
    abstract fun userDao(): UserDao
    abstract fun orderDao(): OrderDao
}

// 在模块的 build.gradle.kts 中配置 Schema 导出路径
ksp {
    // Room 的 Schema JSON 文件将输出到 schemas/ 目录
    arg("room.schemaLocation", "$projectDir/schemas")
}

app/schemas/
  └── com.example.data.AppDatabase/
      ├── 1.json    ← 版本 1 的 Schema 快照
      ├── 2.json    ← 版本 2 的 Schema 快照
      └── 3.json    ← 版本 3 的 Schema 快照

{
  "formatVersion": 1,
  "database": {
    "version": 1,
    "identityHash": "a1b2c3d4e5f6...",
    "entities": [
      {
        "tableName": "users",
        "createSql": "CREATE TABLE IF NOT EXISTS `users` (`id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, `user_name` TEXT NOT NULL, `age` INTEGER NOT NULL, `email` TEXT)",
        "fields": [
          { "fieldPath": "id", "columnName": "id", "affinity": "INTEGER", "notNull": true },
          { "fieldPath": "name", "columnName": "user_name", "affinity": "TEXT", "notNull": true }
        ],
        "primaryKey": { "columnNames": ["id"], "autoGenerate": true },
        "indices": []
      }
    ]
  }
}

-- Room 内部维护的元数据表，开发者通常不需要直接操作
CREATE TABLE IF NOT EXISTS room_master_table (
    id INTEGER PRIMARY KEY,
    identity_hash TEXT
);

// 使用 @Entity 注解将此 data class 标记为一张数据库表
// tableName 参数指定表名；若省略，则默认使用类名 "User" 作为表名
@Entity(tableName = "users")
data class User(
    // @PrimaryKey 标记此字段为主键
    // autoGenerate = true 表示由 SQLite 自动分配递增的整型 ID
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0L,
 
    // @ColumnInfo 允许自定义列名，这里将字段 firstName 映射到列 "first_name"
    // 若省略 @ColumnInfo，列名默认与字段名相同（即 "firstName"）
    @ColumnInfo(name = "first_name")
    val firstName: String,
 
    // 同理，将 lastName 映射为 "last_name" 列
    @ColumnInfo(name = "last_name")
    val lastName: String,
 
    // 未加 @ColumnInfo，列名默认为 "email"
    val email: String,
 
    // @Ignore 标记的字段不会被映射为数据库列
    // 适用于仅在内存中使用的临时计算字段
    @Ignore
    val fullName: String = ""
)

-- Room 编译时自动生成的建表语句（等价形式）
CREATE TABLE IF NOT EXISTS `users` (
    `id`         INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
    `first_name` TEXT NOT NULL,
    `last_name`  TEXT NOT NULL,
    `email`      TEXT NOT NULL
    -- 注意：fullName 因 @Ignore 不会出现在表中
);

// 最常见的自增主键模式
@Entity(tableName = "articles")
data class Article(
    // autoGenerate = true 底层使用 SQLite 的 AUTOINCREMENT 关键字
    // 保证 ID 单调递增，即使删除记录后也不会复用已有 ID
    @PrimaryKey(autoGenerate = true)
    val articleId: Long = 0L,     // 默认值 0L 表示"尚未插入数据库"
 
    val title: String,
    val content: String
)

// 复合主键通过 @Entity 的 primaryKeys 参数声明
// 此时不再在字段上使用 @PrimaryKey 注解
@Entity(
    tableName = "enrollments",
    primaryKeys = ["userId", "courseId"]   // 联合主键：userId + courseId
)
data class Enrollment(
    val userId: Long,       // 学生 ID（外键指向 users 表）
    val courseId: Long,     // 课程 ID（外键指向 courses 表）
    val enrollDate: Long    // 选课时间戳
)

@Entity(
    tableName = "users",
    // indices 参数接收一个 Index 注解数组
    indices = [
        // 单列索引：加速按 email 查询
        // unique = true 表示唯一索引，同一 email 不允许重复
        Index(value = ["email"], unique = true),
 
        // 复合索引：加速同时按 last_name + first_name 查询
        // 注意复合索引的列顺序很重要（最左前缀原则）
        Index(value = ["last_name", "first_name"])
    ]
)
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0L,
 
    @ColumnInfo(name = "first_name")
    val firstName: String,
 
    @ColumnInfo(name = "last_name")
    val lastName: String,
 
    // 也可以直接在 @ColumnInfo 上声明 index = true（简写形式，单列非唯一索引）
    @ColumnInfo(index = true)
    val email: String
)

// 带外键约束的 Entity 示例
@Entity(
    tableName = "articles",
    // 声明外键：articles.authorId 引用 users.id
    foreignKeys = [
        ForeignKey(
            entity = User::class,           // 父表实体类
            parentColumns = ["id"],          // 父表主键列
            childColumns = ["authorId"],     // 子表外键列
            onDelete = ForeignKey.CASCADE    // 父记录删除时级联删除子记录
        )
    ],
    // Room 强烈建议为外键列建索引（否则编译会警告）
    indices = [Index("authorId")]
)
data class Article(
    @PrimaryKey(autoGenerate = true)
    val articleId: Long = 0L,
 
    // 外键列：引用 users 表的 id
    val authorId: Long,
 
    val title: String,
    val content: String
)

// @Dao 注解声明这是一个数据访问对象接口
// Room 会在编译时生成 UserDao_Impl 实现类
@Dao
interface UserDao {
 
    // ==================== @Insert 插入 ====================
 
    // 插入单个用户对象
    // onConflict 指定冲突策略：若主键或唯一索引冲突，用新数据替换旧行
    // 返回值 Long 为插入后自动生成的 rowId（主键值）
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUser(user: User): Long
 
    // 插入多个用户（支持 List / 可变参数）
    // 返回 List<Long>，包含每个插入对象的 rowId
    @Insert
    suspend fun insertUsers(users: List<User>): List<Long>
 
    // ==================== @Update 更新 ====================
 
    // 根据主键匹配，更新对应行的所有列
    // 返回 Int 表示受影响的行数（成功更新了几行）
    @Update
    suspend fun updateUser(user: User): Int
 
    // ==================== @Delete 删除 ====================
 
    // 根据主键匹配，删除对应行
    // 返回 Int 表示实际删除的行数
    @Delete
    suspend fun deleteUser(user: User): Int
 
    // ==================== @Query 自定义查询 ====================
 
    // 查询所有用户，按 last_name 升序排列
    // Room 在编译时验证 SQL 语法和列名是否匹配 Entity 定义
    @Query("SELECT * FROM users ORDER BY last_name ASC")
    suspend fun getAllUsers(): List<User>
 
    // 带参数查询：":userId" 会绑定到方法参数 userId
    // Room 使用 PreparedStatement 实现参数绑定，天然防止 SQL 注入
    @Query("SELECT * FROM users WHERE id = :userId")
    suspend fun getUserById(userId: Long): User?
 
    // 多参数查询 + IN 操作符
    @Query("SELECT * FROM users WHERE id IN (:userIds)")
    suspend fun getUsersByIds(userIds: List<Long>): List<User>
 
    // 模糊查询：注意 LIKE 的参数需要在调用时自行拼接 % 通配符
    // 例如调用时传 "%张%" 来搜索名字包含"张"的用户
    @Query("SELECT * FROM users WHERE first_name LIKE :namePattern")
    suspend fun searchByName(namePattern: String): List<User>
 
    // 聚合查询：返回用户总数
    @Query("SELECT COUNT(*) FROM users")
    suspend fun getUserCount(): Int
 
    // 返回部分列：不一定非要返回完整 Entity，可以返回自定义 POJO
    @Query("SELECT first_name, last_name FROM users WHERE id = :userId")
    suspend fun getUserName(userId: Long): UserName?
 
    // 删除操作也可以用 @Query（当你需要条件删除而非按主键删除时）
    @Query("DELETE FROM users WHERE id = :userId")
    suspend fun deleteUserById(userId: Long)
 
    // ==================== Flow 响应式查询 ====================
 
    // 返回 Flow<List<User>>：当 users 表发生任何变化时
    // Room 的 InvalidationTracker 会自动触发重新查询并发射新数据
    @Query("SELECT * FROM users ORDER BY last_name ASC")
    fun observeAllUsers(): Flow<List<User>>
}

// 部分列查询的返回类型（不需要 @Entity 注解）
// Room 要求字段名与 SQL SELECT 中的列名（或别名）一一对应
data class UserName(
    @ColumnInfo(name = "first_name")
    val firstName: String,          // 对应 SELECT 中的 first_name
 
    @ColumnInfo(name = "last_name")
    val lastName: String            // 对应 SELECT 中的 last_name
)

@Dao
interface UserDao {
 
    // @Transaction 确保方法内的所有数据库操作在同一个事务中执行
    // 要么全部成功，要么全部回滚
    @Transaction
    suspend fun replaceAllUsers(newUsers: List<User>) {
        // 第一步：清空旧数据
        deleteAllUsers()
        // 第二步：插入新数据
        // 如果插入过程中任何一条失败，deleteAllUsers 也会回滚
        insertUsers(newUsers)
    }
 
    @Query("DELETE FROM users")
    suspend fun deleteAllUsers()
 
    @Insert
    suspend fun insertUsers(users: List<User>)
}

// 使用 abstract class 形式的 DAO，支持编写带方法体的事务方法
@Dao
abstract class UserDao {
 
    // 抽象方法：由 Room 自动生成实现
    @Insert
    abstract suspend fun insertUsers(users: List<User>): List<Long>
 
    @Query("DELETE FROM users")
    abstract suspend fun deleteAllUsers()
 
    // 具体方法 + @Transaction：手动组合多个原子操作
    @Transaction
    open suspend fun replaceAllUsers(newUsers: List<User>) {
        deleteAllUsers()          // 清空
        insertUsers(newUsers)     // 重新插入
    }
}

// 地址值对象 —— 不需要 @Entity 注解，它不会生成独立的表
data class Address(
    val street: String,   // 街道，将成为 User 表的 street 列
    val city: String,     // 城市，将成为 User 表的 city 列
    val zipCode: String   // 邮编，将成为 User 表的 zipCode 列
)
 
// 用户实体 —— @Embedded 将 Address 的三个字段"平铺"进 user 表
@Entity(tableName = "user")
data class User(
    @PrimaryKey
    val userId: Long,             // 主键列
    val userName: String,         // 用户名列
    @Embedded                      // 关键注解：将 Address 的字段展开到 user 表
    val address: Address          // 实际不会生成名为 address 的列
)

-- Room 自动生成的建表语句（概念等价）
CREATE TABLE user (
    userId   INTEGER PRIMARY KEY NOT NULL,  -- 来自 User.userId
    userName TEXT NOT NULL,                  -- 来自 User.userName
    street   TEXT NOT NULL,                  -- 来自 Address.street（被展开）
    city     TEXT NOT NULL,                  -- 来自 Address.city（被展开）
    zipCode  TEXT NOT NULL                   -- 来自 Address.zipCode（被展开）
);

@Entity(tableName = "shipment")
data class Shipment(
    @PrimaryKey
    val shipmentId: Long,
    @Embedded(prefix = "from_")   // 所有 Address 字段前加 "from_" 前缀
    val fromAddress: Address,     // 生成列：from_street, from_city, from_zipCode
    @Embedded(prefix = "to_")     // 所有 Address 字段前加 "to_" 前缀
    val toAddress: Address        // 生成列：to_street, to_city, to_zipCode
)

// 关系容器类（不是 Entity，也不建表）
data class UserWithOrders(
    @Embedded                    // 标记父实体，Room 据此获取父表的列信息
    val user: User,
    @Relation(...)               // 标记子实体列表
    val orders: List<Order>
)

// ========== 父实体：用户 ==========
@Entity(tableName = "user")
data class User(
    @PrimaryKey
    val userId: Long,       // 父表主键
    val userName: String    // 用户名
)
 
// ========== 子实体：用户详情 ==========
@Entity(
    tableName = "user_profile",
    foreignKeys = [                          // 可选：声明外键约束
        ForeignKey(
            entity = User::class,            // 引用的父实体类
            parentColumns = ["userId"],      // 父表的关联列
            childColumns = ["profileUserId"],// 子表的外键列
            onDelete = ForeignKey.CASCADE    // 父记录删除时级联删除子记录
        )
    ]
)
data class UserProfile(
    @PrimaryKey
    val profileId: Long,         // 详情表自己的主键
    val profileUserId: Long,     // 外键列，引用 user.userId
    val bio: String,             // 个人简介
    val avatarUrl: String        // 头像链接
)

// ========== 关系容器类 ==========
data class UserWithProfile(
    @Embedded                               // 父实体通过 @Embedded 嵌入
    val user: User,                         // Room 从查询结果中提取 User 的列
    @Relation(
        parentColumn = "userId",            // 父表的关联列（User.userId）
        entityColumn = "profileUserId"      // 子表的关联列（UserProfile.profileUserId）
    )
    val profile: UserProfile                // 一对一：单个对象，不是 List
)

@Dao
interface UserDao {
    // 只需查询父表，Room 会自动生成子查询来获取关联的 UserProfile
    @Transaction   // 必须加 @Transaction，保证父查询和子查询的原子性
    @Query("SELECT * FROM user WHERE userId = :id")
    suspend fun getUserWithProfile(id: Long): UserWithProfile?
 
    // 批量查询所有用户及其详情
    @Transaction
    @Query("SELECT * FROM user")
    fun getAllUsersWithProfiles(): Flow<List<UserWithProfile>>
}

// ===== Room 编译期自动生成的代码（简化版伪代码） =====
override suspend fun getUserWithProfile(id: Long): UserWithProfile? {
    // 第一步：开启事务
    return database.withTransaction {
        // 第二步：执行开发者写的 SQL，查询父表
        val userCursor = query("SELECT * FROM user WHERE userId = ?", arrayOf(id))
        val user = parseUser(userCursor)          // 从 Cursor 解析 User 对象
        if (user == null) return@withTransaction null
 
        // 第三步：自动生成的子查询（开发者不需要写这段 SQL）
        // Room 根据 @Relation 的 parentColumn 和 entityColumn 生成
        val profileCursor = query(
            "SELECT * FROM user_profile WHERE profileUserId = ?",
            arrayOf(user.userId)                   // 用父实体的 userId 作为查询条件
        )
        val profile = parseUserProfile(profileCursor) // 解析 UserProfile 对象
 
        // 第四步：组装容器对象并返回
        UserWithProfile(user = user, profile = profile)
    }
}

// ========== 父实体：用户 ==========
@Entity(tableName = "user")
data class User(
    @PrimaryKey
    val userId: Long,       // 父表主键
    val userName: String    // 用户名
)
 
// ========== 子实体：订单 ==========
@Entity(
    tableName = "order_table",                // "order" 是 SQL 保留字，需换名
    foreignKeys = [
        ForeignKey(
            entity = User::class,             // 引用父实体
            parentColumns = ["userId"],       // 父表关联列
            childColumns = ["orderUserId"],   // 子表外键列
            onDelete = ForeignKey.CASCADE     // 级联删除
        )
    ],
    indices = [Index("orderUserId")]          // 外键列建索引，加速 JOIN 查询
)
data class Order(
    @PrimaryKey(autoGenerate = true)
    val orderId: Long = 0,       // 订单主键，自增
    val orderUserId: Long,       // 外键列，指向 user.userId
    val product: String,         // 商品名
    val amount: Double           // 金额
)
 
// ========== 一对多关系容器 ==========
data class UserWithOrders(
    @Embedded                                 // 嵌入父实体
    val user: User,
    @Relation(
        parentColumn = "userId",              // 父表关联列
        entityColumn = "orderUserId"          // 子表关联列
    )
    val orders: List<Order>                   // 一对多：List 类型
)

@Dao
interface UserDao {
    // 查询单个用户及其所有订单
    @Transaction
    @Query("SELECT * FROM user WHERE userId = :id")
    suspend fun getUserWithOrders(id: Long): UserWithOrders?
 
    // 查询所有用户及其订单，返回 Flow 实现响应式观察
    @Transaction
    @Query("SELECT * FROM user")
    fun getAllUsersWithOrders(): Flow<List<UserWithOrders>>
}

// 精简的订单摘要 —— 不是 Entity，只是一个普通 POJO
data class OrderSummary(
    val orderId: Long,      // 只需要订单 ID
    val product: String     // 和商品名
)
 
data class UserWithOrderSummaries(
    @Embedded
    val user: User,
    @Relation(
        parentColumn = "userId",
        entityColumn = "orderUserId",
        entity = Order::class,               // 告诉 Room 实际查询的是 order_table 表
        projection = ["orderId", "product"]  // 只 SELECT 这两列
    )
    val orderSummaries: List<OrderSummary>   // 映射到精简 POJO
)

// ========== 实体1：学生 ==========
@Entity(tableName = "student")
data class Student(
    @PrimaryKey
    val studentId: Long,      // 学生主键
    val studentName: String   // 学生姓名
)
 
// ========== 实体2：课程 ==========
@Entity(tableName = "course")
data class Course(
    @PrimaryKey
    val courseId: Long,        // 课程主键
    val courseName: String     // 课程名称
)
 
// ========== 中间表（交叉引用表）==========
@Entity(
    tableName = "student_course_cross_ref",
    primaryKeys = ["studentId", "courseId"],  // 联合主键，防止重复关联
    foreignKeys = [
        ForeignKey(                           // 引用学生表
            entity = Student::class,
            parentColumns = ["studentId"],
            childColumns = ["studentId"],
            onDelete = ForeignKey.CASCADE
        ),
        ForeignKey(                           // 引用课程表
            entity = Course::class,
            parentColumns = ["courseId"],
            childColumns = ["courseId"],
            onDelete = ForeignKey.CASCADE
        )
    ],
    indices = [Index("courseId")]             // studentId 已在联合主键中有索引
)
data class StudentCourseCrossRef(
    val studentId: Long,   // 学生 ID（外键）
    val courseId: Long      // 课程 ID（外键）
)

// ========== 方向1：查询学生选了哪些课 ==========
data class StudentWithCourses(
    @Embedded
    val student: Student,                     // 嵌入学生（父侧）
    @Relation(
        parentColumn = "studentId",           // Student 表的关联列
        entityColumn = "courseId",            // Course 表的关联列
        associateBy = Junction(               // 通过中间表关联
            StudentCourseCrossRef::class      // 中间表实体类
        )
    )
    val courses: List<Course>                 // 该学生选修的所有课程
)
 
// ========== 方向2：查询课程被哪些学生选了 ==========
data class CourseWithStudents(
    @Embedded
    val course: Course,                       // 嵌入课程（父侧）
    @Relation(
        parentColumn = "courseId",            // Course 表的关联列
        entityColumn = "studentId",          // Student 表的关联列
        associateBy = Junction(
            StudentCourseCrossRef::class
        )
    )
    val students: List<Student>              // 选修该课程的所有学生
)

// 假设中间表的列名不同于实体主键名
@Entity(
    tableName = "enrollment",
    primaryKeys = ["sid", "cid"]     // 列名是 sid 和 cid，而非 studentId 和 courseId
)
data class Enrollment(
    val sid: Long,    // 对应 Student.studentId
    val cid: Long     // 对应 Course.courseId
)
 
// 关系容器需要显式声明 Junction 的列映射
data class StudentWithCourses(
    @Embedded
    val student: Student,
    @Relation(
        parentColumn = "studentId",         // Student 实体的列
        entityColumn = "courseId",          // Course 实体的列
        associateBy = Junction(
            value = Enrollment::class,      // 中间表实体
            parentColumn = "sid",           // 中间表中对应 parent 的列
            entityColumn = "cid"            // 中间表中对应 entity 的列
        )
    )
    val courses: List<Course>
)

@Dao
interface SchoolDao {
    // ===== 关系查询 =====
    @Transaction
    @Query("SELECT * FROM student WHERE studentId = :id")
    suspend fun getStudentWithCourses(id: Long): StudentWithCourses?
 
    @Transaction
    @Query("SELECT * FROM course WHERE courseId = :id")
    suspend fun getCourseWithStudents(id: Long): CourseWithStudents?
 
    // ===== 中间表的增删操作 =====
    @Insert(onConflict = OnConflictStrategy.IGNORE)  // 忽略重复选课
    suspend fun insertCrossRef(crossRef: StudentCourseCrossRef)
 
    @Delete   // 退课：删除中间表中对应的一行
    suspend fun deleteCrossRef(crossRef: StudentCourseCrossRef)
 
    // ===== 事务操作：学生选课（原子性保证）=====
    @Transaction
    suspend fun enrollStudentInCourse(studentId: Long, courseId: Long) {
        // 先确保学生和课程都存在（可选的业务校验逻辑）
        // 再插入中间表记录
        insertCrossRef(StudentCourseCrossRef(studentId, courseId))
    }
}

// 多层嵌套关系示例
// 第一层：订单包含多个订单项
data class OrderWithItems(
    @Embedded
    val order: Order,                        // 嵌入订单
    @Relation(
        parentColumn = "orderId",            // Order 的主键
        entityColumn = "itemOrderId"         // OrderItem 的外键
    )
    val items: List<OrderItem>               // 一对多：订单项列表
)
 
// 第二层：用户包含多个"带订单项的订单"
data class UserWithOrdersAndItems(
    @Embedded
    val user: User,                          // 嵌入用户
    @Relation(
        entity = Order::class,               // 指定关联的是 Order Entity
        parentColumn = "userId",             // User 的主键
        entityColumn = "orderUserId"         // Order 的外键
    )
    val ordersWithItems: List<OrderWithItems> // 嵌套关系：List<OrderWithItems>
)

@Entity
data class Author(
    @PrimaryKey val authorId: Long,
    val name: String
)
 
@Entity
data class Book(
    @PrimaryKey val bookId: Long,
    val authorId: Long,
    val title: String
)
 
data class AuthorWithBooks(
    @Embedded val author: Author,
    @Relation(
        parentColumn = "authorId",
        entityColumn = "authorId"
    )
    val books: List<Book>
)

// 定义从版本 1 → 版本 2 的迁移对象
// Migration 构造函数接收 (startVersion, endVersion)
val MIGRATION_1_2 = object : Migration(1, 2) {
 
    // Room 在检测到版本不匹配时会调用此方法
    // 参数 db 是底层的 SupportSQLiteDatabase，可执行原生 SQL
    override fun migrate(db: SupportSQLiteDatabase) {
        // 使用 ALTER TABLE 为已有的 user 表添加 age 列
        // INTEGER 对应 Kotlin 的 Int 类型
        // NOT NULL 表示非空约束，DEFAULT 0 提供默认值
        db.execSQL(
            "ALTER TABLE user ADD COLUMN age INTEGER NOT NULL DEFAULT 0"
        )
    }
}

// 构建 Room 数据库实例
val db = Room.databaseBuilder(
    context.applicationContext,   // 使用 Application Context 避免内存泄漏
    AppDatabase::class.java,     // 你的 RoomDatabase 子类
    "app_database"               // 数据库文件名
)
    .addMigrations(MIGRATION_1_2) // 注册迁移对象，可传入多个
    .build()                      // 延迟构建，首次访问时才真正打开

// 版本 1 → 2：新增 age 字段
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE user ADD COLUMN age INTEGER NOT NULL DEFAULT 0")
    }
}
 
// 版本 2 → 3：新增 email 字段
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE user ADD COLUMN email TEXT NOT NULL DEFAULT ''")
    }
}
 
// 版本 3 → 4：创建全新的 order 表
val MIGRATION_3_4 = object : Migration(3, 4) {
    override fun migrate(db: SupportSQLiteDatabase) {
        // 创建 order 表，包含 id 主键、userId 外键、amount 金额
        db.execSQL("""
            CREATE TABLE IF NOT EXISTS `order` (
                `id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                `userId` INTEGER NOT NULL,
                `amount` REAL NOT NULL,
                FOREIGN KEY(`userId`) REFERENCES `user`(`id`)
                    ON DELETE CASCADE
            )
        """.trimIndent())
    }
}
 
// 可选：提供一步到位的 1 → 4 迁移，跳过中间步骤
// 适用于从非常老的版本直接升级的场景，可以合并 SQL 提升效率
val MIGRATION_1_4 = object : Migration(1, 4) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE user ADD COLUMN age INTEGER NOT NULL DEFAULT 0")
        db.execSQL("ALTER TABLE user ADD COLUMN email TEXT NOT NULL DEFAULT ''")
        db.execSQL("""
            CREATE TABLE IF NOT EXISTS `order` (
                `id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                `userId` INTEGER NOT NULL,
                `amount` REAL NOT NULL,
                FOREIGN KEY(`userId`) REFERENCES `user`(`id`)
                    ON DELETE CASCADE
            )
        """.trimIndent())
    }
}
 
// 注册所有迁移：Room 会自动选择最优路径
val db = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    .addMigrations(
        MIGRATION_1_2,   // 1 → 2
        MIGRATION_2_3,   // 2 → 3
        MIGRATION_3_4,   // 3 → 4
        MIGRATION_1_4    // 1 → 4（快捷通道）
    )
    .build()

// build.gradle.kts (KSP 配置方式)
ksp {
    // 指定 schema 导出目录，每个版本生成一个 JSON 文件
    arg("room.schemaLocation", "$projectDir/schemas")
}
 
// @Database 注解中 exportSchema 默认为 true
@Database(
    entities = [User::class, Order::class],
    version = 4,
    exportSchema = true // 推荐显式声明，提醒团队该特性已启用
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun orderDao(): OrderDao
}

// 添加测试依赖
// androidTestImplementation("androidx.room:room-testing:2.6.1")
 
@RunWith(AndroidJUnit4::class)
class MigrationTest {
 
    // MigrationTestHelper 需要 Instrumentation 和数据库类
    // 它会读取 schemas 目录下的 JSON 文件来创建旧版本数据库
    @get:Rule
    val helper = MigrationTestHelper(
        InstrumentationRegistry.getInstrumentation(),
        AppDatabase::class.java               // 数据库类引用
    )
 
    @Test
    fun migrate1To2() {
        // 创建版本 1 的数据库并插入测试数据
        helper.createDatabase("test_db", 1).apply {
            // 使用原生 SQL 插入，因为此时 Entity 还是旧版结构
            execSQL("INSERT INTO user (id, name) VALUES (1, 'Alice')")
            close() // 必须关闭后才能执行迁移
        }
 
        // 执行迁移：从版本 1 升级到版本 2
        val db = helper.runMigrationsAndValidate(
            "test_db",     // 数据库名，与上面一致
            2,             // 目标版本
            true,          // 是否执行 Room 的 Schema 验证
            MIGRATION_1_2  // 要测试的 Migration 对象
        )
 
        // 验证迁移后的数据完整性
        val cursor = db.query("SELECT id, name, age FROM user WHERE id = 1")
        assertTrue(cursor.moveToFirst())                    // 数据应该还在
        assertEquals("Alice", cursor.getString(1))          // name 未丢失
        assertEquals(0, cursor.getInt(2))                   // age 使用了默认值 0
        cursor.close()
    }
}

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    // 当没有找到合适的 Migration 时，允许 Room 销毁并重建数据库
    // ⚠️ 生产环境慎用！用户数据会全部丢失
    .fallbackToDestructiveMigration()
    .build()

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    // 仅在从指定版本升级时允许破坏性迁移
    // 例如：只有从版本 1 或版本 2 升级时才销毁重建
    // 从版本 3 开始必须提供正式的 Migration
    .fallbackToDestructiveMigrationFrom(1, 2)
    .build()

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3) // 升级路径必须完整
    // 只有降级时（高版本 → 低版本）才允许破坏性重建
    .fallbackToDestructiveMigrationOnDowngrade()
    .build()

@Database(
    entities = [User::class, Order::class],
    version = 3,                               // 当前最新版本
    exportSchema = true,                       // 必须为 true
    autoMigrations = [                         // 声明自动迁移列表
        AutoMigration(from = 1, to = 2),       // 1→2 的变更由 Room 自动生成 SQL
        AutoMigration(
            from = 2,
            to = 3,
            spec = AppDatabase.Migration2To3::class // 需要 spec 辅助的复杂场景
        )
    ]
)
abstract class AppDatabase : RoomDatabase() {
 
    // 当 AutoMigration 无法自动推断意图时，需要提供 AutoMigrationSpec
    // 典型场景：表重命名、列重命名、列删除
    @RenameTable(fromTableName = "order", toTableName = "purchase_order")
    class Migration2To3 : AutoMigrationSpec
 
    abstract fun userDao(): UserDao
    abstract fun orderDao(): OrderDao
}

// 从版本 3 → 4 的自动迁移规范
// 场景：将 user 表的 email 列重命名为 email_address，并删除废弃的 temp_flag 列
@RenameColumn(
    tableName = "user",               // 哪张表
    fromColumnName = "email",         // 旧列名
    toColumnName = "email_address"    // 新列名
)
@DeleteColumn(
    tableName = "user",               // 哪张表
    columnName = "temp_flag"          // 要删除的列名
)
class Migration3To4 : AutoMigrationSpec {
 
    // 可选重写：在自动迁移 SQL 执行完毕后调用
    // 适用于需要做数据回填、清理等后处理的场景
    override fun onPostMigrate(db: SupportSQLiteDatabase) {
        // 例如：将所有 email_address 统一转为小写
        db.execSQL("UPDATE user SET email_address = LOWER(email_address)")
    }
}

@Database(
    entities = [User::class],
    version = 3,
    autoMigrations = [
        AutoMigration(from = 1, to = 2) // 简单变更：自动迁移
    ]
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
 
// 复杂变更：手动迁移（版本 2 → 3 涉及表重建）
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        // SQLite 不支持 ALTER TABLE DROP COLUMN（3.35.0 之前）
        // 需要经典的"四步重建法"
        // Step 1: 创建新表
        db.execSQL("""
            CREATE TABLE user_new (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                name TEXT NOT NULL,
                age INTEGER NOT NULL DEFAULT 0
            )
        """.trimIndent())
        // Step 2: 将旧表数据复制到新表
        db.execSQL("INSERT INTO user_new (id, name, age) SELECT id, name, age FROM user")
        // Step 3: 删除旧表
        db.execSQL("DROP TABLE user")
        // Step 4: 将新表重命名为旧表名
        db.execSQL("ALTER TABLE user_new RENAME TO user")
    }
}
 
// 构建时混合注册
val db = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    .addMigrations(MIGRATION_2_3)  // 手动迁移
    // AutoMigration 已在 @Database 注解中声明，无需额外注册
    .build()

@Dao
interface BookDao {
 
    // 返回 Flow<List<Book>>，每当 book 表发生任何写操作（INSERT / UPDATE / DELETE），
    // Room 都会自动重新执行这条 SELECT 并向下游发射最新结果
    @Query("SELECT * FROM book ORDER BY title ASC")
    fun observeAllBooks(): Flow<List<Book>>
 
    // 单行查询同样支持 Flow，当该行数据变化或被删除时会重新发射
    // 注意返回类型是 Flow<Book?>，因为指定 id 的记录可能不存在
    @Query("SELECT * FROM book WHERE id = :bookId")
    fun observeBookById(bookId: Long): Flow<Book?>
 
    // 聚合查询也可以用 Flow 包裹，表发生变更时重新计算
    @Query("SELECT COUNT(*) FROM book")
    fun observeBookCount(): Flow<Int>
}

// Room 编译器自动生成的 BookDao_Impl 中的方法（简化还原）
override fun observeAllBooks(): Flow<List<Book>> {
    // 1. 声明本次查询所涉及的表名数组，用于注册到 InvalidationTracker
    val tableNames: Array<String> = arrayOf("book")
 
    // 2. 使用 Room 提供的 createFlow 扩展函数构建响应式 Flow
    //    该函数内部会注册 InvalidationTracker Observer，并在表失效时重新执行查询
    return db.invalidationTracker.createFlow(
        tableNames = tableNames,          // 监听哪些表
        inTransaction = false             // 本次查询是否需要在事务中执行
    ) {
        // 3. 这个 lambda 就是真正的查询执行体，每次表失效后都会被重新调用
        val cursor: Cursor = db.query(    // 使用 RoomDatabase 的 query 方法执行 SQL
            SimpleSQLiteQuery("SELECT * FROM book ORDER BY title ASC")
        )
 
        // 4. 遍历 Cursor，将每一行映射为 Book 实体对象
        val result = mutableListOf<Book>()
        try {
            val indexId = cursor.getColumnIndexOrThrow("id")       // 获取列索引
            val indexTitle = cursor.getColumnIndexOrThrow("title") // 获取列索引
            while (cursor.moveToNext()) {                          // 逐行遍历
                val book = Book(
                    id = cursor.getLong(indexId),                   // 读取主键
                    title = cursor.getString(indexTitle)            // 读取标题
                )
                result.add(book)                                   // 添加到结果列表
            }
        } finally {
            cursor.close()                                         // 必须关闭 Cursor 释放资源
        }
        result                                                     // 返回查询结果
    }
}

class BookListViewModel(
    private val bookDao: BookDao          // 通过构造注入获取 DAO
) : ViewModel() {
 
    // 将 DAO 的 Flow 转换为 StateFlow，提供给 UI 消费
    // stateIn 会在 viewModelScope 中启动一个协程来收集上游 Flow
    val books: StateFlow<List<Book>> = bookDao.observeAllBooks()
        .distinctUntilChanged()           // 过滤重复值，避免不必要的 UI 重绘
        .stateIn(
            scope = viewModelScope,       // 绑定 ViewModel 的生命周期
            started = SharingStarted.WhileSubscribed(5000), // 下游无订阅者 5 秒后停止上游
            initialValue = emptyList()    // 初始值为空列表
        )
}

@Composable
fun BookListScreen(viewModel: BookListViewModel = viewModel()) {
    // collectAsStateWithLifecycle 会自动在 Lifecycle 处于 STARTED 以上时收集
    // 低于 STARTED（如 Activity 进入后台）时自动暂停，避免无意义的 UI 更新
    val books by viewModel.books.collectAsStateWithLifecycle()
 
    LazyColumn {
        items(books, key = { it.id }) { book ->  // key 提高 diff 效率
            Text(text = book.title)               // 展示书名
        }
    }
}

class BookListActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 在 STARTED 状态下持续收集 Flow
        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.books.collect { books ->
                    // 更新 RecyclerView 的 Adapter 数据
                    adapter.submitList(books)
                }
            }
        }
    }
}

@Dao
interface BookDao {
    // 挂起函数：只执行一次查询，不持续监听表变更
    // Room 会自动切换到内部的查询 Executor 线程执行，完成后恢复调用方的协程
    @Query("SELECT * FROM book WHERE id = :bookId")
    suspend fun getBookById(bookId: Long): Book?
 
    // INSERT / UPDATE / DELETE 操作也应声明为 suspend
    @Insert
    suspend fun insertBook(book: Book): Long
 
    @Update
    suspend fun updateBook(book: Book)
 
    @Delete
    suspend fun deleteBook(book: Book)
}

@Dao
interface BookDao {
    // 返回 LiveData，当 book 表发生写操作时自动重新查询并通知观察者
    @Query("SELECT * FROM book ORDER BY title ASC")
    fun observeAllBooksLiveData(): LiveData<List<Book>>
 
    // 单行查询
    @Query("SELECT * FROM book WHERE id = :bookId")
    fun observeBookByIdLiveData(bookId: Long): LiveData<Book?>
}

// Room 为 LiveData 返回类型生成的核心逻辑（简化还原）
override fun observeAllBooksLiveData(): LiveData<List<Book>> {
    // 1. 创建 ComputableLiveData，它继承自 LiveData 并集成了 InvalidationTracker
    val computable = object : ComputableLiveData<List<Book>>(
        db.queryExecutor,                // 查询使用的线程池
        "book"                           // 监听的表名（可变参数，支持多表）
    ) {
        override fun compute(): List<Book> {
            // 2. 这个方法在后台线程执行，返回查询结果
            val cursor = db.query(
                SimpleSQLiteQuery("SELECT * FROM book ORDER BY title ASC")
            )
            // 3. Cursor → List<Book> 的映射逻辑（与 Flow 版本相同，此处省略）
            return mapCursorToBooks(cursor)
        }
    }
    // 4. 返回内部持有的 LiveData 对象
    return computable.liveData
}

// Flow → LiveData（通常在 ViewModel 中，将 Repository 层的 Flow 转为 LiveData 暴露给 View 层）
val booksLiveData: LiveData<List<Book>> = bookDao.observeAllBooks()
    .distinctUntilChanged()                // Flow 操作符：去重
    .asLiveData(
        context = Dispatchers.IO,          // 上游 Flow 在 IO 线程收集
        timeout = 5.seconds                // 类似 WhileSubscribed(5000) 的超时
    )
 
// LiveData → Flow（不太常用，但在需要用 Flow 操作符处理 LiveData 数据时有用）
val booksFlow: Flow<List<Book>> = booksLiveData.asFlow()

-- Room 内部创建的变更追踪表
-- 每个被观察的应用表在此表中对应一行
CREATE TABLE IF NOT EXISTS room_table_modification_log (
    table_id INTEGER PRIMARY KEY,    -- 表的数字 ID（Room 在编译期为每张表分配）
    invalidated INTEGER NOT NULL     -- 0 = 未变更，1 = 已变更（失效标记）
        DEFAULT 0
);

-- 以 book 表为例（假设其 table_id = 0）
-- INSERT 触发器：当有新行插入时，标记 book 表已失效
CREATE TEMP TRIGGER IF NOT EXISTS room_table_modification_trigger_book_INSERT
AFTER INSERT ON book
BEGIN
    UPDATE room_table_modification_log
    SET invalidated = 1
    WHERE table_id = 0 AND invalidated = 0;  -- 避免重复更新
END;
 
-- UPDATE 触发器：当有行被更新时，标记 book 表已失效
CREATE TEMP TRIGGER IF NOT EXISTS room_table_modification_trigger_book_UPDATE
AFTER UPDATE ON book
BEGIN
    UPDATE room_table_modification_log
    SET invalidated = 1
    WHERE table_id = 0 AND invalidated = 0;
END;
 
-- DELETE 触发器：当有行被删除时，标记 book 表已失效
CREATE TEMP TRIGGER IF NOT EXISTS room_table_modification_trigger_book_DELETE
AFTER DELETE ON book
BEGIN
    UPDATE room_table_modification_log
    SET invalidated = 1
    WHERE table_id = 0 AND invalidated = 0;
END;