埋点与数据分析
字数
2913 字
阅读时间
14 分钟
本方案基于 5 个 Tab（今天 / 随笔 / 任务 / 树洞 / 我的）与独立 SOS 分包，围绕“行为闭环、风险治理、成长激励”三大目标，统一事件命名、参数与落库映射。前端通过 wx.reportAnalytics 上报，后端聚合入 events 集合（docs/数据库/集合-用户事件.events.md）。
命名约定：
- 页面曝光：
pv_* - 列表/组件曝光：
exp_* - 点击/选择：
clk_* - 行为/提交：
act_* - 领域动词：保留已有沉淀（如
mood_checkin_submit,task_status_update）
1. 事件清单（名称 / 触发条件 / 页面或组件 / 参数：字段(类型)-说明）
登录（pages/login/index）
- pv_login｜
onShow/onLoad｜页面｜entry_source(string: mine/auth_guard/deeplink), redirect(string, 可空) - act_login_wechat｜点击微信登录按钮｜微信登录按钮｜has_protocol(bool), attempt_seq(number)
- act_login_protocol_toggle｜点击协议勾选｜协议复选框｜checked(bool)
- act_login_captcha_refresh｜刷新验证码｜验证码组件｜reason(string: timeout/fail/blur), attempt_seq(number)
- act_login_bind_student｜提交学号绑定｜绑定弹窗｜result(string: success/fail/cancel), latency_ms(number), with_sms(bool)
- login_result｜登录接口返回｜全局｜status(string: success/failed/restricted/cancelled), error_code(string, 可空), context(string: login/refresh/bind_student), session_id(string, 可空)
今天（pages/today/index）
- pv_today｜
onShow｜页面｜entry_source(string: launch/switchTab/deeplink), has_login(bool), recommendation_bucket(string) - clk_today_tool｜点击工具金刚区｜ToolTileGrid｜tool_id(string), tool_category(string), position(number), is_pinned(bool)
- mood_checkin_submit｜提交情绪打卡｜情绪打卡弹窗｜mood_score(number 0-100), primary_emotion(
string), mood_tags(array<string>), scene_tags(array<string>), input_type(string: mood_card/manual/task_receipt), energy_level(number 0-5), timestamp(stringISO) - exp_today_suggestions｜Top3 建议渲染完成｜建议列表｜items_count(number), session_id(string)
- suggestion_task_create｜一键生成任务｜建议卡｜suggestion_id(string), task_id(string), category(string), source(string: model/curated/manual), latency_ms(number)
- exp_treehole_feed｜社区高亮卡曝光｜社区高亮卡｜item_count(number), feed_type(string)
任务（pages/tasks/index + packages/tasks/*）
- pv_tasks｜
onShow｜页面｜entry_source(string), has_login(bool), filter_applied(bool) - task_status_update｜开始/完成/跳过/延期｜任务卡/详情/番茄计时器｜task_id(string), status(string: start/in_progress/complete/skip/defer), source_tab(string: today/tasks), delay_minutes(number, 可负), reason(string, 可选)
- task_review_submit｜复盘提交｜复盘表单｜task_id(string), mood_before(number), mood_after(number), notes_len(number), needs_human_followup(bool)
- task_create_manual｜手动新建任务｜新建弹窗｜task_id(string), source(string: manual/quick_note/template), emotion_category(string), estimated_minutes(number), reminder_at(string ISO)
随笔（pages/journal/index）
- pv_journal｜
onShow｜页面｜entry_source(string) - journal_entry_submit｜保存随笔｜多模录入面板｜entry_id(string), entry_type(string: text/voice/image), word_count(number), mood_score(number), use_rebt_template(bool)
- journal_to_task｜随笔生成任务｜随笔卡/弹窗｜entry_id(string), task_id(string), template_id(string, 可空), auto_summary(bool)
树洞（pages/treehole/index, packages/community/*）
- pv_treehole｜
onShow｜页面｜network_type(string) - treehole_post_publish｜发布帖子（含自检）｜post-editor｜post_id(string), topic(string), risk_score(number 0-1), anonymity_mode(string: anon/pseudonym), auto_moderation_result(string: pass/review)
- pv_treehole_post_detail｜帖子详情曝光｜post-detail｜post_id(string), topic(string), risk_level(string), anonymity_mode(string)
- clk_post_action｜帖子底部操作｜post-card/detail toolbar｜post_id(string), action(string: hug/save/report/reply)
- act_comment_submit｜提交评论｜评论框｜post_id(string), comment_id(string), word_count(number), mood_thermometer(number, 可空), is_anonymous(bool), result(string: ok/blocked)
- treehole_care_action｜抱抱/收藏等温和行为｜hug/save 按钮｜post_id(string), action_type(string: hug/save), is_add(bool)
- exp_risk_banner｜风险横幅显示｜risk-banner 组件｜level(string: R1-R4), trigger(string)
- act_risk_action｜点击横幅操作｜risk-banner 组件｜level(string), action(string: view_resource/open_sos/open_ask/request_human), target_url(string, 可空)
SOS（independent/sos/*）
- sos_fab_trigger｜长按 FAB 触发｜全局 FAB｜entry_point(string: today/global/treehole), risk_level(string, 可空), abort(bool), handoff_channel(string, 可空), ticket_id(string, 可空)
- risk_signal_escalate｜风险升级为转介｜风控/审核链路｜risk_signal_id(string), source(string: treehole/ask/task/journal), severity_level(string: R3/R4), handler_role(string), response_latency_s(number, 可空)
我的（pages/mine/index, packages/profile/*）
- pv_mine｜
onShow｜页面｜has_login(bool) - weekly_report_view｜查看/分享周报｜报告卡/详情页｜report_id(string), view_channel(string: push/today/mine), share_action(string: none/counselor/guardian)
- badge_unlock｜徽章解锁｜徽章服务回调｜badge_id(string), badge_type(string: consistency/compliance/recovery), unlock_criteria(string), journey_day(number)
- resource_map_click｜点击资源卡｜resource-map｜resource_id(string), category(string: 校内/热线/社团/外部), open_in(string: phone/map/miniprogram)
- resource_contact｜发起联系/预约｜resource-map/详情｜resource_id(string), channel(string: phone/im/web), anonymous(bool), result(string: ok/cancel/error)
- privacy_setting_update｜隐私与授权变更｜privacy-detail｜setting_key(string), new_value(string|bool), previous_value(string|bool), auth_scope(string)
- profile_edit_enter｜进入资料编辑｜profile-edit｜entry_source(string)
- profile_save｜保存资料｜profile-edit｜changed_fields(array<
string>) - account_logout_request｜发起注销｜account-settings｜reason(string, 可空)
通用 UI 组件
- exp_empty_state｜空态曝光｜empty-state｜pagePath(string), emptyType(string), scene(string)
- act_empty_action｜空态主按钮点击｜empty-state｜pagePath(string), actionType(string), buttonText(string), emptyType(string)
- act_empty_refresh｜空态刷新｜empty-state｜pagePath(string), refreshType(string), emptyType(string)
- act_empty_retry｜空态重试｜empty-state｜pagePath(string), errorType(string), retryCount(number)
- act_topic_select｜话题 Chip 选择｜topic-chip｜topic(string)
- clk_menu_item｜菜单项点击｜menu-list｜menu_key(string)
- clk_stats_item｜统计项点击｜stats-row｜metric_key(string)
- exp_post_detail_first_paint｜帖子详情首屏完成｜post-detail｜ttfp_ms(number), resource_count(number)
晚安模式
- night_mode_toggle｜切换晚安模式｜我的-设置｜enabled(bool), schedule(string "HH:mm-HH:mm"), from_source(string)
- night_reminder_snooze｜夜间提醒延后｜通知弹窗｜notification_id(string), snooze_to(string ISO)
- night_urgent_push｜夜间高优先级推送｜通知系统｜notification_id(string), risk_level(string), delivered(bool)
ASK 情绪助理
- ask_session_start｜开启对话｜ASK 入口｜session_id(string), trigger(string: checkin/journal/treehole/cta/time), mood_before(number, 可空), risk_level(string, 可空)
- ask_action_task_create｜对话转任务｜ASK 对话｜session_id(string), task_id(string), skill(string), recommended_by(string)
- ask_risk_handoff｜转真人/资源｜ASK 对话｜session_id(string), channel(string: counselor/guardian/phone), consent_scope(string)
公共字段（所有事件隐式携带）
- user_id(脱敏或省略，用 openid_hash 关联)、openid_hash、event_time(ISO)、page_path、device、app_version、env(prod/staging/test)、network_type、session_id、trace_id、exp_group(可空)
2. 漏斗映射（事件 → 阶段/目标）
| 事件 | 漏斗阶段 | 用户目标 |
|---|---|---|
| pv_today / pv_tasks / pv_treehole / pv_mine / pv_journal | 曝光 | 进入核心页面 |
| exp_today_suggestions / exp_treehole_feed / exp_risk_banner / exp_empty_state | 触达 | 获取推荐/提示 |
| clk_today_tool / clk_menu_item / clk_stats_item / act_topic_select | 交互 | 导航/筛选 |
| mood_checkin_submit / journal_entry_submit / task_create_manual / action_card 相关（suggestion_task_create） | 激活 | 记录/建任务 |
| task_status_update(status=start) | 激活 | 开始执行 |
| task_status_update(status=complete) | 留存/成就 | 完成任务 |
| task_review_submit | 满意/学习 | 复盘反馈 |
| treehole_post_publish / act_comment_submit / treehole_care_action | 社区参与 | 发帖/互动 |
| weekly_report_view / badge_unlock | 成长激励 | 消费洞察/获得奖励 |
| resource_map_click / resource_contact | 转化（求助） | 使用资源 |
| ask_session_start / ask_action_task_create | 支持介入 | 获得辅导/行动 |
| risk_signal_escalate / sos_fab_trigger / act_risk_action | 风险治理 | 触发/响应干预 |
3. 覆盖矩阵（页面 × 功能 × 事件）
| 页面 | 功能 | 事件 |
|---|---|---|
| 登录 | 登录与会话 | pv_login, act_login_wechat, act_login_bind_student, login_result |
| 今天 | 情绪打卡 | mood_checkin_submit |
| 今天 | 微建议 | exp_today_suggestions, suggestion_task_create |
| 今天 | 工具箱 | clk_today_tool |
| 今天 | 社区高亮 | exp_treehole_feed, pv_treehole_post_detail(跳转后) |
| 任务 | 看板/筛选/执行 | pv_tasks, task_status_update, task_review_submit, task_create_manual |
| 随笔 | 录入/派生任务 | pv_journal, journal_entry_submit, journal_to_task |
| 树洞 | 信息流/互动 | pv_treehole, treehole_post_publish, pv_treehole_post_detail, clk_post_action, act_comment_submit, treehole_care_action, exp_risk_banner, act_risk_action |
| 我的 | 周报/徽章/隐私 | pv_mine, weekly_report_view, badge_unlock, privacy_setting_update, profile_edit_enter, profile_save |
| 我的 | 资源地图 | resource_map_click, resource_contact |
| SOS | 紧急响应 | sos_fab_trigger, risk_signal_escalate |
| 通用 | 空态/菜单/统计 | exp_empty_state, act_empty_action, act_empty_refresh, act_empty_retry, clk_menu_item, clk_stats_item |
| 设置 | 晚安模式 | night_mode_toggle, night_reminder_snooze, night_urgent_push |
| ASK | 对话/转任务 | ask_session_start, ask_action_task_create, ask_risk_handoff |
4. 事件参数 ↔ 数据库字段映射
| 事件 | 参数 | 数据库字段映射 |
|---|---|---|
| pv_login | entry_source, redirect | events.context.entry_source（直接落库），events.context.redirect |
| act_login_wechat | attempt_seq | events.context.attempt_seq，失败次数与 sessions.failed_attempts 对齐 |
| act_login_bind_student | result, latency_ms, with_sms | users.student_binding.status、events.context.latency_ms、events.context.with_sms |
| login_result | status, error_code, context, session_id | sessions.status、sessions._id、authLogin 返回码 |
| mood_checkin_submit | mood_score, primary_emotion, mood_tags, scene_tags, input_type, energy_level | checkins.mood_score, checkins.primary_emotion, checkins.mood_tags, checkins.scene_tags, checkins.input_type, checkins.energy_level |
| suggestion_task_create | suggestion_id, task_id, category, source | suggestions._id, tasks._id, suggestions.category, suggestions.source |
| task_status_update | task_id, status, reason | tasks._id, tasks.status, tasks.task_status_logs.reason(聚合写) |
| task_review_submit | task_id, mood_before, mood_after, needs_human_followup | tasks.review_data.mood_before/after/needs_human_followup, 关联 tasks.linked_checkin_id（由闭环写入） |
| journal_entry_submit | entry_id, entry_type, word_count, mood_score | journals._id, `journals.entry_type |
| journal_to_task | entry_id, task_id, template_id | journals._id, tasks._id, suggestions.task_template_id(可选) |
| treehole_post_publish | post_id, topic, risk_score, anonymity_mode, auto_moderation_result | posts._id, posts.topic, posts.risk_score, posts.anonymity_mode, posts.moderation_result.auto |
| act_comment_submit | post_id, comment_id, is_anonymous, mood_thermometer | comments.post_id, comments._id, comments.is_anonymous, comments.mood_thermometer |
| treehole_care_action | post_id, action_type, is_add | `comments.action_type='hug' |
| pv_treehole_post_detail | post_id, risk_level, topic | posts._id, posts.risk_level, posts.topic |
| exp_risk_banner/act_risk_action | level, action | posts.risk_level 或 risk_alerts.level（R3/R4 时） |
| risk_signal_escalate | risk_signal_id, source, severity_level, handler_role | reports(report_type='risk_alert')._id, risk_alerts.trigger_source, risk_alerts.level, risk_alerts.notified_staff[].role |
| sos_fab_trigger | entry_point, ticket_id, handoff_channel | sos_events.trigger, reports._id(ticket_id), reports.risk_digest.channel |
| weekly_report_view | report_id, view_channel, share_action | reports._id, reports.meta.view_channel, reports.meta.share_action |
| resource_map_click/resource_contact | resource_id, category, channel, anonymous | resources._id, resources.category, audit_logs.action='contact', consents(当匿名→实名变更) |
| privacy_setting_update | setting_key, new_value, previous_value, auth_scope | privacy_settings.* 或 consents.* 差异写入 |
| badge_unlock | badge_id, badge_type, unlock_criteria | badges._id, badges.type, badges.unlock_criteria |
| night_mode_toggle | enabled, schedule | user_preferences.quiet_hours/enabled |
| ask_* | session_id, task_id, channel | ask_sessions._id, tasks._id, reports.risk_alert(handoff) |
说明：所有事件原始载荷统一入 events.event_params，分析任务按表上映射解析并做维表关联（users/tasks/posts 等）。
5. 数据校验与质量门禁（对齐 docs/测试用例.md）
门禁规则（抽样或全量校验）：
- LOGIN-001 微信登录：
pv_login→act_login_wechat→login_result(status=success)成功率 ≥ 95%；失败时error_code必填并与后端日志一致。 - LOGIN-005 刷新成功：
login_result(context=refresh,status=success)后 1 分钟内应有至少一次业务接口成功响应，sessions.last_refresh_at更新。 - TODAY-001 多次打卡：进入今天页后 10 分钟内若存在 ≥2 次
mood_checkin_submit，则应出现对应 2 条checkins写入，且最近一次的pv_today在其前；字段完整率≥99%。 - TODAY-003 建议→任务：发生
suggestion_task_create时，tasks._id可回查，且 5 分钟内出现至少 1 次相关task_status_update（start/complete/skip 任一）。 - TASK-004 执行与复盘：
task_status_update(status=complete)后 5 分钟内必须出现task_review_submit或记录“待复盘”；缺失率<2%。 - JOUR-001 多模随笔：
journal_entry_submit.entry_type in (voice,image)样本需覆盖≥15%；word_count>0 且与journals字数误差<10%。 - TREEHOLE 互动：
clk_post_action(action=reply)后 30 秒内应出现act_comment_submit(result=ok|blocked)；若 blocked，comments.status=hidden。拦截率=blocked/submit。 - SOS 升级：
treehole_post_publish.risk_score≥0.8或risk_level in (L3,L4)样本，必须伴随risk_signal_escalate且 10 分钟内已分配handler_role。 - 周报消费：一周内
weekly_report_view去重 UV / 推送人数 ≥ 60%（阈值可调）。
观测面板建议：
- 事件丢失监控：各关键事件 24h 滑窗波动 >30% 告警。
- 字段有效率：核心字段空值率>1% 告警（如
mood_score,task_id）。 - 时序一致性：
pv_*→act_*平均链路时延周报。
6. 差异与建议（缺失、重复、命名不一致）
缺失/建议新增
- 行动卡：建议补充
action_card_claim、action_card_withdraw（docs/功能文档/功能-行动卡领取与同步.md），与tasks.source='action_card'打通。 - ASK：补充
ask_session_start、ask_action_task_create、ask_risk_handoff（docs/功能文档/功能-Ask心理助理.md）。 - 资源联系：新增
resource_contact以衡量求助转化（docs/功能文档/功能-资源地图导航.md）。 - UI 组件：
risk-banner与empty-state已在组件文档定义事件，需落表并接入。
重复/重叠
treehole_care_action与页面级clk_post_action(hug/save)语义重叠，建议前端点击统一上报treehole_care_action，页面聚合层不再重复。
命名不一致
click_today_tool→ 推荐统一为clk_today_tool（与其他点击类一致）。comment_submit（功能文档）与act_comment_submit（页面文档）不一致，建议统一为act_comment_submit。- 接口文档的
exp_treehole_feed未在原事件表列出，已补齐为曝光事件。 - REST 前缀：接口文档存在
/api/forum/highlight与/api/treehole/*混用，建议统一/api/treehole/*（详见 docs/接口占位文档.md 差异节）。
落库口径
- 所有高敏参数（文本、风险）仅存 ID/哈希/等级，避免原文落库至
events，与集合明细表一致（见 posts/journals/checkins）。
7. 实施与联调
- 前端：统一使用
services/analytics.js（或utils/analytics.ts）封装上报，校验事件名与参数必填性；支持wx.setStorageSync('USE_MOCK', true)切换 Mock。 - 后端：云函数
analyticsIngest校验 schema，按本表入events，并做维表 join（users/tasks/posts），对risk_signal_escalate参数加密。 - 看板：曝光-激活-留存三层大盘、风险响应 SLA、资源转化、行为闭环。（Superset/Metabase）
数据质量注意事项
- 隐私与最小必要：事件载荷不包含原文（随笔/帖子），仅上传必要摘要或 ID。
- 时间与顺序：上报时间使用客户端时间+服务器校准，带
trace_id串联链路。 - 设备与环境：统一
device,app_version,env,network_type字段，便于分层分析。 - 容错与补偿：弱网队列/重试；
sos_fab_trigger等关键事件采用“即发即落库”与本地缓存双保险。 - 实验：A/B 实验加入
exp_group字段，严禁在实验中更改事件名。
变更记录
- 2025-09-22：系统化补齐事件清单、漏斗映射、覆盖矩阵、DB 映射；新增 ASK/行动卡/组件事件；补充数据门禁与命名一致性建议。（来源：功能/页面/UI/接口/数据库/测试/分包文档）
贡献者
Cai Hongyu