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

1. 收集输入材料：Figma、需求文档、图片、现有埋点、业务说明、入口来源、oper_id 分配信息。
2. 抽取事实清单：页面、模块、元素、交互、曝光/点击/播放/滑动/下载等事件、动态业务参数、跳转目标、来源入口。
3. 建立事件矩阵：按页面流转顺序列出页面曝光/结束曝光、模块曝光、元素曝光、元素点击、播放时长、滑动、下载等事件。
4. 分配字段：按 tracking_spec.md 的列顺序写入 page_name、module_name、element_name、element_level、game_id、activity_id、adtag、ext1-ext25 等字段。
5. 标注来源不确定项：缺少真实来源的字段保留空值或写入说明中的「待确认」，不要编造事实。
6. 输出 CSV：优先使用 scripts/tracking_csv_tool.py write events.json output.csv，或复制 assets/tracking_template.csv 后写入事件行。
7. 二次校验：运行 scripts/tracking_csv_tool.py validate output.csv；修复 errors，逐条确认 warnings。
8. 交付时附简短说明：列出已覆盖范围、待确认字段、校验结果。

Figma and Image Workflow

• Figma 输入：先加载并使用 figma skill 提取 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 字段名或前三列 示意图、说明、场景。字段缺失时自动输出为空。