dsh-heatmap 0.1.0

package/src/shared/types.ts

@@ -0,0 +1,103 @@
+/**
+ * 埋点事件契约（host 与 client 共用同一份，保证采集端与收集端字段一致）。
+ *
+ * 设计原则（科学的埋点体系）：
+ * - schema 带版本号 `v`，后续字段演进可平滑迁移；
+ * - 每条事件都有稳定 `id` / `sessionId` / `ts`，可做漏斗与会话回放；
+ * - 只记录「元素身份 + 位置 + 时间 + 视口」，绝不采集输入内容或对话正文，
+ *   从根上满足隐私与合规（默认最小化采集）。
+ */
+
+export const SCHEMA_VERSION = 1
+
+/** 事件类型：覆盖页面生命周期、交互、滚动曝光、热力图坐标四类。 */
+export type EventType =
+  | 'session_start' // 会话开始（页面加载）
+  | 'session_end' // 会话结束（卸载/隐藏）
+  | 'page_view' // 路由/hash 变化
+  | 'click' // 按钮/可点击元素点击（含坐标，供热力图）
+  | 'focus' // 获得焦点
+  | 'blur' // 失去焦点
+  | 'hover' // 鼠标悬停坐标（节流，供热力图）
+  | 'scroll_depth' // 滚动深度（0..1）
+  | 'visibility' // 页签可见性变化（用于停留时长）
+  | 'input' // 输入框输入（仅记录长度，不记录内容）
+  | 'impression' // 元素曝光（面板/控件首次进入视口 ≥50%）
+
+/** 被操作元素的「身份指纹」，用于跨会话聚合到同一控件。 */
+export interface ElementRef {
+  tag: string
+  id?: string
+  role?: string
+  ariaLabel?: string
+  title?: string
+  testId?: string
+  /** 表单控件名（input/textarea/select 的 name 属性，不含内容）。 */
+  name?: string
+  /** 表单占位符（placeholder，不含用户输入内容）。 */
+  placeholder?: string
+  /** 截断后的可见文本（仅限 UI 控件文案，如按钮/链接，最长 40 字；输入类控件不采集）。 */
+  text?: string
+  /** 稳定的元素标识（优先 data-testid > id > aria-label > role+tag > placeholder/name > tag+text）。 */
+  elementId: string
+}
+
+/** 单条埋点事件。 */
+export interface AnalyticsEvent {
+  v: number
+  id: string
+  ts: number
+  sessionId: string
+  type: EventType
+  page: { path: string; hash: string }
+  target?: ElementRef
+  /** 视口内坐标（click / hover 供热力图）。 */
+  position?: { x: number; y: number }
+  /** 滚动深度 0..1（scroll_depth）。 */
+  depth?: number
+  /** 页签是否可见（visibility）。 */
+  visible?: boolean
+  /** 输入长度（input，仅数字，不含内容）。 */
+  inputLength?: number
+}
+
+/** 客户端上传给 host 收集器的一批事件。 */
+export interface AnalyticsBatch {
+  v: number
+  sessionId: string
+  sentAt: number
+  events: AnalyticsEvent[]
+}
+
+/** host 侧聚合统计结果。 */
+export interface StoreStats {
+  total: number
+  byType: Record<string, number>
+  sessions: number
+  clicks: number
+  focus: number
+  impressions: number
+  earliestTs?: number
+  latestTs?: number
+}
+
+/** 漏斗阶段：有序步骤的会话到达数与相对上一阶段的转化率。 */
+export interface FunnelStage {
+  step: string
+  sessions: number
+  conversion: number
+}
+
+/** 漏斗分析结果。 */
+export interface FunnelResult {
+  totalSessions: number
+  stages: FunnelStage[]
+}
+
+/** 单个会话的有序事件时间线（用于会话回放/复现）。 */
+export interface SessionTimeline {
+  sessionId: string
+  startTs?: number
+  endTs?: number
+  events: AnalyticsEvent[]
+}

package/src/store.ts

@@ -0,0 +1,146 @@
+/**
+ * host 侧埋点数据存储：内存环形缓冲 + NDJSON 落盘。
+ *
+ * NDJSON（一行一条 JSON）便于增量追加、流式读取，也能直接给后续统一分析
+ * 平台消费。内存缓冲用于快速聚合统计（stats / export），落盘用于持久化。
+ */
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import type { AnalyticsBatch, AnalyticsEvent, FunnelResult, SessionTimeline, StoreStats } from './shared/types.ts'
+
+export class AnalyticsStore {
+  private events: AnalyticsEvent[] = []
+  private readonly file: string
+  private readonly ready: Promise<void>
+  private readonly maxEvents: number
+
+  constructor(dataDir: string, maxEvents = 20000) {
+    this.maxEvents = maxEvents
+    this.file = resolve(dataDir, 'events.ndjson')
+    this.ready = this.init()
+  }
+
+  /** 数据文件绝对路径（供诊断/调试）。 */
+  get filePath(): string {
+    return this.file
+  }
+
+  private async init(): Promise<void> {
+    await mkdir(dirname(this.file), { recursive: true })
+    try {
+      const raw = await readFile(this.file, 'utf8')
+      this.events = raw
+        .split('\n')
+        .filter(line => line.trim() !== '')
+        .map(line => JSON.parse(line) as AnalyticsEvent)
+      if (this.events.length > this.maxEvents) {
+        this.events = this.events.slice(-this.maxEvents)
+      }
+    } catch {
+      this.events = []
+    }
+  }
+
+  /** 接收一批事件：追加进内存与文件，返回实际接收条数。 */
+  async ingest(batch: AnalyticsBatch): Promise<number> {
+    await this.ready
+    const accepted = Array.isArray(batch?.events) ? batch.events : []
+    if (accepted.length === 0) return 0
+    this.events.push(...accepted)
+    if (this.events.length > this.maxEvents) {
+      this.events = this.events.slice(-this.maxEvents)
+    }
+    const lines = accepted.map(e => JSON.stringify(e)).join('\n') + '\n'
+    await appendFile(this.file, lines, 'utf8')
+    return accepted.length
+  }
+
+  /** 导出事件（`limit <= 0` 表示全部）。 */
+  async list(limit = 0): Promise<AnalyticsEvent[]> {
+    await this.ready
+    if (limit > 0) return this.events.slice(-limit)
+    return this.events
+  }
+
+  /** 聚合统计。 */
+  async stats(): Promise<StoreStats> {
+    await this.ready
+    const byType: Record<string, number> = {}
+    const sessions = new Set<string>()
+    let clicks = 0
+    let focus = 0
+    let impressions = 0
+    let earliestTs: number | undefined
+    let latestTs: number | undefined
+    for (const e of this.events) {
+      byType[e.type] = (byType[e.type] ?? 0) + 1
+      sessions.add(e.sessionId)
+      if (e.type === 'click') clicks += 1
+      if (e.type === 'focus') focus += 1
+      if (e.type === 'impression') impressions += 1
+      if (earliestTs === undefined || e.ts < earliestTs) earliestTs = e.ts
+      if (latestTs === undefined || e.ts > latestTs) latestTs = e.ts
+    }
+    return { total: this.events.length, byType, sessions: sessions.size, clicks, focus, impressions, earliestTs, latestTs }
+  }
+
+  /** 按会话聚合的有序事件时间线（供回放/复现与漏斗分析共用）。 */
+  private async timelines(): Promise<Map<string, AnalyticsEvent[]>> {
+    await this.ready
+    const bySession = new Map<string, AnalyticsEvent[]>()
+    for (const e of this.events) {
+      const list = bySession.get(e.sessionId)
+      if (list === undefined) bySession.set(e.sessionId, [e])
+      else list.push(e)
+    }
+    for (const list of bySession.values()) list.sort((a, b) => a.ts - b.ts)
+    return bySession
+  }
+
+  /** 会话列表：每个会话的有序事件时间线。 */
+  async sessions(limit = 0): Promise<SessionTimeline[]> {
+    const bySession = await this.timelines()
+    const out: SessionTimeline[] = []
+    for (const [sessionId, events] of bySession) {
+      out.push({
+        sessionId,
+        startTs: events.length > 0 ? events[0].ts : undefined,
+        endTs: events.length > 0 ? events[events.length - 1].ts : undefined,
+        events,
+      })
+    }
+    out.sort((a, b) => (b.endTs ?? 0) - (a.endTs ?? 0))
+    return limit > 0 ? out.slice(0, limit) : out
+  }
+
+  /**
+   * 漏斗分析：给定有序事件类型步骤，统计有多少会话按顺序走到每一步，
+   * 并计算相邻步骤的转化率。
+   * @param steps - 有序事件类型（如 ['session_start', 'click', 'input']）。
+   */
+  async funnel(steps: string[]): Promise<FunnelResult> {
+    const bySession = await this.timelines()
+    const valid = (steps ?? []).filter((s): s is string => typeof s === 'string' && s !== '')
+    const counts = new Array<number>(valid.length).fill(0)
+    for (const events of bySession.values()) {
+      let stepIdx = 0
+      for (const e of events) {
+        if (stepIdx < valid.length && e.type === valid[stepIdx]) stepIdx += 1
+      }
+      for (let i = 0; i < stepIdx; i += 1) counts[i] += 1
+    }
+    const stages = valid.map((step, i) => ({
+      step,
+      sessions: counts[i],
+      conversion: i === 0 ? 1 : (counts[i - 1] > 0 ? counts[i] / counts[i - 1] : 0),
+    }))
+    return { totalSessions: bySession.size, stages }
+  }
+
+  /** 清空数据。 */
+  async clear(): Promise<void> {
+    await this.ready
+    this.events = []
+    await writeFile(this.file, '', 'utf8')
+  }
+}