adcloud-server/docs/events.md

事件注册表与标准特征

身份与凭据

本版沿用现有部署 TENANT_ID：一个部署上下文对应一个租户，该租户内按 app_id 隔离注册表和接入凭据。尚未实现客户账号登录、多租户请求路由或客户角色权限；不能把不同客户的应用都放进 default 租户并声称彼此身份图谱隔离。 平台受控后端使用 SERVICE_TOKEN 调用 POST /v1/registry/apps 创建应用，返回 collection_key、server_key、management_key（仅此时返回原值）；数据库只保存带租户密钥的 HMAC。 collection_key 是 SDK 使用的受限写入凭据，不是用户认证或广告反作弊凭据。server_key 只在客户可信后端保存，用于上报服务端专属事件。management_key 用于本版控制台注册管理，页面内存保存，刷新清空；不使用 SERVICE_TOKEN，不存 localStorage。正式管理操作需 HTTPS，并最终接入客户登录。 事件请求头 X-Adcloud-Key 必须匹配 app_id；管理请求头 X-Adcloud-Management-Key 必须属于同一应用。 匿名 token 与 Master ID 沿用身份图谱；事件本身不验证邮箱、不执行登录态身份缝合。

公共请求字段

必选：app_id、name、event_version、event_id（UUID）、occurred_at（带时区，不能为未来或超过 90 天的历史事件）、properties。 可选：session_id、context、anonymous_token。浏览器可使用 Cookie，SDK 也可显式发送此前签发的匿名 token。 context 为有 32 KiB 上限的可选 JSON 上下文；properties 为有 32 KiB 上限的注册参数对象。业务身份/密码/设备推送 token 不应作为埋点字段；query、URL 等可能包含隐私数据，应由客户在上报前清理。 匿名签发 POST /v1/identity/anonymous 也接受可选 anonymous_token，用于 SDK 在 Cookie 不可用时恢复此前签发的匿名身份。

标准事件目录

下表参数都位于 properties。默认拒绝未注册参数、空字符串、类型不符和超出范围的值。quantity 为正整数；金额为最小货币单位非负整数，并要求三位大写 currency。 items 为 1–100 个商品对象，每项必选 product_id / quantity，可选 category_id / unit_price。 content.engage.action: like / save / share / comment；不采集评论正文。 content.progress 是累计进度信号，本版没有将其自动累加成时长特征。 ad.response.result: filled / no_fill / error；filled 需 delivery_id。ad.error 需 request_id 或 delivery_id。 ad.impression / ad.click 是客户端信号，本版不实现广告归属验证、有效曝光认定、反作弊或计费。 delivery_id 是单次广告投递 ID；message_id 必须是单个接收方的一次消息投递 ID，群发活动使用 campaign_id。push.open 按 message_id 统计首次打开，非每次重复打开。 push.delivery.result.status: accepted / delivered / failed，只有供应商确实提供的状态才上报。

标准事件	分类 / 含义	必选参数	可选参数	来源	业务去重键
page.view	访问与内容 / 页面访问	page_id	referrer, title, url	SDK / 服务端	event_id
content.view	访问与内容 / 内容查看	content_id, content_type	author_id, category_id	SDK / 服务端	event_id
content.engage	访问与内容 / 内容互动	content_id, action	category_id, content_type	SDK / 服务端	event_id
content.progress	访问与内容 / 内容消费进度	content_id, consumed_ms	duration_ms, progress_percent	SDK / 服务端	event_id
search.submit	访问与内容 / 发起搜索	query	category_id, result_count	SDK / 服务端	event_id
navigation.click	访问与内容 / 导航点击	target_id	destination, placement_id	SDK / 服务端	event_id
commerce.product.view	电商与交易 / 商品查看	product_id	category_id, currency, price	SDK / 服务端	event_id
commerce.cart.add	电商与交易 / 加入购物车	product_id, quantity	cart_id, category_id, currency, price	SDK / 服务端	event_id
commerce.cart.remove	电商与交易 / 移出购物车	product_id, quantity	cart_id, category_id	SDK / 服务端	event_id
commerce.checkout.start	电商与交易 / 开始结算	checkout_id, items	amount, coupon_id, currency	SDK / 服务端	event_id
commerce.order.create	电商与交易 / 创建订单	order_id, items, amount, currency	checkout_id, coupon_id	服务端	order_id
commerce.payment.success	电商与交易 / 支付成功	order_id, payment_id, amount, currency	items, payment_method	服务端	payment_id
commerce.order.cancel	电商与交易 / 订单取消	order_id	reason_code	服务端	order_id
commerce.refund.success	电商与交易 / 退款成功	order_id, refund_id, amount, currency	items, reason_code	服务端	refund_id
account.signup.success	注册与线索 / 注册成功	registration_id, method	campaign_id	服务端	registration_id
account.login.success	注册与线索 / 登录成功	method	login_id	服务端	event_id
lead.form.start	注册与线索 / 开始填写表单	form_id	campaign_id, placement_id	SDK / 服务端	event_id
lead.submit.success	注册与线索 / 留资成功	lead_id, form_id	campaign_id, lead_type	服务端	lead_id
conversion.complete	注册与线索 / 业务转化完成	conversion_id, conversion_type	currency, related_object_id, value	服务端	conversion_id
ad.request	广告 / 请求广告	request_id, placement_id	format, page_id	SDK / 服务端	request_id
ad.response	广告 / 广告返回	request_id, result	delivery_id, latency_ms, reason_code	服务端	request_id
ad.render	广告 / 广告渲染	delivery_id	render_ms	SDK / 服务端	delivery_id
ad.impression	广告 / 广告展示信号	delivery_id, impression_id	visible_ms, visible_ratio	SDK / 服务端	impression_id
ad.click	广告 / 广告点击信号	delivery_id, click_id	destination_id, impression_id	SDK / 服务端	click_id
ad.video.progress	广告 / 广告视频进度	delivery_id, milestone	played_ms	SDK / 服务端	delivery_id, milestone
ad.dismiss	广告 / 关闭广告	delivery_id, action	reason_code	SDK / 服务端	event_id
ad.error	广告 / 广告错误	stage, error_code	delivery_id, request_id	SDK / 服务端	event_id
push.permission.result	推送 / 推送权限结果	status, channel	prompt_id	SDK / 服务端	event_id
push.send	推送 / 发送推送	message_id, channel	campaign_id	服务端	message_id
push.delivery.result	推送 / 推送投递结果	message_id, status	failure_reason, provider_code	服务端	message_id, status
push.open	推送 / 打开推送	message_id	campaign_id	SDK / 服务端	message_id
push.click	推送 / 点击推送入口	message_id, action_id	destination_id	SDK / 服务端	message_id, action_id
push.unsubscribe	推送 / 取消推送订阅	channel	reason_code, subscription_id	SDK / 服务端	event_id

注册、发布、试算

公共 GET /v1/registry/catalog 返回事件字段类型、必选字段、枚举、范围，以及标准特征字典。 应用管理接口路径前缀 /v1/registry/apps/{app_id}：

• GET /events：查看应用所有事件参数版本和草稿。
• PUT /events/{name}/versions/{version}：新增或保存草稿。
• POST 同一路径 /preview：传入 properties，显示命中规则和特征增量，无事件或特征写入。
• POST /publish：产生不可变 rule_revision 并激活。
• POST /disable：拒绝新事件；已经接受的任务继续执行，原 event_id 的幂等重试仍返回原回执。
• GET /publications：列出不可变历史发布配置。
• POST /rollback：传入 revision，激活该历史规则；不重算此前接受的事件。

配置示例：

{
  "standard_event": "commerce.cart.add",
  "description": "用户将数码商品加入购物车",
  "extra_fields": {},
  "required_extra": [],
  "rules": [{
    "conditions": [{"field": "properties.category_id", "operator": "eq", "value": "digital"}],
    "effects": [{"feature": "intent.purchase.digital", "operation": "increment", "value": 1}]
  }]
}

name 可以是客户自己的 add_cart；参数仍使用标准字段名。本版不做参数字段重命名或商品目录补全。 规则条件引用可选字段时，该字段会成为该事件定义的必选字段；上例因此必须提供 category_id。 扩展字段支持 string / integer / number / boolean；不能覆盖标准字段。发布过的参数结构不可变，改结构需要新 event_version；只改规则增量或描述可发布新 rule_revision。 规则内条件全部满足才执行；多条规则独立匹配。支持 eq / in / contains / gt / gte / lt / lte，contains 只支持字符串。 仅支持正数 increment，增量精度最多 6 位小数，单个增量 ≤100。规则只能引用平台已有特征；不运行任意代码、脚本或正则表达式。 最多 20 条规则、每条 20 个条件和 20 个增量、30 个扩展字段，配置正文最大 64 KiB。

持久化与计算

PostgreSQL 新增 event_apps、event_definitions、event_rule_publications、event_receipts、event_feature_contributions。元数据与冻结的请求/规则快照使用 JSONB，本地使用 SQLite JSON；已有表不改列，初始化时增加新表。 POST /v1/events 在同一事务中保存原始事件和规则任务；adcloud-events worker 在同一事务中写特征贡献、更新画像并入画像 outbox、标记任务完成。失败回滚，任务仍可重试。 同一租户下 event_id 不能用于不同事件；有业务去重键的事件还会按应用和标准事件业务键去重，避免同一支付、广告点击或推送投递重复计算。 贡献绑定原始身份节点。读取时按 Master ID 对应的所有图谱成员汇总；缝合前后不复制贡献，不重复加分。GET /v1/users/{master_id} 提供 features；GET /v1/users/{master_id}/features 提供最近 100 个贡献及其 rule_revision，使用现有可信服务鉴权。 标准特征值按事件发生时间计算窗口和上限，而非简单覆盖 attributes；不能通过画像 PATCH 修改标准特征。 adcloud-profiles 将含特征快照的画像同步 Cassandra。画像读取的 features 按关系库贡献实时计算，避免过期分数被 Cassandra 缓存延长；Cassandra 画像仍保持其版本回退机制。 没有自动打标签、历史事件重放、商品类目查询、通用累积观看时长或客户自建标准特征功能。购买次数等特征按客户映射的业务事件计数，映射时应明确最终成交的业务含义。

标准特征	展示名称	窗口	上限
intent.purchase.digital	数码购买意向	7 天	100
interest.category.digital	数码兴趣	30 天	100
engagement.ad.click	广告点击活跃度	7 天	1000
engagement.push.open	推送打开活跃度	30 天	1000
commerce.purchase.count	购买次数	30 天	10000
conversion.lead.count	留资次数	30 天	10000

兼容与部署

EVENT_REGISTRY_REQUIRED 默认 true。旧版未带应用字段的埋点将返回 422，应先创建应用、注册并发布事件、更新 SDK。仅本地旧代码联调可设置 false；一旦带 app_id 仍必须通过注册表校验。平台专属结果事件不会因为兼容开关而允许 collection_key 上报。 Compose 已增加常驻 event-worker；部署 smoke 创建合成应用、注册加购、发送与重试事件，并验证 +1、身份缝合及 Cassandra 当前版本。临时 CI 对 SQLite 与真实 PostgreSQL 都测试注册、参数、去重、规则版本、worker 回滚和窗口。