Game Center Tracking CSV
Overview
生成、补全、审校 QQ 游戏中心埋点文档，并按「游戏中心改版二期-埋点-新规范」输出 CSV。重点保证字段命名、事件结构、元素层级、扩展字段说明和可追溯性一致，避免凭空编造 oper_id、页面、模块、入口来源或业务参数。
When to Use
- 根据 Figma 链接/文件、需求文档、PRD、截图、流程图或图片编写埋点 CSV。
- 根据现有埋点 CSV 补齐缺失事件、统一字段命名、迁移到新规范。
- 二次校验埋点文档，检查结构、必填字段、命名、层级、事件类型和事实来源。
- 输出可交付给产品、开发、测试使用的
.csv埋点文档。
Required References
- 阅读
references/tracking_spec.md获取字段口径、必填规则、输出列顺序。 - 阅读
references/example_patterns.md获取示例中的页面/模块/元素命名、事件组合和扩展字段分配模式。 - 使用
scripts/tracking_csv_tool.py生成模板、写入 CSV 或校验 CSV。 - 使用
assets/tracking_template.csv作为标准 CSV 表头模板。
Authoring Workflow
- 收集输入材料：Figma、需求文档、图片、现有埋点、业务说明、入口来源、oper_id 分配信息。
- 抽取事实清单：页面、模块、元素、交互、曝光/点击/播放/滑动/下载等事件、动态业务参数、跳转目标、来源入口。
- 建立事件矩阵：按页面流转顺序列出页面曝光/结束曝光、模块曝光、元素曝光、元素点击、播放时长、滑动、下载等事件。
- 分配字段：按
tracking_spec.md的列顺序写入page_name、module_name、element_name、element_level、game_id、activity_id、adtag、ext1-ext25等字段。 - 标注来源不确定项：缺少真实来源的字段保留空值或写入说明中的「待确认」，不要编造事实。
- 输出 CSV：优先使用
scripts/tracking_csv_tool.py write events.json output.csv，或复制assets/tracking_template.csv后写入事件行。 - 二次校验：运行
scripts/tracking_csv_tool.py validate output.csv；修复 errors，逐条确认 warnings。 - 交付时附简短说明：列出已覆盖范围、待确认字段、校验结果。
Figma and Image Workflow
- Figma 输入：先加载并使用
figmaskill 提取 frame、node、组件、文案、交互态和导出截图；仅基于可见节点和用户提供的交互说明生成埋点。 - 图片/截图输入：使用图片读取能力识别页面结构、按钮、列表、浮层、tab、卡片、空态和反馈态；无法确认的跳转、动态参数、埋点 ID 标记为待确认。
- PRD/需求输入：按需求中的用户路径、状态机、权限/失败态、弹窗/半浮层、分享/下载/播放等流程补齐事件。
- 多来源输入：优先级为明确埋点需求 > PRD 文案 > Figma 可见 UI > 图片识别结果 > 合理模式推断；推断项必须标记待确认。
Core Rules
- 不编造
oper_id：未提供或无法从既有文档确认时，留空并在说明写「新增加operid（待分配）」或「待确认oper_id」。 - 不编造业务参数：如
game_id、activity_id、adtag、material_id、tianshu_ad_id、red_dot_id缺少来源时留空或标待确认。 - 保持命名一致：
page_name使用page_...，module_name使用module_...，sub_module_name使用sub_module_...，元素沿用示例常见em_...。 - 保持层级一致：元素事件的
element_level使用英文逗号倒序，如em_action_button,module_choose_script；模块级事件可填module_xxx。 - 页面事件保持干净：
page_show、page_hide通常只填page_name和必要业务参数，不强行填模块/元素。 - 曝光与点击成对检查：入口、按钮、卡片、tab、浮层、模块通常需要同时考虑曝光与点击。
- 播放事件使用
video_end，并补充视频总时长、播放时长等扩展字段说明。 - 复杂列表/卡片事件补充排序、点击位置、内容 ID、故事线 ID、模板 ID、战报 ID 等动态字段说明。
ext13在示例中常用于kuikly版本号；复用扩展字段时保持同一文档内语义稳定。
CSV Output Standard
- 使用 UTF-8 with BOM 编码，保证 Excel 正常打开中文。
- 保留前 5 行表头结构：导航行、分组行、字段分区行、英文字段名行、中文字段说明行。
- 从第 6 行开始写埋点事件，每行一个事件。
- 允许空值单元格，但不能删除标准列或改变列顺序。
- 输出文件名建议：
游戏中心改版二期-埋点-<需求名>.csv。
Validation Requirements
- 结构校验：找到
oper_id、event_code、page_name等标准列；列顺序不可随意改动。 - 必要字段校验：每个事件至少确认
场景、event_code、page_name；元素/模块事件补齐相应层级字段。 - 事实校验：逐项回看 Figma/PRD/图片/现有埋点来源；没有来源的值不落为确定事实。
- 语义校验：确认事件类型与场景一致，如曝光不用
click，播放时长不用普通点击。 - 层级校验：确认
element_level与element_name、module_name、sub_module_name一致。 - 扩展字段校验：同一字段在相邻/同类事件中语义保持一致；长文本放
ext21。
Tool Commands
python scripts/tracking_csv_tool.py template output.csv
python scripts/tracking_csv_tool.py write events.json output.csv
python scripts/tracking_csv_tool.py validate output.csv
python scripts/tracking_csv_tool.py validate --strict output.csv
events.json 使用 rows 数组，每个对象的键名为 CSV 字段名或前三列 示意图、说明、场景。字段缺失时自动输出为空。
