docs: spec 评审修正(M1/M3 范围对齐、跨站串联口径、IPv6 截断等)

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
2026-09-15 09:54:56 +08:00
parent 3d013fd0b7
commit 53827a6aca
@@ -43,7 +43,7 @@
```
┌─────────────────────────────────────────────┐
│ 网站浏览器 │
│ JS SDK(自研 ~10KB,异步加载,绝不阻塞页面) │
│ JS SDK(自研 ≤15KB gzip,异步加载,不阻塞页面) │
└──────────────────┬──────────────────────────┘
│ HTTPS 批量 JSON 上报
▼
@@ -80,7 +80,7 @@ ctk('init', { siteId: 'site_xxx', endpoint: 'https://track.example.com' });
### 4.2 身份模型
- `visitor_id`:加密安全随机数,存 localStorage(第一方存储,不用 Cookie+localStorage 双恢复对抗用户清除)。
- `session_id`:30 分钟无活动切新会话;跨天访问 = 新会话、同一 visitor。
- `session_id`:30 分钟无活动切新会话;跨天访问 = 新会话、同一 visitor。会话权威在 SDK;服务端按同一 30 分钟规则做兜底校验(超长/跨天异常时切分修正),不产生第二套会话口径。
- 首次落地时保存**首触来源**(referrer + UTM + 落地页)到访客档案;每次会话各自记录来源。
### 4.3 事件清单
@@ -91,7 +91,7 @@ ctk('init', { siteId: 'site_xxx', endpoint: 'https://track.example.com' });
| `page_stay` | P0 | `active_ms` 有效停留:页面可见 + 有鼠标/键盘/滚动活动才累计;`visibilitychange` 停止;`sendBeacon` 兜底上报 |
| `scroll_depth` | P1 | 25/50/75/100% 四档 |
| `click` | P1 | 可配置范围(按钮/导航/外链/下载),`data-track-id` 优先标识 |
| `form_start` / `form_submit` | P1 | 表单标识、字段名清单、成功/失败;字段值**白名单制** |
| `form_start` / `form_submit` | P1 | 表单标识、字段名清单、成功/失败;字段值**白名单制**(白名单在后台按站点配置,SDK init 可覆盖) |
| `copy` / `download` / `print` | P1 | 意图事件:复制了邮箱/电话、下载报价单 PDF、打印页面 |
| `rage_click` / `dead_click` | P2 | 反复点无反应区域 |
| `first_interaction` | P1 | 进页面后首次互动耗时 |
@@ -171,7 +171,7 @@ contact(客户档案)── identity 关联表 ── visitor_id / 邮箱哈
| 来源 | referrer 域名、UTM、落地页、部分搜索词 |
| 设备环境 | 设备类型、OS/浏览器及版本、分辨率、语言、时区、触屏、硬件(可选)、Client Hints、网络质量、页面性能 |
| 网络地理(服务端) | IP(保留期限见 9.2)、国家/省/市(ip2region 离线库)、运营商、爬虫识别 |
| 跨站关联 | 同一访客在自有多个域名间串联(首方合法做法) |
| 跨站关联 | 自有域名间经站间跳转传 token 串联(M3,首方合法做法);或经客户识别后归并到同一档案 |
拿不到(诚实边界):匿名阶段真实身份(姓名/邮箱/电话);跨设备同一人(直到提交表单/登录/token 命中);清存储/无痕后重新开始(不对抗)。
@@ -213,7 +213,7 @@ SDK 端 + 服务端**双重拦截**:password/验证码/银行卡/身份证等
| 数据 | 保留期 |
|---|---|
| 原始事件(events 分区) | 180 天,分区清理 |
| 原始 IP | 180 天,到期后台任务截断为 /24 前缀;地理/运营商解析结果长期保留 |
| 原始 IP | 180 天,到期后台任务截断(IPv4 → /24,IPv6 → /64 前缀);地理/运营商解析结果长期保留 |
| 客户档案、标签、备注 | 长期(直至客户删除) |
| 审计日志 | 1 年 |
@@ -256,13 +256,13 @@ SDK 端 + 服务端**双重拦截**:password/验证码/银行卡/身份证等
- SDK 体积 ≤ 15KB(gzip),初始化不阻塞首屏;加载失败对网站零影响。
- 采集接口:日均 10 万事件内单 Django 实例 + MySQL 从容承载;监控接受率、去重率、拒绝原因分布。
- 准实时:事件从发生到后台可见 ≤ 60 秒(列表刷新即得,无长连接)。
- 部署:1Panel Docker Compose(Nginx + Django/uwsgi 或 gunicorn + 复用 MySQL 容器);.env 管理密钥;数据库迁移向前兼容。
- 部署:1Panel Docker Compose(Nginx + Django + gunicorn + 复用 MySQL 容器);.env 管理密钥;数据库迁移向前兼容。
- 备份:MySQL 自动备份 + 恢复演练(复用 1Panel 能力)。
## 13. 里程碑
### M1 · 最小闭环(端到端技术验证)
- SDK:接入两行代码、visitor/session 身份、page_view、page_stay、批量传输、幂等去重、UTM/referrer 首触记录、环境信息。
- SDK:接入两行代码、visitor/session 身份、page_view、page_stay、批量传输、幂等去重、UTM/referrer 首触记录、环境信息、sdk_loaded 诊断事件。
- 后端:采集 API(域名白名单/限流/黑名单校验)、核心表、会话化与日聚合任务。
- 后台:C1 登录权限、C2 总览、C3 访客列表、C4 访客/会话详情、C5 站点管理。
- **验收**:一个真实网站接入,后台能看到"某访客今天看了 3 页、每页停多久、昨天来过、首触来源是 Google"。
@@ -276,9 +276,12 @@ SDK 端 + 服务端**双重拦截**:password/验证码/银行卡/身份证等
### M3 · 增强与扩展
- rage/dead click、远程配置(采样/开关,ETag)、npm 包发布。
- 登录绑定 `identify(user_id)`(含服务端签名令牌机制)、同意管理模式完善(consent 分目的开关)。
- 服务端签名事件 API(订单/注册事实)、WordPress 连接器插件(注入 SDK + CF7/WPForms 钩子)。
- IP 企业反查(Leadfeeder 式 B2B 线索提示,可选付费库,只提示不自动合并)、邮箱后缀→公司名补全。
- 跨自有域名访客串联(站间跳转传 token)。
- 数据导出、事件字典、Redis 限流加固、(独立评估)会话回放。
- 上线门禁:跨境/隐私合规专项确认(按原方案文档第十二章执行)。
## 14. 风险与开放项