2026-09-18 09:39:43 +08:00
# 采集底座修复（阶段A）实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 修复采集底座——事件级归属快照（消灭孤立停留）、区间制停留（单调时钟/15s 结算）、版本可诊断、URL 清洗三轨制，SDK 0.1.0→0.2.0 + 服务端 schema v2 兼容 v1。
**Architecture:** SDK 引入 PageSession 上下文（事件入队时冻结 site/visitor/session/page 四元组，flush 用快照拆子批）；停留改 performance.now 区间制；服务端按事件级归属落库、stay_ms 重算式回写（区间并集）、清洗升级三轨制（参数名黑名单 + 归因白名单 + 值判别），TS/Python 共享单源测试向量。
**Tech Stack:** sdk/ = TypeScript + vitest + esbuild（ ，
**Spec:** docs/superpowers/specs/2026-09-18-collection-foundation-phase-a-design.md（含全部决策与边界）
**执行顺序约束：** T1-T4（
**测试命令：** server 在 `server/` 下 `python -m pytest tracker/tests/ -x -q` （142 个基线，随任务递增）；sdk 在 `sdk/` 下 `npx vitest run` （
**红线（沿袭 spec §4.5）：** SDK 任何回调异常不得冒泡到宿主页；服务端 ingest 失败不得丢整批（savepoint 隔离既有模式）。
---
### Task 1: 清洗三轨制 + 共享测试向量（server）
**Files:**
- Create: `server/tracker/tests/fixtures/sanitize_vectors.json`
- Modify: `server/tracker/constants.py` （新增三轨制常量与规则版本）
- Modify: `server/tracker/services/validation.py:19-24` （
- Test: `server/tracker/tests/test_validation.py` （新增向量驱动的测试）
- [ ] **Step 1: 写共享测试向量 fixtures**
`server/tracker/tests/fixtures/sanitize_vectors.json` （单源文件，SDK T9 复用同一份）：
```json
{
"rule_version" : "v2" ,
"vectors" : [
{ "in" : "/product?id=456" , "out" : "/product?id=456" },
{ "in" : "/product?id=456&email=a@b.com" , "out" : "/product?id=456" },
{ "in" : "/page?phone=13800138000" , "out" : "/page" },
{ "in" : "/lp?utm_source=meta&utm_campaign=x" , "out" : "/lp?utm_source=meta&utm_campaign=x" },
{ "in" : "/lp?gclid=EAIaIQ&fbclid=IwAR2x" , "out" : "/lp?gclid=EAIaIQ&fbclid=IwAR2x" },
{ "in" : "/p?token=abcdef0123456789abcdef0123456789x" , "out" : "/p" },
{ "in" : "/p?ref=abcdefghijklmnopqrstuvwxyz012345" , "out" : "/p" },
2026-09-18 09:50:13 +08:00
{ "in" : "/p?slug=abcdefghijklmnopqrstuvwxyz0123456" , "out" : "/p" },
2026-09-18 09:39:43 +08:00
{ "in" : "/p?cat=sedans&sort=price" , "out" : "/p?cat=sedans&sort=price" },
{ "in" : "/p?q=%E5%BC%A0%E4%B8%89%E7%9A%84%E9%82%AE%E7%AE%B1a%40b.com" , "out" : "/p" },
{ "in" : "/a/b?name=zhangsan" , "out" : "/a/b" },
{ "in" : "/view?v=abc123DEF-_456" , "out" : "/view?v=abc123DEF-_456" },
{ "in" : "/long?v=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" , "out" : "/long" },
{ "in" : "https://user:pass@example.com/p?x=1&email=c@d.com#frag" , "out" : "https://example.com/p?x=1" }
]
}
```
2026-09-18 09:50:13 +08:00
（执行者注意：vectors 覆盖四类——业务参数保留、黑名单参数删、值判别删（@/长随机/超长 ）、userinfo+fragment 清理。`x=1` 值"1"是短数字→保留。**slug 安全线定 32**： `ref=abcdefghijklmnopqrstuvwxyz012345` （32 连续字母数字）按随机 token 删——真实业务 slug 含 `._-` 分隔或更短，32+ 连续字母数字视为 token（ `slug=` 向量钉死语义。）
2026-09-18 09:39:43 +08:00
- [ ] **Step 2: 写失败测试（向量驱动）**
`server/tracker/tests/test_validation.py` 追加：
```python
import json , pathlib
2026-09-18 09:50:13 +08:00
from tracker import constants as C
2026-09-18 09:39:43 +08:00
VECTORS = json . loads (( pathlib . Path ( __file__ ) . parent / "fixtures" / "sanitize_vectors.json" ) . read_text ( encoding = "utf-8" ))
def test_sanitize_url_vectors ():
for v in VECTORS [ "vectors" ]:
assert sanitize_url ( v [ "in" ]) == v [ "out" ], v [ "in" ]
def test_sanitize_rule_version_exported ():
assert C . SANITIZE_RULE_VERSION == VECTORS [ "rule_version" ]
```
- [ ] **Step 3: 跑测试确认失败**
Run: `cd server && python -m pytest tracker/tests/test_validation.py -x -q`
Expected: FAIL（ `SANITIZE_RULE_VERSION` 不存在 / userinfo 未剥离）
- [ ] **Step 4: 实现——constants.py 追加**
```python
SANITIZE_RULE_VERSION = "v2"
2026-09-18 09:55:29 +08:00
# 三轨制（spec §2.4，slug 安全线以本计划为准=32）：①参数名黑名单整键删；
# ②归因白名单提取保留；③其余按值判别：纯数字≤10位或 slug≤32 保留，其余删。
2026-09-18 09:39:43 +08:00
URL_PARAM_DROP_PATTERNS = ( "email" , "phone" , "mobile" , "tel" , "name" , "user" ,
"token" , "key" , "password" , "verif" , "passwd" , "idcard" )
ATTRIBUTION_PARAM_WHITELIST = { "gclid" , "gbraid" , "wbraid" , "fbclid" , "msclkid" ,
"yclid" , "gad_source" , "gad_campaignid" , "dclid" }
2026-09-18 09:50:13 +08:00
_SAFE_VALUE = re . compile ( r "^(?:\d{1,10}|[A-Za-z0-9][A-Za-z0-9._-]{0,30})$" ) # slug≤32：
2026-09-18 09:39:43 +08:00
```
（ `import re` 。）
- [ ] **Step 5: 实现——validation.py 的 sanitize_url 重写**
```python
def sanitize_url ( url : str ) -> str :
"""三轨制清洗（spec §2.4）：黑名单参数名删 + 归因白名单提 + 其余按值判别。
另：userinfo 剥离、fragment 删除。规则版本 SANITIZE_RULE_VERSION。"""
p = urlparse ( url )
kept = []
for k , v in parse_qsl ( p . query , keep_blank_values = True ):
if _URL_DROP_KEY . fullmatch ( k ):
continue
if k . lower () in C . ATTRIBUTION_PARAM_WHITELIST or k . lower () . startswith ( "utm_" ):
kept . append (( k , v )); continue
if C . _SAFE_VALUE . match ( v or "" ):
kept . append (( k , v ))
netloc = p . hostname or ""
if p . port : netloc = f " { netloc } : { p . port } "
return p . _replace ( netloc = netloc , query = urlencode ( kept ), fragment = "" ) . geturl ()
```
（注意 `_URL_DROP_KEY` 正则要重建以覆盖新黑名单——它在模块头 join constants。）
- [ ] **Step 6: 跑测试通过 + 全量回归**
Run: `python -m pytest tracker/tests/ -q`
Expected: 全 PASS（既有 sanitize 测试如断言旧行为需同步更新——保持语义：黑名单参数仍删）
- [ ] **Step 7: Commit**
```bash
git add server/tracker/constants.py server/tracker/services/validation.py server/tracker/tests/
git commit -m "feat(server): URL清洗三轨制+共享测试向量（D08）"
```
---
### Task 2: 契约扩展 + 模型迁移
**Files:**
- Modify: `server/tracker/constants.py:1,13-17` （白名单）
- Modify: `server/tracker/models.py` （
- Create: migration（ `python manage.py makemigrations tracker` ）
- Test: `server/tracker/tests/test_models.py`
- [ ] **Step 1: constants.py 契约更新**
```python
EVENT_NAMES = { "page_view" , "page_stay" , "sdk_loaded" , "session_resume" }
EVENT_PROP_WHITELIST = {
"page_view" : { "referrer" , "referrer_domain" , "utm" , "nav_type" , "prerendering" },
"page_stay" : { "active_ms" , "path" , "active_from" , "active_to" , "flush_reason" , "measurement_version" },
"sdk_loaded" : { "sdk_version" , "build_id" , "schema_version" , "config_version" },
"session_resume" : { "prev_session_id" , "reason" },
}
SCHEMA_VERSION = 2 # 批级信缺省 = v1（旧SDK）
```
- [ ] **Step 2: 写失败测试（test_models.py 追加字段存在性+约束）**
```python
def test_event_has_phase_a_fields ():
e = Event ( ** _base_event_kwargs (), page_id = "p1" , active_from_ms = 0 ,
active_to_ms = 15000 , flush_reason = "periodic" ,
time_quality = "ok" , sdk_version = "0.2.0" , schema_version = 2 )
e . full_clean () # 验证字段与长度约束
def test_visit_session_resume_of_self_fk ():
assert VisitSession . _meta . get_field ( "resume_of" ) . related_model is VisitSession
```
- [ ] **Step 3: 跑失败 → makemigrations 前先加模型字段**
models.py：
```python
page_id = models . CharField ( max_length = 64 , blank = True , default = "" , db_index = True )
active_from_ms = models . BigIntegerField ( null = True , blank = True )
active_to_ms = models . BigIntegerField ( null = True , blank = True )
flush_reason = models . CharField ( max_length = 16 , blank = True , default = "" )
time_quality = models . CharField ( max_length = 16 , blank = True , default = "" )
sdk_version = models . CharField ( max_length = 16 , blank = True , default = "" )
schema_version = models . PositiveSmallIntegerField ( null = True , blank = True )
```
VisitSession 追加 `resume_of = models.ForeignKey("self", null=True, blank=True, on_delete=models.SET_NULL, related_name="resumes")` ； `request_id = models.CharField(max_length=64, blank=True, default="")` 。
- [ ] **Step 4: `python manage.py makemigrations tracker && python manage.py migrate`（测试库自动建）**
- [ ] **Step 5: 全量回归 + Commit**
```bash
git add server/tracker/constants.py server/tracker/models.py server/tracker/migrations/
git commit -m "feat(server): schema v2契约——session_resume白名单/Event归属与区间字段/会话resume_of/request_id"
```
---
### Task 3: ingest v2 路径 + 响应契约
**Files:**
- Modify: `server/tracker/services/ingest.py` （核心改造）
- Modify: `server/tracker/services/validation.py:67+` （
- Modify: `server/tracker/api/collect.py:44-79` （
- Test: `server/tracker/tests/test_ingest.py` 、`test_collect.py`
- [ ] **Step 1: 写失败测试（v2 归属，test_ingest.py 追加）**
```python
def _v2_event ( name , page_id , sid , seq = 1 , ** props ):
return { "event_id" : f "e- { name } - { seq } " , "event_name" : name ,
"occurred_at" : _now_iso (), "path" : "/p" , "title" : "t" ,
"site_id" : SITE_ID , "visitor_id" : "v1" , "session_id" : sid ,
"page_id" : page_id , "seq" : seq , "properties" : props }
def test_v2_event_level_attribution ():
# 同批两个 session_id 的事件 → 各自落库到正确会话（v1 信封 session_id 不再唯一依据）
...
def test_session_resume_creates_linked_session ():
# resume 事件 → 新 VisitSession， ；
...
def test_stay_interval_union_not_sum ():
# 同 page_id 三条 page_stay 区间 [0,15][15,30][40,55]（第三条与1、2重叠边界）
# → VisitSession.stay_ms == 45000（并集），不是 sum=60000 也不是 sum-active_ms
...
def test_v1_events_unchanged_path ():
# 无 page_id 的 v1 批 → 走现有路径，stay_ms 仍为 active_ms 加法（混合解释基线）
...
def test_time_quality_classification ():
# occurred_at 未来 5s → "ok"；
...
```
- [ ] **Step 2: 跑失败**
- [ ] **Step 3: 实现 ingest_batch 改造** （关键逻辑，伪码展开级）
```
ingest_batch(site, payload, ip, ua):
v2 = payload.get("schema_version") == 2
... 现有 visitor touch / 首触逻辑不变 ...
for ev in events:
reason = validate_event(ev, v2=v2) # v2 时校验事件级四元组与 page_id uuid
... 拒绝/同批去重逻辑不变 ...
# 归属解析：
if v2: sid, vid = ev["session_id"], ev["visitor_id"]
（ ）
if ev.event_name == "session_resume":
prev = props.prev_session_id
sess = _get_or_create_session(...新 sid...)
sess.resume_of = VisitSession.filter(prev).first() or None（软处理+计数）
else: sess = _get_session(...)（同现有）
else: sid = payload["session_id"]（现有路径不动）
Event(..., page_id=ev.get("page_id",""), active_from_ms=..., active_to_ms=...,
flush_reason=..., time_quality=分类(now-occ),
sdk_version=payload.get("sdk_version","")[:16], schema_version=2 if v2 else None)
# stay 聚合（v2）：对 ready 中每个受影响 session：
# intervals = [(e.active_from_ms, e.active_to_ms) for e in new_events
# if e.event_name=="page_stay" and e.page_id] # v2 区间
# v1_add = sum(active_ms for v1 page_stay in session 内 DB 已有？No——)
# 简化重算：stay_total = Session 内全部 page_stay 的 v1 加法部分（DB 已有 stay_ms_v1
# 无法区分）→ 方案：VisitSession.stay_ms = DB.stay_ms 不再增量，改由
# _recompute_session_stay(session) 全量重算：v1 事件 SUM(active_ms) + v2 事件区间并集。
# （量级安全：单会话事件 <几百；每次入库重算一次受影响会话）
def _recompute_session_stay(sess):
stays = Event.objects.filter(session=sess, event_name="page_stay")
total = sum(p.get("active_ms",0) or 0 for e in stays.filter(page_id="")
for p in [e.properties])
by_page = defaultdict(list)
for e in stays.exclude(page_id=""):
by_page[e.page_id].append((e.active_from_ms, e.active_to_ms))
for ivs in by_page.values():
total += _union_ms(ivs) # 排序合并区间
VisitSession.objects.filter(pk=sess.pk).update(stay_ms=total)
```
（执行者注意：`_union_ms` = 经典排序合并；`duration_ms` /`event_count` /`ended_at` 沿用现有 F 增量逻辑不变——只有 stay_ms 改重算。v1 路径的 stay_ms 也统一走重算（v1 事件 SUM 语义与原逻辑等价，代码单一路径）。）
- [ ] **Step 4: 实现 collect.py 改造**
- `post()` 开头 `request_id = uuid4().hex[:32]` ； `_save_raw_batch(..., request_id)` 落库；响应改为：
```python
return Response ({ "code" : 200 , "data" : { "accepted" : r [ "accepted" ], "duplicated" : r [ "duplicated" ],
"rejected" : r [ "rejected" ], "request_id" : request_id , "server_time" : timezone . now () . isoformat ()},
"message" : "ok" })
```
- collect 级拒绝（invalid_payload 等）响应同样带 request_id。
- [ ] **Step 5: test_collect.py 追加响应契约测试（rejected 明细回传、request_id 存在）→ 全量回归**
- [ ] **Step 6: Commit**
```bash
git add server/tracker/
git commit -m "feat(server): ingest v2事件级归属+session_resume+stay区间并集重算+响应明细契约"
```
---
### Task 4: 聚合点核查适配 + server 收尾回归
**Files:**
- 核查（按需修改）: `server/tracker/api/dashboard.py:45-51` 、`server/tracker/api/visitors.py:54,88,106`
- Test: `server/tracker/tests/test_dashboard.py` 、`test_visitors.py`
- [ ] **Step 1: 核查三处聚合的取数来源**
- 若读 `VisitSession.stay_ms` / `Visitor.total_stay_ms` （
- 若任何一处直接 `SUM(Event.properties.active_ms)` → 改为读 VisitSession.stay_ms 或并集逻辑。
- 访客详情时间线（visitors.py）若按事件列表展示 → page_stay 多条增量正常显示（区间展示阶段B优化），仅确认不崩。
- [ ] **Step 2: 追加回归测试** ：构造 v1+v2 混合会话数据，断言 dashboard avg_stay / visitors total_stay 数值正确（v1 加法 + v2 并集相加）。
- [ ] **Step 3: server 全量回归（基线 142 + 新增全部通过）**
Run: `cd server && python -m pytest tracker/tests/ -q`
Expected: 0 failed
- [ ] **Step 4: Commit**
```bash
git add server/tracker/
git commit -m "test(server): v1/v2混合停留聚合回归+聚合点核查适配"
```
---
### Task 5: SDK 版本注入 + 事件归属骨架
**Files:**
- Modify: `sdk/package.json` （ ）
- Modify: `sdk/build.mjs` （
2026-09-18 09:50:13 +08:00
- Modify: `sdk/vitest.config.ts` （ `__BUILD_ID__` 在 dispatch 的静默 catch 里 ReferenceError，
- Create: `sdk/src/types.ts` （归属快照类型 + `__BUILD_ID__` ambient 声明）
2026-09-18 09:39:43 +08:00
- Test: `sdk/test/index.test.ts` 适配
- [ ] **Step 1: types.ts（新建）**
```ts
/** 事件归属四元组：入队时冻结，flush 不再重读（spec §1.1）
export interface Attribution {
site_id : string ;
visitor_id : string ;
session_id : string ;
page_id : string ;
seq : number ;
purpose? : null ; // V1.1 预留
epoch? : null ; // V1.1 预留
grant_ref? : null ; // V1.1 预留
}
export const SDK_VERSION = "0.2.0" ; // 与 package.json 同步手维护
export const SCHEMA_VERSION = 2 ;
export const CONFIG_VERSION = "1" ;
2026-09-18 09:50:13 +08:00
/** build_id 由 esbuild/vitest define 注入的全局常量（ambient 声明，
不能用模块级 export declare——esbuild 打包时会被擦除导致引用悬空） */
declare global {
// eslint-disable-next-line no-var
var __BUILD_ID__ : string | undefined ;
}
/** 运行时兜底读取（build 注入缺失时降级 "unknown"，绝不抛） */
export const BUILD_ID : string = globalThis . __BUILD_ID__ ?? "unknown" ;
2026-09-18 09:39:43 +08:00
```
- [ ] **Step 2: build.mjs 注入**
```js
import { execSync } from "node:child_process" ;
const buildId = execSync ( "git log -1 --format=%h-%cd --date=format:%Y%m%d%H%M" ). toString (). trim ();
await build ({ entryPoints : [ "src/index.ts" ], bundle : true , minify : true , format : "iife" ,
outfile : "dist/v1.js" , target : [ "es2020" ],
2026-09-18 09:55:29 +08:00
// define 键必须用点链：esbuild 只做精确表达式匹配，裸键 __BUILD_ID__
// 不会替换 globalThis.__BUILD_ID__ 成员访问（实测 0.24.2），build_id 将恒为 "unknown"
define : { "globalThis.__BUILD_ID__" : JSON . stringify ( buildId ) } });
2026-09-18 09:39:43 +08:00
```
（ ： `"dev-" + Date.now()` ，try/catch 包裹——构建环境无 git 不得挂。）
2026-09-18 09:55:29 +08:00
vitest.config.ts 同步注入（键同样用点链）：
2026-09-18 09:50:13 +08:00
```ts
export default defineConfig ({
2026-09-18 09:55:29 +08:00
define : { "globalThis.__BUILD_ID__" : JSON . stringify ( "vitest" ) },
2026-09-18 09:50:13 +08:00
test : { environment : "happy-dom" },
});
```
2026-09-18 09:39:43 +08:00
- [ ] **Step 3: 失败测试 → 实现 sdk_loaded 携带版本组 → 全量跑过 → Commit**
```bash
git add sdk/package.json sdk/build.mjs sdk/src/types.ts sdk/test/
git commit -m "feat(sdk): 版本注入与事件归属骨架（0.2.0/build_id/schema_version）
```
---
### Task 6: PageSession 模块（归属冻结核心）
**Files:**
- Create: `sdk/src/page.ts`
- Test: `sdk/test/page.test.ts` （新建，fake timers）
- [ ] **Step 1: 失败测试（核心用例清单）**
```ts
// vitest vi.useFakeTimers + vi.setSystemTime 模拟
test ( "事件入队时冻结归属：flush 延迟且期间会话超时，事件仍带旧 session_id" )
test ( "会话恢复：空闲>30min 后交互 → session_resume 事件（prev_session_id/reason） )
test ( "恢复检查点三处：交互时 / visibilitychange visible 时 / flush 前" )
test ( "bfcache： ， )
test ( "SPA pushState path 变化 → 新 page_id + 新 page_view； )
test ( "seq 页内单调递增；hidden 期间不推进活动判定" )
```
- [ ] **Step 2: 实现 page.ts（结构）**
```ts
export class PageSession {
readonly pageId : string ;
private sessionId : string ; // 入队快照用；resume 时换新
private seqCounter = 0 ;
private lastActivity : number ; // performance.now 基准
// API:
attribution () : Attribution // {site,visitor,session:sessionId,page:pageId,seq:++seqCounter}
touch () : void // 活动刷新 + 空闲超时检查（>30min → resume 流程）
maybeResume () : void // visible/flush 前检查点
close () : void // 结算尾部停留（由 stay.ts 回调协作）
}
// 模块级单例 current + startPageSession()/SPA hook 安装
// history.pushState/replaceState/popstate hook：规范化 path（ ）
// 变化 → current.close() → 新 PageSession → 发 page_view
// pageshow persisted → current 复活标记（不新建）
```
（ `touchActivity` 语义并入 PageSession.touch。）
- [ ] **Step 3: 跑过 → Commit** `feat(sdk): PageSession事件级归属冻结+会话恢复+bfcache+SPA切段`
---
### Task 7: stay.ts 区间制重做
**Files:**
- Create: `sdk/src/stay.ts`
- Modify: `sdk/src/events.ts` （ ）
- Test: `sdk/test/stay.test.ts` （新建）
- [ ] **Step 1: 失败测试（fake timers + fake performance.now）
```ts
test ( "15s 连续活动切 4 条相邻区间，各自 [from,to] 不重叠" )
test ( "hidden 结算当前区间；pagehide 紧随不重发（共享结算状态）" )
test ( "hidden 期间不累计；恢复 visible 后活动从恢复点开新区间" )
test ( "单调时钟：vi.spyOn(performance,'now') 推进，系统墙钟回拨不影响区间长度" )
test ( "flush_reason 正确：periodic/hidden/pagehide/route_change" )
test ( "入队事件携带 active_from/active_to/active_ms/page_id/measurement_version=2" )
```
- [ ] **Step 2: 实现（核心算法）**
```
区间状态: intervalStart | null（活动有效时非 null）
tick(1s): 若 可见 && now-lastAct<30s: 若 !intervalStart → intervalStart=now-1000
（宽限对齐现有语义：沿用"可见+30s 交互"判定，measurement_version 标记）
cut(reason): 若 intervalStart: emit page_stay{active_from: epochMs(intervalStart),
active_to: epochMs(now), active_ms: now-intervalStart, flush_reason: reason,
measurement_version: "2", ...pageSession.attribution()}; intervalStart=null
setInterval(stayIntervalMs=15000): cut("periodic")
visibilitychange hidden / pagehide: cut(reason) 幂等（intervalStart==null 则 no-op）
epochMs(perfNow): 页面加载墙钟 Date.now() - performance.timeOrigin + perfNow（展示时间）
```
- [ ] **Step 3: 跑过 → Commit** `feat(sdk): 停留改单调时钟区间制——15s切分/共享结算/幂等`
---
### Task 8: transport 重构（快照信封/拆子批/预算/响应）
**Files:**
- Modify: `sdk/src/transport.ts`
- Test: `sdk/test/transport.test.ts` （扩展）
- [ ] **Step 1: 失败测试**
```ts
test ( "flush 从队首事件快照取归属，不调用 getSessionId（ )
test ( "混合归属队列拆子批：两组 (session,page) → 两次独立请求体各含正确信封" )
test ( "子批独立重试：组A 500 失败重试，组B 200 不重试" )
test ( "beacon 超 60KB → 降级 fetch keepalive；再失败丢最旧计 dropped" )
test ( "响应解析：rejected 明细累计进 counts； )
test ( "v1 兼容形态不再产生（新 SDK 恒 schema_version:2 信封 + 事件级归属）" )
```
- [ ] **Step 2: 实现要点**
- `flush()` ：取 `q` 分组 `groupEvents(events)` （ `${visitor}:${session}:${page}` ，组内保持顺序）→ 每组构造 body `{batch_id, site_id, schema_version:2, sdk_version, build_id, visitor_id, session_id, sent_at, context, events}` （信封归属=组首事件快照）→ `send()` /beacon。
- beacon 路径：`new Blob([body]).size > 60_000` → 改 `fetch keepalive` 。
- send 成功：`await res.json().catch(()=>null)` → `counts.rejected += data.rejected.length` 等；记录 `lastServerTime` 。
- [ ] **Step 3: 跑过 → Commit** `feat(sdk): 传输快照信封+混合拆批+beacon预算+响应计数`
---
### Task 9: SDK 侧 sanitizeUrl 三轨制对齐（共享向量）
**Files:**
- Modify: `sdk/src/context.ts:1-58` （
2026-09-18 09:50:13 +08:00
- Modify: `sdk/tsconfig.json` （ `resolveJsonModule: true` ——跨树 JSON import 的 typecheck 支持）
2026-09-18 09:39:43 +08:00
- Test: `sdk/test/context.test.ts` （追加向量测试）
- [ ] **Step 1: 失败测试（读 server 的同一份 fixtures）
```ts
import vectors from "../../server/tracker/tests/fixtures/sanitize_vectors.json" ;
2026-09-18 09:55:29 +08:00
test . each ( vectors . vectors )( "sanitizeUrl vector" , ( v ) => {
2026-09-18 09:50:13 +08:00
expect ( sanitizeUrl ( v . in )). toBe ( v . out );
2026-09-18 09:39:43 +08:00
});
```
2026-09-18 09:50:13 +08:00
（ `in` 是保留字不能作解构绑定名——用整对象参数 `v` 。vitest/vite 原生支持 JSON import 且无 root 限制（已核 vitest.config.ts），跨出 sdk/ 的相对路径可解析。）
2026-09-18 09:39:43 +08:00
- [ ] **Step 2: TS 实现与服务端规则逐条对齐** （黑名单 fullmatch、归因白名单+utm_ 前缀、`_SAFE_VALUE` 同正则、userinfo/fragment 清理——TS 用 `new URL()` 处理 userinfo，注意相对路径 input 时 URL 不可用 → 沿用字符串切分法与 Python urlparse 行为对齐）
- [ ] **Step 3: 跑过（含 server 侧同步再跑一遍防漂移）→ Commit** `feat(sdk): 入队前清洗三轨制对齐服务端（共享向量）`
---
### Task 10: index.ts 接线 + SDK 全量回归 + 构建
**Files:**
- Modify: `sdk/src/index.ts` （
- [ ] **Step 1: 接线** ： `startPageSession()` （创建 PageSession、安装 SPA hook、pageshow 监听）→ `startStayTracking(transport, pageSession)` → page_view 携带 attribution → sdk_loaded `{sdk_version, build_id, schema_version, config_version}` 。
- [ ] **Step 2: 全量测试** ： `cd sdk && npx vitest run` （基线 58 + 新增全过；旧断言按新结构更新——归属字段进事件体、信封拆组）
- [ ] **Step 3: 构建** ： `npm run build` （ `dist/v1.js` 生成 + gzip 体积记录（目标 <4KB gzip）
- [ ] **Step 4: Commit** `feat(sdk): 0.2.0接线——归属快照/区间停留/清洗对齐/响应契约全链路`
---
### Task 11: server 部署 + v1 线上回归
- [ ] **Step 1: 本地全量测试最后一遍 + 打包** ： `cd server && python -m pytest tracker/tests/ -q`
- [ ] **Step 2: 部署** （标准流程，tar server → scp 经跳板 → 解压 /opt/cms-cj 原地覆盖 → `cd deploy && docker compose up -d --build web` （自动 migrate）→ 容器状态 + API 探活）
- [ ] **Step 3: v1 线上回归** ：
- [ ] **Step 4: 汇报** ：容器状态、migrate 输出、回归结果
### Task 12: SDK 部署 + 生产验证 + 验收台账
- [ ] **Step 1: 部署 sdk/dist** ：tar → scp 经跳板 → 解压覆盖 `/opt/cms-cj/sdk/dist` （ `docker inspect tracker-nginx` 复核 Mounts）
- [ ] **Step 2: v2 上线验证** ：
- [ ] **Step 3: 48h 观察指标** （D02 复现指标）：孤立 page_stay 会话（同 session 只有 page_stay 无 page_view）占比 → 应为 0；事件量增幅记录；RawBatch status 分布
- [ ] **Step 4: 写台账** `docs/验收记录-阶段A.md` ：
- [ ] **Step 5: Commit 台账 + 汇报** ：部署版本（build_id）、验证结果、遗留项（阶段B 清单）
---
## 风险提示（执行者必读）
2026-09-18 09:50:13 +08:00
1. **勿动归属之外的既有不变量** ：ingest.py 头注释五条并发不变量中 ①②④⑤ 全保留，③ 的 F 表达式模式保留——唯 stay_ms 字段按风险项 2 改重算（其余字段 duration_ms/event_count/ended_at 仍 F 增量）。
2. **stay_ms 重算是唯一聚合改动** ： `page_id` 非空但 `active_from_ms/active_to_ms` 为 null 的脏数据 filter 防御（validate_event v2 分支强制区间完整，双保险）。
3. **SDK 红线** ：任何回调异常静默（spec §4.5）；PageSession/SPA hook 全部 try/catch 包裹。BUILD_ID 经 `globalThis.__BUILD_ID__ ?? "unknown"` 兜底——define 缺失（vitest/异常构建环境）不得炸。
2026-09-18 09:39:43 +08:00
4. **测试向量是契约** ：
5. 生产部署顺序：server 先（T11）验证 v1 无回归后才发 SDK（T12）；SDK 回滚只需还原 sdk/dist，服务端不动。
2026-09-18 09:50:13 +08:00
6. **测试 helper 均为新建** ： `_base_event_kwargs` /`_now_iso` /`SITE_ID` 等在 server tests 中不存在——执行者创建它们而非寻找。Task 1 Step 6 点名更新既有测试 `test_pageview_referrer_truncated_after_reencode` （ `q` 值不再匹配 _SAFE_VALUE，改用超长 utm 值驱动同一路径）。
