moeka-project/apps/server/docs/ai-context/data-model-and-state.md

Data Model And State

真相源原则

这套服务端最关键的状态归属如下：

• Postgres
  • 用户认证数据
  • 角色、聊天、Provider 配置
  • Flux 余额与账本
  • Stripe 业务镜像
  • LLM 请求日志
  • outbox 事件
• 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_ledger
• flux_audit_log

来源文件：

• src/schemas/flux.ts
• src/schemas/flux-ledger.ts
• src/schemas/flux-audit-log.ts

职责边界：

• user_flux
  • 当前余额快照
• flux_ledger
  • append-only 账本流水
  • 偏系统真相源
• flux_audit_log
  • 用户可见历史
  • 偏产品展示

关键约束：

• flux_ledger 对 (userId, requestId) 有部分唯一索引
• 用来做扣费 / 充值幂等

Stripe 业务镜像

• stripe_customer
• stripe_checkout_session
• stripe_subscription
• stripe_invoice

来源文件：

• src/schemas/stripe.ts

说明：

• 这些表是 Stripe 状态的本地镜像
• 真正的余额变化仍由 billingService 写入 user_flux + flux_ledger
• fluxCredited 字段用于避免重复入账

LLM 请求日志

• llm_request_log

来源文件：

• src/schemas/llm-request-log.ts

说明：

• 只做追加写入
• 明确不加 user 外键，以避免高并发写入的额外约束成本

Outbox

• outbox_events

来源文件：

• src/schemas/outbox-events.ts

说明：

• 本质上是 DB 内事件暂存区
• 通过 claimedBy + claimExpiresAt + publishedAt 实现 lease/claim 分发

服务与状态写入边界

createFluxService()

负责：

• 余额读取
• 新用户首次读取时初始化 user_flux
• Redis cache-aside

不负责：

• 扣费
• 充值
• ledger / audit / outbox 写入

createBillingService()

负责：

• 所有余额写操作
• DB 事务
• ledger / audit / outbox 联动
• 事务完成后 best-effort 更新 Redis

这是所有 Flux 写路径应收敛到的中心。

createStripeService()

负责：

• Stripe 实体 upsert

不负责：

• 最终 Flux 入账

真正入账通过 billingService.creditFluxFromStripeCheckout() 或相关 credit 方法完成。

Redis 中的数据类型

Flux 缓存

• key: flux:<userId>
• value: 字符串化整数

写入来源：

• fluxService.getFlux() cache miss 后回填
• billingService 余额事务成功后 best-effort 更新
• cache-sync-consumer 消费 flux.debited / flux.credited 后同步

配置 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. 写余额
4. 写 ledger / audit / outbox

这保证同一用户余额更新是串行化的。

Stripe 幂等

主要依赖：

• stripe_checkout_session.fluxCredited
• stripe_invoice.fluxCredited
• flux_ledger(userId, requestId) 唯一约束

outbox 并发

outbox-service.ts 使用：

• FOR UPDATE SKIP LOCKED
• claimExpiresAt

这允许多个 dispatcher 并行拉取待发布事件。

现有代码中的结构信号

• request-log.ts 与 llm-request-log.ts 完全重叠，后者更像旧名残留。
• accounts.ts 与 auth.ts 也是重复 schema，后续如果做整理，应先统一真实使用入口再删副本。