Lumen · AI 视频创作平台技术方案 v1.1 已与最终设计对齐

1.1 背景、目标与原则

现有体系由 7 个以上独立仓库拼成：Vue3 前端 wise-cut、Go 业务后端 wisecut、Python 工具型 Agent maa（100+ 工具）、对话式 Agent maa_agent、素材检索 knowhub、模型网关 insai-middle-platform、Go 工具集 go-maa-tools。业务已跑通，但存在"多 Agent 栈并存、两套任务/事件模型、MySQL+PostgreSQL 并存、配置散落 Nacos/TOML/ENV、无统一画布与时间线"等结构性问题。本方案不在旧项目上修补，从零设计一套平台。

1.2 旧系统业务知识抽取（只取"业务事实"，不取实现）

1.3 竞品分析（能力参考）

能力对比矩阵（● 已确认　◐ 部分　○ 未见　? 待实测）

1.4 用户角色与场景

1.5 功能需求（带编号，可直接转 Backlog）

1.6 范围边界与指标

2.1 架构原则

1. 模块化单体 + 少量独立服务：业务域强耦合部分（项目/画布/账务/素材）放在一个 Go 单体内按模块分层；只有"生命周期、伸缩特性、语言栈"明显不同的部分独立：Agent Runtime（Python）、模型网关、渲染集群、采集器，以及容量模型不同的实时推送与分析，共 6 个（见 2.3）。
2. 异步任务全部走持久化工作流：生成/渲染/采集一律由 Temporal 编排，不再自造租约与轮询。
3. 单一事实来源：PostgreSQL 为唯一业务库；所有状态机显式建模，状态只前进；副作用经 outbox 外发。
4. 账务先于调用：先报价、由用户批准，批准时冻结积分，再调用供应商；结果确定后结算或释放，状态不明时保持冻结、人工核对。
5. 画布即数据：Agent 的每个产物都是画布节点，用户与 Agent 编辑同一份文档（版本化）。
6. 供应商可替换：业务代码只依赖"能力（capability）"，不依赖具体模型名。

2.2 总体分层

flowchart TB
  subgraph Client[客户端]
    W[Web 应用 Next.js
画布 / 时间线 / 对话]
    O[开放平台
REST · Webhook · MCP · Skill]
  end
  subgraph Edge[接入层]
    GW[API Gateway / BFF
鉴权 · 限流 · WAF]
    RT[实时通道
SSE / WebSocket]
  end
  subgraph Core[核心域服务 Go 模块化单体]
    ID[Identity & Org]
    PR[Project & Canvas]
    AS[Asset & Library]
    BL[Billing & Ledger]
    SF[Safety]
    TK[Task Facade]
    ADM[Admin & Config]
  end
  subgraph Agent[Agent 域 Python]
    AR[Agent Runtime
LangGraph]
    SK[Skill Registry]
    TL[Tool Servers MCP]
  end
  subgraph Gen[生成域]
    MG[Model Gateway]
    RN[Render Service
FFmpeg · GPU]
    CR[Crawler / Collector]
  end
  subgraph Plat[平台层]
    TP[Temporal]
    PG[(PostgreSQL)]
    RD[(Redis)]
    KF[(Kafka)]
    OS[(COS/S3 + CDN)]
    CH[(ClickHouse)]
    VS[(pgvector)]
  end
  W --> GW
  O --> GW
  W --> RT
  GW --> Core
  GW --> AR
  Core --> TP
  AR --> TP
  TP --> MG
  TP --> RN
  TP --> CR
  AR --> TL
  TL --> Core
  MG --> Vendors[(模型供应商
Seedance · Kling · Wan · Veo · GPT-Image ...)]
  Core --> PG
  Core --> RD
  Core --> KF
  RN --> OS
  KF --> CH
  AS --> VS

2.3 服务清单与边界

core 内部模块与依赖规则

core/
├── identity/    用户、组织、工作区、角色、API Key、OAuth
├── project/     项目、画布文档、节点、版本、协作锁
├── asset/       素材、解析、打标、向量检索、角色资产（asset.kind = character_ref）
├── billing/     账本、冻结/结算、订阅、订单、支付、发票
├── safety/      审核策略、违禁词、风控规则
├── taskfacade/  对外统一"生成任务"视图，屏蔽 Temporal/Gateway 细节
├── admin/       模型目录、价格、限额、配置、审计
└── platform/    db、cache、outbox、event、temporal client、telemetry（只被上面引用）
规则：模块间只通过 Go interface（每个模块的 api 包）调用；禁止跨模块直接读表；
      CI 里用 depguard + archunit 风格测试强制，违反即失败。

2.4 领域模型（限界上下文）

下图由最终 DDL 生成，用的是真实表名和真实基数（鸦脚符号）。原设计这里画的 CANVAS 实体在最终版不单独建表：画布 = project + node + edge；原图里“一个工作区一个账本账户”也不对，最终版每个工作区按用途有多个账户（UNIQUE(workspace_id, kind)）。完整 45 张表见 ER 图页。

erDiagram
  workspace ||--o{ member : "workspace_id"
  workspace ||--o{ project : "workspace_id"
  asset |o--o{ project : "cover_asset_id"
  project ||--o{ node : "project_id"
  workspace ||--o{ node : "workspace_id"
  node |o--o{ node : "parent_id"
  node ||--o{ node_version : "node_id"
  asset |o--o{ node_version : "output_asset_id"
  generation_task |o--o{ node_version : "task_id"
  project ||--o{ edge : "project_id"
  node ||--o{ edge : "src_node_id"
  node ||--o{ edge : "dst_node_id"
  project ||--o{ timeline : "project_id"
  workspace ||--o{ timeline : "workspace_id"
  workspace ||--o{ export_job : "workspace_id"
  timeline ||--o{ export_job : "timeline_id"
  asset |o--o{ export_job : "output_asset_id"
  hold |o--o| export_job : "hold_id"
  project ||--o{ agent_session : "project_id"
  workspace ||--o{ agent_session : "workspace_id"
  agent_session ||--o{ agent_run : "session_id"
  workspace ||--o{ agent_run : "workspace_id"
  agent_run ||--o{ run_event : "run_id"
  agent_run ||--o{ interaction : "run_id"
  workspace ||--o{ generation_task : "workspace_id"
  project |o--o{ generation_task : "project_id"
  node |o--o{ generation_task : "node_id"
  agent_run |o--o{ generation_task : "run_id"
  hold |o--o| generation_task : "hold_id"
  generation_task ||--o{ task_attempt : "task_id"
  workspace ||--o{ asset : "workspace_id"
  generation_task |o--o{ asset : "origin_task_id"
  workspace |o--o{ ledger_account : "workspace_id"
  ledger_account ||--o{ ledger_entry : "account_id"
  point_lot |o--o{ ledger_entry : "lot_id"
  workspace ||--o{ point_lot : "workspace_id"
  workspace ||--o{ hold : "workspace_id"
  generation_quote ||--o{ generation_approval : "quote_id"
  generation_task |o--o{ generation_approval : "task_id"
  org ||--o{ workspace : "org_id"
  app_user ||--o{ member : "user_id"
  app_user ||--o{ agent_session : "user_id"
  app_user ||--o{ project : "owner_id"
  skill ||--o{ skill_version : "skill_id"
  skill ||--o{ agent_session : "skill_id"
  workspace |o--o{ skill : "owner_workspace_id"
  workspace ||--o{ generation_quote : "workspace_id"
  agent_run |o--o{ generation_quote : "source_run_id"
  project ||--o{ project_asset_ref : "project_id"
  asset ||--o{ project_asset_ref : "asset_id"
  timeline ||--o{ timeline_version : "timeline_id"

2.5 关键架构决策（ADR 摘要）

2.6 Agent 架构

flowchart LR
  U[用户消息/链接/参考视频] --> O[Orchestrator]
  O -->|plan| P[Plan 节点
可编辑]
  O --> E1[采集专家]
  O --> E2[策略/脚本专家]
  O --> E3[分镜专家]
  O --> E4[生产专家]
  O --> E5[后期专家]
  E1 & E2 & E3 & E4 & E5 -->|MCP tool call| T[(Tool Servers)]
  T --> C[Canvas API]
  T --> G[Generation API]
  T --> A[Asset API]
  E4 -->|提交| TF[Task Facade]
  O <-->|interrupt / resume| H[HITL 卡片]
  O --> CP[(Checkpoint PG)]

• Skill 包：目录结构 skill.yaml + prompts/ + tools.json + evals/，版本化（skill_version）、可发布到开放平台（POST /skills）；会话创建时固定一个版本。灰度发布没有单独建模。旧 ad-video-editing / viral-ad-replication / product-link-collection 等能力包直接作为初始 Skill 迁移。
• 工具通过 MCP：Core 与 Gateway 各暴露 MCP Server，Agent 与外部 Agent 使用同一套工具，避免"内部一套外部一套"。
• 产物溯源：每个视频节点的版本（node_version）必须记录 task_id；经 task_attempt 可追到 provider_task_id，经 generation_task.request_hash 可追到输入。Agent 不能凭空写入成片 URL（继承旧系统硬规则）。
• 预算守卫：Run 持有 budget_centi（预算）与 spent_centi（已花）；接近上限发 budget.warning，超限进入 waiting_user 由用户决定。

2.7 部署视图（单 Region）

flowchart TB
  CDN[CDN] --> LB[LB / Ingress]
  LB --> AP[core ×N]
  LB --> RTM[realtime ×N]
  LB --> AG[agent-runtime ×N]
  AP --> PGM[(PG 主)]
  PGM --> PGR[(PG 只读副本 ×2)]
  AP --> RDS[(Redis Cluster)]
  AP --> KFK[(Kafka 3 节点)]
  AP --> TPS[Temporal 集群]
  TPS --> WK1[workflow worker]
  WK1 --> MGW[model-gateway ×N]
  WK1 --> RNW[render worker
CPU Pool + GPU Pool]
  WK1 --> COL[collector 浏览器池]
  RNW --> COS[(对象存储)]
  KFK --> CHS[(ClickHouse)]

3.1 选型方法

每项选型按 团队熟悉度 20% · 生态成熟度 20% · 性能/伸缩 20% · 运维成本 15% · 可替换性 10% · 合规/数据驻留 15% 打分（1–5），写明备选与否决理由。旧技术栈（Vue3、Go/Gin、Python/FastAPI、MySQL+PG）只作"团队已有能力"的输入项，不构成约束。

3.2 选型总表

3.3 模型供应商策略

3.4 关键选型论证

为什么引入 Temporal 而不是延续"PG 租约 + Redis Streams"

为什么单一 PostgreSQL

旧系统业务库为 MySQL，Agent/网关侧为 PostgreSQL，数据与口径割裂。新方案统一 PG：事务、JSONB 画布文档、部分唯一索引（"同会话仅一个 active run"可直接用 UNIQUE ... WHERE status IN (...)）、pgvector 一体化。大表（run_event、ledger_entry）按月分区（最终版没有 task_event 表）；超过 TB 级后以 Citus/分库按 workspace_id 切分，表设计从第一天就带 workspace_id。

前端为什么重选 React

核心交互是无限画布与多轨时间线，其依赖库（React Flow、dnd-kit、Remotion Player 等）集中于 React；旧项目 Vue3 的 Arco 组件体系可被 Radix + Tailwind 替换。迁移成本由新项目承担，不涉及旧页面兼容。

3.5 技术风险与缓解

4.1 数据设计总则

• PostgreSQL 16，不建数据库外键（沿用旧网关经验），一致性由应用事务、唯一索引、对账任务保证。
• 主键：对外资源用 ULID（CHAR(26)，带前缀如 prj_、tsk_ 仅在 API 层加）；内部流水用 BIGINT IDENTITY。
• 租户内的业务表带 workspace_id（分库键）；子表经父表确定工作区（例如 node_version 经 node）；全局表（用户、组织、模型目录、技能、套餐）不带。时间用 timestamptz；需要软删除的表用 deleted_at。
• 金额与积分：BIGINT 存最小单位（积分 = 1/100 点，即 "centi-point"；货币 = 分/美分），禁止浮点。
• 大表按月分区：run_event、ledger_entry。原设计还列了 task_event、usage_record，最终版没有建这两张表（任务事件走 outbox，用量从账本与任务聚合进 ClickHouse）。
• 状态字段用 TEXT + CHECK，状态迁移通过 UPDATE ... WHERE status = :from 乐观实现，不满足影响行数为 0 即视为冲突。

4.2 表域总览（最终版）

原设计提到、最终版没有单独建表的表

原设计的“表域总览”列了约 60 个名字，但只给了 30 张的 DDL。最终版把每个名字都交代清楚：要么建了，要么说明由谁代替，要么明确没做。

4.3 表结构与 DDL（最终版）

按域列出每张表的列（类型、可空、默认值都来自库内读取）；完整 DDL 是同一份可直接执行的脚本，账本分录表带“只追加”触发器。

租户与成员

画布 · 时间轴（项目文档）

⭕ Agent 交互

生成 · 报价批准 · 模型

素材

积分账本 · 订阅 · 额度

平台

完整 DDL（PostgreSQL 16）

CREATE TABLE workspace (
  id            CHAR(26) PRIMARY KEY,
  org_id        CHAR(26) NOT NULL,
  name          TEXT NOT NULL,
  region        TEXT NOT NULL CHECK (region IN ('cn','global')),
  plan_code     TEXT NOT NULL DEFAULT 'free',
  status        TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','suspended','closed')),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE member (
  id            BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  user_id       CHAR(26) NOT NULL,
  role          TEXT NOT NULL CHECK (role IN ('owner','admin','editor','viewer')),
  seat          BOOLEAN NOT NULL DEFAULT true,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (workspace_id, user_id)
);

CREATE TABLE api_key (
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  name          TEXT NOT NULL,
  key_prefix    TEXT NOT NULL,            -- 展示用前 8 位
  key_hash      BYTEA NOT NULL UNIQUE,    -- SHA-256，明文不入库
  scopes        TEXT[] NOT NULL,          -- e.g. {'generate:write','project:read'}
  status        TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','revoked','expired')),
  expires_at    TIMESTAMPTZ,
  last_used_at  TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE project (
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  owner_id      CHAR(26) NOT NULL,
  title         TEXT NOT NULL,
  kind          TEXT NOT NULL CHECK (kind IN ('freeform','url_ad','viral_clone','drama','batch')),
  aspect_ratio  TEXT NOT NULL DEFAULT '9:16',
  language      TEXT NOT NULL DEFAULT 'en',
  cover_asset_id CHAR(26),
  status        TEXT NOT NULL DEFAULT 'draft' CHECK (status IN ('draft','generating','ready','archived')),
  doc_version   BIGINT NOT NULL DEFAULT 0,        -- 画布整体版本，节点变更自增
  deleted_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX project_ws_updated ON project (workspace_id, updated_at DESC) WHERE deleted_at IS NULL;

CREATE TABLE node (
  id            CHAR(26) PRIMARY KEY,
  project_id    CHAR(26) NOT NULL,
  workspace_id  CHAR(26) NOT NULL,
  type          TEXT NOT NULL CHECK (type IN
                 ('text','script','image','video','audio','character','storyboard','scene','shot','ref_video','product','plan','final_video')),
  parent_id     CHAR(26),                       -- scene → shot 层级
  title         TEXT,
  pos_x         REAL NOT NULL DEFAULT 0,
  pos_y         REAL NOT NULL DEFAULT 0,
  data          JSONB NOT NULL DEFAULT '{}',    -- 按 type 的 schema，见 4.5
  current_ver   INT NOT NULL DEFAULT 1,
  lock_owner    CHAR(26),                       -- 节点级编辑提示锁（软锁，30s 租期）
  lock_until    TIMESTAMPTZ,
  status        TEXT NOT NULL DEFAULT 'idle' CHECK (status IN ('idle','pending','running','done','failed','stale')),
  created_by    TEXT NOT NULL,                  -- 'user:<id>' | 'agent:<run_id>'
  deleted_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX node_project ON node (project_id) WHERE deleted_at IS NULL;

CREATE TABLE node_version (
  node_id       CHAR(26) NOT NULL,
  version       INT NOT NULL,
  data          JSONB NOT NULL,
  output_asset_id CHAR(26),                     -- 该版本产物
  task_id       CHAR(26),                       -- 来源生成任务（溯源）
  created_by    TEXT NOT NULL,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (node_id, version)
);

CREATE TABLE edge (
  id            CHAR(26) PRIMARY KEY,
  project_id    CHAR(26) NOT NULL,
  src_node_id   CHAR(26) NOT NULL,
  dst_node_id   CHAR(26) NOT NULL,
  kind          TEXT NOT NULL CHECK (kind IN ('data','ref','sequence')),
  UNIQUE (src_node_id, dst_node_id, kind)
);

CREATE TABLE timeline (
  id           CHAR(26) PRIMARY KEY,
  project_id   CHAR(26) NOT NULL,
  workspace_id CHAR(26) NOT NULL,
  fps          SMALLINT NOT NULL DEFAULT 30,
  width        INT NOT NULL, height INT NOT NULL,
  duration_ms  INT NOT NULL DEFAULT 0,
  doc          JSONB NOT NULL,             -- 轨道/片段/转场/字幕样式，见 4.5
  version      BIGINT NOT NULL DEFAULT 1,
  updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE export_job (
  id           CHAR(26) PRIMARY KEY,
  workspace_id CHAR(26) NOT NULL,
  timeline_id  CHAR(26) NOT NULL,
  timeline_ver BIGINT NOT NULL,
  preset       TEXT NOT NULL,              -- '1080p_h264' | '720p_h264' | '4k_h265'
  status       TEXT NOT NULL DEFAULT 'queued'
               CHECK (status IN ('queued','rendering','succeeded','failed','cancelled')),
  workflow_id  TEXT,
  output_asset_id CHAR(26),
  hold_id      CHAR(26) UNIQUE,                 -- 一个导出只对应一笔冻结（与 hold.UNIQUE(ref_type, ref_id) 一致）
  error_code   TEXT, error_message TEXT,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  finished_at  TIMESTAMPTZ
);

CREATE TABLE agent_session (
  id            CHAR(26) PRIMARY KEY,
  project_id    CHAR(26) NOT NULL,
  workspace_id  CHAR(26) NOT NULL,
  user_id       CHAR(26) NOT NULL,
  skill_id      TEXT NOT NULL,              -- 'url_to_ad' | 'viral_clone' | 'freeform'
  skill_version TEXT NOT NULL,              -- 会话创建时固定的技能版本（决策 D9）
  title         TEXT,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE agent_run (
  id             CHAR(26) PRIMARY KEY,
  session_id     CHAR(26) NOT NULL,
  workspace_id   CHAR(26) NOT NULL,
  status         TEXT NOT NULL CHECK (status IN
                  ('queued','running','waiting_user','succeeded','failed','cancelled')),
  workflow_id    TEXT NOT NULL,
  skill_version  TEXT NOT NULL,
  budget_centi   BIGINT NOT NULL,           -- 本 run 预算
  spent_centi    BIGINT NOT NULL DEFAULT 0,
  input          JSONB NOT NULL,
  error_code     TEXT, error_message TEXT,
  started_at     TIMESTAMPTZ, finished_at TIMESTAMPTZ,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 同一会话同一时刻只允许一个"活跃 run"
CREATE UNIQUE INDEX one_active_run_per_session
  ON agent_run (session_id) WHERE status IN ('queued','running','waiting_user');

CREATE TABLE run_event (
  id           BIGINT GENERATED ALWAYS AS IDENTITY,
  run_id       CHAR(26) NOT NULL,
  seq          INT NOT NULL,                -- run 内单调递增，SSE 断线续传依据
  type         TEXT NOT NULL,               -- 见 5.6 事件表
  payload      JSONB NOT NULL,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (created_at, id)
) PARTITION BY RANGE (created_at);
CREATE UNIQUE INDEX run_event_run_seq ON run_event (run_id, seq, created_at);

CREATE TABLE interaction (
  id            CHAR(26) PRIMARY KEY,
  run_id        CHAR(26) NOT NULL,
  kind          TEXT NOT NULL,              -- 'collect_info'|'confirm_plan'|'pick_option'|'confirm_cost'|'review_script'
  request       JSONB NOT NULL,
  response      JSONB,
  card_sha256   CHAR(64),                   -- 卡片内容哈希：答案按原卡校验
  schema        JSONB,                      -- 字段 key / kind / required / options
  client_action_id TEXT,                    -- 幂等键
  status        TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','resolved','expired','cancelled')),
  expires_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  resolved_at   TIMESTAMPTZ
);
CREATE UNIQUE INDEX interaction_idem ON interaction (id, client_action_id) WHERE client_action_id IS NOT NULL;

CREATE TABLE model_catalog (
  id             CHAR(26) PRIMARY KEY,
  capability     TEXT NOT NULL,             -- 't2v' 'i2v' 'flf2v' 'r2v' 't2i' 'tts' 'lipsync' ...
  provider_key   TEXT NOT NULL,             -- 'ark' 'dashscope' 'tencent_vod' ...
  model_name     TEXT NOT NULL,
  display_name   TEXT NOT NULL,
  input_schema   JSONB NOT NULL,            -- JSON Schema：可传参数
  limits         JSONB NOT NULL,            -- 最长时长、分辨率、参考图数量
  default_params JSONB NOT NULL DEFAULT '{}',
  max_concurrency INT NOT NULL DEFAULT 10,
  timeout_s      INT NOT NULL DEFAULT 900,
  status         TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','disabled','beta')),
  adapter_key    TEXT NOT NULL DEFAULT 'default',  -- 适配器注册键：新增模型只加数据 + 一个适配器
  UNIQUE (provider_key, model_name, capability)
);

CREATE TABLE price_rule (
  id            CHAR(26) PRIMARY KEY,
  model_id      CHAR(26) NOT NULL,
  unit          TEXT NOT NULL CHECK (unit IN ('second','image','token','call','char')),
  cost_micro    BIGINT NOT NULL,            -- 我方成本，1e-6 USD
  charge_centi  BIGINT NOT NULL,            -- 向用户收取积分(1/100 点)/单位
  modifiers     JSONB NOT NULL DEFAULT '{}',-- {"resolution":{"1080p":1.5},"audio":1.3}
  effective_from TIMESTAMPTZ NOT NULL,
  effective_to   TIMESTAMPTZ
);

CREATE TABLE generation_task (
  id             CHAR(26) PRIMARY KEY,
  workspace_id   CHAR(26) NOT NULL,
  project_id     CHAR(26),
  node_id        CHAR(26),
  run_id         CHAR(26),
  api_key_id     CHAR(26),
  capability     TEXT NOT NULL,
  model_id       CHAR(26),                  -- 路由决定后写入
  request        JSONB NOT NULL,
  request_hash   BYTEA NOT NULL,
  idem_key       TEXT,
  status         TEXT NOT NULL CHECK (status IN
                  ('created','held','queued','submitting','submit_uncertain','running',
                   'succeeded','failed','cancelling','cancelled','expired')),
  hold_id        CHAR(26) UNIQUE,                   -- 一个任务只对应一笔冻结（与 hold.UNIQUE(ref_type, ref_id) 一致）
  quoted_centi   BIGINT NOT NULL,
  charged_centi  BIGINT,
  outputs        JSONB,
  error_code     TEXT, error_message TEXT,
  workflow_id    TEXT,
  attempt_count  INT NOT NULL DEFAULT 0,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  finished_at    TIMESTAMPTZ
);
CREATE UNIQUE INDEX task_idem ON generation_task (workspace_id, idem_key) WHERE idem_key IS NOT NULL;
CREATE INDEX task_ws_created ON generation_task (workspace_id, created_at DESC);
CREATE INDEX task_active ON generation_task (status) WHERE status IN ('queued','submitting','submit_uncertain','running','cancelling');

CREATE TABLE task_attempt (
  id             CHAR(26) PRIMARY KEY,
  task_id        CHAR(26) NOT NULL,
  seq            SMALLINT NOT NULL,
  model_id       CHAR(26) NOT NULL,
  provider_task_id TEXT,
  provider_request_id TEXT,
  status         TEXT NOT NULL,             -- submitted/succeeded/failed/uncertain
  cost_micro     BIGINT,
  usage          JSONB,
  error_code     TEXT, error_message TEXT,
  submitted_at   TIMESTAMPTZ, finished_at TIMESTAMPTZ,
  UNIQUE (task_id, seq)
);
CREATE INDEX attempt_provider ON task_attempt (model_id, provider_task_id);

CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE asset (
  id           CHAR(26) PRIMARY KEY,
  workspace_id CHAR(26) NOT NULL,
  kind         TEXT NOT NULL CHECK (kind IN ('image','video','audio','font','doc','character_ref')),
  source       TEXT NOT NULL CHECK (source IN ('upload','generated','collected','library')),
  storage_key  TEXT NOT NULL,               -- COS/S3 key
  mime         TEXT NOT NULL, bytes BIGINT NOT NULL,
  duration_ms  INT, width INT, height INT, fps REAL,
  sha256       BYTEA NOT NULL,
  origin_task_id CHAR(26),                  -- 生成溯源
  origin_url   TEXT,                        -- 采集来源
  moderation   TEXT NOT NULL DEFAULT 'pending' CHECK (moderation IN ('pending','pass','review','reject')),
  tags         TEXT[] NOT NULL DEFAULT '{}',
  meta         JSONB NOT NULL DEFAULT '{}',
  deleted_at   TIMESTAMPTZ,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX asset_ws_kind ON asset (workspace_id, kind, created_at DESC) WHERE deleted_at IS NULL;
CREATE INDEX asset_hash ON asset (workspace_id, sha256);

CREATE TABLE asset_embedding (
  asset_id   CHAR(26) NOT NULL,
  segment_no INT NOT NULL DEFAULT 0,        -- 视频按镜头切分
  start_ms   INT, end_ms INT,
  caption    TEXT,
  embedding  vector(1024) NOT NULL,
  PRIMARY KEY (asset_id, segment_no)
);
CREATE INDEX asset_emb_hnsw ON asset_embedding USING hnsw (embedding vector_cosine_ops) WITH (m=16, ef_construction=128);

CREATE TABLE retrieval_seen (                -- 继承旧 knowhub 的 context_key 去重语义
  context_key TEXT NOT NULL,
  asset_id    CHAR(26) NOT NULL,
  PRIMARY KEY (context_key, asset_id)
);

CREATE TABLE ledger_account (
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26),                   -- 系统账户为 NULL
  kind          TEXT NOT NULL CHECK (kind IN
                 ('wallet_paid','wallet_bonus','wallet_subscription','held','revenue','cost_of_goods','expired','refund_pool')),
  balance_centi BIGINT NOT NULL DEFAULT 0,  -- 缓存余额，可由 entry 重算
  version       BIGINT NOT NULL DEFAULT 0,
  UNIQUE (workspace_id, kind)
);

CREATE TABLE ledger_entry (
  id            BIGINT GENERATED ALWAYS AS IDENTITY,
  txn_id        CHAR(26) NOT NULL,          -- 同一笔业务的所有分录
  account_id    CHAR(26) NOT NULL,
  direction     SMALLINT NOT NULL CHECK (direction IN (1,-1)),   -- +入 / -出
  amount_centi  BIGINT NOT NULL CHECK (amount_centi > 0),
  ref_type      TEXT NOT NULL,              -- 'hold'|'task'|'run'|'order'|'subscription'|'adjust'|'expire'（run = 对话推理用量，task = 媒体生成，决策 D4）
  ref_id        TEXT NOT NULL,
  lot_id        CHAR(26),                   -- 积分批次（有过期时间、扣减顺序）
  memo          TEXT,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (created_at, id)
) PARTITION BY RANGE (created_at);
CREATE INDEX entry_txn ON ledger_entry (txn_id);
CREATE INDEX entry_ref ON ledger_entry (ref_type, ref_id);

CREATE TABLE point_lot (                      -- 积分批次：过期时间 + 扣减优先级
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  source        TEXT NOT NULL CHECK (source IN ('purchase','subscription','bonus','promo','compensation')),
  granted_centi BIGINT NOT NULL,
  remaining_centi BIGINT NOT NULL,
  expires_at    TIMESTAMPTZ,
  priority      SMALLINT NOT NULL,          -- 小者先扣：promo < subscription < bonus < purchase
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX lot_spend ON point_lot (workspace_id, priority, expires_at NULLS LAST) WHERE remaining_centi > 0;

CREATE TABLE hold (
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  ref_type      TEXT NOT NULL, ref_id TEXT NOT NULL,
  amount_centi  BIGINT NOT NULL,
  status        TEXT NOT NULL CHECK (status IN ('active','settled','released','expired')),
  lot_allocation JSONB NOT NULL,            -- [{lot_id, centi}]，释放/结算时按此回写
  expires_at    TIMESTAMPTZ NOT NULL,       -- 兜底：超时自动 release
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (ref_type, ref_id)                 -- 同一业务只能一个冻结 → 幂等
);

CREATE TABLE plan (
  code TEXT PRIMARY KEY, name TEXT NOT NULL, interval TEXT NOT NULL CHECK (interval IN ('month','year')),
  price_cents INT NOT NULL, currency TEXT NOT NULL,
  monthly_points_centi BIGINT NOT NULL, seats INT NOT NULL, features JSONB NOT NULL
);
CREATE TABLE subscription (
  id CHAR(26) PRIMARY KEY, workspace_id CHAR(26) NOT NULL, plan_code TEXT NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('trialing','active','past_due','cancelled','expired')),
  provider TEXT NOT NULL, provider_sub_id TEXT NOT NULL,
  current_period_start TIMESTAMPTZ, current_period_end TIMESTAMPTZ,
  cancel_at_period_end BOOLEAN NOT NULL DEFAULT false,
  UNIQUE (provider, provider_sub_id)
);
CREATE TABLE purchase_order (
  id CHAR(26) PRIMARY KEY, workspace_id CHAR(26) NOT NULL,
  kind TEXT NOT NULL CHECK (kind IN ('subscription','topup','seat','storage')),
  sku_code TEXT, amount_cents INT NOT NULL, currency TEXT NOT NULL,
  status TEXT NOT NULL CHECK (status IN ('created','paid','failed','refunded','partially_refunded')),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE payment_event (                  -- Webhook 原始事件，幂等入账依据
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  provider TEXT NOT NULL, event_id TEXT NOT NULL, type TEXT NOT NULL,
  payload JSONB NOT NULL, processed_at TIMESTAMPTZ,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (provider, event_id)
);

CREATE TABLE outbox (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  topic TEXT NOT NULL, key TEXT NOT NULL, payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','sent','dead')),
  attempts INT NOT NULL DEFAULT 0, next_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX outbox_pending ON outbox (next_at) WHERE status='pending';

CREATE TABLE audit_log (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  workspace_id CHAR(26), actor TEXT NOT NULL, action TEXT NOT NULL,
  target_type TEXT, target_id TEXT, diff JSONB, ip INET, created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- 分区父表必须有分区才能写入。DEFAULT 分区兜底；生产用 pg_partman 按月预建并滚动归档。
CREATE TABLE run_event_default    PARTITION OF run_event    DEFAULT;
CREATE TABLE ledger_entry_default PARTITION OF ledger_entry DEFAULT;

-- ===== 吸收竞品后新增的 7 张表 =====
-- 1) 报价与批准：批准必须带两个哈希，并有有效期（来自复刻里跑通的流程；LibTV 预算只提醒的做法被否决）
CREATE TABLE generation_quote (
  id              CHAR(26) PRIMARY KEY,
  workspace_id    CHAR(26) NOT NULL,
  client_request_id TEXT NOT NULL,
  request_sha256  CHAR(64) NOT NULL,              -- 提示词、参数、模型版本的规范化摘要
  quote_sha256    CHAR(64) NOT NULL,              -- 价格与有效期的摘要
  model_version_id CHAR(26) NOT NULL,
  quoted_centi    BIGINT NOT NULL CHECK (quoted_centi >= 0),
  expires_at      TIMESTAMPTZ NOT NULL,
  source_run_id   CHAR(26),                       -- 来自 Agent 回复时记录来源
  source_sha256   CHAR(64),
  status          TEXT NOT NULL DEFAULT 'quoted' CHECK (status IN ('quoted','approved','expired','rejected')),
  UNIQUE (workspace_id, client_request_id)
);
CREATE TABLE generation_approval (
  id               CHAR(26) PRIMARY KEY,
  quote_id         CHAR(26) NOT NULL,             -- → generation_quote.id（沿用 Lumen 约定：不建数据库外键，靠应用层与唯一键）
  client_approval_id TEXT NOT NULL,
  request_sha256   CHAR(64) NOT NULL,
  quote_sha256     CHAR(64) NOT NULL,
  task_id          CHAR(26),
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (quote_id, client_approval_id)            -- 重放只返回同一个任务
);
-- 2) 审批策略：Ask First / Always Allow（来自 TopView），带额度上限
CREATE TABLE approval_policy (
  id              CHAR(26) PRIMARY KEY,
  workspace_id    CHAR(26) NOT NULL,
  member_id       BIGINT,                         -- NULL = 工作区默认策略
  mode            TEXT NOT NULL CHECK (mode IN ('ask_first','always_allow_within_limit')),
  per_task_limit_centi BIGINT,
  daily_limit_centi    BIGINT
);
CREATE UNIQUE INDEX approval_policy_scope ON approval_policy (workspace_id, COALESCE(member_id, 0));
-- 3) 额度窗口：日额度与「额外用量」开关（来自 CreaTok）；与积分分开
CREATE TABLE quota_window (
  workspace_id    CHAR(26) NOT NULL,
  window_start    DATE NOT NULL,
  kind            TEXT NOT NULL CHECK (kind IN ('agent_daily','plan_monthly')),
  limit_units     BIGINT NOT NULL,
  used_units      BIGINT NOT NULL DEFAULT 0,
  overage_enabled BOOLEAN NOT NULL DEFAULT FALSE,
  PRIMARY KEY (workspace_id, window_start, kind)
);
-- 4) 创作意图：URL / 商品 / 脚本 / 参考视频等入口统一成 intent（来自 Creatify、Pollo、TopView）
CREATE TABLE intent (
  id              CHAR(26) PRIMARY KEY,
  workspace_id    CHAR(26) NOT NULL,
  project_id      CHAR(26) NOT NULL,
  adapter         TEXT NOT NULL,                  -- 'url' | 'product' | 'script' | 'ref_video' | 'freeform'
  source_ref      JSONB NOT NULL,
  skill_id        TEXT,
  skill_version   TEXT,
  status          TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open','planned','running','done','cancelled')),
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 5) 模型注册：版本、价格表、适配器键（我们在复刻里遇到的最大扩展障碍）
CREATE TABLE model_version (
  id              CHAR(26) PRIMARY KEY,
  model_id        CHAR(26) NOT NULL,              -- → model_catalog.id
  version_key     TEXT NOT NULL,
  config          JSONB NOT NULL,                 -- 时长/画幅/分辨率约束、价格表、是否可取消
  config_sha256   CHAR(64) NOT NULL,
  published_at    TIMESTAMPTZ,
  UNIQUE (model_id, version_key)
);
-- 6) 动作回执：消息、停止、切换模型、澄清卡回答都是幂等动作
CREATE TABLE run_action (
  id              CHAR(26) PRIMARY KEY,
  run_id          CHAR(26) NOT NULL,
  kind            TEXT NOT NULL CHECK (kind IN ('message','stop','model_change','interaction_response')),
  client_action_id TEXT NOT NULL,
  request_sha256  CHAR(64) NOT NULL,
  status          TEXT NOT NULL,                  -- accepted | terminal_observed | rejected | unknown
  attempt         INT NOT NULL DEFAULT 1,
  result          JSONB,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (run_id, kind, client_action_id)         -- 同一个动作 ID 内容不同则冲突（409）
);
-- 7) 澄清卡：带内容哈希，答案按原卡校验

-- 补全：最终设计里被其他表、接口、决策引用，但原设计没有给 DDL 的表。
-- 沿用 Lumen 的约定：不建数据库外键，关系由应用层与唯一键保证。
CREATE TABLE org (
  id            CHAR(26) PRIMARY KEY,
  name          TEXT NOT NULL,
  status        TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','suspended','closed')),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE app_user (                          -- “user” 是 PostgreSQL 保留字，所以叫 app_user
  id            CHAR(26) PRIMARY KEY,
  email         TEXT NOT NULL UNIQUE,
  display_name  TEXT,
  password_hash TEXT,                              -- 为空表示走 SSO
  status        TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','locked','deleted')),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  last_login_at TIMESTAMPTZ
);

CREATE TABLE session_token (                     -- 刷新令牌（只存哈希），登出与轮换都落在这里
  id            CHAR(26) PRIMARY KEY,
  user_id       CHAR(26) NOT NULL,
  token_hash    BYTEA NOT NULL UNIQUE,
  expires_at    TIMESTAMPTZ NOT NULL,
  revoked_at    TIMESTAMPTZ,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE skill (
  id                 TEXT PRIMARY KEY,             -- 'url_to_ad' | 'viral_clone' | 'freeform' | 开发者发布的 id
  display_name       TEXT NOT NULL,
  owner_workspace_id CHAR(26),                     -- 为空表示官方
  status             TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','retired')),
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE skill_version (                     -- 会话创建时固定一个版本，发布新版不影响进行中的会话
  skill_id      TEXT NOT NULL,
  version       TEXT NOT NULL,
  manifest      JSONB NOT NULL,
  sha256        CHAR(64) NOT NULL,
  status        TEXT NOT NULL DEFAULT 'published' CHECK (status IN ('draft','published','retired')),
  published_at  TIMESTAMPTZ,
  PRIMARY KEY (skill_id, version)
);

CREATE TABLE webhook_endpoint (                  -- 开放平台回调地址；投递走 outbox
  id            CHAR(26) PRIMARY KEY,
  workspace_id  CHAR(26) NOT NULL,
  url           TEXT NOT NULL,
  secret_hash   BYTEA NOT NULL,
  events        TEXT[] NOT NULL,
  status        TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','disabled')),
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE project_asset_ref (                 -- 素材归工作区，项目只记引用和用途（项目 ⇄ 素材 多对多）
  project_id    CHAR(26) NOT NULL,
  asset_id      CHAR(26) NOT NULL,
  purpose       TEXT NOT NULL DEFAULT 'reference',
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (project_id, asset_id)
);

CREATE TABLE timeline_version (                  -- 时间线每次保存一条历史；恢复 = 以旧内容新建一个版本
  timeline_id   CHAR(26) NOT NULL,
  version       BIGINT NOT NULL,
  doc           JSONB NOT NULL,
  restored_from BIGINT,
  created_by    TEXT NOT NULL,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (timeline_id, version)
);

-- 账本只追加：分录写入后不能改、不能删（决策 D3）。归档用分区的 DETACH，不经过这个触发器。
CREATE FUNCTION ledger_entry_append_only() RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
  RAISE EXCEPTION 'ledger_entry is append-only';
END $$;
CREATE TRIGGER ledger_entry_no_change BEFORE UPDATE OR DELETE ON ledger_entry
  FOR EACH ROW EXECUTE FUNCTION ledger_entry_append_only();

4.4 状态机

生成任务 generation_task

stateDiagram-v2
  [*] --> created: 批准报价（与冻结同一事务）
  created --> held: 冻结积分成功（同一事务内）
  held --> queued: outbox 启动工作流
  queued --> cancelled: 排队中取消
  queued --> submitting: Worker 领取
  submitting --> running: 供应商受理(拿到 provider_task_id)
  submitting --> submit_uncertain: 超时/连接断开,是否受理未知
  submit_uncertain --> running: 查询确认已受理
  submit_uncertain --> queued: 查询确认未受理,重投(可换供应商)
  running --> succeeded: 产物落库+审核通过
  running --> failed: 供应商失败/审核拒绝
  running --> cancelling: 用户取消
  cancelling --> cancelled: 供应商确认/超时强制
  running --> expired: 超过 timeout
  succeeded --> [*]
  failed --> [*]
  cancelled --> [*]
  expired --> [*]

结算规则：succeeded → settle（实扣 = 报价，可含供应商返回的实际 usage 修正）；failed/cancelled/expired → release 全额；submit_uncertain 保持冻结，直到确认；供应商返回失败但没有原因、无法确认是否已计费时同样保持冻结，界面显示“费用待核对”，人工处理。余额不足、报价过期、哈希不符在批准时被拒（402 / 409），输入审核在报价时被拒（403），这些情况都不建任务、不扣费；路由也在报价时完成。对外只暴露 6 态：queued / running / succeeded / failed / cancelled / expired。

Agent Run

stateDiagram-v2
  [*] --> queued
  queued --> running: Workflow 启动
  running --> waiting_user: 发出 interaction
  waiting_user --> running: interaction_response(Signal)
  waiting_user --> cancelled: 取消 / 卡片过期
  running --> succeeded
  running --> failed
  running --> cancelled

积分冻结 hold

stateDiagram-v2
  [*] --> active: reserve
  active --> settled: settle(实扣 ≤ 冻结,差额返还)
  active --> released: release(失败/取消)
  active --> expired: 到期兜底释放（跳过状态不明、待人工核对的任务）

节点 node

stateDiagram-v2
  direction LR
  [*] --> idle
  idle --> pending: 触发生成
  pending --> running
  running --> done
  running --> failed
  failed --> pending: 重试
  done --> stale: 上游变更
  stale --> pending: 重生成
  done --> pending: 重新生成

导出 export_job

stateDiagram-v2
  [*] --> queued
  queued --> rendering: Worker 领取
  rendering --> succeeded: 产出入库
  rendering --> failed
  queued --> cancelled: 取消
  rendering --> cancelled: 取消

4.5 JSONB 结构约定（节选）

// node.data  type=shot
{
  "prompt": "Close-up of the bottle, water droplets, soft light",
  "negative": "",
  "duration_s": 5,
  "aspect_ratio": "9:16",
  "capability": "i2v",
  "model": {"mode":"auto","quality":"standard"},        // auto → 报价时由路由决定，批准后固定为报价里的版本
  "refs": [{"role":"first_frame","asset_id":"01J..."},{"role":"character","node_id":"01J..."}],
  "camera": {"move":"push_in","speed":0.4},
  "audio": {"mode":"native|tts|none","tts_text":"..."},
  "seed": 123456
}

// timeline.doc
{
  "tracks":[
    {"id":"v1","type":"video","clips":[
       {"id":"c1","asset_id":"01J..","in_ms":0,"out_ms":5000,"start_ms":0,"transform":{"scale":1,"x":0,"y":0},
        "transition_in":{"type":"fade","ms":300},"source_node":"01J.."}]},
    {"id":"a1","type":"audio","clips":[{"asset_id":"01J..","start_ms":0,"gain_db":-6}]},
    {"id":"s1","type":"subtitle","clips":[{"text":"...","start_ms":200,"end_ms":2400,"style_id":"sty_01"}]}
  ]
}

4.6 索引与分区策略

4.7 数据迁移（旧 → 新，仅业务数据）

4.8 ER 图（最终版）

租户与成员 画布 · 时间轴（项目文档） Agent 交互 生成 · 报价批准 · 模型 素材 积分账本 · 订阅 · 额度 平台

基数标注（线上的文字，箭头从父表指向子表）：1:N 一对多，子表外键必填（NOT NULL）；0..1:N 一对多，但外键可空，所以父是可选的；1:1 一对一，子表外键上有唯一键；0..1:1 一对一且父可选。红色粗双向线 = N:M 多对多，经带 ⇄ 的关联表。★ = 吸收竞品后新增的 7 张表；◆ = 补全的 8 张表（原设计提到或被别的表、接口、决策引用，但没给 DDL）；橙色粗线与橙色粗框 = Agent 交互相关。本设计沿用“不建数据库外键”的约定，所以基数取自库里真实存在的约束：外键列是否 NOT NULL、是否有单列唯一键。

租户边界：workspace 是租户，下面 21 张表都带 workspace_id、都属于某一个工作区。为了让图清楚，全景图没有把这 21 条线逐条画出，它们都列在下面的“关系清单”里。

全景图：全部实体与关系

默认缩放到页面宽度，先看整体结构；点一下图切换到原始大小（看清表名，在框内上下左右滚动），再点一下缩回。

%%{init:{"flowchart":{"useMaxWidth":false,"nodeSpacing":28,"rankSpacing":70}}}%%
flowchart TB
  subgraph sg_tenant["租户与成员"]
    direction TB
    t_org["org ◆"]
    t_app_user["app_user ◆"]
    t_session_token["session_token ◆"]
    t_plan["plan"]
    t_workspace["workspace"]
    t_member["⇄ member"]
    t_api_key["api_key"]
  end
  subgraph sg_canvas["画布 · 时间轴（项目文档）"]
    direction TB
    t_project["project"]
    t_project_asset_ref["⇄ project_asset_ref ◆"]
    t_node["node"]
    t_node_version["node_version"]
    t_edge["⇄ edge"]
    t_timeline["timeline"]
    t_timeline_version["timeline_version ◆"]
    t_export_job["export_job"]
    t_intent["intent ★"]
  end
  subgraph sg_agent["⭕ Agent 交互"]
    direction TB
    t_agent_session["agent_session"]
    t_agent_run["agent_run"]
    t_run_event["run_event"]
    t_interaction["interaction"]
    t_run_action["run_action ★"]
    t_skill["skill ◆"]
    t_skill_version["skill_version ◆"]
  end
  subgraph sg_gen["生成 · 报价批准 · 模型"]
    direction TB
    t_model_catalog["model_catalog"]
    t_model_version["model_version ★"]
    t_price_rule["price_rule"]
    t_generation_quote["generation_quote ★"]
    t_generation_approval["generation_approval ★"]
    t_generation_task["generation_task"]
    t_task_attempt["task_attempt"]
  end
  subgraph sg_asset["素材"]
    direction TB
    t_asset["asset"]
    t_asset_embedding["asset_embedding"]
    t_retrieval_seen["retrieval_seen"]
  end
  subgraph sg_billing["积分账本 · 订阅 · 额度"]
    direction TB
    t_ledger_account["ledger_account"]
    t_ledger_entry["ledger_entry"]
    t_point_lot["point_lot"]
    t_hold["hold"]
    t_quota_window["quota_window ★"]
    t_approval_policy["approval_policy ★"]
    t_subscription["subscription"]
    t_purchase_order["purchase_order"]
    t_payment_event["payment_event"]
  end
  subgraph sg_platform["平台"]
    direction TB
    t_outbox["outbox"]
    t_webhook_endpoint["webhook_endpoint ◆"]
    t_audit_log["audit_log"]
  end
  t_plan -->|"1:N"| t_workspace
  t_workspace -->|"1:N"| t_member
  t_workspace -->|"1:N"| t_api_key
  t_asset -->|"0..1:N"| t_project
  t_project -->|"1:N"| t_node
  t_node -->|"0..1:N"| t_node
  t_node -->|"1:N"| t_node_version
  t_asset -->|"0..1:N"| t_node_version
  t_generation_task -->|"0..1:N"| t_node_version
  t_project -->|"1:N"| t_edge
  t_node -->|"1:N"| t_edge
  t_node -->|"1:N"| t_edge
  t_project -->|"1:N"| t_timeline
  t_timeline -->|"1:N"| t_export_job
  t_asset -->|"0..1:N"| t_export_job
  t_hold -->|"0..1:1"| t_export_job
  t_project -->|"1:N"| t_agent_session
  t_agent_session -->|"1:N"| t_agent_run
  t_agent_run -->|"1:N"| t_run_event
  t_agent_run -->|"1:N"| t_interaction
  t_model_catalog -->|"1:N"| t_price_rule
  t_project -->|"0..1:N"| t_generation_task
  t_node -->|"0..1:N"| t_generation_task
  t_agent_run -->|"0..1:N"| t_generation_task
  t_api_key -->|"0..1:N"| t_generation_task
  t_model_catalog -->|"0..1:N"| t_generation_task
  t_hold -->|"0..1:1"| t_generation_task
  t_generation_task -->|"1:N"| t_task_attempt
  t_model_catalog -->|"1:N"| t_task_attempt
  t_generation_task -->|"0..1:N"| t_asset
  t_asset -->|"1:N"| t_asset_embedding
  t_asset -->|"1:N"| t_retrieval_seen
  t_ledger_account -->|"1:N"| t_ledger_entry
  t_point_lot -->|"0..1:N"| t_ledger_entry
  t_plan -->|"1:N"| t_subscription
  t_generation_quote -->|"1:N"| t_generation_approval
  t_generation_task -->|"0..1:N"| t_generation_approval
  t_model_version -->|"1:N"| t_generation_quote
  t_model_catalog -->|"1:N"| t_model_version
  t_project -->|"1:N"| t_intent
  t_agent_run -->|"1:N"| t_run_action
  t_org -->|"1:N"| t_workspace
  t_app_user -->|"1:N"| t_member
  t_app_user -->|"1:N"| t_agent_session
  t_app_user -->|"1:N"| t_project
  t_app_user -->|"1:N"| t_session_token
  t_skill -->|"1:N"| t_skill_version
  t_skill -->|"1:N"| t_agent_session
  t_skill -->|"0..1:N"| t_intent
  t_agent_run -->|"0..1:N"| t_generation_quote
  t_member -->|"0..1:N"| t_approval_policy
  t_project -->|"1:N"| t_project_asset_ref
  t_asset -->|"1:N"| t_project_asset_ref
  t_timeline -->|"1:N"| t_timeline_version
  t_node <-.->|"N:M · 经 edge"| t_node
  t_workspace <-.->|"N:M · 经 member"| t_app_user
  t_project <-.->|"N:M · 经 project_asset_ref"| t_asset
classDef tenant fill:#dbeafe,stroke:#3b82f6,color:#111,stroke-width:1.5px
classDef canvas fill:#ede9fe,stroke:#8b5cf6,color:#111,stroke-width:1.5px
classDef agent fill:#ffedd5,stroke:#f97316,color:#111,stroke-width:1.5px
classDef gen fill:#dcfce7,stroke:#22c55e,color:#111,stroke-width:1.5px
classDef asset fill:#cffafe,stroke:#06b6d4,color:#111,stroke-width:1.5px
classDef billing fill:#fef9c3,stroke:#eab308,color:#111,stroke-width:1.5px
classDef platform fill:#e5e7eb,stroke:#6b7280,color:#111,stroke-width:1.5px
class t_api_key,t_app_user,t_member,t_org,t_plan,t_session_token,t_workspace tenant
class t_edge,t_export_job,t_intent,t_node,t_node_version,t_project,t_project_asset_ref,t_timeline,t_timeline_version canvas
class t_agent_run,t_agent_session,t_interaction,t_run_action,t_run_event,t_skill,t_skill_version agent
class t_generation_approval,t_generation_quote,t_generation_task,t_model_catalog,t_model_version,t_price_rule,t_task_attempt gen
class t_asset,t_asset_embedding,t_retrieval_seen asset
class t_approval_policy,t_hold,t_ledger_account,t_ledger_entry,t_payment_event,t_point_lot,t_purchase_order,t_quota_window,t_subscription billing
class t_audit_log,t_outbox,t_webhook_endpoint platform
classDef junction stroke-dasharray:4 3,stroke-width:3px
class t_edge,t_member,t_project_asset_ref junction
  style sg_tenant fill:none,stroke:#3b82f6,stroke-width:1px,stroke-dasharray:5 4
  style sg_canvas fill:none,stroke:#8b5cf6,stroke-width:1px,stroke-dasharray:5 4
  style sg_agent fill:#fff7ed,stroke:#f97316,stroke-width:4px,stroke-dasharray:0
  style sg_gen fill:none,stroke:#22c55e,stroke-width:1px,stroke-dasharray:5 4
  style sg_asset fill:none,stroke:#06b6d4,stroke-width:1px,stroke-dasharray:5 4
  style sg_billing fill:none,stroke:#eab308,stroke-width:1px,stroke-dasharray:5 4
  style sg_platform fill:none,stroke:#6b7280,stroke-width:1px,stroke-dasharray:5 4
  linkStyle 16,17,18,19,23,40,43,46,47,48,49 stroke:#f97316,stroke-width:2.5px
  linkStyle 54,55,56 stroke:#dc2626,stroke-width:3px

Agent 交互相关（圈出来）

%%{init:{"flowchart":{"useMaxWidth":false,"nodeSpacing":40,"rankSpacing":80}}}%%
flowchart LR
  subgraph sg_agent["⭕ Agent 交互"]
    direction TB
    t_agent_session["agent_session"]
    t_agent_run["agent_run"]
    t_run_event["run_event"]
    t_interaction["interaction"]
    t_run_action["run_action ★"]
    t_skill["skill ◆"]
    t_skill_version["skill_version ◆"]
  end
  subgraph sg_tenant["租户与成员"]
    direction TB
    t_workspace["workspace"]
  end
  subgraph sg_canvas["画布 · 时间轴（项目文档）"]
    direction TB
    t_project["project"]
  end
  subgraph sg_gen["生成 · 报价批准 · 模型"]
    direction TB
    t_generation_task["generation_task"]
  end
  t_workspace -->|"workspace_id · 1:N"| t_project
  t_project -->|"project_id · 1:N"| t_agent_session
  t_workspace -->|"workspace_id · 1:N"| t_agent_session
  t_agent_session -->|"session_id · 1:N"| t_agent_run
  t_workspace -->|"workspace_id · 1:N"| t_agent_run
  t_agent_run -->|"run_id · 1:N"| t_run_event
  t_agent_run -->|"run_id · 1:N"| t_interaction
  t_workspace -->|"workspace_id · 1:N"| t_generation_task
  t_project -->|"project_id · 0..1:N"| t_generation_task
  t_agent_run -->|"run_id · 0..1:N"| t_generation_task
  t_agent_run -->|"run_id · 1:N"| t_run_action
  t_skill -->|"skill_id · 1:N"| t_skill_version
  t_skill -->|"skill_id · 1:N"| t_agent_session
  t_workspace -->|"owner_workspace_id · 0..1:N"| t_skill
classDef tenant fill:#dbeafe,stroke:#3b82f6,color:#111,stroke-width:1.5px
classDef canvas fill:#ede9fe,stroke:#8b5cf6,color:#111,stroke-width:1.5px
classDef agent fill:#ffedd5,stroke:#f97316,color:#111,stroke-width:1.5px
classDef gen fill:#dcfce7,stroke:#22c55e,color:#111,stroke-width:1.5px
classDef asset fill:#cffafe,stroke:#06b6d4,color:#111,stroke-width:1.5px
classDef billing fill:#fef9c3,stroke:#eab308,color:#111,stroke-width:1.5px
classDef platform fill:#e5e7eb,stroke:#6b7280,color:#111,stroke-width:1.5px
class t_workspace tenant
class t_project canvas
class t_skill_version,t_interaction,t_skill,t_run_action,t_run_event,t_agent_session,t_agent_run agent
class t_generation_task gen
classDef junction stroke-dasharray:4 3,stroke-width:3px
  style sg_tenant fill:none,stroke:#3b82f6,stroke-width:1px
  style sg_canvas fill:none,stroke:#8b5cf6,stroke-width:1px
  style sg_agent fill:#fff7ed,stroke:#f97316,stroke-width:4px
  style sg_gen fill:none,stroke:#22c55e,stroke-width:1px
  linkStyle 1,2,3,4,5,6,9,10,11,12,13 stroke:#f97316,stroke-width:2.5px

画布与时间轴

%%{init:{"flowchart":{"useMaxWidth":false,"nodeSpacing":40,"rankSpacing":80}}}%%
flowchart LR
  subgraph sg_canvas["画布 · 时间轴（项目文档）"]
    direction TB
    t_project["project"]
    t_node["node"]
    t_node_version["node_version"]
    t_edge["⇄ edge"]
    t_timeline["timeline"]
    t_export_job["export_job"]
    t_intent["intent ★"]
  end
  subgraph sg_asset["素材"]
    direction TB
    t_asset["asset"]
  end
  subgraph sg_gen["生成 · 报价批准 · 模型"]
    direction TB
    t_generation_task["generation_task"]
  end
  subgraph sg_billing["积分账本 · 订阅 · 额度"]
    direction TB
    t_hold["hold"]
  end
  t_asset -->|"cover_asset_id · 0..1:N"| t_project
  t_project -->|"project_id · 1:N"| t_node
  t_node -->|"parent_id · 0..1:N"| t_node
  t_node -->|"node_id · 1:N"| t_node_version
  t_asset -->|"output_asset_id · 0..1:N"| t_node_version
  t_generation_task -->|"task_id · 0..1:N"| t_node_version
  t_project -->|"project_id · 1:N"| t_edge
  t_node -->|"src_node_id · 1:N"| t_edge
  t_node -->|"dst_node_id · 1:N"| t_edge
  t_project -->|"project_id · 1:N"| t_timeline
  t_timeline -->|"timeline_id · 1:N"| t_export_job
  t_asset -->|"output_asset_id · 0..1:N"| t_export_job
  t_hold -->|"hold_id · 0..1:1"| t_export_job
  t_project -->|"project_id · 0..1:N"| t_generation_task
  t_node -->|"node_id · 0..1:N"| t_generation_task
  t_hold -->|"hold_id · 0..1:1"| t_generation_task
  t_generation_task -->|"origin_task_id · 0..1:N"| t_asset
  t_project -->|"project_id · 1:N"| t_intent
  t_node <-.->|"N:M · 经 edge"| t_node
  t_project <-.->|"N:M · 经 project_asset_ref"| t_asset
classDef tenant fill:#dbeafe,stroke:#3b82f6,color:#111,stroke-width:1.5px
classDef canvas fill:#ede9fe,stroke:#8b5cf6,color:#111,stroke-width:1.5px
classDef agent fill:#ffedd5,stroke:#f97316,color:#111,stroke-width:1.5px
classDef gen fill:#dcfce7,stroke:#22c55e,color:#111,stroke-width:1.5px
classDef asset fill:#cffafe,stroke:#06b6d4,color:#111,stroke-width:1.5px
classDef billing fill:#fef9c3,stroke:#eab308,color:#111,stroke-width:1.5px
classDef platform fill:#e5e7eb,stroke:#6b7280,color:#111,stroke-width:1.5px
class t_node,t_project,t_edge,t_timeline,t_node_version,t_export_job,t_intent canvas
class t_generation_task gen
class t_asset asset
class t_hold billing
classDef junction stroke-dasharray:4 3,stroke-width:3px
class t_edge junction
  style sg_canvas fill:none,stroke:#8b5cf6,stroke-width:1px
  style sg_gen fill:none,stroke:#22c55e,stroke-width:1px
  style sg_asset fill:none,stroke:#06b6d4,stroke-width:1px
  style sg_billing fill:none,stroke:#eab308,stroke-width:1px
  linkStyle 18,19 stroke:#dc2626,stroke-width:3px

多对多（N:M）

erDiagram
  agent_run {
    CHAR id PK
    CHAR session_id FK
    CHAR workspace_id FK
    TEXT status
    TEXT workflow_id
    TEXT skill_version
    BIGINT budget_centi
    BIGINT spent_centi
    JSONB input
    TEXT error_code
    TEXT error_message
    TIMESTAMPTZ started_at
    TIMESTAMPTZ finished_at
    TIMESTAMPTZ created_at
  }
  agent_session {
    CHAR id PK
    CHAR project_id FK
    CHAR workspace_id FK
    CHAR user_id FK
    TEXT skill_id FK
    TEXT skill_version
    TEXT title
    TIMESTAMPTZ created_at
  }
  api_key {
    CHAR id PK
    CHAR workspace_id FK
    TEXT name
    TEXT key_prefix
    BYTEA key_hash
    TEXT_ARR scopes
    TEXT status
    TIMESTAMPTZ expires_at
    TIMESTAMPTZ last_used_at
    TIMESTAMPTZ created_at
  }
  app_user {
    CHAR id PK
    TEXT email
    TEXT display_name
    TEXT password_hash
    TEXT status
    TIMESTAMPTZ created_at
    TIMESTAMPTZ last_login_at
  }
  approval_policy {
    CHAR id PK
    CHAR workspace_id FK
    BIGINT member_id FK
    TEXT mode
    BIGINT per_task_limit_centi
    BIGINT daily_limit_centi
  }
  asset {
    CHAR id PK
    CHAR workspace_id FK
    TEXT kind
    TEXT source
    TEXT storage_key
    TEXT mime
    BIGINT bytes
    INT duration_ms
    INT width
    INT height
    REAL fps
    BYTEA sha256
    CHAR origin_task_id FK
    TEXT origin_url
    TEXT moderation
    TEXT_ARR tags
    JSONB meta
    TIMESTAMPTZ deleted_at
    TIMESTAMPTZ created_at
  }
  asset_embedding {
    CHAR asset_id PK
    INT segment_no PK
    INT start_ms
    INT end_ms
    TEXT caption
    FLOAT4__ embedding
  }
  audit_log {
    BIGINT id PK
    CHAR workspace_id FK
    TEXT actor
    TEXT action
    TEXT target_type
    TEXT target_id
    JSONB diff
    INET ip
    TIMESTAMPTZ created_at
  }
  edge {
    CHAR id PK
    CHAR project_id FK
    CHAR src_node_id FK
    CHAR dst_node_id FK
    TEXT kind
  }
  export_job {
    CHAR id PK
    CHAR workspace_id FK
    CHAR timeline_id FK
    BIGINT timeline_ver
    TEXT preset
    TEXT status
    TEXT workflow_id
    CHAR output_asset_id FK
    CHAR hold_id FK
    TEXT error_code
    TEXT error_message
    TIMESTAMPTZ created_at
    TIMESTAMPTZ finished_at
  }
  generation_approval {
    CHAR id PK
    CHAR quote_id FK
    TEXT client_approval_id
    CHAR request_sha256
    CHAR quote_sha256
    CHAR task_id FK
    TIMESTAMPTZ created_at
  }
  generation_quote {
    CHAR id PK
    CHAR workspace_id FK
    TEXT client_request_id
    CHAR request_sha256
    CHAR quote_sha256
    CHAR model_version_id FK
    BIGINT quoted_centi
    TIMESTAMPTZ expires_at
    CHAR source_run_id FK
    CHAR source_sha256
    TEXT status
  }
  generation_task {
    CHAR id PK
    CHAR workspace_id FK
    CHAR project_id FK
    CHAR node_id FK
    CHAR run_id FK
    CHAR api_key_id FK
    TEXT capability
    CHAR model_id FK
    JSONB request
    BYTEA request_hash
    TEXT idem_key
    TEXT status
    CHAR hold_id FK
    BIGINT quoted_centi
    BIGINT charged_centi
    JSONB outputs
    TEXT error_code
    TEXT error_message
    TEXT workflow_id
    INT attempt_count
    TIMESTAMPTZ created_at
    TIMESTAMPTZ finished_at
  }
  hold {
    CHAR id PK
    CHAR workspace_id FK
    TEXT ref_type
    TEXT ref_id
    BIGINT amount_centi
    TEXT status
    JSONB lot_allocation
    TIMESTAMPTZ expires_at
    TIMESTAMPTZ created_at
  }
  intent {
    CHAR id PK
    CHAR workspace_id FK
    CHAR project_id FK
    TEXT adapter
    JSONB source_ref
    TEXT skill_id FK
    TEXT skill_version
    TEXT status
    TIMESTAMPTZ created_at
  }
  interaction {
    CHAR id PK
    CHAR run_id FK
    TEXT kind
    JSONB request
    JSONB response
    CHAR card_sha256
    JSONB schema
    TEXT client_action_id
    TEXT status
    TIMESTAMPTZ expires_at
    TIMESTAMPTZ created_at
    TIMESTAMPTZ resolved_at
  }
  ledger_account {
    CHAR id PK
    CHAR workspace_id FK
    TEXT kind
    BIGINT balance_centi
    BIGINT version
  }
  ledger_entry {
    BIGINT id PK
    CHAR txn_id
    CHAR account_id FK
    SMALLINT direction
    BIGINT amount_centi
    TEXT ref_type
    TEXT ref_id
    CHAR lot_id FK
    TEXT memo
    TIMESTAMPTZ created_at PK
  }
  member {
    BIGINT id PK
    CHAR workspace_id FK
    CHAR user_id FK
    TEXT role
    BOOL seat
    TIMESTAMPTZ created_at
  }
  model_catalog {
    CHAR id PK
    TEXT capability
    TEXT provider_key
    TEXT model_name
    TEXT display_name
    JSONB input_schema
    JSONB limits
    JSONB default_params
    INT max_concurrency
    INT timeout_s
    TEXT status
    TEXT adapter_key
  }
  model_version {
    CHAR id PK
    CHAR model_id FK
    TEXT version_key
    JSONB config
    CHAR config_sha256
    TIMESTAMPTZ published_at
  }
  node {
    CHAR id PK
    CHAR project_id FK
    CHAR workspace_id FK
    TEXT type
    CHAR parent_id FK
    TEXT title
    REAL pos_x
    REAL pos_y
    JSONB data
    INT current_ver
    CHAR lock_owner
    TIMESTAMPTZ lock_until
    TEXT status
    TEXT created_by
    TIMESTAMPTZ deleted_at
    TIMESTAMPTZ created_at
    TIMESTAMPTZ updated_at
  }
  node_version {
    CHAR node_id PK
    INT version PK
    JSONB data
    CHAR output_asset_id FK
    CHAR task_id FK
    TEXT created_by
    TIMESTAMPTZ created_at
  }
  org {
    CHAR id PK
    TEXT name
    TEXT status
    TIMESTAMPTZ created_at
  }
  outbox {
    BIGINT id PK
    TEXT topic
    TEXT key
    JSONB payload
    TEXT status
    INT attempts
    TIMESTAMPTZ next_at
    TIMESTAMPTZ created_at
  }
  payment_event {
    BIGINT id PK
    TEXT provider
    TEXT event_id
    TEXT type
    JSONB payload
    TIMESTAMPTZ processed_at
    TIMESTAMPTZ received_at
  }
  plan {
    TEXT code PK
    TEXT name
    TEXT interval
    INT price_cents
    TEXT currency
    BIGINT monthly_points_centi
    INT seats
    JSONB features
  }
  point_lot {
    CHAR id PK
    CHAR workspace_id FK
    TEXT source
    BIGINT granted_centi
    BIGINT remaining_centi
    TIMESTAMPTZ expires_at
    SMALLINT priority
    TIMESTAMPTZ created_at
  }
  price_rule {
    CHAR id PK
    CHAR model_id FK
    TEXT unit
    BIGINT cost_micro
    BIGINT charge_centi
    JSONB modifiers
    TIMESTAMPTZ effective_from
    TIMESTAMPTZ effective_to
  }
  project {
    CHAR id PK
    CHAR workspace_id FK
    CHAR owner_id FK
    TEXT title
    TEXT kind
    TEXT aspect_ratio
    TEXT language
    CHAR cover_asset_id FK
    TEXT status
    BIGINT doc_version
    TIMESTAMPTZ deleted_at
    TIMESTAMPTZ created_at
    TIMESTAMPTZ updated_at
  }
  project_asset_ref {
    CHAR project_id PK
    CHAR asset_id PK
    TEXT purpose
    TIMESTAMPTZ created_at
  }
  purchase_order {
    CHAR id PK
    CHAR workspace_id FK
    TEXT kind
    TEXT sku_code
    INT amount_cents
    TEXT currency
    TEXT status
    TIMESTAMPTZ created_at
  }
  quota_window {
    CHAR workspace_id PK
    DATE window_start PK
    TEXT kind PK
    BIGINT limit_units
    BIGINT used_units
    BOOL overage_enabled
  }
  retrieval_seen {
    TEXT context_key PK
    CHAR asset_id PK
  }
  run_action {
    CHAR id PK
    CHAR run_id FK
    TEXT kind
    TEXT client_action_id
    CHAR request_sha256
    TEXT status
    INT attempt
    JSONB result
    TIMESTAMPTZ created_at
  }
  run_event {
    BIGINT id PK
    CHAR run_id FK
    INT seq
    TEXT type
    JSONB payload
    TIMESTAMPTZ created_at PK
  }
  session_token {
    CHAR id PK
    CHAR user_id FK
    BYTEA token_hash
    TIMESTAMPTZ expires_at
    TIMESTAMPTZ revoked_at
    TIMESTAMPTZ created_at
  }
  skill {
    TEXT id PK
    TEXT display_name
    CHAR owner_workspace_id FK
    TEXT status
    TIMESTAMPTZ created_at
  }
  skill_version {
    TEXT skill_id PK
    TEXT version PK
    JSONB manifest
    CHAR sha256
    TEXT status
    TIMESTAMPTZ published_at
  }
  subscription {
    CHAR id PK
    CHAR workspace_id FK
    TEXT plan_code FK
    TEXT status
    TEXT provider
    TEXT provider_sub_id
    TIMESTAMPTZ current_period_start
    TIMESTAMPTZ current_period_end
    BOOL cancel_at_period_end
  }
  task_attempt {
    CHAR id PK
    CHAR task_id FK
    SMALLINT seq
    CHAR model_id FK
    TEXT provider_task_id
    TEXT provider_request_id
    TEXT status
    BIGINT cost_micro
    JSONB usage
    TEXT error_code
    TEXT error_message
    TIMESTAMPTZ submitted_at
    TIMESTAMPTZ finished_at
  }
  timeline {
    CHAR id PK
    CHAR project_id FK
    CHAR workspace_id FK
    SMALLINT fps
    INT width
    INT height
    INT duration_ms
    JSONB doc
    BIGINT version
    TIMESTAMPTZ updated_at
  }
  timeline_version {
    CHAR timeline_id PK
    BIGINT version PK
    JSONB doc
    BIGINT restored_from
    TEXT created_by
    TIMESTAMPTZ created_at
  }
  webhook_endpoint {
    CHAR id PK
    CHAR workspace_id FK
    TEXT url
    BYTEA secret_hash
    TEXT_ARR events
    TEXT status
    TIMESTAMPTZ created_at
  }
  workspace {
    CHAR id PK
    CHAR org_id FK
    TEXT name
    TEXT region
    TEXT plan_code FK
    TEXT status
    TIMESTAMPTZ created_at
    TIMESTAMPTZ updated_at
  }
  plan ||--o{ workspace : "plan_code"
  workspace ||--o{ member : "workspace_id"
  workspace ||--o{ api_key : "workspace_id"
  workspace ||--o{ project : "workspace_id"
  asset |o--o{ project : "cover_asset_id"
  project ||--o{ node : "project_id"
  workspace ||--o{ node : "workspace_id"
  node |o--o{ node : "parent_id"
  node ||--o{ node_version : "node_id"
  asset |o--o{ node_version : "output_asset_id"
  generation_task |o--o{ node_version : "task_id"
  project ||--o{ edge : "project_id"
  node ||--o{ edge : "src_node_id"
  node ||--o{ edge : "dst_node_id"
  project ||--o{ timeline : "project_id"
  workspace ||--o{ timeline : "workspace_id"
  workspace ||--o{ export_job : "workspace_id"
  timeline ||--o{ export_job : "timeline_id"
  asset |o--o{ export_job : "output_asset_id"
  hold |o--o| export_job : "hold_id"
  project ||--o{ agent_session : "project_id"
  workspace ||--o{ agent_session : "workspace_id"
  agent_session ||--o{ agent_run : "session_id"
  workspace ||--o{ agent_run : "workspace_id"
  agent_run ||--o{ run_event : "run_id"
  agent_run ||--o{ interaction : "run_id"
  model_catalog ||--o{ price_rule : "model_id"
  workspace ||--o{ generation_task : "workspace_id"
  project |o--o{ generation_task : "project_id"
  node |o--o{ generation_task : "node_id"
  agent_run |o--o{ generation_task : "run_id"
  api_key |o--o{ generation_task : "api_key_id"
  model_catalog |o--o{ generation_task : "model_id"
  hold |o--o| generation_task : "hold_id"
  generation_task ||--o{ task_attempt : "task_id"
  model_catalog ||--o{ task_attempt : "model_id"
  workspace ||--o{ asset : "workspace_id"
  generation_task |o--o{ asset : "origin_task_id"
  asset ||--o{ asset_embedding : "asset_id"
  asset ||--o{ retrieval_seen : "asset_id"
  workspace |o--o{ ledger_account : "workspace_id"
  ledger_account ||--o{ ledger_entry : "account_id"
  point_lot |o--o{ ledger_entry : "lot_id"
  workspace ||--o{ point_lot : "workspace_id"
  workspace ||--o{ hold : "workspace_id"
  workspace ||--o{ subscription : "workspace_id"
  plan ||--o{ subscription : "plan_code"
  workspace ||--o{ purchase_order : "workspace_id"
  workspace |o--o{ audit_log : "workspace_id"
  generation_quote ||--o{ generation_approval : "quote_id"
  generation_task |o--o{ generation_approval : "task_id"
  model_version ||--o{ generation_quote : "model_version_id"
  model_catalog ||--o{ model_version : "model_id"
  workspace ||--o{ quota_window : "workspace_id"
  workspace ||--o{ approval_policy : "workspace_id"
  project ||--o{ intent : "project_id"
  agent_run ||--o{ run_action : "run_id"
  org ||--o{ workspace : "org_id"
  app_user ||--o{ member : "user_id"
  app_user ||--o{ agent_session : "user_id"
  app_user ||--o{ project : "owner_id"
  app_user ||--o{ session_token : "user_id"
  skill ||--o{ skill_version : "skill_id"
  skill ||--o{ agent_session : "skill_id"
  skill |o--o{ intent : "skill_id"
  workspace |o--o{ skill : "owner_workspace_id"
  workspace ||--o{ webhook_endpoint : "workspace_id"
  workspace ||--o{ generation_quote : "workspace_id"
  workspace ||--o{ intent : "workspace_id"
  agent_run |o--o{ generation_quote : "source_run_id"
  member |o--o{ approval_policy : "member_id"
  project ||--o{ project_asset_ref : "project_id"
  asset ||--o{ project_asset_ref : "asset_id"
  timeline ||--o{ timeline_version : "timeline_id"

5.1 通用约定

错误模型

HTTP 4xx/5xx
{
  "error": {
    "code": "insufficient_points",       // 稳定的机器可读码，调用方只判断 code
    "message": "Insufficient points.",   // 人读，按 Accept-Language 本地化
    "details": {"required_centi": 12000, "available_centi": 3000},
    "request_id": "req_01J..."
  }
}

5.2 接口总览（最终版）

最终产物：52 条接口，按业务领域分成 7 组，和 ER 图里的表域一一对应（每组标出它主要读写的表）。原有 40，调整 6，新增 6；「状态」列只标明它相对原设计是否变化。

用户领域 11 项目与会话领域 6 Agent 交互领域 7 画布与时间轴领域 11 生成与报价批准领域 7 素材领域 6 开放平台与能力 4

用户领域 · 11 条

谁在用、怎么付费：登录与成员、API Key、支付、订阅、积分、用量。读写的表：org、app_user、session_token、plan、workspace、member、api_key、generation_task、ledger_account、ledger_entry、point_lot、hold、quota_window、approval_policy、subscription、purchase_order、payment_event

项目与会话领域 · 6 条

项目是一份文档；会话挂在项目下；创作意图从不同入口汇入。读写的表：workspace、project、node、edge、intent、agent_session、skill、skill_version

⭕ Agent 交互领域 · 7 条

发消息、事件流、停止、澄清卡片、技能。读写的表：agent_session、agent_run、run_event、interaction、run_action、skill、skill_version

画布与时间轴领域 · 11 条

节点与边、批量变更、版本、时间线、导出。读写的表：project、node、node_version、edge、timeline、timeline_version、export_job、asset、hold

生成与报价批准领域 · 7 条

先报价再批准、生成任务、模型目录与价格。读写的表：model_catalog、model_version、price_rule、generation_quote、generation_approval、generation_task、task_attempt、ledger_entry、point_lot、hold、quota_window、approval_policy

素材领域 · 6 条

上传、检索、采集、角色。读写的表：project_asset_ref、asset、asset_embedding、retrieval_seen

开放平台与能力 · 4 条

Webhook 注册、MCP、OpenAPI、能力注册表。读写的表：api_key、skill、model_catalog、outbox、webhook_endpoint

5.3 核心接口详解

5.3.1 POST /generations:quote 与 POST /generations — 先报价，再批准

POST /v1/generations:quote
{
  "client_request_id": "c-52ad",
  "capability": "i2v",
  "project_id": "prj_01J...",                       // 可选，挂到项目/节点
  "node_id": "nod_01J...",
  "input": { "prompt": "A bottle on a marble table, slow push-in", "duration_s": 5, "aspect_ratio": "9:16", "resolution": "1080p" },
  "model": {"mode": "auto", "quality": "standard"},    // 或 {"mode":"fixed","id":"mdl_..."}
  "source": {"run_id": "run_01J..."}                   // 可选：来自 Agent 回复时带上
}
200 { "quote_id": "qte_01J...", "request_sha256": "…", "quote_sha256": "…",
      "model": {"id": "mdl_01J...", "version": "v1"}, "quoted_centi": 15000, "points": "150.00",
      "expires_at": "2026-10-19T10:05:00Z" }          // 不扣费；输入审核和模型路由在这一步完成

POST /v1/generations
{ "quote_id": "qte_01J...", "client_approval_id": "c-9a10", "request_sha256": "…", "quote_sha256": "…" }
201 Created
{ "id": "tsk_01J...", "status": "queued", "quoted_centi": 15000, "links": {"self": "/v1/generations/tsk_01J...", "events": "/v1/generations/tsk_01J.../events"} }

同一个 (quote_id, client_approval_id) 重放 → 返回同一个任务，不会重复扣费
409 quote_expired        报价过期：不建任务、不扣费，重新报价
409 state_conflict       请求或价格与报价不一致（哈希不符）
402 insufficient_points  {"required_centi":15000,"available_centi":3000}
403 content_rejected     {"category":"violence","field":"input.prompt"}
422 unsupported_combination  {"field":"input.duration_s","allowed":[5,8,10]}

语义：批准时在一个本地事务内完成 ① 校验报价未过期、两个哈希一致 ② 冻结积分 ③ 写 generation_approval、generation_task 与 outbox ④ 通过 outbox 异步启动 Temporal 工作流（保证不丢）。用户看到的价格和提示词，就是被批准、被执行的那一份。

5.3.2 GET /generations/{id} — 查询

200
{
  "id":"tsk_01J...", "status":"succeeded",
  "outputs":[{"asset_id":"ast_01J...","type":"video","url":"https://cdn.../a.mp4?sig=..","duration_s":5,"width":1080,"height":1920}],
  "charged_centi":15000,
  "created_at":"2026-10-11T08:00:00Z","finished_at":"2026-10-11T08:01:34Z",
  "error":null,
  "attempts":[{"seq":1,"model":"Seedance 2.5","status":"succeeded"}],
  "quote_id":"qte_01J..."          // 这个任务是由哪份报价批准出来的
}

5.3.3 POST /sessions/{id}/messages — 向 Agent 发消息

POST /v1/sessions/ses_01J.../messages
{
  "client_action_id": "c-31ab",
  "content": [
    {"type":"text","text":"用这个商品做 3 条 15 秒的 TikTok 广告，风格偏 ASMR"},
    {"type":"url","url":"https://shop.example.com/p/123"},
    {"type":"asset","asset_id":"ast_01J..."}
  ]
}

202 Accepted
{"run_id":"run_01J...","mode":"new_run"}   // new_run | guidance；消息永远不会恢复一个等待中的 run

状态规则（沿用旧网关的规则；本方案没有重新验证）：
- 会话空闲 → 新建 run
- run 运行中 → 作为 guidance 追加给当前 run（mode=guidance）
- run 等待交互且收到普通消息 → 取消旧 run，新建 run
- 只有 interactions/{id}:respond 才恢复同一个 run
409 run_busy：guidance 通道被关闭（run 正在收尾）时返回，客户端稍后重试

同一个 client_action_id 内容不同 → 409。消息不能附带“自动批准”：花积分只能走“报价 → 批准”。要免确认，只能由用户在工作区里开启审批策略（approval_policy，Always Allow，限额度内，仍写账本）。

5.3.4 GET /sessions/{id}/events — SSE

GET /v1/sessions/ses_01J.../events?from_seq=120
Accept: text/event-stream
Last-Event-ID: run_01J...:120

id: run_01J...:121
event: assistant.delta
data: {"run_id":"run_01J...","seq":121,"text":"我先分析商品页面…"}

id: run_01J...:130
event: node.created
data: {"seq":130,"node":{"id":"nod_01J...","type":"script","data":{...}},"graph_version":42}

id: run_01J...:135
event: interaction.requested
data: {"seq":135,"interaction":{"id":"itx_01J...","kind":"collect_info","card_sha256":"…",
        "title":"需要补充商品信息","schema":{"fields":[{"key":"product_name","kind":"input","label":"商品名称","required":true}]},
        "expires_at":"2026-10-11T09:00:00Z"}}      // 答案用 :respond 提交，必须带这个 card_sha256

: heartbeat   (每 15s)

断线续传：服务端按 (run_id, seq) 从 PG 热分区补读；Redis Stream 仅作低延迟提示。事件顺序以 seq 为准，客户端去重。

5.3.5 POST /interactions/{id}:respond

POST /v1/interactions/itx_01J...:respond
{ "client_action_id": "c-9f3e", "card_sha256": "…", "action": "submit", "values": {"product_name": "不锈钢保温杯"} }
200 {"status":"resolved","run_id":"run_01J..."}
同 client_action_id 重放 → 200 返回同样结果；同 id 不同内容 → 409 state_conflict
卡片哈希与当前卡不一致（卡已更新）→ 409 state_conflict，不提交旧答案
action="cancel" → 取消这一轮

答案按卡片 schema 校验（必填、选项取值）；已经恢复过的卡再提交，返回原回执，不会恢复两次。只有这个接口能恢复同一个 run。

5.3.6 POST /projects/{id}/graph:patch — 批量图变更

{
  "base_version": 41,
  "ops": [
    {"op":"add_node","temp_id":"t1","type":"shot","parent_id":"nod_scene1","data":{"prompt":"..."},"pos":{"x":120,"y":80}},
    {"op":"update_node","id":"nod_02","if_ver":3,"data":{"prompt":"new"}},
    {"op":"add_edge","src":"nod_01","dst":"t1","kind":"data"},
    {"op":"delete_node","id":"nod_09"}
  ]
}
200 {"graph_version":42,"id_map":{"t1":"nod_01J..."},"stale_nodes":["nod_05"]}
409 state_conflict {"conflicts":[{"id":"nod_02","server_ver":4}]}   // 乐观锁失败,客户端 rebase

base_version 与响应里的 graph_version 都是 project.doc_version；if_ver 对应 node.current_ver。

5.3.7 POST /assets:search

{
  "query": "close-up of hands applying serum, soft light",
  "kinds": ["video"],
  "filters": {"duration_s": {"lte": 8}, "tags_any": ["beauty"]},
  "scope": ["workspace","library"],
  "context_key": "prj_01J...:scene3",     // 同 key 下已返回过的素材不再返回
  "top_k": 8
}
200 {"items":[{"asset_id":"ast_..","score":0.82,"segment":{"start_ms":1200,"end_ms":4200},"url":"..."}]}

5.4 内部接口（core ↔ model-gateway，gRPC）

service ModelGateway {
  rpc Route(RouteRequest) returns (RouteDecision);                 // 能力 → 模型 + 版本 + 价格（报价写入 generation_quote）
  rpc Submit(SubmitRequest) returns (SubmitResponse);               // 幂等键 = task_id + attempt_seq
  rpc Query(QueryRequest) returns (QueryResponse);                  // 按 provider_task_id 或 idempotency
  rpc Cancel(CancelRequest) returns (CancelResponse);
  rpc ListModels(ListModelsRequest) returns (ListModelsResponse);
}
message SubmitRequest {
  string task_id = 1; int32 attempt_seq = 2; string model_id = 3; string model_version_id = 8;   // 必须是报价时的版本
  google.protobuf.Struct input = 4; repeated AssetRef refs = 5;     // 网关负责把 asset 转成供应商可访问 URL
  string callback_url = 6; int64 deadline_unix = 7;
}
enum SubmitOutcome { ACCEPTED = 0; REJECTED = 1; UNCERTAIN = 2; }   // UNCERTAIN: 超时/断连,无法确认供应商是否受理

5.5 Webhook 事件

5.6 Agent 事件类型

5.7 MCP 工具面（对内外一致）

6.1 流程清单

F1 积分冻结 → 生成 → 结算（最核心）

sequenceDiagram
  autonumber
  participant C as 客户端
  participant API as core.taskfacade
  participant B as core.billing
  participant S as core.safety
  participant PG as PostgreSQL
  participant TP as Temporal
  participant W as GenWorkflow
  participant G as model-gateway
  participant V as 供应商
  participant A as core.asset
  C->>API: POST /generations:quote
  API->>S: 输入审核(prompt+参考图)
  S-->>API: pass
  API->>G: Route(capability,params)
  G-->>API: model_version + 价格
  API->>PG: INSERT generation_quote(request_sha256, quote_sha256, expires_at)
  API-->>C: quote_id + 两个哈希 + expires_at（不扣费）
  C->>API: POST /generations {quote_id, client_approval_id, 两个哈希}
  API->>PG: 校验报价未过期、哈希一致（重放同一批准返回同一任务）
  rect rgb(40,60,90)
  note over API,PG: 单个本地事务
  API->>B: Reserve(ref=task_id, amount=quoted)
  B->>PG: 选 lot → hold(active) → 分录
  API->>PG: INSERT generation_approval + generation_task(held→queued) + outbox(start_workflow)
  end
  API-->>C: 201 queued
  PG-->>TP: outbox relay → StartWorkflow(task_id)
  TP->>W: run
  W->>G: Submit(task_id, attempt=1)
  G->>V: 创建视频任务
  V-->>G: provider_task_id
  G-->>W: ACCEPTED
  loop 回调优先,轮询兜底
    V-->>G: webhook / 轮询 Query
    G-->>W: Signal(progress)
  end
  V-->>G: 成功 + 视频URL
  W->>A: 下载转存 COS,生成缩略图,审核
  A-->>W: asset_id(pass)
  W->>B: Settle(hold, actual)
  B->>PG: hold=settled,分录:held→revenue/cogs,差额返还
  W->>PG: task=succeeded + 节点新版本 + 事件
  PG-->>C: SSE task.completed / node.updated

要点：① 积分冻结与任务创建同事务，不会出现"扣了没任务"或"有任务没扣"；② Workflow 里每一步是 Activity，失败自动重试（带退避），结算与释放都是幂等的（以 hold 的 UNIQUE(ref_type, ref_id) 保证）；③ 视频必须转存到自有存储后才视为成功，供应商链接通常 24h 失效；④ 任务只能由批准创建：先 generations:quote，再带 quote_id 与两个哈希调用 POST /generations，报价过期或哈希不一致都不会建任务、不会扣费。

F2 提交不确定（submit_uncertain）

sequenceDiagram
  participant W as GenWorkflow
  participant G as Gateway
  participant V as 供应商
  W->>G: Submit(task, attempt=1)
  G->>V: POST create (带 client_token=task:attempt)
  Note over G,V: 超时/连接重置
  G-->>W: UNCERTAIN
  W->>W: task=submit_uncertain (保持冻结)
  loop 最多 N 次, 间隔递增
    W->>G: Query(by client_token)
    G->>V: 按 token 查询 / 列表对账
  end
  alt 供应商确认受理
    G-->>W: ACCEPTED(provider_task_id)
    W->>W: → running
  else 确认未受理
    G-->>W: NOT_FOUND
    W->>W: attempt=2 (可换供应商) → queued
  else 无法确认(超过 T_max)
    W->>W: 标记 needs_manual, 保持冻结, 告警
    Note right of W: 运营对账后 release 或 settle
  end

F3 URL → 广告视频（Agent 全流程）

sequenceDiagram
  autonumber
  participant U as 用户
  participant O as Orchestrator
  participant CO as 采集专家
  participant ST as 策略/脚本专家
  participant SB as 分镜专家
  participant PD as 生产专家
  participant PP as 后期专家
  participant K as Canvas/Task API
  U->>O: 商品链接 + "3 条 15s TikTok 广告"
  O->>CO: collect_url
  CO->>K: collector job → 商品信息/图片
  CO-->>O: product 节点 (标题/卖点/价格/图)
  O->>ST: 提炼卖点+受众+3 个创意角度
  ST-->>O: script 节点 ×3
  O-->>U: interaction: review_script (HITL)
  U-->>O: 选定/修改
  O->>SB: 分镜(每条 4-6 镜头)+角色+首帧图
  SB->>K: shot 节点 + 首帧 t2i 任务
  SB-->>O: storyboard 节点
  O->>K: POST /generations:quote ×N（逐镜头报价）
  O-->>U: interaction: confirm_cost(Σ报价 = N 积分)
  U-->>O: 批准
  O->>PD: 并发生成所有 shot(i2v) + TTS + 字幕
  PD->>K: POST /generations ×N {quote_id, client_approval_id, 哈希}
  K-->>PD: task 完成事件
  PD-->>O: shot_assets(溯源齐全)
  O->>PP: 合成时间线(BGM,转场,字幕,混音)
  PP->>K: 写 timeline + 创建 export
  PP-->>O: final_video
  O-->>U: 成片 + 可编辑画布

溯源规则（硬约束）：final_video 的每个镜头片段必须引用 node_version.task_id 对应的 succeeded 任务；写入工具校验，不通过则拒绝，Agent 无法伪造成片。

F4 HITL 暂停与恢复

sequenceDiagram
  participant AR as agent-runtime
  participant WF as RunWorkflow
  participant PG as PG
  participant RT as realtime
  participant U as 用户
  AR->>WF: interrupt(kind, request)
  WF->>PG: INSERT interaction(pending) + run=waiting_user + event (同事务)
  PG-->>RT: outbox → interaction.requested
  RT-->>U: SSE 卡片
  Note over WF: 等待 Signal (最长 TTL, 无资源占用)
  U->>PG: POST respond (client_action_id)
  PG->>PG: 校验幂等/状态, interaction=resolved
  PG->>WF: Signal(response)
  WF->>AR: resume(thread_id, response)
  AR-->>WF: 继续执行
  alt 超时
    WF->>PG: interaction=expired, run=cancelled, release holds
  end

F5 单镜头重生成

flowchart LR
  A[用户点击重生成<br/>可改 prompt/参考] --> B[quote 报价]
  B --> C{余额足够?}
  C -- 否 --> D[402 引导充值]
  C -- 是 --> B2[用户批准报价<br/>quote_id + 哈希]
  B2 --> E[冻结 + 新建 task<br/>base=旧版本上下文]
  E --> F[读取: 角色参考图<br/>前后镜头尾帧/首帧<br/>风格种子]
  F --> G[提交生成]
  G --> H[成功: node_version+1<br/>旧版本保留]
  H --> I[标记下游 timeline clip 为 outdated<br/>可一键替换]
  H --> J[旧任务费用不退<br/>新任务单独计费]

F6 时间线导出

sequenceDiagram
  participant C as 客户端
  participant API as core
  participant WF as ExportWorkflow
  participant R as render worker
  participant S as COS
  C->>API: POST /timelines/{id}/exports (version=V)
  API->>API: 校验所有 clip 素材可用/审核通过
  API->>API: 冻结导出积分(可为0)
  API->>WF: start (timeline snapshot V 固化)
  WF->>R: 拆分: 分段渲染 (每段 ≤10s)
  par 并行分段
    R->>S: 读源素材(分段区间)
    R->>R: FFmpeg filter_complex 合成
    R->>S: 写分段
  end
  WF->>R: 拼接+混音+字幕烧录+封面
  R->>S: 写成片
  WF->>API: asset 入库 + export=succeeded
  API-->>C: SSE export.succeeded

分段并行把 60s 1080p 的导出压缩到约 40–90s；失败只重试失败的分段；timeline 在提交时固化快照，导出期间用户继续编辑不影响结果。

F7 充值 / 订阅

sequenceDiagram
  participant U as 用户
  participant API as billing
  participant PSP as Stripe/微信
  participant PG as PG
  U->>API: POST /billing/checkout (sku)
  API->>PG: order(created)
  API->>PSP: 创建支付会话
  PSP-->>U: 跳转支付
  PSP->>API: webhook payment.succeeded (event_id)
  API->>PG: INSERT payment_event ON CONFLICT DO NOTHING
  alt 首次处理
    API->>PG: 事务: order=paid, point_lot(purchase), 分录(revenue→wallet_paid)
  else 重复事件
    API-->>PSP: 200(幂等忽略)
  end
  API-->>U: SSE billing.balance_changed
  Note over API,PG: 退款: 先 hold 对应剩余积分,不足则标记欠费并限制使用

F8 爆款复刻

flowchart TB
  A[参考视频 URL/文件] --> B[采集+转存+审核]
  B --> C[镜头切分<br/>PySceneDetect]
  C --> D[逐镜 VLM 理解:<br/>景别/运镜/主体/台词/情绪]
  D --> E[ASR+文案结构化<br/>钩子/卖点/CTA 时间轴]
  E --> F[节奏提取: 镜头时长、BGM 节拍]
  F --> G[生成 blueprint 节点<br/>可编辑]
  G --> H{用户确认}
  H --> I[套入新商品:<br/>替换主体/文案/素材]
  I --> J[进入 F3 生产段]

F9 批量变体

flowchart LR
  A[母版项目 + 变量矩阵<br/>风格×角色×语种×CTA] --> B[展开为 N 个子项目]
  B --> B2[逐个报价，用户一次批准整批<br/>每个子项目一个 quote_id]
  B2 --> C[预算校验: Σ报价 ≤ 余额<br/>冻结总额]
  C --> D[Child Workflow ×N<br/>限并发 K]
  D --> E{单个失败?}
  E -- 是 --> F[自动重试 ≤2 次<br/>仍失败释放该份冻结]
  E -- 否 --> G[产物回收]
  D --> H[进度聚合: 暂停/继续/取消]

F10 素材上传与解析

sequenceDiagram
  participant C as 客户端
  participant API as asset
  participant S as COS
  participant WF as AssetWorkflow
  C->>API: POST /assets:init-upload (size,mime,sha256)
  API->>API: 配额校验，sha256 命中 → 直接复用(秒传)
  API-->>C: 预签名 URL (分片)
  C->>S: 直传
  C->>API: POST /assets/{id}:complete
  API->>WF: start
  WF->>WF: 病毒/格式校验 → 转码代理 → 抽帧/镜头切分
  WF->>WF: 审核 (图像/视频/ASR 文本)
  WF->>WF: VLM 描述 + 标签 + embedding
  WF->>API: asset 可用 (moderation=pass)

F11 内容审核分层

6.2 Temporal 工作流设计

6.3 并发与一致性规则

• 每工作区并发上限：按套餐（Free 2 / Pro 6 / Team 20）+ 每模型全局并发（来自 model_catalog.max_concurrency）；Redis 令牌桶 + 排队，超出进入 queued 而非拒绝。
• 公平调度：Gateway 提交队列按 workspace_id 加权轮询，防止大客户批量任务饿死其他租户。
• 画布并发：graph:patch 使用 base_version 乐观锁；Agent 写入与用户编辑冲突时，Agent 侧收到 409 后 rebase 并重试一次，仍冲突则以用户版本为准。
• 事件顺序：run 内 seq 由 Workflow 单点分配；同一 run 的事件只由其 Workflow 写入。

7.1 SLO 与性能目标

错误预算：核心 API 99.95% → 每月约 21.6 分钟；预算耗尽时冻结功能发布，只允许稳定性修复。

7.2 容量估算（可交互）

公式
任务/日        = DAU × 镜头/日
平均 TPS       = 任务/日 / 86400
峰值 TPS       = 平均 TPS × 峰均比
峰值并发生成    = 峰值 TPS × 平均耗时        (Little 定律: L = λ·W)
新增存储/日     = 任务/日 × 秒数 × 码率 × (1 + 代理/缩略图 15%)
渲染核·秒/日    = 导出数 × 导出时长 × 单核渲染系数(≈2.0 核·秒/秒视频, x264 medium 1080p)
峰值渲染核数    = 渲染核·秒/日 / 86400 × 峰均比 × 冗余 1.3
run_event/日   = DAU × run/日 × 事件/run;   字节 ≈ 400B/行(含索引 ×1.8)
毛利率         = (计价 − 成本) / 计价      (不含存储/CDN/渲染)

默认参数下的基线结果（评审摘要）

7.3 弹性、限流与降级

7.4 安全

7.5 隐私与合规

• 数据驻留：国内 Region 数据不出境；海外 Region 满足 GDPR/CCPA（导出、删除请求 30 天内完成）。
• 人脸/声音克隆：必须上传授权声明，记录授权证据；禁止克隆公众人物；可撤销授权并删除模型/嵌入。
• AI 生成内容标识：国内按法规加显式/隐式标识（水印+元数据）；海外可选 C2PA。
• 日志：不记录原始 prompt 全文于通用日志，仅在受控审计库保留 30 天并加密。
• 训练使用：默认不使用用户内容训练；供应商侧开启"不留存/不训练"选项并在合同中确认。

7.6 可观测性

7.7 可靠性与灾备

• PG：同城多可用区高可用 + PITR（7 天）+ 每日全量快照跨区域复制；每季度恢复演练。
• 对象存储：多 AZ，重要成品开启跨区域复制（付费用户）。
• Temporal：使用持久化到独立 PG 集群；Namespace 按 Region；Workflow 版本变更用 GetVersion/Patch，禁止破坏性修改。
• 幂等清单：报价（client_request_id）、批准建任务（quote_id + client_approval_id）、发消息与 Run 动作（client_action_id）、支付回调（provider + event_id）、结算/释放（hold 的 UNIQUE(ref_type, ref_id)）、Webhook 投递、interaction 响应（client_action_id + card_sha256）、outbox relay。
• 混沌演练：每月一次，随机杀 Worker / 注入供应商 5xx / 断开 Redis，验证账务无偏差。

7.8 国际化与可访问性

• UI 文案 ICU MessageFormat，语言包随构建发布，CMS 只管运营文案；首批 zh-CN / en / ja / ko / es / pt-BR / de / fr / id / th。
• Agent 语言策略：回复语言跟随用户；脚本/配音语言由项目 language 决定（继承旧系统 task_language 协议）。
• WCAG 2.1 AA：键盘可操作画布、焦点可见、对比度、字幕。

8.1 环境与 Region

两个 prod 使用同一代码与 Helm Chart，区别仅在 values（供应商、LLM、支付渠道、合规开关）。控制面（Admin、模型目录）各 Region 独立，通过 GitOps 同步配置模板。

8.2 K8s 工作负载规格（单 Region 起步）

示例 Helm values（节选）

# charts/core/values-prod-global.yaml
replicaCount: 6
image: { repository: registry/lumen/core, tag: "{{ .Release.AppVersion }}" }
resources: { requests: {cpu: "1", memory: 2Gi}, limits: {cpu: "2", memory: 4Gi} }
autoscaling: { minReplicas: 6, maxReplicas: 30, targetCPUUtilizationPercentage: 60 }
env:
  LUMEN_REGION: global
  LUMEN_DB_DSN:        { secretKeyRef: { name: core-secrets, key: db_dsn } }
  LUMEN_TEMPORAL_ADDR: temporal-frontend.temporal:7233
  LUMEN_STORAGE_BUCKET: lumen-global-assets
probes:
  startup:   { httpGet: { path: /healthz/startup, port: 8080 }, failureThreshold: 30 }
  readiness: { httpGet: { path: /healthz/ready,   port: 8080 }, periodSeconds: 5 }
  liveness:  { httpGet: { path: /healthz/live,    port: 8080 }, periodSeconds: 10 }
terminationGracePeriodSeconds: 60     # 先摘流量,再等在途请求 ≤ 30s
topologySpreadConstraints: [{ maxSkew: 1, topologyKey: topology.kubernetes.io/zone, whenUnsatisfiable: DoNotSchedule }]

8.3 CI/CD 流水线

flowchart LR
  PR[PR] --> L[lint / typecheck / depguard]
  L --> UT[单元测试 + 覆盖率门禁]
  UT --> IT[集成测试
testcontainers: PG/Redis/Temporal]
  IT --> CT[契约测试
OpenAPI diff + provider 录制回放]
  CT --> SEC[安全扫描
trivy · gitleaks · semgrep]
  SEC --> B[构建镜像 + SBOM + cosign]
  B --> DEV[自动部署 dev
预览环境]
  DEV --> E2E[E2E 冒烟]
  E2E --> M[合并 main]
  M --> STG[部署 staging + 压测基线]
  STG --> APP{人工审批}
  APP --> CAN[prod 金丝雀 5%→25%→100%
Argo Rollouts 指标自动判定]

8.4 发布与回滚

• 配置/特性开关：放在运行时配置里（按用户/工作区/百分比），不在 45 张业务表中。新模型走 model_version 发布与 model_catalog.status（active / beta / disabled）；新 Skill 走 skill_version，会话创建时固定版本，新版本只影响新会话；新定价走 price_rule 的生效区间。
• Temporal Workflow 变更：使用 Worker Versioning，旧版本 Worker 保留至在途 Workflow 清零。
• 数据库迁移：golang-migrate；向前兼容 N-1 版本，回滚只回滚应用不回滚数据库；破坏性变更分 3 次发布。
• 回滚 SLA：5 分钟内完成应用回滚（Argo Rollouts abort）；数据修复通过预审的补偿脚本。

8.5 运维手册（Runbook 索引）

8.6 备份、数据生命周期、成本

8.7 值班与响应

事故复盘模板：时间线、影响面（用户数/积分/金额）、根因、检测延迟、修复延迟、行动项（含负责人与截止日）。

9.1 测试策略总览

flowchart TB
  subgraph L5[5 线上]
    O1[合成监控] --- O2[金丝雀] --- O3[灰度指标]
  end
  subgraph L4[4 E2E / 体验]
    E1[关键旅程 Playwright] --- E2[真实供应商小流量冒烟]
  end
  subgraph L3[3 系统]
    S1[性能/压测] --- S2[混沌] --- S3[安全测试]
  end
  subgraph L2[2 集成/契约]
    I1[testcontainers] --- I2[Temporal 回放] --- I3[Provider 录制回放] --- I4[OpenAPI 契约]
  end
  subgraph L1[1 单元]
    U1[领域/状态机/账本] --- U2[属性测试] --- U3[前端组件]
  end
  L1 --> L2 --> L3 --> L4 --> L5

9.2 关键模块测试设计

9.2.1 积分账本（最高优先级）

9.2.2 生成任务状态机与网关

9.2.3 Agent 与 HITL

9.2.4 Agent 质量评测（离线 + 线上）

任何改动 prompt、Skill、工具面、路由、模型的 PR 必须跑对应评测集并贴报告（继承旧 maa_agent 的轨迹回归做法）。

9.2.5 时间线与渲染

• 黄金文件测试：同一 timeline JSON 渲染，逐帧 SSIM ≥ 0.98、音频 RMS 误差 < 1dB。
• 边界：0 长片段、负偏移、跨轨转场、字幕换行（CJK / RTL / emoji）、字体缺失回退。
• 浏览器预览与服务端导出一致性：抽 10 帧对比。
• 分段并发导出：故意杀死某分段 Worker，验证只重试该分段。

9.2.6 前端

• 组件：Vitest + Testing Library；画布操作（拖拽/连线/撤销重做）用 Playwright 组件测试。
• 视觉回归：关键页面 Percy/截图对比（亮/暗、3 种宽度）。
• 性能：1000 节点基准场景的 FPS 与内存，PR 对比基线，退化 >15% 阻断。
• 可访问性：axe-core 无严重问题。

9.3 性能与压测方案

9.4 混沌与容灾演练

9.5 安全测试

• 授权矩阵：角色 × 资源 × 操作自动化穿越测试，越权用例必须全部 403/404。
• 租户隔离：模糊测试所有带 ID 的接口，换 workspace 的 ID 访问；RLS 开关对照。
• SSRF / 采集器：内网地址、重定向、DNS rebinding、file://、gopher://。
• 支付：伪造 webhook、重放、金额篡改。
• 上传：恶意文件、超大文件、zip 炸弹、畸形视频（ffprobe 沙箱，限制资源）。
• 每季度外部渗透；上线前 OWASP ASVS L2 检查表。

9.6 测试数据与环境

• fake-provider：可配置耗时分布、失败率、uncertain 行为、审核拒绝；是集成与压测的主角，成本为 0。
• 真实供应商冒烟：staging 每日 20 条最小成本用例（5s/480p），并与 fake 行为对照，发现供应商协议漂移。
• 数据：工厂函数生成；脱敏生产快照仅限 staging；任何测试不得使用真实支付渠道。

9.7 发布质量门禁（Go / No-Go）

10.1 团队与里程碑

假设编制（28 人）：后端 8（Go 6 / Python 2）、Agent/AI 5、前端 7、基础设施/SRE 3、QA/测试开发 3、产品 1、设计 1。人天估算以"熟练工程师 + 含自测与评审"为口径，未含假期与会议。

gantt
  dateFormat  YYYY-MM-DD
  axisFormat  %m-%d
  section M0 地基
  脚手架/CI/环境/PoC       :m0, 2026-11-02, 4w
  section M1 生成与计费
  账本+网关+任务工作流     :m1, after m0, 6w
  section M2 画布与Agent
  画布+Agent+URL广告       :m2, after m1, 8w
  section M3 编辑与开放
  时间线+导出+角色+API/MCP :m3, after m2, 6w
  section 内测→公测
  内测(M2后)               :milestone, after m2, 0d
  Beta(M3后)               :milestone, after m3, 0d
  section M4 团队与规模
  团队/批量/多语言/性能    :m4, after m3, 6w
  section M5 增长与投放
  复刻增强/直发/回流       :m5, after m4, 6w
  section 迁移
  旧数据迁移+灰度          :mig, after m3, 8w

总工期约 36 周（9 个月）；关键路径：账本 → 网关/任务工作流 → Agent 写画布 → 导出。

10.2 WBS：任务拆解与验收标准

格式：ID · 任务 · 角色 · 人天 · 依赖 · 验收标准（可测试）。人天为估算中位数。

M0 地基（共 ≈ 118 人天）

M1 生成与计费（共 ≈ 235 人天）

M2 画布与 Agent（共 ≈ 330 人天）

M3 编辑与开放（共 ≈ 250 人天）