本文件是投放中台所有字段、参数、指标的唯一定义源,跨版本生效。
需求文档、原型、接口文档一律引用本表,不另行定义。
改字段先改这里;改含义必须写变更记录。

项内容
版本v1(跨版本维护)
适用范围投放中台全部版本(v1.0 起)
维护人Davanee
更新日期2026-11-12

0. 三条命名规则

  1. 一个字段一个名字。 同一个东西不允许有两个名字,也不允许「对内叫 A、对外叫 B」——因为它们指向同一个值,换名只会制造歧义。
  2. 内部名以实体为准:作品用 work_*,语种版本用 content_*,分集用 episode_*。
  3. 平台协议字段同名时直接透传;不同名时登记映射,但不因此给自己再起一个别名。

命名历史:项目早期曾同时使用 content_id 与 series_id 表示同一个键,属于「一名二物」。开发实现已统一为 content_id,本文档同步废弃 series_id,全库不再出现该名字。


1. 实体层级

work(作品) 1 ──── N content(语种版本) 1 ──── N episode(分集)
  • 一部作品按语种拆成多个内容版本;每个版本下挂自己的分集
  • content_id 单独确定一条版本记录,lang 只是它的属性(不是复合主键)
  • 各语种 content_id 不同,但共用同一个 work_id,因此可以按作品汇总
  • 投放链路只认 content_id;作品级汇总用 work_id

2. 字段总表

2.1 作品 work

字段类型示例定义可变写入方
work_idchar(8)WQPMZKAB作品主键,跨语言聚合用。8 位大写字母(去 I/O),随机生成❌ 永久不可变运营后台
work_codevarcharLOVE-001人读业务编码,运营/客服/口头沟通用✅ 可改运营后台

2.2 语种版本 content

字段类型示例定义可变写入方
content_idchar(8)PBVXQEWU投放主键,一条记录一个 ID。8 位大写字母(去 I/O),随机生成,不复用❌ 永久不可变运营后台
langvarcharen / es / zh-Hant语种(BCP-47),content_id 的属性,不参与唯一性判定。后台下拉选择,取值见附录 A。原不可编辑,开发已确认后续放开修改(建议仅在无消耗/无订单时允许)⚠️ 有条件可改运营后台
content_statusenumdraft / live / offline版本状态✅ 可改运营后台
online_datedate2026-09-18首次上架日期❌ 不可变运营后台

存储路径规则(2026-11-13 确认):

https://{域名}/{前缀}/video/{content_id}/{episode_id}/{24位随机字符串}.{扩展名}

开发答复中路径示例写作 {series_id},按统一口径应为 {content_id}。待确认是消息笔误还是代码变量名;若为后者,建议改名以免一名二物。

已废弃字段:legacy_code(旧剧集编号)—— 2026-11-13 开发确认不再保留,全系统只有 content_id 一个版本级主键。

唯一约束:(work_id, lang) 唯一。同一作品下不允许出现两个同语种版本——否则剧级 ROI 会被拆成两半,且报表上看不出来。

2.3 分集 episode

字段类型示例定义可变写入方
episode_noint1 ~ N集号,在 content_id 内唯一。分集只追加、不重排❌ 不可变运营后台
episode_idbigint10231分集内部 ID,进 OSS 路径用(路径第二段)。不对外、不进投放参数❌ 不可变运营后台
is_freebooltrue是否免费集(默认前 10 集免费,可按集覆盖)✅ 可改运营后台

2.4 投放链路

字段类型示例定义可变写入方
campaign_idvarcharLOVE-001-EN-US投放计划标识,按命名规范生成,用于成本与收入缝合—投放
click_idvarcharttclid / fbclid / gclid 的值广告平台点击 ID,用于归因❌ 不可变广告平台
panel_typeenumcoin_pack / sub_099 / vip付费墙类型,决定落地后展示哪种付费面板—投放
sceneenumin_drama / profile订单发生场景。in_drama 必带 content_id,profile 不带❌ 不可变客户端

2.5 订单

字段类型示例定义可变写入方
order_idvarchar20261111000123内部订单号❌服务端
platform_txn_idvarchar2000000123456789Apple / Google 交易 ID,财务对账唯一凭据❌支付网关
amount_grossdecimal29.99用户实付金额(USD)❌支付网关
amount_netdecimal20.99净收入 = 实付 × (1 − 渠道抽成 30%) − 税 − 退款❌计算

2.6 账号与权限

字段类型示例定义可变
user_idbigint10231账号主键,永不复用❌
emailvarcharlinxiao@company.com登录账号,全局唯一(含停用账号)⚠️ 仅「释放邮箱」时可改
namevarchar林晓姓名,匿名化后替换✅
departmentvarchar增长部部门,审批依据✅
employee_novarcharA1024工号,选填✅
password_hashvarchar—bcrypt 哈希,禁止明文与可逆加密✅
statusenumpending / active / rejected / disabled / locked账号状态,见下方枚举✅
roleenumsuper_admin / management / ads / ops生效角色,v1 单角色✅
applied_roleenumads申请人自选角色,仅用于留痕对比❌
reject_reasontext非公司邮箱,无法确认身份驳回原因,登录页展示✅
approved_by / approved_atbigint / datetime1 / 2026-11-12 10:30审批人与时间❌
token_versionint3每次停用 +1,用于立即作废旧会话✅
last_login_atdatetime2026-11-12 17:31最后登录时间✅
expire_atdatetime2027-01-01临时账号到期自动停用(选填)✅
anonymized_atdatetime2027-06-01停用满 6 个月匿名化时写入❌

唯一约束:email 全局唯一。释放邮箱时,旧账号邮箱改写为 archived+{user_id}@local,原邮箱可给新人使用。

账号交接:不做账号所有权转移。离职 = 停用保留;交接 = 新建账号。否则历史操作日志会变成新人的。

角色枚举

code中文权限概要可申请
super_admin超管全部权限;管理账号与权限矩阵❌ 仅现有超管创建
management管理层看全量收入与操作日志;不能改口径、不能管账号✅
ads投放看渠道与剧级数据;可导出✅
ops运营只看剧级数据;不可导出✅

状态枚举

status能否登录页面表现
pending❌已提交,等待管理员审核
active✅按角色加载菜单
rejected❌显示驳回原因,可修改重提
disabled❌账号已停用,请联系管理员
locked❌显示剩余锁定时间,15 分钟后自动解锁

权限矩阵表

字段类型说明
matrix_versionint每次保存 +1,可回滚到任一历史版本
roleenum角色 code
feature_keyvarchar功能点标识,如 revenue.total
levelenumedit / read_only / hidden
changed_by / changed_atbigint / datetime谁在何时改的
diff_jsonjson改前 / 改后对比,用于回滚与审计

fail-closed 规则:新增 feature_key 时,全部角色默认 hidden,必须显式授权后才出现。


3. 投放参数(URL Query)

参数名必须与字段名一致,不做缩写、不做别名。

参数必填示例说明
content_id✅ABKQZPWM目标剧集版本
episode_no⬜3目标集号;为空时落到第 1 集
panel_type⬜coin_pack付费墙类型;为空时用默认面板
campaign_id✅LOVE-001-EN-US计划标识
click_id有则必传ttclid 值由平台宏注入

示例:

https://app.example.com/r?content_id=ABKQZPWM&episode_no=3&panel_type=coin_pack&campaign_id=LOVE-001-EN-US

不进参数:work_id(内部聚合)、work_code(人读)、lang(由 content_id 隐含)、episode_id(存储用)。


4. 外部字段映射

平台协议里的字段名由对方定义,我们不改自己的字段名,只在此登记映射。

平台 / 系统对方字段名接我们哪个字段说明
TikTok Events APIcontents[].content_idcontent_id同名,直接透传,无需转换
TikTok Events APIcontents[].content_type固定填 drama内容类型标识
Meta Conversions APIcontent_idscontent_id数组,单剧时只放一个
Meta Conversions APIcontent_type固定填 product—
AppsFlyeraf_content_idcontent_id同名,自定义事件参数
广告平台 URL 宏{{ad.id}} 等不映射宏只用于拼 campaign_id

统一叫 content_id 的一个额外收益:与平台协议同名,少一层映射,回传时直接透传即可。

记住:content_id 既是我们的字段名,也是平台协议里的字段名——同名同义,不需要别名,也不需要映射表做转换。


5. 事件与事件参数

事件触发时机必带参数本期状态
install首开click_id、campaign_id可用
register注册 / 绑定账号user_id、registered_days可用
first_play首次播放content_id、episode_no可用
episode_3_complete第 3 集完播content_id可用
paywall_view付费墙曝光content_id、panel_type可用
purchase支付成功amount_net、order_id、scene、content_id(scene=in_drama 时)占位
ad_revenue广告收入回传ad_unit、revenue占位

6. 指标与口径

指标公式口径说明
ROAS已归因收入 ÷ 消耗剧级只用 revenue_attributed
CPI消耗 ÷ 安装分子分母须同源(同为平台口径或同为归因口径)
归因覆盖率MMP 归因安装 ÷ 平台安装目标 ≥ 90%
对账差异率|平台值 − 自建值| ÷ 平台值阈值 5%
revenue_attributed有 content_id 的净收入之和—
revenue_unattributed无 content_id 的净收入之和(个人中心充值)不计入剧级 ROAS
amount_net实付 × 0.7 − 税 − 退款渠道抽成按 30%

7. 命名规范

对象规则示例
campaign{work_code}-{lang}-{country}LOVE-001-EN-US
adset{country}_{age}_{gender}US_25-34_F
广告素材{content_id}_{钩子类型}_{版本}ABKQZPWM_hook_strong_v2

附录 A. 语种枚举

与后台下拉实现一致(2026-11-12 核对前端代码),共 7 个取值,禁止手填。

语言语言码市场约定
英语en美 / 英 / 澳 / 加,不区分 en-US / en-GB(内容版本相同)
简体中文zh-Hans大陆 / 东南亚华人
繁体中文zh-Hant台 / 港 / 澳,不用 zh-TW / zh-HK
西语es默认指拉美西语(墨西哥 / 哥伦比亚 / 阿根廷等)
葡语pt默认指巴西葡语
印尼语id印尼
泰语th泰国

扩展规则(重要):

  1. 只能新增语言码,不能修改已有码的含义。
  2. 如果将来要做西班牙(es-ES)或葡萄牙(pt-PT),新增 es-ES / pt-PT,保留 es / pt 原义,不做改名。
  3. 拆分原则:按「内容是否真的不同」拆。配音/字幕/用词有实质差异才拆两个码。

注 1:当前 (work_id, lang) 的唯一性在 UI 层已由「按语种加载已有版本」保证;仍建议数据库加唯一索引,防止接口直调绕过。
注 2:lang 的「不可编辑」已确认将放开(开发口径:后续可修改)。放开时建议加条件:仅在无消耗、无订单时允许,且修改需写操作日志。

8. 变更记录

版本日期变更
v12026-11-12建立。统一使用 content_id 作为版本级投放主键(与开发实现一致);lang 定义为 content_id 的属性,不构成复合主键
v22026-11-12新增 2.6 账号与权限(含角色/状态枚举、权限矩阵表);lang 标注为后续可修改
v32026-11-13删除 legacy_code(旧剧集编号)。开发已统一为单一 content_id,不再保留新旧双轨