---
url: /docs/database/schema.md
---
# 数据模型

## 表的职责

| 模型 | 保存内容 |
| --- | --- |
| `user` | 用户资料与邮箱验证状态 |
| `identity` | 认证身份，Better Auth 的 account 模型映射到此表 |
| `session` | 会话及活动组织 |
| `verification` | 邮箱验证、验证码等验证信息 |
| `organization`、`member` | 组织资料、用户成员关系及角色 |
| `invitation` | 组织邀请，投递流程尚未完整接入 |
| `passkey` | 通行密钥公钥和凭据资料 |
| `subscription` | Stripe 插件同步的订阅状态 |
| `toolRun` | 用户工具保存结果、输入指纹和请求 ID |
| `creditAccount`、`creditLedger` | 当前积分余额和事件流水 |

具体列、索引和关系以 `db/schema/*.ts` 为准。某列存在不代表已经有界面或写入流程，例如邀请扩展时间字段需要单独核对。

## 命名与标识

TypeScript 字段用驼峰，数据库通过 `snake_case` 转换。实体使用固定前缀加 16 位 CUID2，例如 `usr_...`、`org_...`，生成器在 `db/schema/id.ts`。用户密钥使用 `key_`，签发请求记录使用 `kis_`；都保留 16 位 CUID2。前缀方便排查，不承担权限判断。

日期使用带时区时间戳；关键列设非空、外键、唯一约束和索引，不只依赖前端校验。引用用户的数据按模型定义设置删除行为。

## 订阅与组织范围

订阅的 `referenceId` 可以指向用户或组织，没有单一外键可替代业务归属检查。读取前从会话选择范围，再实时核对组织成员。

工具记录和积分当前按用户隔离。`toolRun` 的用户与请求 ID 唯一约束防止重复保存；积分事件的用户与事件键唯一约束防止重复发放，余额有非负约束。

## 新增或改列

修改 `db/schema/` 并补齐导出与关系，然后生成迁移、审查 SQL，再应用到隔离开发库。新增 Better Auth 字段还要同步插件配置；不要只改表然后期待插件自动读写。

涉及上线数据时分阶段增加新列、迁移数据、切换代码、最后清理旧列。详见 [新增数据表](../recipes/new-table.md) 和 [数据库迁移](./migrations.md)。