本文件是投放中台所有字段、参数、指标的唯一定义源,跨版本生效。
需求文档、原型、接口文档一律引用本表,不另行定义。
改字段先改这里;改含义必须写变更记录。
| 项 | 内容 |
|---|---|
| 版本 | v1(跨版本维护) |
| 适用范围 | 投放中台全部版本(v1.0 起) |
| 维护人 | Davanee |
| 更新日期 | 2026-11-12 |
0. 三条命名规则
- 一个字段一个名字。 同一个东西不允许有两个名字,也不允许「对内叫 A、对外叫 B」——因为它们指向同一个值,换名只会制造歧义。
- 内部名以实体为准:作品用
work_*,语种版本用content_*,分集用episode_*。 - 平台协议字段同名时直接透传;不同名时登记映射,但不因此给自己再起一个别名。
命名历史:项目早期曾同时使用
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_id | char(8) | WQPMZKAB | 作品主键,跨语言聚合用。8 位大写字母(去 I/O),随机生成 | ❌ 永久不可变 | 运营后台 |
work_code | varchar | LOVE-001 | 人读业务编码,运营/客服/口头沟通用 | ✅ 可改 | 运营后台 |
2.2 语种版本 content
| 字段 | 类型 | 示例 | 定义 | 可变 | 写入方 |
|---|---|---|---|---|---|
content_id | char(8) | PBVXQEWU | 投放主键,一条记录一个 ID。8 位大写字母(去 I/O),随机生成,不复用 | ❌ 永久不可变 | 运营后台 |
lang | varchar | en / es / zh-Hant | 语种(BCP-47),content_id 的属性,不参与唯一性判定。后台下拉选择,取值见附录 A。原不可编辑,开发已确认后续放开修改(建议仅在无消耗/无订单时允许) | ⚠️ 有条件可改 | 运营后台 |
content_status | enum | draft / live / offline | 版本状态 | ✅ 可改 | 运营后台 |
online_date | date | 2026-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_no | int | 1 ~ N | 集号,在 content_id 内唯一。分集只追加、不重排 | ❌ 不可变 | 运营后台 |
episode_id | bigint | 10231 | 分集内部 ID,进 OSS 路径用(路径第二段)。不对外、不进投放参数 | ❌ 不可变 | 运营后台 |
is_free | bool | true | 是否免费集(默认前 10 集免费,可按集覆盖) | ✅ 可改 | 运营后台 |
2.4 投放链路
| 字段 | 类型 | 示例 | 定义 | 可变 | 写入方 |
|---|---|---|---|---|---|
campaign_id | varchar | LOVE-001-EN-US | 投放计划标识,按命名规范生成,用于成本与收入缝合 | — | 投放 |
click_id | varchar | ttclid / fbclid / gclid 的值 | 广告平台点击 ID,用于归因 | ❌ 不可变 | 广告平台 |
panel_type | enum | coin_pack / sub_099 / vip | 付费墙类型,决定落地后展示哪种付费面板 | — | 投放 |
scene | enum | in_drama / profile | 订单发生场景。in_drama 必带 content_id,profile 不带 | ❌ 不可变 | 客户端 |
2.5 订单
| 字段 | 类型 | 示例 | 定义 | 可变 | 写入方 |
|---|---|---|---|---|---|
order_id | varchar | 20261111000123 | 内部订单号 | ❌ | 服务端 |
platform_txn_id | varchar | 2000000123456789 | Apple / Google 交易 ID,财务对账唯一凭据 | ❌ | 支付网关 |
amount_gross | decimal | 29.99 | 用户实付金额(USD) | ❌ | 支付网关 |
amount_net | decimal | 20.99 | 净收入 = 实付 × (1 − 渠道抽成 30%) − 税 − 退款 | ❌ | 计算 |
2.6 账号与权限
| 字段 | 类型 | 示例 | 定义 | 可变 |
|---|---|---|---|---|
user_id | bigint | 10231 | 账号主键,永不复用 | ❌ |
email | varchar | linxiao@company.com | 登录账号,全局唯一(含停用账号) | ⚠️ 仅「释放邮箱」时可改 |
name | varchar | 林晓 | 姓名,匿名化后替换 | ✅ |
department | varchar | 增长部 | 部门,审批依据 | ✅ |
employee_no | varchar | A1024 | 工号,选填 | ✅ |
password_hash | varchar | — | bcrypt 哈希,禁止明文与可逆加密 | ✅ |
status | enum | pending / active / rejected / disabled / locked | 账号状态,见下方枚举 | ✅ |
role | enum | super_admin / management / ads / ops | 生效角色,v1 单角色 | ✅ |
applied_role | enum | ads | 申请人自选角色,仅用于留痕对比 | ❌ |
reject_reason | text | 非公司邮箱,无法确认身份 | 驳回原因,登录页展示 | ✅ |
approved_by / approved_at | bigint / datetime | 1 / 2026-11-12 10:30 | 审批人与时间 | ❌ |
token_version | int | 3 | 每次停用 +1,用于立即作废旧会话 | ✅ |
last_login_at | datetime | 2026-11-12 17:31 | 最后登录时间 | ✅ |
expire_at | datetime | 2027-01-01 | 临时账号到期自动停用(选填) | ✅ |
anonymized_at | datetime | 2027-06-01 | 停用满 6 个月匿名化时写入 | ❌ |
唯一约束:email 全局唯一。释放邮箱时,旧账号邮箱改写为 archived+{user_id}@local,原邮箱可给新人使用。
账号交接:不做账号所有权转移。离职 = 停用保留;交接 = 新建账号。否则历史操作日志会变成新人的。
角色枚举
| code | 中文 | 权限概要 | 可申请 |
|---|---|---|---|
super_admin | 超管 | 全部权限;管理账号与权限矩阵 | ❌ 仅现有超管创建 |
management | 管理层 | 看全量收入与操作日志;不能改口径、不能管账号 | ✅ |
ads | 投放 | 看渠道与剧级数据;可导出 | ✅ |
ops | 运营 | 只看剧级数据;不可导出 | ✅ |
状态枚举
| status | 能否登录 | 页面表现 |
|---|---|---|
pending | ❌ | 已提交,等待管理员审核 |
active | ✅ | 按角色加载菜单 |
rejected | ❌ | 显示驳回原因,可修改重提 |
disabled | ❌ | 账号已停用,请联系管理员 |
locked | ❌ | 显示剩余锁定时间,15 分钟后自动解锁 |
权限矩阵表
| 字段 | 类型 | 说明 |
|---|---|---|
matrix_version | int | 每次保存 +1,可回滚到任一历史版本 |
role | enum | 角色 code |
feature_key | varchar | 功能点标识,如 revenue.total |
level | enum | edit / read_only / hidden |
changed_by / changed_at | bigint / datetime | 谁在何时改的 |
diff_json | json | 改前 / 改后对比,用于回滚与审计 |
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 API | contents[].content_id | content_id | 同名,直接透传,无需转换 |
| TikTok Events API | contents[].content_type | 固定填 drama | 内容类型标识 |
| Meta Conversions API | content_ids | content_id | 数组,单剧时只放一个 |
| Meta Conversions API | content_type | 固定填 product | — |
| AppsFlyer | af_content_id | content_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 | 泰国 |
扩展规则(重要):
- 只能新增语言码,不能修改已有码的含义。
- 如果将来要做西班牙(es-ES)或葡萄牙(pt-PT),新增
es-ES/pt-PT,保留es/pt原义,不做改名。 - 拆分原则:按「内容是否真的不同」拆。配音/字幕/用词有实质差异才拆两个码。
注 1:当前
(work_id, lang)的唯一性在 UI 层已由「按语种加载已有版本」保证;仍建议数据库加唯一索引,防止接口直调绕过。
注 2:lang的「不可编辑」已确认将放开(开发口径:后续可修改)。放开时建议加条件:仅在无消耗、无订单时允许,且修改需写操作日志。
8. 变更记录
| 版本 | 日期 | 变更 |
|---|---|---|
| v1 | 2026-11-12 | 建立。统一使用 content_id 作为版本级投放主键(与开发实现一致);lang 定义为 content_id 的属性,不构成复合主键 |
| v2 | 2026-11-12 | 新增 2.6 账号与权限(含角色/状态枚举、权限矩阵表);lang 标注为后续可修改 |
| v3 | 2026-11-13 | 删除 legacy_code(旧剧集编号)。开发已统一为单一 content_id,不再保留新旧双轨 |