giime 1.1.5 → 1.1.6

package/lib/track/src/core/tracker.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @file 前端统一全埋点核心控制器 GiimeTracker
+ * @description 整合会话管理、浏览器环境指纹、内存攒批队列、L1/L2/L3 自动采集器与 8 大类标准业务埋点方法
+ */
+import type { BrowserContext, GiimeTrackConfig, TrackBatchListener, TrackEventListener, TrackEventName, TrackEventRecord } from '../types';
+import { TrackSessionManager } from './session';
+/** SDK 当前版本号 */
+export declare const GIIME_TRACK_SDK_VERSION = "1.0.0";
+/**
+ * 统一全埋点核心类
+ */
+export declare class GiimeTracker {
+    private config;
+    private customEndpoint?;
+    private sessionManager;
+    private batchQueue;
+    private cachedBrowserContext;
+    private collectorCleanups;
+    private initializedCollectors;
+    constructor(config?: GiimeTrackConfig);
+    /**
+     * 安装或重启所有自动采集器插件
+     */
+    installCollectors(): void;
+    /**
+     * 动态更新 SDK 配置
+     * @param nextConfig 新增或变更的配置项
+     */
+    updateConfig(nextConfig: Partial<GiimeTrackConfig>): void;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): GiimeTrackConfig;
+    /**
+     * 获取会话与页面上下文管理器
+     */
+    getSessionManager(): TrackSessionManager;
+    /**
+     * 获取实时更新视口尺寸后的浏览器与设备环境信息
+     */
+    getBrowserContext(): BrowserContext;
+    /**
+     * 核心事件上报入口：组装完整契约报文并推入批量队列
+     * @param eventName 事件名称（小驼峰标准事件名或商城存量事件名）
+     * @param payload 事件专属业务属性
+     * @param overrides 单次事件覆盖公共字段（如自定义 functionId / pageKey）
+     */
+    track<TPayload extends Record<string, any> = Record<string, any>>(eventName: TrackEventName, payload?: TPayload, overrides?: Partial<Pick<TrackEventRecord, 'functionId' | 'moduleId' | 'pageKey' | 'pageName' | 'source' | 'templateId'>>): TrackEventRecord<TPayload> | null;
+    /**
+     * 兼容上报商城 ShopPlus 存量 102 个埋点事件
+     * @param eventName 商城原始事件名
+     * @param options 商城原始扩展字段
+     * @param time 商城性能耗时（毫秒）
+     */
+    trackShopPlusLegacyEvent(eventName: string, options?: Record<string, any>, time?: number): TrackEventRecord | null;
+    /**
+     * SPA 路由切换通知（由 Vue3 / Vue2 路由钩子调用：先结清上一页 pageLeave，再开启新一页 pageEnter）
+     */
+    handleRouteChange(routeMeta: {
+        pageKey: string;
+        pageName: string;
+        functionId?: string;
+        url?: string;
+        entrySource?: string;
+    }): void;
+    /**
+     * 上报业务页面加载结果 (pageBizLoadResult)
+     */
+    trackPageBizLoadResult(params: {
+        loadId?: string;
+        status: 'success' | 'fail';
+        duration: number;
+        errorCode?: string;
+    }): TrackEventRecord<{
+        loadId: string;
+        status: "success" | "fail";
+        duration: number;
+        errorCode: string;
+    }> | null;
+    /**
+     * 上报查询提交与查询结果 (querySubmit / queryResult)
+     */
+    trackQuery(params: {
+        phase: 'submit' | 'result';
+        queryId?: string;
+        resourceType: string;
+        queryAction?: 'search' | 'filter' | 'sort' | 'paginate' | 'refresh';
+        filterKeys?: string[];
+        sortField?: string;
+        sortOrder?: 'asc' | 'desc';
+        pageNumber?: number;
+        pageSize?: number;
+        returnedCount?: number;
+        totalCount?: number;
+        status?: 'success' | 'fail' | 'cancel';
+        duration?: number;
+        errorCode?: string;
+    }): TrackEventRecord<{
+        queryId: string;
+        phase: 'submit' | 'result';
+        resourceType: string;
+        queryAction?: "sort" | "filter" | "search" | "refresh" | "paginate" | undefined;
+        filterKeys?: string[] | undefined;
+        sortField?: string | undefined;
+        sortOrder?: "desc" | "asc" | undefined;
+        pageNumber?: number | undefined;
+        pageSize?: number | undefined;
+        returnedCount?: number | undefined;
+        totalCount?: number | undefined;
+        status?: "cancel" | "success" | "fail" | undefined;
+        duration?: number | undefined;
+        errorCode?: string | undefined;
+    }> | null;
+    /**
+     * 上报资源维护操作提交或结果 (resourceOperateSubmit / resourceOperateResult)
+     */
+    trackResourceOperate(params: {
+        phase: 'submit' | 'result';
+        operationId?: string;
+        batchId?: string;
+        resourceType: string;
+        resourceId?: string;
+        resourceVersion?: string;
+        operationType: 'create' | 'update' | 'delete' | 'favorite' | 'publish' | string;
+        status?: 'success' | 'fail' | 'cancel';
+        duration?: number;
+        errorCode?: string;
+    }): TrackEventRecord<{
+        operationId: string;
+        phase: 'submit' | 'result';
+        batchId?: string | undefined;
+        resourceType: string;
+        resourceId?: string | undefined;
+        resourceVersion?: string | undefined;
+        operationType: 'create' | 'update' | 'delete' | 'favorite' | 'publish' | string;
+        status?: "cancel" | "success" | "fail" | undefined;
+        duration?: number | undefined;
+        errorCode?: string | undefined;
+    }> | null;
+    /**
+     * 上报任务操作提交或状态变化 (taskOperateSubmit / taskStatusChange)
+     */
+    trackTask(params: {
+        phase: 'submit' | 'statusChange';
+        operationId?: string;
+        operationType?: 'run' | 'cancel' | 'retry';
+        taskType: string;
+        taskId?: string;
+        relatedTaskId?: string;
+        resourceType?: string;
+        resourceId?: string;
+        resourceVersion?: string;
+        parameterKeys?: string[];
+        previousStatus?: string;
+        status?: 'queued' | 'running' | 'success' | 'fail' | 'cancelled' | string;
+        attemptNumber?: number;
+        queueDuration?: number;
+        executionDuration?: number;
+        errorCode?: string;
+    }): TrackEventRecord<{
+        operationId: string;
+        phase: 'submit' | 'statusChange';
+        operationType?: "cancel" | "run" | "retry" | undefined;
+        taskType: string;
+        taskId?: string | undefined;
+        relatedTaskId?: string | undefined;
+        resourceType?: string | undefined;
+        resourceId?: string | undefined;
+        resourceVersion?: string | undefined;
+        parameterKeys?: string[] | undefined;
+        previousStatus?: string | undefined;
+        status?: string | undefined;
+        attemptNumber?: number | undefined;
+        queueDuration?: number | undefined;
+        executionDuration?: number | undefined;
+        errorCode?: string | undefined;
+    }> | null;
+    /**
+     * 上报接口请求异常 (errorRequest)
+     */
+    trackErrorRequest(params: {
+        requestId?: string;
+        requestPath: string;
+        requestMethod: string;
+        statusCode?: number;
+        errorType: 'timeout' | 'network' | 'httpError' | 'bizError';
+        errorCode?: string;
+        duration?: number;
+    }): TrackEventRecord<{
+        requestId: string;
+        requestPath: string;
+        requestMethod: string;
+        statusCode: number | undefined;
+        errorType: "timeout" | "network" | "httpError" | "bizError";
+        errorCode: string;
+        duration: number;
+    }> | null;
+    /**
+     * 手动触发队列立即上报
+     */
+    flush(isUnload?: boolean): Promise<boolean>;
+    /**
+     * 获取当前待发送队列快照
+     */
+    getPendingEvents(): TrackEventRecord[];
+    /**
+     * 获取历史已发送批次列表
+     */
+    getSentBatchesHistory(): {
+        envelope: import("../types").TrackBatchEnvelope;
+        mode: "fetch" | "custom" | "beacon";
+        success: boolean;
+    }[];
+    /**
+     * 订阅实时采集事件（返回取消订阅函数）
+     */
+    onEvent(listener: TrackEventListener): () => void;
+    /**
+     * 订阅批次发送事件（返回取消订阅函数）
+     */
+    onBatch(listener: TrackBatchListener): () => void;
+    /**
+     * 销毁实例并清理所有事件监听器
+     */
+    destroy(): void;
+}

package/lib/track/src/types/index.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @file 前端统一全埋点 SDK (@giime/track) 核心类型与契约定义
+ * @description 严格对齐《单点埋点系统（AI中台).md》小驼峰规范、评审会决议及商城 ShopPlus 102 个存量事件
+ */
+/**
+ * 8大类28个标准通用事件名（小驼峰） + 深度微交互扩展事件名
+ */
+export type StandardTrackEventName = 'pageEnter' | 'domContentLoaded' | 'pageLoaded' | 'pageBizLoadResult' | 'pageVisibilityChange' | 'pageHeartbeat' | 'pageLeave' | 'elementClick' | 'elementExposure' | 'elementHover' | 'pointerPath' | 'rageClick' | 'inputFocus' | 'inputBlur' | 'inputChange' | 'optionChange' | 'dragEnd' | 'pageScroll' | 'formSubmit' | 'formValidateResult' | 'querySubmit' | 'queryResult' | 'resourceOpenResult' | 'resourcePreviewResult' | 'resourceOperateSubmit' | 'resourceOperateResult' | 'fileSelect' | 'fileUploadStart' | 'fileUploadResult' | 'fileDownloadRequest' | 'contentCopyResult' | 'taskOperateSubmit' | 'taskStatusChange' | 'approvalSubmit' | 'approvalResult' | 'configChangeSubmit' | 'configChangeResult' | 'errorResourceLoad' | 'errorRuntime' | 'errorRequest';
+/**
+ * 商城 ShopPlus 常见核心存量事件名（支持任意存量 102 个事件字符串）
+ */
+export type ShopPlusLegacyEventName = 'enter' | 'leave' | 'DOMContentLoaded' | 'DOMContentLoadedDiff' | 'loaded' | 'buyNow' | 'cartCheckout' | 'submitForm' | 'addToCart' | 'showRecommend' | 'beforeSubmitOrder' | 'createOrderSuccess' | 'createOrderFail' | 'submitOrderTime' | 'expressPaySuccess' | 'successPage' | 'unpaidContinuePay' | 'unpaidCancelOrder' | 'failBuyAgain' | 'inputAddressForm' | 'customerEmail' | 'echoCustomerAddress' | (string & {});
+/**
+ * 统一事件名称类型
+ */
+export type TrackEventName = StandardTrackEventName | ShopPlusLegacyEventName;
+/**
+ * 浏览器与设备环境详细指纹（用于分析用户实际使用的浏览器、内核、WebView、系统与设备能力）
+ */
+export interface BrowserContext {
+    /** 原始 User-Agent 字符串 */
+    userAgent: string;
+    /** 浏览器名称：Chrome / Safari / Firefox / Edge / Opera / SamsungBrowser / UCBrowser / QQBrowser / WeChat / TikTokWebView / FacebookWebView / LineWebView 等 */
+    browserName: string;
+    /** 浏览器完整版本号，如 "130.0.6723.70" */
+    browserVersion: string;
+    /** 浏览器主版本号，如 "130" */
+    browserMajorVersion: string;
+    /** 渲染引擎内核：Blink / WebKit / Gecko / Trident / EdgeHTML / Unknown */
+    engineName: string;
+    /** 操作系统名称：Windows / macOS / iOS / Android / HarmonyOS / Linux / ChromeOS / Unknown */
+    osName: string;
+    /** 操作系统版本，如 "10/11"、"15.1"、"18.1" */
+    osVersion: string;
+    /** 设备类型：pc / mobile / tablet */
+    deviceType: 'pc' | 'mobile' | 'tablet';
+    /** 平台类型（对齐数仓公共属性）：pc-web / mobile-web */
+    platformType: 'pc-web' | 'mobile-web';
+    /** 设备品牌或型号摘要（如 Apple iPhone / Mac / Android Device） */
+    deviceModel: string;
+    /** 是否运行在 App 内置 WebView 中 */
+    isWebView: boolean;
+    /** 内置浏览器所属 App 标识：tiktok / facebook / instagram / line / wechat / dingtalk / weibo / none */
+    inAppBrowser: string;
+    /** 是否为自动化爬虫/无头浏览器 (navigator.webdriver) */
+    isWebdriver: boolean;
+    /** 当前首选语言，如 "zh-CN"、"ja-JP" */
+    language: string;
+    /** 浏览器支持的语言列表 */
+    languages: string;
+    /** IANA 时区名称，如 "Asia/Shanghai" */
+    timezoneName: string;
+    /** 中文时区偏移描述（兼容商城格式），如 "东8区"、"西5区" */
+    timezoneOffset: string;
+    /** UTC 偏移分钟数 */
+    timezoneOffsetMinutes: number;
+    /** 屏幕物理分辨率宽 */
+    screenWidth: number;
+    /** 屏幕物理分辨率高 */
+    screenHeight: number;
+    /** 当前浏览器视口宽 */
+    viewportWidth: number;
+    /** 当前浏览器视口高 */
+    viewportHeight: number;
+    /** 设备像素比 DPR */
+    devicePixelRatio: number;
+    /** 屏幕色深 */
+    colorDepth: number;
+    /** 屏幕方向：landscape / portrait */
+    orientation: 'landscape' | 'portrait';
+    /** 网络连接类型（4g / wifi / 3g / slow-2g / unknown） */
+    networkType: string;
+    /** 估算下行带宽 Mbps */
+    downlinkMbps: number;
+    /** 估算往返延迟 ms */
+    rttMs: number;
+    /** CPU 逻辑核心数 */
+    hardwareConcurrency: number;
+    /** 设备内存估算 GB */
+    deviceMemoryGb: number;
+    /** 最大触摸点数（>0 代表支持触控） */
+    maxTouchPoints: number;
+    /** Cookie 是否启用 */
+    cookieEnabled: boolean;
+    /** 关键埋点 Web API 兼容性支持情况 */
+    featureSupport: {
+        sendBeacon: boolean;
+        fetchKeepalive: boolean;
+        intersectionObserver: boolean;
+        mutationObserver: boolean;
+        performanceObserver: boolean;
+    };
+}
+/**
+ * 商城端（ShopPlus）专属上下文信息（100% 兼容 statistics.[hash].ts 的 getBase 字段）
+ */
+export interface ShopPlusContext {
+    /** 访客永久设备 ID (__sx_event_poster_uid) */
+    uid: string;
+    /** 当前购物结算会话 ID (__sx_event_poster_eid) */
+    eid: string;
+    /** 上一次成单结算会话 ID (g_pre_eid) */
+    preEid: string;
+    /** 模板名称，默认 'plus' */
+    tplName: string;
+    /** 详情页模板标识（如 SGK02 / default / amazon） */
+    detailTemplate?: string;
+    /** 详情页模式（如 single / onePage / default） */
+    detailMode?: string;
+    /** 是否为斗篷页 */
+    isCloak?: string;
+    /** 是否为 Easymall 单页模板 */
+    isEasymall?: boolean;
+    /** Easymall 原始配置对象 */
+    easymall?: Record<string, any>;
+    /** 促销活动 ID 列表（逗号分隔） */
+    promotionIds?: string;
+    /** 站长用户 ID */
+    siteUserId?: string;
+    /** 地区 ID */
+    areaId?: string;
+    /** 市场 ID */
+    marketId?: string;
+    /** 店铺 ID */
+    shopId?: string;
+    /** 集合/站点 ID */
+    collId?: string;
+    /** 货币 ID */
+    currencyId?: number | string;
+    /** 商品 Sale ID（单个或逗号分隔多个） */
+    saleId?: string | number;
+    /** 订单号 */
+    orderNumber?: string;
+    /** 服务端写入的浏览器唯一标记 (window.gcookie) */
+    serviceUid?: string;
+    /** 流量来源标识 (from) */
+    from?: string;
+    /** URL 查询参数 JSON 字符串 */
+    queryParams?: string;
+    /** 服务端追踪 ID (Cookie: g_trace_id) */
+    traceId?: string;
+    /** 页面级服务端追踪 ID (Cookie: p_trace_id) */
+    pTraceId?: string;
+    /** 页面自定义注解返回值 (window.pageAnnotation()) */
+    pageAnnotation?: any;
+    /** 请求签名时间戳（12位毫秒+1位校验和） */
+    _t?: number;
+    /** 请求 MD5 签名 */
+    _s?: string;
+}
+/**
+ * 视区内可见业务元素摘要（会议决议：停留区域挂载具体元素集合）
+ */
+export interface VisibleElementSummary {
+    /** 元素稳定标识 */
+    elementId: string;
+    /** 元素类型：button / menu / card / link / input / module */
+    elementType: string;
+    /** 元素固定名称或文本摘要 */
+    elementName: string;
+    /** 所属区域容器标识 */
+    containerId?: string;
+    /** 关联业务资源类型 */
+    resourceType?: string;
+    /** 关联业务资源 ID */
+    resourceId?: string;
+    /** 当前在视口内的可见比例 (0 ~ 1) */
+    visibleRatio?: number;
+}
+/**
+ * 鼠标或手势划过元素轨迹节点（RLE 游程压缩序列项）
+ */
+export interface PointerPathNode {
+    /** 轨迹序号，从 1 开始 */
+    seq: number;
+    /** 元素稳定标识或选择器 */
+    elementId: string;
+    /** 元素类型 */
+    elementType: string;
+    /** 元素文本摘要 */
+    elementName: string;
+    /** 所属容器标识 */
+    containerId?: string;
+    /** 在该元素上的连续停留时长（毫秒） */
+    duration: number;
+    /** 归一化视口水平相对坐标 (0 ~ 1) */
+    rx: number;
+    /** 归一化页面垂直相对坐标 (0 ~ 1) */
+    ry: number;
+}
+/**
+ * 单条埋点事件完整契约结构（对齐 2026-10-23 数据契约评审会决议）
+ * - 外层请求体仅保留 { events: TrackEventRecord[] }，所有批次与环境字段全部收拢在每条 Event 内
+ * - sessionId 代表单次进入/刷新页面的会话标识（原 pageId），preSessionId 代表上一页会话标识（原 prePageId）
+ * - visitId 代表跨页面的连续访问会话标识（30分钟超时重建，商城端 shop 映射为购物会话 eid）
+ */
+export interface TrackEventRecord<TPayload extends Record<string, any> = Record<string, any>> {
+    /** 事件唯一标识（重发时保持不变，由数据团队在入湖后去重） */
+    eventId: string;
+    /** 所属上报批次唯一标识（发送时由批量队列统一注入，同批事件共享同一 batchId） */
+    batchId: string;
+    /** 批次实际发出时的客户端毫秒时间戳（发送时由批量队列统一注入） */
+    sendTime: number;
+    /** 事件名称（小驼峰，如 pageEnter / elementClick / createOrderSuccess） */
+    eventName: TrackEventName;
+    /** 事件实际发生时间（毫秒时间戳） */
+    eventTime: number;
+    /** 用户标识：商城端 (shop) 直接上报访客 uid；管理端 (manage) 固定传空字符串，由后端接收接口层按登录态补充 */
+    userId: string;
+    /** 来源标识：商城端 (shop) 区分 5 套商城体系（如 plus / single / third / shopline / shopify），管理端 (manage) 默认传空字符串 '' */
+    source: string;
+    /** 前端路由名称（纯粹取路由 route.name，商城 HTML 取 ShopPlus.router.pageId；必传字段，无路由时允许为空字符串 ''） */
+    pageKey: string;
+    /** 页面标题（纯粹取浏览器 document.title，不与 route.name 掺和） */
+    pageName: string;
+    /** 页面会话标识（原 pageId，每次进入或刷新页面生成新值，串联当页内所有事件） */
+    sessionId: string;
+    /** 上一页会话标识（原 prePageId，串联跨页面跳转链路，首次进入为空字符串 ''） */
+    preSessionId: string;
+    /** 连续访问会话标识（原 sessionId，关联跨页面的连续访问，30分钟超时重建；商城端 shop 映射为购物会话 eid） */
+    visitId: string;
+    /** 当前页面完整地址（已过滤敏感参数，供数据团队入湖后映射系统/模块/功能） */
+    url: string;
+    /** 来源页面地址 */
+    referrer: string;
+    /** 事件产生端：固定为 client */
+    eventSource: 'client' | 'server';
+    /** SDK 版本号 */
+    sdkVersion: string;
+    /** 数据结构契约版本号 */
+    schemaVersion: string;
+    /** 页面模板/皮肤标识（会议决议：解决商城同一链接切换多套模板归因） */
+    templateId: string;
+    /** 兼容旧版显式配置；当前默认不传，由数据团队入湖后补充系统归属 */
+    systemId?: string;
+    /** 兼容旧版显式配置；当前默认不传，由数据团队入湖后补充模块归属 */
+    moduleId?: string;
+    /** 兼容旧版显式配置；当前默认不传，由数据团队入湖后补充功能归属 */
+    functionId?: string;
+    /** 各事件专属业务属性负载（对应《单点埋点系统》第三章各表字段） */
+    payload: TPayload;
+    /** 浏览器与设备环境指纹信息 */
+    browserContext: BrowserContext;
+    /** 商城端 (shop) 专属上下文（管理端 manage 模式为 null） */
+    shopContext: ShopPlusContext | null;
+}
+/**
+ * 批量推送请求体契约（2026-10-23 评审会决议：外层仅保留 events 数组，所有字段收拢到每条 event 内）
+ */
+export interface TrackBatchEnvelope {
+    /** 批量事件数组（每条 event 已内含 batchId / sendTime / sdkVersion / schemaVersion / source / browserContext） */
+    events: TrackEventRecord[];
+}
+/**
+ * SDK 各采集插件开关与阈值配置
+ */
+export interface GiimeTrackPluginOptions {
+    /** 是否开启页面进入/加载/离开自动采集，默认 true */
+    pageLifecycle?: boolean;
+    /** 是否开启页面心跳自动采集（会议要求：严控非正常关页丢数率并支撑大促实时在线统计），默认 true */
+    heartbeat?: boolean;
+    /** 页面心跳间隔（毫秒），2026-10-23 评审会锁定默认值为 5000 (5秒) */
+    heartbeatIntervalMs?: number;
+    /** 是否开启全量元素点击采集，默认 true */
+    click?: boolean;
+    /** 同元素防连点节流间隔（毫秒），默认 300 */
+    clickThrottleMs?: number;
+    /** 是否开启愤怒点击（Rage Click）检测，默认 true */
+    rageClick?: boolean;
+    /** 是否开启元素视口曝光采集（IntersectionObserver），默认 true */
+    exposure?: boolean;
+    /** 元素曝光可见面积比例阈值 (0 ~ 1)，默认 0.5 (50%) */
+    exposureThreshold?: number;
+    /** 元素曝光最小连续可见时长（毫秒），默认 1000 */
+    exposureMinDurationMs?: number;
+    /** 是否开启有效鼠标悬停与悬浮显隐（Tooltip/Popover/Dropdown）采集，默认 true */
+    hover?: boolean;
+    /** 有效悬停最小连续停留时长（毫秒），默认 500 */
+    hoverMinDurationMs?: number;
+    /** 是否开启滚动深度与停顿采集，默认 true */
+    scroll?: boolean;
+    /** 是否开启鼠标划过元素轨迹序列（PC）与触摸滑动轨迹（Mobile）采集，默认 true */
+    pointerPath?: boolean;
+    /** 是否开启表单输入/选项变化与复制采集，默认 true */
+    formAndCopy?: boolean;
+    /** 是否开启资源加载异常与 JS 运行时异常采集，默认 true */
+    error?: boolean;
+    /** 在商城端 (shop) 模式下，是否开启对存量 window.statisticsPoster 的非侵入式双轨镜像代理，默认 true */
+    shopPlusDualTrackProxy?: boolean;
+}
+/**
+ * 业务端采集模式类型：manage（管理端） / shop（商城端）
+ */
+export type TrackAppType = 'manage' | 'shop';
+/**
+ * SDK 初始化总配置项（所有字段均为可选，默认内置自动识别）
+ */
+export interface GiimeTrackConfig {
+    /** 环境变量对象（可傳 import.meta.env 或 process.env，不传则根据当前域名自动识别环境） */
+    env?: Record<string, any> | string;
+    /** 接收服务接口地址（管理端 manage 默认 4 套环境 + '/guard/data-capture/ingest/v1/auth/track'，商城端 shop 默认相对路径 '/ingest/v1/shop/track'，一般无需传） */
+    endpoint?: string;
+    /** SDK 本地采集模式：manage（管理端） / shop（商城端），仅控制端侧行为，不随 JSON 上报；报文 appType 由后端按接收接口补充 */
+    appType?: TrackAppType;
+    /** 来源标识（2026-10-23 评审会新增：商城端 shop 区分 5 套商城体系如 'plus' | 'single' | 'third' | 'shopline' | 'shopify'，管理端 manage 默认 ''） */
+    source?: string;
+    /** 页面模板标识（商城多皮肤模板自动提取） */
+    templateId?: string;
+    /** 数据结构契约版本，默认 '1.0.0' */
+    schemaVersion?: string;
+    /** 总开关，默认 true */
+    enabled?: boolean;
+    /** 采样率 (0 ~ 1)，按会话采样，默认 1.0 (100% 全采) */
+    sampleRate?: number;
+    /** 队列定时 flush 间隔（毫秒），默认 5000 */
+    flushIntervalMs?: number;
+    /** 单批次最大事件条数，默认 20 */
+    maxBatchSize?: number;
+    /** 内存队列最大容量，超出丢弃最旧事件，默认 500 */
+    maxQueueSize?: number;
+    /** 单批目标字节上限，默认 60000；单条超大事件保留原结构，使用普通请求发送 */
+    maxBatchBytes?: number;
+    /** 失败重试初始间隔（毫秒），默认 5000，连续失败退避到最多 30000 */
+    retryIntervalMs?: number;
+    /** 单次发送超时（毫秒），默认 10000 */
+    requestTimeoutMs?: number;
+    /** 是否在控制台打印调试日志（默认根据 env.DEV 自动开启，无需手动传） */
+    debug?: boolean;
+    /** 是否将 payload 字段同时平铺到事件顶层（兼容不同 Flink 契约习惯），默认 false */
+    flattenPayload?: boolean;
+    /** 兼容旧版系统标识配置；新接入无需配置，由数据团队入湖后补充 */
+    systemId?: string;
+    /** 兼容旧版模块标识配置；新接入无需配置，由数据团队入湖后补充 */
+    moduleId?: string;
+    /** 兼容旧版功能标识配置；新接入无需配置，由数据团队入湖后补充 */
+    functionId?: string;
+    /** 动态获取请求头（默认已内置自动从 Cookie 读取 token 拼接 Authorization，无需手动传） */
+    getHeaders?: () => Record<string, string>;
+    /** 自定义上报传输函数（用于本地 Playground 拦截或自定义通道；返回 true 代表发送成功） */
+    customTransport?: (envelope: TrackBatchEnvelope, isUnload: boolean) => Promise<boolean> | boolean;
+    /** 采集插件细粒度配置 */
+    plugins?: GiimeTrackPluginOptions;
+}
+/**
+ * 事件订阅监听器（供 Playground 面板或调试工具实时观测采集到的事件）
+ */
+export type TrackEventListener = (event: TrackEventRecord, queueLength: number) => void;
+/**
+ * 批次发送订阅监听器
+ */
+export type TrackBatchListener = (envelope: TrackBatchEnvelope, mode: 'fetch' | 'beacon' | 'custom', success: boolean) => void;

package/lib/track/src/utils/browser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file 浏览器、渲染内核、操作系统、App WebView 及设备能力全方位识别工具
+ * @description 帮助团队精确统计分析管理端（manage）与商城端（shop）用户实际使用的浏览器版本、移动端广告内置容器及 API 兼容性
+ */
+import type { BrowserContext } from '../types';
+/**
+ * 获取中文时区偏移描述（完全兼容商城 statistics.[hash].ts 的 getTimezoneOffset 格式）
+ */
+export declare const getChineseTimezoneOffset: () => {
+    timezoneOffset: string;
+    timezoneOffsetMinutes: number;
+};
+/**
+ * 采集完整的浏览器与设备环境上下文
+ */
+export declare const parseBrowserContext: () => BrowserContext;

package/lib/track/src/utils/dom.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file DOM 元素属性提取、上下文向上冒泡推导、视区可见元素扫描与自动翻译原文保护工具
+ * @description 解决多语言翻译污染按钮口径、Excel 30+ 自定义事件自动推导及视区停留挂载元素集合需求
+ */
+import type { VisibleElementSummary } from '../types';
+/**
+ * 提取出的元素标准化元数据
+ */
+export interface ExtractedElementMeta {
+    /** 命中的可交互或业务 DOM 元素 */
+    element: HTMLElement;
+    /** 元素稳定标识（优先 data-giime-id / data-track / id / 语义选择器） */
+    elementId: string;
+    /** 元素类型：button / link / menu / card / tab / input / switch / media / other */
+    elementType: string;
+    /** 当前界面展示的控件名称（截断 50 字） */
+    elementName: string;
+    /** 自动翻译前的原始中文控件名称（防 i18n-jsautotranslate 污染口径） */
+    rawElementName: string;
+    /** 所属区域容器标识（如 toolbar / list / dialog / header / discount_offer） */
+    containerId: string;
+    /** 关联业务对象类型（如 agent / workflow / product / skill） */
+    resourceType: string;
+    /** 关联业务对象 ID */
+    resourceId: string;
+    /** 元素 CSS 选择器摘要 */
+    elementSelector: string;
+    /** DOM 树路径摘要 */
+    elementPath: string;
+    /** 在列表或同级容器中的序号（从 1 开始） */
+    rank: number;
+    /** 链接跳转目标地址（若是 a 标签） */
+    hrefUrl: string;
+}
+/**
+ * 启动 DOM 文本突变监听，在 i18n-jsautotranslate 替换中文前备份原始中文文本
+ */
+export declare const installTranslationRawTextObserver: () => void;
+/**
+ * 查找事件目标最近的可交互或业务标记祖先节点
+ * @param target 事件触发原始节点
+ */
+export declare const findInteractiveElement: (target: EventTarget | null) => HTMLElement | null;
+/**
+ * 推断元素的标准类型（对齐《单点埋点系统（AI中台).md》 elementType）
+ * @param el 目标元素
+ */
+export declare const inferElementType: (el: HTMLElement) => string;
+/**
+ * 提取元素的纯净名称文本
+ * @param el 目标元素
+ */
+export declare const extractCleanElementText: (el: HTMLElement) => string;
+/**
+ * 沿 DOM 树向上推导所属区域容器 containerId（对齐《单点埋点系统》与 Excel module_name/slot_id）
+ * @param el 目标元素
+ */
+export declare const resolveContainerId: (el: HTMLElement) => string;
+/**
+ * 沿 DOM 树向上查找关联的业务资源类型与资源 ID
+ * @param el 目标元素
+ */
+export declare const resolveResourceContext: (el: HTMLElement) => {
+    resourceType: string;
+    resourceId: string;
+};
+/**
+ * 计算元素在同级列表中的位置序号 rank（从 1 开始）
+ * @param el 目标元素
+ */
+export declare const computeElementRank: (el: HTMLElement) => number;
+/**
+ * 生成简短稳定的 CSS 选择器与 DOM 树路径
+ * @param el 目标元素
+ */
+export declare const computeSelectorAndPath: (el: HTMLElement) => {
+    elementSelector: string;
+    elementPath: string;
+};
+/**
+ * 提取目标元素的完整标准化埋点元数据
+ * @param el 目标元素
+ */
+export declare const extractElementMeta: (el: HTMLElement) => ExtractedElementMeta;
+/**
+ * 扫描当前视口内可见的关键业务元素集合（满足评审会要求：页面心跳与视区停留挂载具体元素列表）
+ * @param maxCount 最大采集数量，默认 12
+ */
+export declare const collectVisibleElementsInViewport: (maxCount?: number) => VisibleElementSummary[];