用途
该技能是一份数据层问题索引，面向使用 Kotlin 与 Compose Multiplatform 的工程。它的 26 个陷阱条目全部来自一个生产应用，每个条目是一个独立短文，放在 references/ 目录下，用来在写代码之前或追查症状时快速对照。
主要能力
-
数据库与 SQL：级联删除顺序（先删容器再删叶子、区分“按状态保留”与真正的垃圾、在 DELETE 内部复查条件、固定当前正在使用的记录）；
NOT IN遇到子查询结果含 NULL 时匹配零行却报告成功；用 LIKE 匹配机器生成 id 时_与%会静默扩大匹配，需嵌套 replace() 加显式 ESCAPE 字符并按带引号的 token 匹配；raw query DAO 方法跑在只读连接上导致 VACUUM 失败；在状态转换时清理只为该状态而存在的卫星行；Room KMP 多平台配置（按平台 expect/actual 构建器、注入点统一选择 SQLite 驱动、按架构审计驱动产物）；二十多个 schema 版本后的迁移图与触发器幂等重建；DataStore 多平台偏好管理器；纯设备端的收听/使用分析（只追加事件表加反规范化表、两个完成阈值、读取时才补标题与封面、窗口查询参数化为 start/end）。 -
导入：导入/导出格式契约设计（版本字段何时更糟、解析为空要拒绝、等长规则、禁止生产方输出旧值、按有意义的键而非位置取值）；大文件批量 JSON 导入的分块写入与逐块进度、解析为空先于触库拒绝、过滤掉父级不存在的行。
-
时间与统计：时间戳列经 ORM 类型转换器可能把本地墙钟当作 UTC 写入，且转换器由字段目标类型决定，投影字段声明为原始数字会静默绕过并二次应用偏移；本地时间分桶应在应用代码中从一次原始扫描完成，而非在 SQL 中用本地时间修饰符（后者取进程时区，且多个本地聚合多次扫描可能互相矛盾）；Top-N 适合列表但不适合份额统计（截断会缩小分母并抬高集中度与多样性）；“首次出现”需对实体全历史取 MIN 再判断窗口，窗口应在 HAVING 而非 WHERE；周期导航的边界约定要统一（闭区间上界丢亚秒余量、半开区间交给 BETWEEN 会重复计数），粒度切换时重置步进偏移。
-
仓库、缓存与分页：仓库方法形态约定（本地读为移到 IO 调度器的冷流、远程读为成功/错误信封流、写用 withContext）；先缓存后网络（单条流先发存储副本再发新数据，仅在什么都没发出时才报错）；带 TTL 的键控 JSON 缓存与宽松解码；通用分页 DB 累加器（有界循环按短页停止）；续传令牌分页契约（null 令牌表示结束，只存令牌，有界预取）；本地排序/洗牌与远程游标共用令牌槽位（前缀模式标签 + 编码游标，未识别前缀要显式报错）；分区响应按到达顺序映射为 (title, items) 列表，不可按位置取字段；大型发布索引解析为行并配合服务器 ETag 校验；对分页列表的搜索必须查数据源并以兄弟覆盖层渲染；把本地开关镜像到远程账户（开启时回填、关闭不撤销、三值区分未尝试与失败）。
使用方式
将即将编写的代码或正在追查的症状与索引条目对照，找到相关条目后，用 Read 工具读取所有可能适用的文件（每个不超过 150 行），再提出代码或修复方案。条目中的验证命令若引用源项目路径，替换为用户代码树中的等价路径。文件中未在本索引列出的反引号陷阱名，位于同级其他技能，可用 glob ../*/references/<name>.md 打开。
适用场景与限制
适用于在用 Room/SQLite、DataStore 或仓库/缓存/分页层开发或排错的 Kotlin 与 Compose Multiplatform 项目。限制：资料仅描述上述 26 个陷阱条目及其写作结构，未提供安装方式、依赖版本、收费或许可信息；验证命令针对源项目路径，需自行替换；文件内部引用的其他陷阱需另行打开同级技能文件。