Civitai Creator Studio 收益页实战解析:基于 `buzzTransactions` 的按来源收益统计与 ClickHouse 查询设计
Civitai Creator Studio 收益页实战解析:基于 buzzTransactions 的按来源收益统计与 ClickHouse 查询设计
导读
本文围绕 Civitai Creator Studio 中 /earnings 页面(即 earnings.md 规格文档)展开,深入剖析"创作者赚了多少钱、钱从哪个来源来"这一收益聚合能力的完整实现:从五大收益来源的数据模型、ClickHouse 查询与过滤设计,到页面组件、服务端加载管线、现金面板与页面状态。读者将掌握 default.buzzTransactions 这一单一事实表上按来源拆分收益的核心 SQL 模式、purchase 类型陷阱与 license-fee 类型值 '27' 的兼容处理,以及"整数结算 vs 分数计提"、"不做货币换算(B8)"等关键设计决策,并能在自己的 ClickHouse 收益分析场景中直接复用。
页面定位:回答"赚了多少、来自哪里"
/earnings 是 Creator Studio 中一个只读的收益聚合页面(v1 已交付)。它的用户故事是:创作者打开页面后,能在一个所选时间窗口内看到按来源拆分的收益总额(授权费 / 打赏 / 生成补偿 / 模型访问与装扮销售)、每日收益的时间序列,以及当前 Creator Program 的**现金余额(pending + settled)**和提现入口。它回答的是 "how much money, from what"(多少钱、来自哪);而 "what usage drives it"(什么使用行为驱动了这些收益,如生成次数、下载量、单模型漏斗)则由 analytics.md 对应的 /analytics 页面承担。
该页面在 Creator Studio 页面体系中与 dashboard.md(概览总览)、models.md(费用的写入侧)形成清晰边界:/earnings 展示创作者实际赚到的金额,/models 是设置费用/访问权限的地方,/dashboard 只给"一眼看全"的总数。
数据基石:所有五个收益来源都来自 default.buzzTransactions
页面最核心的架构决策(文档中标注为 D2,2026-07-14 由 Justin 拍板)是:五个收益来源全部从 default.buzzTransactions 读取,而不是此前计划中的 resourceCompensations 或其他表。理由很直接:创作者是通过 buzz 交易获得报酬的,所以收益天然就在交易流水里——一张表、一条查询、无需 UNION。此前文档中因"数据不在同一张表"而设想的 deferred-source 状态因此被删除。
在源码 apps/creator-studio/src/lib/server/earnings.ts 中,这一决策落实为两个核心 SQL 片段:
const ACCESS_SALE_PREFIXES = `(externalTransactionId LIKE 'early-access-%' OR externalTransactionId LIKE 'permanent-access-%')`;
const RECEIVING_TYPES = `(type IN ('tip','compensation','licenseFee','27','sell') OR (type = 'purchase' AND ${ACCESS_SALE_PREFIXES}))`;
const whereClause = (uid: number, from: string, to: string) =>
`toAccountId = ${uid} AND date >= toDate('${from}') AND date < toDate('${to}') + 1 AND ${RECEIVING_TYPES}`;
所有查询统一以 toAccountId = <创作者 userId> 作为 owner 过滤条件,再叠加来源类型过滤。收益来源的类型过滤规则(文档中的核心表格,已被源码逐一实现)如下:
| 来源 | 过滤条件 |
|---|---|
| Tip 打赏 | type = 'tip' |
| Compensation 生成补偿 | type = 'compensation' |
| License fee 授权费 | type IN ('licenseFee','27') —— ⚠️ 存在 ingest bug,见下文 |
| Access sale 访问销售 | type = 'purchase' AND externalTransactionId LIKE 'early-access-%' |
| Cosmetic sale 装扮销售 | type = 'sell' |
源码中的 SOURCE_EXPR 进一步把原始 type 值映射为页面统一的来源词汇表(multiIf):
multiIf(type = 'tip', 'tip',
type = 'compensation', 'compensation',
type IN ('licenseFee','27'), 'licenseFee',
type = 'sell', 'cosmeticSale',
'accessSale')
这里注意两个源码级别的细节,它们比文档表格更进一步:
- 访问销售匹配两个前缀:
ACCESS_SALE_PREFIXES同时匹配early-access-%和permanent-access-%。因为永久付费访问(permanent paid access)拆分上线之前的历史行全部是early-access-前缀,两个前缀都必须匹配,任何一个都不能丢弃(见 earnings.ts 的注释)。 - 来源词汇表是客户端共享的:
EARNINGS_SOURCES = <a href="https://link.gitcode.com/i/146a862a641512f930a9e9c5214158bf" target="_blank">'compensation','tip','licenseFee','accessSale','cosmeticSale']及其显示标签、图表配色定义在客户端安全的 [apps/creator-studio/src/lib/earnings.ts 中,服务端读取模块与页面共用,保证两侧词汇一致。
为什么不用 resourceCompensations?
owner-rollup-handoff.md 记录了这一判断的依据:resourceCompensations 是按创作者每日聚合的分数计提(accrual)数据,且其 accountType 字段存在历史标签变迁(User→Yellow/Blue),而 buzzTransactions 是整数结算(settlement)数据——夜间任务在每日边界对补偿做一次取整(见下文"精度"一节)。页面要报告的是创作者实际到账的金额,因此 buzzTransactions 是唯一正确的数据源。
三个必须绕开的查询陷阱
文档与 owner-rollup-handoff.md 共同记录了三类会在真实数据上咬人的陷阱,源码都已显式处理:
1. type='purchase' 本身不是"销售"
90 天实测:np-deposit-(NOWPayments 充值)有 39,402 行 / 6.86 亿 buzz,而 early-access- 只有 29,993 行 / 5,480 万 buzz。充值流的 toAccountId 是买家自己,所以一条朴素的 toAccountId = X AND type='purchase' 会把创作者给自己充值的行为误算成收益。因此必须始终用 externalTransactionId 前缀来圈定访问销售,且要排除 accountId = 0(那是系统/平台账户,不是用户 0)。
2. License fee 的 type 字面值是 '27'
TransactionType.LicenseFee = 27,但 ClickHouse 的 ingest 物化视图 buzz.tx_to_staged_mv 中手写的 caseWithExpression 映射只枚举了 0..26,超出部分回退为 toString(Type)。结果是从 2026-05-21 起每条授权费支出都被标记为 '27'(92 行、每天 02:00 持续增长)。修复与回填由 Justin 负责,在修复落地前查询必须写成 type IN ('licenseFee','27'),否则授权费卡片会读成零。源码的 RECEIVING_TYPES 与 SOURCE_EXPR 均已按此双值处理。
3. 装扮销售是两段式交易
装扮收入不是 purchase 而是 sell:买家支付的 purchase 先进平台银行(toAccountId: 0,externalTransactionId 为 cosmetic-purchase-…),随后一条独立的 sell 腿把约 70% 转发给 cosmetic.createdById。面向创作者的行是 sell 腿。此外 details 字段是 JSON 字符串,任何实体提取都要在查询时付出 JSONExtract 代价,表里没有现成的 entityType/entityId 列。
精度决策:整数就是对的
文档明确了一条反直觉但正确的设计:金额是整数,且这是对的。其依据(来自 Justin 的确认)是:
orchestration.resourceCompensations.amount是Float64且为分数(如0.0234)——这是计提(accrual);default.buzzTransactions.amount是Int32——这是结算(settlement)。夜间任务(主应用src/server/jobs/deliver-creator-compensation.ts)在每日边界只取整一次,这正是 A2 规格要求的行为,而非 bug。
因此 /earnings 展示的是创作者实际被支付的金额;计提与实付会按设计略有出入(每日边界丢弃了 sub-buzz 余数)。这也引出一条使用警告:不要把按来源的总数与按模型的收益(来自 resourceCompensations 的分数计提)当作同一个数字——前者是整数结算,后者是分数计提。
性能与依赖:owner 键天然存在,无需字典
文档记录了一个重要的范围收窄结论:gap #1(owner-keyed rollup 字典)不再是本页面的阻塞依赖。原因有二:
default.buzzTransactions.toAccountId就是创作者的userId(已验证 1:1:1,791/1,791 条purchase行的details.userId与toAccountId匹配;22,310/22,310 条tip行匹配details.targetUserIds);- 表上已有
PROJECTION byToAccount (SELECT * ORDER BY toAccountId, date, fromAccountId, transactionId),使 owner 键查询变成点查。基表的ORDER BY以date开头,若只按toAccountId过滤会全表扫描,投影正是为让它变成低成本查找而存在。使用该投影,不要在证明其慢之前新建物化视图。
字典方案(A1 Part 2 的 CDC/ClickPipe 方案)最终被更简单的方案取代:owner 在写入时被直接盖到每条 ResourceCompensation 行上,按模型收益只需 GROUP BY ownerId(见 licensing-fee-owner-stamping.md,该文档位于 docs/creator-studio/ 下)。因此字典仅对 /analytics 的按模型表格有意义,本页面不再依赖。
服务端加载管线:+page.server.ts 的并行读取与独立降级
实际实现位于 apps/creator-studio/src/routes/(app)/earnings/+page.server.ts/earnings/+page.server.ts)。其核心设计是多个数据源并行读取、独立降级:
const [earnings, cmpSummary, cmpSeries, cash, monthly, buzzRatio] = await Promise.all([
Promise.all([
getEarningsSummary({ userId, ...range }),
getEarningsSeries({ userId, ...range }),
]).catch(() => [null, null] as const),
getEarningsSummary({ userId, ...compare.range }).catch(() => null),
getEarningsSeries({ userId, ...compare.range }).catch(() => null),
getCreatorCash({ userId }).catch(() => null),
getMonthlyEarnings({ userId }).catch(() => null),
getBuzzDollarRatio({ userId }).catch(() => null),
]);
要点:
- 时间段来自共享 cookie,而非 URL:
readAnalyticsPeriod(cookies)从ANALYTICS_PERIOD_COOKIE(格式from|cmp,host-only)读取所选月份与对比月份。这样月份切换不会回弹到当前月(RangeSelector 只写该 cookie),且与/analytics共用同一数据源。对比月份(严格早于所选月份)同时驱动趋势叠加线与卡片上的 delta 徽标。 through语义:趋势图在 x 轴上画完整月份,但当前月的折线只画到已流逝的最后一天through(range.to < todayIso ? range.to : todayIso),避免把尚未发生的日子读成"跌到零"。- 缓存:
getEarningsSummary/getEarningsSeries/getMonthlyEarnings/getBuzzDollarRatio都经createCache包装,TTL 依据rangeTtlSeconds({ from, to })计算,且缓存键派生自参数而非负载(earnings:series:v2的后缀在返回形状变化时需递增)。 - 独立降级:ClickHouse 收益与 buzz 服务现金余额来自不同系统,任一失败都以
null进入页面,各自渲染独立的错误占位,互不拖累。
页面还提供了三类超出文档规格的扩展数据:
- 月度表现表(monthly performance):近 12 个月的按月 buzz 收益,按货币拆分、逐月显示环比 delta(
getMonthlyEarnings,独立于所选月份),对应"本月 vs 前几个月"的反馈诉求; - Buzz→$ 汇率历史(
getBuzzDollarRatio):每月"银行化 Buzz 价值多少美元",封顶 $0.001/Buzz(即每 1,000 Buzz 最高 $1.00)。实现上有两个值得注意的 SQL 细节:comp 现金(comp-pool-unified-<pool月>-<userId>拨款到 cashPending,单位为美分)按 externalId 解析出的 pool 月份归属而非支付日期,使迟到的 true-up 落回正确月份;银行化 Buzz =bank减withdrawal/refund。bank是从fromAccountId借记的,因此查询用 UNION ALL 按账户列拆分而非OR——因为表的排序键是(date, fromAccountId, toAccountId),单列各走索引,OR无法走索引会全表扫描(约慢 40 倍); - 销售计数(sales counts):
accessSale的count是产品中唯一的销售计数——销售不是一个表,只是一个externalTransactionId前缀。
核心查询拆解:按来源汇总与按日序列
两个核心读模型定义在 apps/creator-studio/src/lib/server/earnings.ts:
按来源 × 货币汇总(来源卡片与 dashboard 头部的数据来源):
SELECT multiIf(...) AS source, toAccountType AS currency, sum(amount) AS total, count() AS count
FROM default.buzzTransactions
WHERE toAccountId = <uid>
AND date >= toDate('<from>') AND date < toDate('<to>') + 1
AND <RECEIVING_TYPES>
GROUP BY source, currency
ORDER BY total DESC
按来源 × 日期的趋势序列(趋势图数据来源):额外 GROUP BY date, source,并且只统计 buzz 货币(toAccountType IN ('yellow','blue','green','club'))——趋势图是 buzz 趋势,现金单独放在面板里。
货币处理:toAccountType 就是币种,永不换算(B8 / D1)
一个贯穿全页的设计约束是 B8:展示创作者实际收到的货币,不做任何换算或合并。货币就是行上的 toAccountType(LowCardinality(String) 小写值:yellow、blue、green、club、creatorProgramBank、cashSettled、cashPending 等),汇总必须把 toAccountType 留在分组键里,否则黄/蓝/绿/现金会坍缩成一个无意义的桶。客户端 lib/earnings.ts 定义了 currencyMeta:buzz 家族(yellow/blue/green/club)、cash 家族(cashSettled/cashPending)、bank 家族(creatorProgramBank 等),但 family 只用于视觉分组与格式化,绝不跨家族求和。
值得注意的实现细节:buzz 读取统一限定在 BUZZ_CURRENCIES = ['yellow','blue','green','club'],而不是用 currencyMeta(c).family === 'buzz' 过滤——后者会把未知币种当作 buzz,导致同一笔数在一张卡片上出现、另一张上不出现的错位。
格式化规则:buzz 是整数单位(底层补偿是分数但永不展示部分 buzz,向下取整),cash 账户余额以美分存储(cashSettled/cashPending 的余额是 USD 美分而非 buzz),展示时 /100 转成美元。
页面组件与交互:@civitai/ui 原语组合
前端实现位于 apps/creator-studio/src/routes/(app)/earnings/+page.svelte/earnings/+page.svelte),全部基于 @civitai/ui(shadcn-svelte)原语,不手写:
- 来源卡片(StatCard):每个来源一张卡片,显示窗口内总和 + 与对比月份的
DeltaChip环比徽标;访问销售卡片额外显示销售笔数与最近日期计数(throughIsToday决定显示 "today" 还是具体日期)。 - 来源过滤(ToggleGroup):一个来源过滤器同时支配来源卡片、按来源表格与趋势图(
shownSources状态)。隐藏任何来源时,所有受影响区块都会被黄色Filtered · hiding N of M sources标识,防止被误读为完整收益。 - 趋势图(Chart):基于 Chart.js(
@civitai/ui的Chart包装,决策 C1),支持折线/柱状切换(ChartTypeToggle)。当前期折线画真实 0(已流逝无收益的日子)与null间隙(through之后的日子);对比期折线按序数偏移对齐到当前期下方,30 天的对比月放在 31 天月份下也不会在第 31 天错误跌到 0(pointRadius在超过 45 天时置 0 以避免密集点)。 - 按来源表格(Table):支持 Split(按货币分列)/ Combined(合计 Buzz 单列)切换,选择持久化到 localStorage;单元格同样带环比
DeltaChip。 - CP 现金面板:pending / settled / withdrawn 三个数字 + Buzz Dashboard 外链按钮(
https://civitai.com/user/buzz-dashboard),现金余额来自 buzz 服务而非 ClickHouse(CH 现金是期间流量,会与真实余额漂移)。 - 空态:无收益时显示"Set access prices on your models to start earning"并链接
/models;非 CP 成员额外提示/join。注意空态文案不区分是否 CP 成员——因为打赏与访问销售对任何创作者都累计,只有额外的 CP 渠道需要 upsell。 - 月度表现表与 Buzz→$ 汇率表:如上节所述。
CP 现金面板:复用主应用,不重建
现金数据来自 apps/creator-studio/src/lib/server/cash.ts 的 getCreatorCash:settled 与 pending 来自 buzz 服务(getUserBuzzByAccountType(userId, 'cashSettled' | 'cashPending')),withdrawn 来自 Postgres CashWithdrawal 表的净额汇总(排除 Rejected/Canceled/FailedFee/Reclaimed 状态),与主应用 Buzz dashboard 的三个数字逐美分一致。页面唯一的"动作"就是 Withdraw 外链到现有 CP 现金/提现流程——这是刻意不重建支付流程的设计(决策 C6:cash home 在 /earnings,提现入口链接到 Buzz Dashboard)。
页面状态与访问控制
文档定义的状态机在实现中均有对应:
| 状态 | 处理 |
|---|---|
| Loading | 骨架卡片 + 图表占位 |
| Empty(从未赚过钱) | 友好空态 + 链接到 /models(设置费用)/ 上传 |
| 已删除——五个来源同表同查询,无需设计延迟来源状态 | |
| Pre-cutover(comp⇔fee 切换前) | 授权费收益可能"尚不可支付",需标注以免总额被误读为现金 |
| Error(ClickHouse 读失败) | 内联错误卡片;CP 现金面板独立渲染不受影响 |
门控(Gating):任何登录用户都可访问——这是只读页面,member-tier 门控是针对动作(如在 /models 设置费用)而非视图的。非会员也能正常查看自己的收益。
边界划分与相关页面
- analytics.md(
/analytics)——使用侧(生成/下载/漏斗),即驱动这些收益的"因";与/earnings共享 ClickHouse 读取模块与图表库决策。页面底部有明确的 creator-level 提示:"For earnings broken down by individual model, see Model analytics"。 - models.md——费用/访问的设置处(写入侧);
/earnings展示他们赚到了什么。 - dashboard.md——一眼看全的总数;
/earnings是完整的按来源拆分。 - CP 现金/提现——现有主应用 / Creator Program 流程,链接而非重建。
- 主应用遗留的
getDailyCompensationRewardByUser正被重定向,完整切换后两者汇聚到同一个 CH 读取模块。
已决问题与遗留开放项
文档记录的开放问题大多已解决:
- v1 交付哪些来源? → D2(2026-07-14):全部五个。它们是对
default.buzzTransactions的一条查询,包含访问/装扮销售没有额外成本。 - owner-keyed rollup(gap #1)是否是硬依赖? → 不是。
buzzTransactions已按toAccountId拥有键并带byToAccount投影;字典仍排期,但只服务于/analytics的按模型表格。 - "top-earning models" → 仍走 A1 依赖:comp/licenseFee 行是每日按创作者聚合、不含
modelVersionId,无法从buzzTransactions回答,改读resourceCompensations(现在依赖 owner-stamping 而非字典,见 licensing-fee-owner-stamping.md)。
仍开放的设计问题包括:/earnings 与 /earnings/analytics、dashboard 的边界(按来源总额 + 现金是其独有价值,避免与另两页重复);CP 现金 + 提现是内联还是外链(当前实现选择外链);时间粒度与默认窗口(当前实现为按月主控、对比月叠加、近 12 个月月度表)。
给读者的实践要点
- 收益统计先找交易流水表:如果"创作者通过某种内部货币交易获得报酬",收益按来源拆分的第一选择是交易流水(如
buzzTransactions),它天然带 owner 键(toAccountId)与币种(toAccountType),一表一查询即可覆盖所有来源。 - 警惕类型字段的语义陷阱:
purchase不等于销售(可能混入充值);类型枚举值可能与上游 ingest 映射脱节('27');业务上"两段式"的交易(装扮购买 + 创作者分成)要认准创作者那一腿的type。 - 收益用结算值、预测用计提值:整数结算(实际到账)与分数计提(应计)是两个数,展示"赚了多少"用前者,不要混用或宣称相等。
- owner 键查询靠投影而不是新物化视图:先确认表上已有
PROJECTION能服务查询计划(EXPLAIN indexes=1),再决定是否需要新建 MV。 - 币种永远留在分组键里:任何收益聚合若按
toAccountType分组,否则多币种会坍缩成无意义的总和。
延伸阅读(仓库内)
- docs/creator-studio/earnings.md —— 本文对应的页面规格文档
- docs/creator-studio/owner-rollup-handoff.md —— owner 键收益汇总的完整论证、陷阱与精度说明
- docs/creator-studio/analytics.md —— 使用侧分析页面的规格
- docs/creator-studio/dashboard.md —— 概览页规格
- apps/creator-studio/src/lib/server/earnings.ts —— 服务端收益读取模块(SQL 实现)
- apps/creator-studio/src/lib/earnings.ts —— 客户端共享的来源/币种词汇表
- apps/creator-studio/src/routes/(app)/earnings/+page.server.ts/earnings/+page.server.ts) —— 页面服务端加载
- apps/creator-studio/src/routes/(app)/earnings/+page.svelte/earnings/+page.svelte) —— 页面组件
- apps/creator-studio/src/lib/server/cash.ts —— CP 现金读取