# AGENTS.md — @app/dao

## 职责

**数据访问层（DAO）**：封装 Drizzle 查询。service 只调本包，不直接 `db.select`。不含业务规则、HTTP/tRPC。

## 结构

```
src/
  index.ts             # 出口：daos + 行类型
  users.ts             # userDao
  sessions.ts          # sessionDao
  password-resets.ts   # passwordResetDao
  mounts.ts            # mountDao
  media-items.ts       # mediaItemDao
  playback-progress.ts # playbackProgressDao
  danmaku-cache.ts     # danmakuCacheDao
```

## 依赖

- `@app/db`：`db` 单例（连接）
- `@app/models`：表定义与 `$infer*` 行类型

## 约定

- 一表一个 dao 对象；方法名 `list` / `getById` / `create` / `update` / `delete`（媒体域可加 `getByPath`、`upsert` 等，但保持动词清晰）。
- `exactOptionalPropertyTypes`：update 入参用 `Partial<Omit<Row, "id" | "createdAt" | "updatedAt">>`。
- `noUncheckedIndexedAccess`：`returning()[0]` 判空后抛错或 `?? null`。
- 不读 env、不建 client；环境变量校验在 `@app/db`。
- 分页/过滤等查询参数类型一并从本包导出（如 `ListUsersParams`）。

## 修改指南

- 加查询：新建或扩展对应 `*.ts`，在 `index.ts` 导出。
- 新表：先改 `@app/models` → `yarn db:generate`/`db:push` → 本包加 dao。
- 媒体域查询注意 `mediaItems` 唯一键含 `mountId`，按路径查找时必须带挂载维度。

## 命令

```bash
yarn workspace @app/dao typecheck
yarn workspace @app/dao build
```