数据模型（Backend 数据库设计）
权威来源：src/backend/db/models/。
文档与代码不一致时以 ORM 为准。主键多为 UUID；时间字段为 timestamptz。
当前 ORM 导出约 64 张业务表（含 canvas_folders）。
计费业务规则见 membership-agent-sales-guide.md、membership-tiers.md。
模型池路由行为见 architecture/model_pool.md。
迁移规范见 standards/database-migrations.md。
分域文档
设计约定
字段表格式（分域子页统一）
| 列 |
含义 |
| 字段 |
数据库列名（英文） |
| 中文名 |
列的中文名称 |
| 类型 |
ORM / PostgreSQL 类型摘要 |
| 可空 |
YES / NO |
| 作用 |
该列在业务中的用途、约束与枚举含义 |
主键与基类
- 基类仅为
Base(DeclarativeBase)，无统一 Timestamp / SoftDelete Mixin；各模型手写时间戳。
- 主键几乎全是
UUID(as_uuid=True) + default=uuid.uuid4。
- 例外：
ai_model_group_members、ai_model_account_bindings 为 复合主键（无单独 id 列）。
时间与软删
| 模式 |
说明 |
created_at / updated_at |
DateTime(timezone=True)，常 server_default=now()，updated_at 常带 onupdate |
deleted_at |
可空；非空表示软删。用于 users、tasks、多数模板、plans、ai_models、画布、chat、hot_styles、video_scripts 等 |
启用开关
| 风格 |
典型表 |
取值 |
status: SmallInteger |
users、plans、agents、product_*、视频剧本等 |
多为 0=停用/停售，1=正常/在售 |
is_active: Boolean |
模板、Banner、FeatureCard、模型池等 |
true / false |
status: String |
orders、tasks、分账、支付、对账等 |
业务状态机字符串 |
JSONB 与多态关联
- JSONB：配置、匹配键列表、画布文档、试跑状态、事件 payload 等。
template_images：template_type（PG enum）+ template_id（无 FK，指向各模板表）。transaction_ledger：owner_type + owner_id（无 FK），统一用户/代理流水。
兼容与遗留
AiModel.group_id 与中间表 ai_model_group_members 并存（过渡期）；正式成员关系以中间表为准。ai_model_api_keys 为模型私有 Key（遗留）；共享账号走 ai_model_api_accounts + bindings。- 主图/详情模板保留
product_sub_type_ids / fabric_material_ids（遗留），新匹配键为 product_category_ids / style_ids。
ER 总览（跨域骨架）
erDiagram
users ||--o{ subscriptions : has
users ||--o{ usage_quotas : has
users ||--o{ tasks : owns
users ||--o| agents : may_be
users ||--o{ orders : places
users ||--o{ canvas_projects : owns
users ||--o{ canvas_folders : owns
users ||--o{ user_assets : owns
users ||--o{ chat_sessions : owns
agents ||--o{ customer_agent_bindings : binds
agents ||--o{ commission_records : earns
agents ||--o{ commission_settlements : settles
agents ||--o{ agent_withdrawals : withdraws
member_plans ||--o{ orders : priced_by
orders ||--o{ payment_records : paid_via
product_categories ||--o{ product_sub_types : contains
product_sub_types ||--o{ hot_styles : has
fabric_types ||--o{ fabric_materials : contains
ai_model_groups ||--o{ ai_model_group_members : has
ai_models ||--o{ ai_model_group_members : in
tasks ||--o| task_params : params
tasks ||--o{ task_status_events : audits
tasks ||--o{ consumption_records : costs
全表索引
| 表名 |
域 |
用途（一句话） |
users |
用户 |
C 端用户（含主/子账号） |
admin_users |
用户 |
后台管理员 |
subscriptions |
用户 |
用户订阅 |
usage_quotas |
用户 |
使用配额 |
user_models |
用户 |
用户自定义模特 |
member_plans |
计费 |
会员方案 |
user_point_wallets |
计费 |
六桶积分钱包 |
agents |
计费 |
代理商 |
customer_agent_bindings |
计费 |
一客一代理绑定 |
customer_invite_bindings |
计费 |
人人邀请归属 |
agent_withdrawals |
计费 |
提现申请 |
agent_link_clicks |
计费 |
推广点击 |
agent_commission_rules |
计费 |
分账规则 |
commission_settlements |
计费 |
佣金月结批次 |
commission_records |
计费 |
分账明细 |
orders |
计费 |
订单 |
payment_records |
计费 |
支付流水 |
consumption_records |
计费 |
任务扣点 |
transaction_ledger |
计费 |
统一账户流水 |
daily_login_claims |
计费 |
每日登录积分领取 |
recon_batches |
计费 |
日终对账批次 |
product_categories |
产品 |
产品大类 |
product_sub_types |
产品 |
子类树 |
fabric_types |
产品 |
面料类型 |
fabric_materials |
产品 |
面料材质 |
sub_type_fabric_materials |
产品 |
子类×材质 |
product_styles |
产品 |
大类下风格 |
hot_styles |
产品 |
爆款叶子 |
comp_templates |
模板 |
构图模板 |
sub_type_comp_templates |
模板 |
子类×构图 |
scene_templates |
模板 |
场景模板 |
sub_type_scene_templates |
模板 |
子类×场景 |
model_templates |
模板 |
模特模板 |
model_template_poses |
模板 |
模特姿势 |
sub_type_model_templates |
模板 |
子类×模特 |
main_image_templates |
模板 |
主图模板 |
detail_image_templates |
模板 |
详情图模板 |
replica_image_templates |
模板 |
复刻模板 |
template_images |
模板 |
多态图库条目 |
ai_model_groups |
AI |
逻辑模型池 |
ai_models |
AI |
物理模型 |
ai_model_group_members |
AI |
模型↔池 |
ai_model_api_keys |
AI |
模型私有 Key（遗留） |
ai_model_api_accounts |
AI |
共享 API 账号 |
ai_model_account_bindings |
AI |
模型↔账号 |
model_generation_attributes |
AI |
模特生成属性选项 |
tasks |
任务 |
生图任务 |
task_params |
任务 |
任务参数 1:1 |
task_status_events |
任务 |
状态审计事件 |
prompt_test_runs |
任务 |
Admin Prompt 试跑 |
canvas_folders |
画布 |
画布文件夹（单层） |
canvas_projects |
画布 |
画布文档 |
user_assets |
画布 |
跨画布用户资产 |
chat_sessions |
Chat |
Chat↔Hermes 会话归属 |
word_sessions |
Word |
Word 上传解析会话 |
word_prompt_items |
Word |
Word 解析条目 |
video_categories |
视频 |
视频品类树（部分遗留） |
video_prompt_groups |
视频 |
提示词组 |
video_prompt_segments |
视频 |
分段提示词 |
video_scripts |
视频 |
共用剧本库 |
video_test_runs |
视频 |
Admin/流水线试跑 |
video_dead_letters |
视频 |
死信 |
system_configs |
系统 |
KV 配置 |
banners |
系统 |
Banner |
feature_cards |
系统 |
功能卡片 |
operation_logs |
系统 |
Admin 操作审计 |
迁移
| 项 |
说明 |
| 配置 |
仓库根 alembic_backend.ini → alembic_backend/ |
| 元数据发现 |
env.py import backend.db.models → Base.metadata |
| 本地升级 |
make backend-migrate |
| 生成迁移 |
alembic -c alembic_backend.ini revision --autogenerate -m "..." |
| 规范 |
生产只 upgrade head；禁止随意 drop/改类型；见 pre-commit check_alembic_migrations.py |
改库流程：先改 ORM → autogenerate 审查 → 迁移上线。勿以本文档直接改生产库。
根目录另有旧栈 alembic/（myapp），与 Backend 无关。