第4章：数据埋点事件定义步骤

适用场景

当需要进行权限颗粒度的用户行为追踪、权限使用频率统计、权限冲突检测或RICE评分因子采集时，必须先对每一个数据埋点进行标准化的事件定义。本章适用于权限迭代周期中的“埋点设计”环节，尤其是当产品经理与数据团队首次建立权限埋点字典或对已有埋点进行重构时。

前置条件

• 已输出权限颗粒度清单（第2章产物）
• 已确定RICE评分模型需要的指标维度（第3章产物）
• 现有技术架构支持事件采集（客户端SDK / 服务端日志系统）
• 事件命名规范文档已批准（若无则先建立最小规范）

操作步骤

事件定义分为四个子步骤，需按序执行并逐项确认。每个子步骤完成后须在事件定义表中填录相应字段。

1. 定义事件名称
   • 采用“对象_动作_来源”三段式，如 perm_edit_role_admin
   • 全小写英文，单词间下划线分隔，不超过5个单词
   • 确保全局唯一性（与存量事件名称检重）
2. 定义属性字段
   • 区分“用户属性”（uid、角色、部门）与“事件属性”（权限ID、操作结果、时间戳）
   • 必填字段：user_id, timestamp, action, target_perm_id
   • 可选字段：source_page, device_type
   • 每个属性标注数据类型（string、int、boolean）、最大长度、是否为数组
3. 确定触发时机
   • 主动触发：用户点击“保存权限”按钮时立即采集
   • 自动触发：页面加载、定时任务、权限同步完成时自动上报
   • 条件触发：仅当权限申请通过/驳回/超时时触发
   • 记录触发逻辑表达式（如 点击保存 && (修改了角色admin的权限)）
4. 选择数据采集方式
   • 客户端埋点：通过前端SDK（如神策、友盟）直接上报
   • 服务端日志：后端接口配合输出JSON日志，由日志管道（Fluentd、Filebeat）采集
   • 桥接方式：客户端触发后调用服务端API，服务端代为上报
   • 选择依据：延迟要求、数据准确性、设备离线场景

输入输出物

类型	名称	说明
输入	权限颗粒度清单	第2章产物，包含所有权限ID及描述
输入	RICE评分指标映射表	第3章产物，指明需要哪些事件数据
输出	事件定义表（.csv / .xlsx）	包含事件id、名称、属性字段、触发时机、采集方式、负责人
输出	埋点规范说明书	文档记录命名规则、属性字典、触发条件逻辑

责任边界

• 产品经理：定义事件业务含义、触发场景、属性业务逻辑
• 数据分析师：审核属性字段是否满足RICE指标计算、确保非冗余
• 前端/后端工程师：按定义实现采集代码，保证触发时机准确
• 测试工程师：验证事件名称唯一性、属性值格式、触发条件覆盖

记录材料

事件定义过程中须同步维护以下文档（推荐使用在线协同表格）：

• 事件定义草稿表：包含“待确认”状态标记，用于跨组评审
• 属性字段字典：统一字段名称、类型、枚举值列表（如action: {0: “创建”, 1: “修改”, 2: “删除”}）
• 触发时机日志：记录每次触发逻辑的讨论结果及其对应的埋点验证case

异常处理

验收标准

• 所有事件名称在系统中唯一，且符合命名规范
• 事件属性字段覆盖RICE评分所需的所有维度（第3章输出）
• 触发逻辑通过测试用例覆盖（包含正常、边界、异常情况）
• 采集方式在生产环境可正常上报，且数据无丢失（抽样100条对比服务端日志）
• 事件定义表已完成产品、数据、开发三方评审并签字确认