# AGENTS.md — @app/db

## 职责

创建并导出 **Drizzle + libSQL 客户端单例**，以及 drizzle-kit 配置与种子脚本。查询在 `@app/dao`，业务在 `@app/trpc` service。

## 结构

```
src/
  client.ts   # export const db = drizzle(client, { schema })
  index.ts    # 对外 re-export
scripts/
  seed.ts     # 幂等初始化默认管理员（yarn db:seed）
drizzle.config.ts    # dialect: turso；schema 指向 ../models/dist/index.js
```

## 行为要点

- 读环境变量：`TURSO_DATABASE_URL`（必填，缺失则启动抛错）、`TURSO_AUTH_TOKEN`（可选）。
- 本地开发常用 `TURSO_DATABASE_URL=file:local.db`。
- `schema` 来自 `@app/models`——**模型定义请去 models 改**，本包只聚合导入。
- **不写业务查询**；SQL/Drizzle query 在 `@app/dao`。
- `drizzle.config.ts` 与 `scripts/seed.ts` 都会手动解析根目录 `.env`（monorepo 下 drizzle-kit / tsx 不自动加载）。改 env 路径时保持一致。

## seed 脚本

- `yarn db:seed`：创建默认管理员（用户名 + 密码），已存在同名用户则跳过（幂等）。
- 密码哈希格式与 `@app/trpc` 的 `password.ts` 一致（scrypt `salt:hash` hex）——改哈希算法时两处同步。
- 脚本可直接依赖 `@app/models` 与 `@libsql/client`，但不要在 `src/` 里塞业务逻辑。

## 修改指南

- 需要新表时：改 `@app/models` → `yarn db:generate` / `db:push`，不要在本包手写 SQL 迁移（除非 drizzle-kit 生成物不够用）。
- 不要在模块顶层执行查询以外的副作用；保持「import 即得 client」。
- 多环境：本地 `file:`，线上 `libsql://...` + token；不要写死 URL。

## 命令

```bash
yarn workspace @app/db typecheck
yarn workspace @app/db build
yarn db:generate
yarn db:push
yarn db:seed
yarn db:studio
```