Database

Tanplate 使用 Cloudflare D1 保存关系事实，使用 Drizzle 提供唯一 schema 和类型化客户端。应用只负责注入 D1 binding；表结构和跨应用数据合同集中在 packages/db。

什么时候需要 D1

D1 不是文档站或纯 Landing 的固定依赖。Authentication、Projects、User Assets、Newsletter、Developer API、Product AI 配额、Jobs/Webhooks 和 Admin audit 等能力会按 Capability Profile 派生数据库需求。

Web 与 Admin 同时消费同一能力时共享目标环境中的 D1；两个应用仍保留独立 origin、Cookie 和授权边界。Docs 始终不绑定业务 D1。

Schema 与迁移

• packages/db/src/schema.ts：Auth、Projects、Assets、Newsletter、Developer API、AI、Jobs/Webhooks 和 audit 的聚合 schema。
• packages/db/src/client.ts：从 D1Database 创建 Drizzle client。
• packages/db/drizzle/：受版本控制的迁移 SQL 与元数据。

不要在应用 route 中维护第二套建表语句。schema 变化后生成迁移，并同时检查共享领域包、Web/Admin adapter 和恢复脚本。

本地开发

pnpm data:migrate:local
pnpm data:seed:local

data:migrate:local 只在当前 Profile 需要 D1 时执行迁移。data:seed:local 用于部署 Admin 的本地测试管理员，不填充 Projects 或 R2 业务数据。

Web 的 .wrangler/state 是本地 D1/R2 状态源，Admin 显式复用它。远程迁移、备份与恢复必须面向明确 target 执行，不从 Local 配置推断 Production。

数据边界

D1 保存权威状态和对象元数据，R2 保存文件 bytes。涉及两者的写入必须经过共享领域 service，并使用状态机、幂等或补偿操作处理部分失败；浏览器不能直接持有数据库 binding。

资源命名、环境检查和部署顺序见 Cloudflare，对象数据见 Storage。