247 lines
4.7 KiB
Markdown
247 lines
4.7 KiB
Markdown
# Data Model And State
|
||
|
||
## 真相源原则
|
||
|
||
这套服务端最关键的状态归属如下：
|
||
|
||
- `Postgres`
|
||
- 用户认证数据
|
||
- 角色、聊天、Provider 配置
|
||
- Flux 余额与账本
|
||
- Stripe 业务镜像
|
||
- LLM 请求日志
|
||
- `Redis`
|
||
- Flux 余额缓存
|
||
- 服务配置 KV
|
||
- 聊天跨实例广播
|
||
- 计费事件队列
|
||
|
||
如果要判断“改哪个地方才算真的改成功”，大多数场景答案都是 Postgres。
|
||
|
||
## 主要表分组
|
||
|
||
### 认证
|
||
|
||
- `user`
|
||
- `session`
|
||
- `account`
|
||
- `verification`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/accounts.ts`
|
||
|
||
说明：
|
||
|
||
- `better-auth` 直接用这组表
|
||
- `src/schemas/auth.ts` 基本是重复副本，目前不是主要依赖入口
|
||
|
||
### 角色与用户交互
|
||
|
||
- `characters`
|
||
- `character_covers`
|
||
- `avatar_model`
|
||
- `character_capabilities`
|
||
- `character_i18n`
|
||
- `character_prompts`
|
||
- `user_character_likes`
|
||
- `user_character_bookmarks`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/characters.ts`
|
||
- `src/schemas/user-character.ts`
|
||
|
||
说明：
|
||
|
||
- 角色实体采用软删除
|
||
- 点赞与收藏通过中间表建模
|
||
- 计数值冗余保存在 `characters` 表上
|
||
|
||
### 聊天
|
||
|
||
- `chats`
|
||
- `chat_members`
|
||
- `messages`
|
||
- `media`
|
||
- `stickers`
|
||
- `sticker_packs`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/chats.ts`
|
||
|
||
说明：
|
||
|
||
- `messages.seq` 是会话内顺序字段
|
||
- 写消息时通过 `SELECT ... FOR UPDATE` 锁 chat 以串行生成 seq
|
||
- `senderId` 是宽松字段，不强制外键
|
||
|
||
### Provider 配置
|
||
|
||
- `user_provider_configs`
|
||
- `system_provider_configs`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/providers.ts`
|
||
|
||
说明：
|
||
|
||
- 运行时查询时会把系统配置和用户配置拼接成一个结果集
|
||
- `config` 是 `jsonb`
|
||
|
||
### Flux / 账本 / 审计
|
||
|
||
- `user_flux`
|
||
- `flux_transaction`
|
||
- `flux_transaction`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/flux.ts`
|
||
- `src/schemas/flux-transaction.ts`
|
||
- `src/schemas/flux-transaction.ts`
|
||
|
||
职责边界：
|
||
|
||
- `user_flux`
|
||
- 当前余额快照
|
||
- `flux_transaction`
|
||
- append-only 账本流水
|
||
- 偏系统真相源
|
||
- `flux_transaction`
|
||
- 用户可见历史
|
||
- 偏产品展示
|
||
|
||
关键约束：
|
||
|
||
- `flux_transaction` 对 `(userId, requestId)` 有部分唯一索引
|
||
- 用来做扣费 / 充值幂等
|
||
|
||
### Stripe 业务镜像
|
||
|
||
- `stripe_customer`
|
||
- `stripe_checkout_session`
|
||
- `stripe_subscription`
|
||
- `stripe_invoice`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/stripe.ts`
|
||
|
||
说明：
|
||
|
||
- 这些表是 Stripe 状态的本地镜像
|
||
- 真正的余额变化仍由 `billingService` 写入 `user_flux + flux_transaction`
|
||
- `fluxCredited` 字段用于避免重复入账
|
||
|
||
### LLM 请求日志
|
||
|
||
- `llm_request_log`
|
||
|
||
来源文件：
|
||
|
||
- `src/schemas/llm-request-log.ts`
|
||
|
||
说明：
|
||
|
||
- 只做追加写入
|
||
- 明确不加 user 外键，以避免高并发写入的额外约束成本
|
||
|
||
## 服务与状态写入边界
|
||
|
||
### `createFluxService()`
|
||
|
||
负责：
|
||
|
||
- 余额读取
|
||
- 新用户首次读取时初始化 `user_flux`
|
||
- Redis cache-aside
|
||
|
||
不负责：
|
||
|
||
- 扣费
|
||
- 充值
|
||
- transaction 写入
|
||
|
||
### `createBillingService()`
|
||
|
||
负责：
|
||
|
||
- 所有余额写操作
|
||
- DB 事务
|
||
- debitFlux：事务内仅更新余额；事务后 XADD Redis Stream，transaction log 由 billing-consumer 异步写入
|
||
- credit 方法：事务内同步写 transaction
|
||
- 事务提交后 best-effort `redis.set` 更新 Flux 余额缓存
|
||
|
||
这是所有 Flux 写路径应收敛到的中心。
|
||
|
||
### `createStripeService()`
|
||
|
||
负责：
|
||
|
||
- Stripe 实体 upsert
|
||
|
||
不负责：
|
||
|
||
- 最终 Flux 入账
|
||
|
||
真正入账通过 `billingService.creditFluxFromStripeCheckout()` 或相关 credit 方法完成。
|
||
|
||
## Redis 中的数据类型
|
||
|
||
### Flux 缓存
|
||
|
||
- key: `flux:<userId>`
|
||
- value: 字符串化整数
|
||
|
||
写入来源：
|
||
|
||
- `fluxService.getFlux()` cache miss 后回填
|
||
- `billingService` 余额事务提交后 best-effort `redis.set` 直接更新（API 进程内同步）
|
||
|
||
### 配置 KV
|
||
|
||
- key: `config:<CONFIG_NAME>`
|
||
|
||
由 `config-kv.ts` 管理，支持：
|
||
|
||
- 数值
|
||
- 字符串
|
||
- `FLUX_PACKAGES` JSON
|
||
|
||
### 聊天跨实例广播
|
||
|
||
- channel: `chat:broadcast:<userId>`
|
||
|
||
### 计费事件流
|
||
|
||
- stream: 默认 `billing-events`
|
||
|
||
## 幂等与并发控制
|
||
|
||
### 余额并发
|
||
|
||
`billingService` 在事务中：
|
||
|
||
1. `SELECT user_flux FOR UPDATE`
|
||
2. 计算新余额
|
||
3. 写余额（debitFlux 事务内仅此一步；credit 方法同步写 transaction）
|
||
4. 事务提交后 XADD Redis Stream（debitFlux）或直接返回（credit）
|
||
|
||
这保证同一用户余额更新是串行化的。
|
||
|
||
### Stripe 幂等
|
||
|
||
主要依赖：
|
||
|
||
- `stripe_checkout_session.fluxCredited`
|
||
- `stripe_invoice.fluxCredited`
|
||
- `flux_transaction(userId, requestId)` 唯一约束
|
||
|
||
## 现有代码中的结构信号
|
||
|
||
- `request-log.ts` 与 `llm-request-log.ts` 完全重叠，后者更像旧名残留。
|
||
- `accounts.ts` 与 `auth.ts` 也是重复 schema，后续如果做整理，应先统一真实使用入口再删副本。
|