From 50afd23a26dd4cadca8cdd50a4e354ced9d1e7eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Fri, 18 Sep 2026 17:47:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=98=B6=E6=AE=B5B=20spec=E5=90=B8?= =?UTF-8?q?=E6=94=B6=E5=AE=A1=E6=9F=A5=E4=BF=AE=E6=AD=A3=E2=80=94=E2=80=94?= =?UTF-8?q?onSegmentChange=E8=A7=A6=E5=8F=91=E7=82=B9=E9=92=89=E6=AD=BB/?= =?UTF-8?q?=E7=A9=BA=E5=8D=A0=E4=BD=8D=E7=AD=96=E7=95=A5/recompute?= =?UTF-8?q?=E5=B7=B2=E5=AD=98=E5=9C=A8/form=5Fid=E6=A0=BC=E5=BC=8F/error?= =?UTF-8?q?=5Fcode=E5=89=8D=E5=90=91=E6=A1=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- .../specs/2026-09-18-collection-phase-b-design.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/superpowers/specs/2026-09-18-collection-phase-b-design.md b/docs/superpowers/specs/2026-09-18-collection-phase-b-design.md index d966bc9..4ed5a09 100644 --- a/docs/superpowers/specs/2026-09-18-collection-phase-b-design.md +++ b/docs/superpowers/specs/2026-09-18-collection-phase-b-design.md @@ -33,7 +33,7 @@ |---|---|---| | form_start | .wpcf7-form 内首次 isTrusted focusin/input（每表单实例一次） | form_id | | form_submit | wpcf7submit（**每次尝试**） | form_id, submission_id（当次新生成 uuid） | -| form_error | wpcf7invalid / wpcf7spam | form_id, submission_id, error_code（CF7 status 规整枚举）， field_count | +| form_error | wpcf7invalid / wpcf7spam | form_id, submission_id, error_code（invalid/spam/other——other 为 forward-compat 桶，若 CF7 源码核验发现其他失败事件则启用）， field_count | | form_submit_result | wpcf7mailsent → result_code:"mail_sent"；wpcf7mailfailed → "mail_failed" | form_id, submission_id, result_code | - **submission_id 语义**：一次提交尝试 = 一个 ID（form_submit 时生成；result 引用最近一次的 ID）。form_start 不生成。 @@ -45,7 +45,7 @@ - 规则：path 匹配 `/product/{slug}/`（pattern 内置默认，init 可覆盖——为未来站点预留，hesucar 用默认）。 - 属性：`{product_id: slug, inferred: true, rule_version: "v1"}`。多语言同产品无法关联——诚实标注（inferred 降级路径，gpt/14 §5.1）。 -- **触发时机**：init 时同步判定 + SPA 切段回调。PageSession 新增 `onSegmentChange(fn)` 钩子（与 onClose 对称；**单点 hook history**，business.ts 注册回调判定新段 path，不重复 wrap）。 +- **触发时机**：init 时同步判定 + SPA 切段回调。PageSession 新增 `onSegmentChange(fn)` 钩子——**触发点钉死在 `onRouteChange` 内新段创建之后**（模块级注册表，不在 `close()` 内触发——close 还覆盖 pagehide/重复 init，放在那里会在卸载时重复发 product_view）；单点 hook history，business.ts 注册回调判定新段 path，不重复 wrap。 - PV 不双计：服务端 PV 统计已有 event_name 过滤（87261ab）。 ### 1.4 track 通道修复（阶段A 终审 I-1） @@ -55,7 +55,7 @@ ### 1.5 隐藏字段 `_ctk_sid`（服务端确认契约预留的浏览器侧半边） -- form_start 时向表单注入 ``——**注意**：submission_id 在 form_submit 才生成，故注入策略：focusin 时注入占位（空值或预生成 ID），form_submit 事件触发时**更新**该字段值为当次 submission_id（CF7 的 AJAX FormData 构造在 wpcf7submit 事件之后的同步流程内，更新可见性以实测为准，不可靠则该次对齐缺失）。 +- form_start 时向表单注入 ``（**空占位**——不用预生成 ID：若 submit 时更新对 CF7 FormData 不可见，空值=干净缺失，预生成 ID 则阶段C 会收到匹配不到任何事件的孤儿确认，更糟）；form_submit 事件触发时更新该字段为当次 submission_id（更新可见性以 CF7 源码核验为准，不可靠则该次对齐缺失）。 - 作用：CF7 提交 POST 天然携带，阶段C 的 WP mu-plugin 从 `$_POST['_ctk_sid']` 读取对齐。CF7 忽略未注册字段、正常传输——对现有表单行为无害。 - known-limitation：无任何交互直接提交的极端场景，submission_id 可能为空（事件与漏斗不受损，仅确认对齐缺失）。 @@ -70,7 +70,8 @@ - **优先级重排**：点击参数决定平台性质——fbclid → **paid_social**（Meta 平台本质），gclid/msclkid/yclid → paid_search；utm_medium 仅在无点击参数时参与判定（label_only 证据）。 - `CHANNELS` +`paid_social`；utm_medium 规范化映射（写死）：paid_search 强化集 {cpc, ppc, paidsearch, paid}、paid_social 判定集 {social, paid_social, social_ads, paidsocial}（需同时有 fb 家族 utm_source）。 -- **`ATTRIBUTION_RULE_VERSION` bump v1→v2** + 历史重算：**计划第一步先验证 recompute 管理命令是否存在**（constants.py 注释提及约定但命令本体未核验）——不存在则本任务含实现（按 site 幂等重算 SourceClassification）。 +- **`ATTRIBUTION_RULE_VERSION` bump v1→v2** + 历史重算：`recompute_attribution` 管理命令**已存在**（management/commands/recompute_attribution.py，含 --site 参数与既有幂等测试 test_attribution.py:226 可参照），本任务只需 bump 版本 + 新渠道分支测试 + 线上重算执行。 +- `form_id` 服务端格式校验：`cf7-\d+`。 - admin 中文标签同步：付费社交（渠道徽章/来源分布，grep 全部渠道显示点统一改）。 ## 4. Admin 前端