fangke/docs/验收记录-阶段A.md

采集底座修复（阶段A）验收台账

日期：2026-09-18 · 分支 m1 · SDK 0.2.0 · 服务端 schema v2 生产 build_id：87261ab-202609181516（部署于 2026-09-18 15:22，tracker.12418113.xyz/sdk/v1.js）

部署记录

项	结果
server 部署	tar → scp 经跳板 → /opt/cms-cj 原地覆盖 → docker compose up -d --build web；迁移 0006 应用成功；tracker-web Up
v1 线上回归	手工 v1 批 accepted=2（响应契约已生效：request_id/server_time/rejected 明细）
v2 线上预验	手工 v2 批（归属+区间）accepted=2；回归测试数据已清理（events/raw/visitors 4/2/8）
SDK 部署	build.mjs → dist/v1.js 12202B（gzip 4824B，0.1.0 为 3838，增量 +986）→ /opt/cms-cj/sdk/dist（nginx 挂载点）
部署路径教训	tar 解压落 /opt/cms-cj/dist 需 cp 到真实挂载 sdk/dist（与 admin/dist 同类陷阱，memory 已记录）
生产验证	hesucar.com 加载新 SDK；生产库当日 20 条 v2 事件：page_id 归属、periodic/hidden 区间、SPA 切段（3 page_id）、stay_ms 区间并集（65143ms 会话）、time_quality=ok

OT 用例 ↔ 自动化测试映射

用例	场景	自动化证据（位置）
OT01	同页超 30min 退出/恢复	sdk/test/page.test.ts：冻结归属（35min 后 resume 旧快照不变）；flush 检查点（hidden 期 flush 刷活后仍恢复，d7d5ed9 双向验证）
OT02	多标签/SPA/bfcache/重试	page.test.ts：bfcache revive 沿用 page_id/seq 续、SPA 仅 pathname 切段（query/hash/replaceState 不切）；transport.test.ts：拆批独立重试、重放同 body
OT03	时钟异常	stay.test.ts：墙钟回拨 -8min 区间长度/端点不变式保持；server test_ingest：time_quality 分类（late/skew_backwards）
OT04	定时器延迟/隐藏 pagehide	stay.test.ts：15s 切 4 相邻区间不重叠、hidden 后 pagehide 不重发（共享结算）、失活悬置
OT06	合成敏感值不残留	server/test_validation + sdk/test/context.test.ts：14 组共享向量（server/tracker/tests/fixtures/sanitize_vectors.json）双侧逐字节一致；review 实测 10 组向量外探测
OT17	beacon unknown/部分拒绝	transport.test.ts：beacon 60KB 预算降级 fetch、超 64KB 丢最旧闭环、响应 rejected 计数、非 JSON 容错；server test_collect：rejected 明细回传

量化指标（基线 → 目标）

指标	基线（9/16 样本）	上线后（48h 观察窗确认）
孤立 page_stay 会话（D02）	5 个会话/8 条事件	机制上已消灭（归属入队冻结）；待 48h 数据确认归零
事件量	~1000 事件/日（319PV）	page_stay 增量 +3~4 倍预期（15s 切分），PV 口径不受影响（event_name 过滤已修，87261ab）
PV 统计口径	全事件计数（潜伏 bug）	仅 page_view（stats.py/dashboard.py 双修 + 2 防回归测试）

遗留与后续

• 48h 观察窗（至 2026-09-20）：D02 指标归零确认、事件量增幅记录、RawBatch status 分布
• 阶段B（M2 核心）：O04/O05 业务事件（产品上下文/咨询点击/表单过程/服务端确认通道）、sdk_diag 低频诊断、admin 前端展示新字段（区间时间线/归属）、站点级清洗参数配置、hash 路由 SPA 适配
• track 通道（终审 I-1，阶段B 必修）：ctk('track', …) 宿主自定义事件无论 v1/v2 均被服务端事件白名单拒（M1 白名单制如此，非阶段A 回归；v2 兜底组信封+无归属字段的组合缝隙使其在 rejected 明细中可观测）。阶段B 扩业务事件字典（O01/O04）时同步定义 track 通道的归属补齐（getPageSession()?.attribution()）与白名单，并补组合形态回归测试
• 已知行为（终审 M-3）：多标签 resume 后并行会话行——旧 sid 事件复用旧会话行不分裂不丢失，visits 口径短期 +1，getSessionId() 下次采纳新 sid 自愈，符合 spec §5 多标签语义
• 记录性事项：seq 乱序标记未实现（宽松方向，随阶段B sdk_diag 做）；page_id 校验宽松口径（≤64 UTF-8，实发 uuid 无风险）；纯 v2 会话时间线 active_ms 展示为 0（展示层不折算区间，阶段B 处理）；端口 0/非 http userinfo 等向量外边缘分歧（双层清洗收敛，Task9 审查备案）；IPv6 字面量 netloc（Task1 审查备案）
• gzip 体积 4824B 超 ~3KB 基线（归属/区间/传输逻辑成本，硬预算 15KB 内），如需精简可评估双监听合并与 encode 辅助函数内联

提交清单（阶段A）

5881046 清洗三轨制+共享向量 → d899903 schema v2 契约+迁移 → 8459e6f ingest v2+响应契约 → 5e024b8 入口加固（孤代理/NaN） → 0cb8c6f 聚合核查+混合回归 → 77ca0ea SDK 版本注入 → 9cd2a65 PageSession → d7d5ed9 flush 检查点+onClose 竞态 → d6b2289 区间停留 → 25e37f5 stayIntervalMs 守卫 → 6432435 传输拆批 → 08495bc 超预算裁剪+4xx 计数 → 2a9c98c TS 清洗对齐 → f24060d 0.2.0 接线 → 87261ab PV 口径修复

测试基线：server 142→161，sdk 58→100。全任务经子代理实现 + spec 合规 + 代码质量两阶段审查（含 3 轮实测复验：esbuild define 点链、并集算法探针、清洗向量双侧探测）。