第3章 埋点体系设计前置条件：权限颗粒度梳理、事件分类、元数据规范
适用场景
- 团队首次对权限系统进行数据驱动迭代，需要建立标准埋点基线。
- 现有权限模型存在语义歧义，不同模块对同一操作的定义不一致。
- 需要将权限评估从“人工经验”迁移到“量化评分”体系（RICE）。
- 跨部门协作时，数据产品经理、后端开发与安全运维对事件口径无法对齐。
前置条件
- 已完成权限体系的目录树梳理（至少识别出功能权限、数据权限、操作权限三类）。
- 确定埋点采集的技术栈（如前端SDK、后端API网关日志、或消息中间件）。
- 获得数据治理委员会对元数据规范的预审批。
- 准备至少3个历史典型权限变更案例用于校准事件分类。
操作步骤
- 权限颗粒度三棱镜梳理 – 将每个权限点按功能模块→子功能→操作原子拆解，形成权限粒度的最小原子单元（Atom Permission）。
- 事件分类映射 – 针对每个原子权限，识别可能触发的用户行为（点击、查看、编辑）和系统行为（鉴权、资源创建、权限变更），并归类到预定义的事件大类。
- 元数据规范制定 – 为每类事件定义固定字段（event_name、event_id、timestamp、user_id、resource_type、permission_atom、action、result、context）及枚举值约束。
- 交叉验证 – 用历史数据或灰度环境验证事件分类覆盖度，确保每个原子权限至少对应一个事件类型。
- 发布埋点字典 – 输出包含权限颗粒度、事件分类、元数据结构的正式文档，并同步到所有相关团队。
输入输出物
| 阶段 | 输入物 | 输出物 |
|---|---|---|
| 颗粒度梳理 | 权限目录树（Excel/脑图） | 原子权限清单（含唯一ID、所属模块、操作类型） |
| 事件分类 | 原子权限清单 + 用户行为日志示例 | 事件分类映射表（权限→事件名称→事件类型） |
| 元数据规范 | 业内埋点最佳实践 + 公司数据规范 | 元数据规范文档（含字段定义、枚举值、JSON Schema） |
| 验收 | 埋点字典（V1） | 埋点字典V1.0（已评审签批） |
责任边界
| 角色 | 职责 |
|---|---|
| 数据产品经理 | 主导原子权限梳理，定义事件分类逻辑，编写元数据规范初稿 |
| 后端开发（权限模块） | 验证原子权限在系统中的实际实现，提供接口参数文档 |
| 数据开发（埋点通道） | 评估元数据字段与已有埋点基础设施的兼容性 |
| 安全合规团队 | 审核事件分类是否覆盖审计要求（如敏感操作必须单独标记） |
| 测试与QA | 设计埋点用例，验证事件分类映射的完整性 |
记录材料
- 原子权限登记表（字段：权限ID、模块、子模块、操作、描述、创建时间）
- 事件分类映射表（字段：权限ID、事件名、事件类型、触发条件、示例URL/API）
- 元数据规范v1.0（包含JSON Schema示例）
提示：元数据规范中的
context字段建议设计为可扩展KV结构，以便后续新增上下文属性时无需变更Schema版本。
异常处理
- 颗粒度过细 – 原子权限超过500个时，建议合并同类型操作，或引入“资源类型+操作”组合键。否则事件爆炸导致成本不可控。
- 事件分类冲突 – 同一权限在不同场景下触发不同事件（前端点击 vs 后端API调用），则拆分为两个独立事件，并在备注中关联。
- 元数据字段缺失 – 若发现已有埋点体系无法携带新字段（如无resource_type），则优先推动平台升级；短期可在context中传递，并标记为“待迁移”。
避坑提醒：不要试图一步到位完美覆盖所有权限。优先覆盖核心业务权限（占总操作量80%的权限），剩余权限可通过“其他”事件兜底，后续迭代中再细化。
验收标准
- 原子权限清单覆盖所有已识别的线上权限点，覆盖率≥95%。
- 每个原子权限至少映射到1个事件类型，且事件分类命中率（即事件触发后能正确归类）≥90%。
- 元数据规范经过至少3个不同团队的评审，无重大分歧。
- 通过一次全量埋点校验：在测试环境模拟10个典型操作，上报的数据符合定义的Schema格式，且字段完整性≥98%。