app-template/packages/models/AGENTS.md

AGENTS.md — @app/models

职责

Drizzle ORM 表定义（数据库 schema 的唯一源）。只描述表结构与行类型，不含连接、查询逻辑或迁移脚本。

结构

src/
  users.ts             # users + User / NewUser
  sessions.ts          # sessions + Session / NewSession
  password-resets.ts   # passwordResets + PasswordReset / NewPasswordReset
  mounts.ts            # mounts（网盘挂载：WebDAV 等）+ Mount / NewMount
  media-items.ts       # mediaItems（媒体条目，唯一键含 mountId）+ MediaItem / NewMediaItem
  playback-progress.ts # playbackProgress（观看进度）
  danmaku-cache.ts     # danmakuCache（弹幕缓存行）
  index.ts             # 重导出全部表与行类型

域划分：账户域（users / sessions / password-resets）与媒体域（mounts / media-items / playback-progress / danmaku-cache）。

约定

• 表用 sqliteTable（Turso/libSQL）。主键默认 text + crypto.randomUUID()。
• 时间戳用 integer(..., { mode: "timestamp" })，默认 unixepoch()。
• 同步导出 $inferSelect / $inferInsert 类型（如 User、NewUser）。
• mediaItems 唯一约束含 mountId（同路径可存在于不同挂载）。

修改指南

• 加表/改列：改这里 → yarn workspace @app/db db:generate（或 db:push）→ 更新 @app/dao 对应 dao。
• 查询写在 @app/dao，不在本包写 db.select。
• 不要引入 @libsql/client 或环境变量；本包保持纯 schema。
• 重命名/删除列是破坏性变更：先确认无 dao/service/API 依赖，再生成迁移。
• 新表在 index.ts 重导出表 + 行类型，保持命名 xxx / Xxx / NewXxx。

命令

yarn workspace @app/models typecheck
yarn workspace @app/models build
# schema 变更后的迁移在 @app/db：
yarn db:generate
yarn db:push