feat(sdk): 0.2.0接线——归属快照/区间停留/清洗对齐/响应契约全链路

Co-Authored-By: Claude Code <noreply@anthropic.com>

sdk/src/events.ts

@@ -2,11 +2,11 @@ import type { Transport } from "./transport";
 import { pageContext } from "./context";
 import { uuid } from "./util";
 
-// 来源信号（Navigation Timing L2）：startPageTracking 仅 init 时调用一次，
+// 来源信号（Navigation Timing L2）：page_view 构造时读取，
-// 读一次 Navigation Entry 即冻结进 page_view——nav_type ∈ navigate/reload/
+// 读一次 Navigation Entry 即冻结——nav_type ∈ navigate/reload/
 // back_forward（浏览器不给则空串）；activationStart>0 = 页面由预渲染激活
 // （AI 搜索/聚合器预加载的强指纹）。任何环境异常静默（spec §4.5 红线）。
-// T6 起导出供 page.ts 的 page_view 复用（T7 拆分后保留于此）。
+// page.ts 的 page_view 复用本函数（T6 起导出）。
 export function navSignals(): { nav_type: string; prerendering: boolean } {
   try {
     const nav = performance.getEntriesByType("navigation")[0] as
@@ -19,9 +19,10 @@ export function navSignals(): { nav_type: string; prerendering: boolean } {
 
 // T7 拆分：有效停留（区间制重做）移至 stay.ts（startStayTracking 与 PageSession
 // 协作：单调时钟区间 / 15s 周期切分 / hidden-pagehide 共享结算幂等）。
-// 本函数保留 v1 接线兼容（index.ts 过渡期仍调用，T10 改接 page.ts+stay.ts）：
+// T10 起 index.ts 改接 page.ts+stay.ts，本函数不再接线——保留是因为
-// 只发 page_view，并在 hidden/pagehide 时 flush(true)（沿 v1 卸载 beacon 路径，
+// events.test.ts 仍守 v1 行为基线（page_view 形态与卸载 flush 路径）。
-// 防首屏事件随页面关闭丢失），不再产生 page_stay。
+// 行为：只发 page_view，并在 hidden/pagehide 时 flush(true)（沿 v1 卸载
+// beacon 路径，防首屏事件随页面关闭丢失），不产生 page_stay。
 // 红线：任何回调异常不得冒泡到宿主页（spec §4.5）。
 export function startPageTracking(t: Transport) {
   // emit 内 pageContext() 只取一次（pc）复用于 path/title——避免多次读取间

sdk/src/index.ts

@@ -1,7 +1,8 @@
 import { uuid } from "./util";
 import { mergeConfig } from "./config";
 import { Transport } from "./transport";
-import { startPageTracking } from "./events";
+import { startPageSession } from "./page";
+import { startStayTracking } from "./stay";
 import { buildEnvContext, collectHighEntropyHints, pageContext } from "./context";
 import { SDK_VERSION, BUILD_ID, SCHEMA_VERSION, CONFIG_VERSION } from "./types";
 import type { CtkConfig } from "./config";
@@ -44,6 +45,14 @@ function dispatch(cmd: string, arg?: unknown) {
           /* 静默：绝不冒泡到宿主页（spec §4.5） */
         });
       transport = new Transport(cfg);
+      // 0.2.0 接线（T10）：PageSession 发初始 page_view（携带归属快照）并安装
+      // SPA 切段/bfcache/交互 hook；stay.ts 区间停留（onClose 已挂钩
+      // route_change/pagehide 结算）。交互监听双份属过渡期设计（page.ts 用于
+      // 会话恢复判定、stay.ts 用于活动窗口判定）——8 个 passive capture 监听
+      // 性能可忽略，不合并（合并会耦合两个模块的测试，收益低）。
+      const ps = startPageSession(transport);
+      // sdk_loaded 先于 startStayTracking 入队：即使 stay 极端环境注册抛错，
+      // init 心跳（版本组诊断）也不丢失（dispatch 外层 catch 只兜异常不补事件）
       transport.push({
         event_id: uuid(),
         event_name: "sdk_loaded",
@@ -51,8 +60,11 @@ function dispatch(cmd: string, arg?: unknown) {
         path: pc.path,
         title: pc.title,
         properties: { sdk_version: SDK_VERSION, build_id: BUILD_ID, schema_version: SCHEMA_VERSION, config_version: CONFIG_VERSION },
+        // 顶层归属快照展开（...a 含 V1.1 预留 null 位——attribution() 将来填
+        // 实值时事件自动携带，不会静默漏）；seq 在初始 page_view 之后自增
+        ...ps.attribution(),
       });
-      startPageTracking(transport);
+      startStayTracking(transport, ps);
     } else if (cmd === "track" && transport) {
       transport.push(arg as object);
     } else if (cmd === "flush" && transport) {

sdk/test/index.test.ts

@@ -2,7 +2,9 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 
 // index.ts 是 IIFE 打包入口：模块加载即读取全局队列、替换 g.ctk 并重放。
 // 隔离手段：vi.resetModules() + 动态 import，每用例拿到全新模块级 transport 状态。
-// startPageTracking 注册的 document/window 监听跨用例存留，用独立 siteId 过滤批次。
+// startPageSession/startStayTracking 注册的 document/window 监听跨用例存留，
+// 用独立 siteId 过滤批次。0.2.0 接线（T10）：初始 page_view 由 startPageSession
+// 发（seq=1），sdk_loaded 随后入队（seq=2）——队列顺序 [page_view, sdk_loaded]。
 
 type Cmd = [string, unknown?];
 type CtkFn = ((cmd: string, arg?: unknown) => void) & { q?: Cmd[] };
@@ -70,6 +72,29 @@ describe("index 入口", () => {
     expect(loaded.event_id).toMatch(UUID_RE);
   });
 
+  it("接线冒烟（T10）：init 后 page_view+sdk_loaded 两事件均带顶层归属快照（四元组+seq+V1.1 预留位）", async () => {
+    await loadSdk([["init", { siteId: "site-wire", endpoint: "/e", flushMs: 60000 }]]);
+    g.ctk!("flush");
+
+    const bodies = bodiesOf("site-wire");
+    expect(bodies).toHaveLength(1); // 两事件同归属四元组 → 单组子批
+    const evs = bodies[0].events;
+    expect(evs.map((e: { event_name: string }) => e.event_name)).toEqual(["page_view", "sdk_loaded"]);
+    for (const e of evs as Record<string, unknown>[]) {
+      expect(e.site_id).toBe("site-wire");
+      expect(e.visitor_id).toMatch(UUID_RE);
+      expect(e.session_id).toMatch(UUID_RE);
+      expect(e.page_id).toMatch(UUID_RE);
+      expect(typeof e.seq).toBe("number");
+      expect(e.purpose).toBe(null); // V1.1 预留位从快照展开（非字面量）
+      expect(e.epoch).toBe(null);
+      expect(e.grant_ref).toBe(null);
+    }
+    expect(evs[0].seq).toBe(1); // 初始 page_view：段内首快照（startPageSession 内发）
+    expect(evs[1].seq).toBe(2); // sdk_loaded：归属取自同一 PageSession
+    expect(evs[0].page_id).toBe(evs[1].page_id); // 同段归属
+  });
+
   it("批次 context 含设备环境 + referrer_domain/utm/path（首触归因链路）", async () => {
     Object.defineProperty(document, "referrer", {
       value: "https://news.example/a",
@@ -139,9 +164,11 @@ describe("index 入口", () => {
     expect(bodies).toHaveLength(1);
     expect(bodies[0].visitor_id).toMatch(UUID_RE); // 内存降级身份仍可用
     expect(bodies[0].session_id).toMatch(UUID_RE);
+    // page_view 由 startPageSession 先发（seq=1），sdk_loaded 随后（seq=2）；
+    // 15s 的 stay 周期切分在同一 fake 时刻触发，但 flush 定时器注册更早（先发）
     expect(bodies[0].events.map((e: { event_name: string }) => e.event_name)).toEqual([
-      "sdk_loaded",
       "page_view",
+      "sdk_loaded",
     ]);
   });
 
@@ -197,19 +224,21 @@ describe("index 入口", () => {
     expect(g.ctk!.q).toBeUndefined(); // 桩（带 q）已被 dispatch 替换
     g.ctk!("flush");
     let bodies = bodiesOf("site-8");
-    expect(bodies).toHaveLength(1);
+    // T8 分组拆批：归属组（page_view+sdk_loaded 同四元组）+ 兜底组（track 宿主
+    // 对象无归属顶层字段，信封走 identity 旧路径）——一次 flush 两个子批
+    expect(bodies).toHaveLength(2);
     expect(bodies[0].events.map((e: { event_name: string }) => e.event_name)).toEqual([
-      "sdk_loaded",
       "page_view",
-      "cta_click",
+      "sdk_loaded",
     ]);
-    expect(bodies[0].events[2].properties).toEqual({ k: 1 });
+    expect(bodies[1].events.map((e: { event_name: string }) => e.event_name)).toEqual(["cta_click"]);
+    expect(bodies[1].events[0].properties).toEqual({ k: 1 });
 
     // 重放结束后宿主新调用直接进 dispatch（不再排队丢失）
     g.ctk!("track", { ...trackEv, event_id: "e-2", event_name: "cta_click2" });
     g.ctk!("flush");
     bodies = bodiesOf("site-8");
-    expect(bodies).toHaveLength(2);
+    expect(bodies).toHaveLength(3);
-    expect(bodies[1].events.map((e: { event_name: string }) => e.event_name)).toEqual(["cta_click2"]);
+    expect(bodies[2].events.map((e: { event_name: string }) => e.event_name)).toEqual(["cta_click2"]);
   });
 });