@jx3box/jx3box-ui 2.4.2 → 2.4.3

package/docs/agents/traffic-analytics.md

@@ -0,0 +1,50 @@
+# Traffic 路径采集适配
+
+`jx3box-ui` 只提供无渲染、显式启用的适配器，不会在安装组件库或渲染 `CommonHeader` 时自动采集。
+
+```js
+import { createJx3boxTrafficAnalytics } from "@jx3box/jx3box-ui";
+
+const traffic = createJx3boxTrafficAnalytics({
+    router,
+    project: "index",
+    client: "pc_web",
+    surface: "pc_web",
+    gameClient: "std",
+    // 传 heartbeat 的实时结果。未知态失败关闭，不发送。
+    resolveTrafficPermission: () => heartbeatState,
+});
+
+// 应在 router 已建立，并取得 heartbeat 权限后显式执行。
+await traffic.init();
+
+// heartbeat 后续发现机器人或关闭采集时，立即持久阻断并清空队列。
+traffic.setTrafficPermission({
+    traffic_allowed: false,
+    collection_blocked_reason: "robot",
+});
+
+// heartbeat 明确恢复后才解除持久阻断。
+traffic.setTrafficPermission({ traffic_allowed: true });
+
+// 同义的显式生命周期接口，供宿主的隐私开关直接调用。
+traffic.block("host_privacy_disabled");
+traffic.unblock();
+
+// 宿主卸载时释放唯一 Router owner、pagehide 监听和队列请求。
+traffic.destroy();
+```
+
+适配器只创建一个 Analytics Core、一个 Router owner 和一个 `TrafficSink`。它不会创建 `TrackingSink`，也不会安装点击、曝光、热力图指令，因此一次路由变化只产生一个 canonical `page_view`。已经由宿主启用 Tracking 的应用不能再初始化本适配器；这类应用应直接用 `jx3box-common@9.5.2` 的组合 sink 创建唯一 Core/Router owner。
+
+运行时规则只能来自 `/api/cms/system/traffic/config`。配置缺失、请求失败、规则字段不完整或动态参数没有 named validator 时不建立页面事件，也不使用本地放行规则。heartbeat 权限未知时会进入内存级 fail-closed：不建立新的 Journal 事件、取消进行中的请求；已经完成脱敏的 Journal 项会保留，直到明确允许后再恢复。宿主应优先等 heartbeat 给出明确权限后再调用 `init()`。批量请求发往 `/api/cms/system/traffic/visits/batch`，依赖逐 `event_id` ACK；409、429、网络错误和缺失 ACK 都保留原事件重试。
+
+Config 请求与 Traffic envelope 共用同一个 recipient domain。`pc_web` 保留小写真实 hostname（由后端 allowlist 决定是否启用）；`app`、`miniprogram`、`pc_game`、`mobile_game` 统一使用 `embedded`，不会把 WebView 的 `localhost` 等内部地址发给规则接口。
+
+`traffic_allowed=false`、`is_robot=true`、`traffic.block(reason)` 或可信 `blocked` 会写入 `jx3box:analytics:traffic:block:v1`，并调用 `block({ clear: true, cancelInflight: true })`。下次初始化先恢复阻断，再接入 Router。只有 heartbeat 明确返回允许，或宿主显式调用 `setTrafficPermission({ traffic_allowed: true })` / `unblock()` 才解除。
+
+宿主可通过 `beforeFlush(context)` 在每次网络发送前追加权限判断；返回 `false`/`{ allow: false }` 会保留队列并拒绝发送，返回可信 `block` 会持久阻断。`clear(reason)` 与 `cancelInflight(reason)` 分别清除安全 Journal 和取消当前请求。`init()` 幂等占有唯一 Router owner，`destroy()` 释放 Router/pagehide 监听并取消请求；销毁后不能再次初始化。
+
+Traffic-only 队列使用独立的 `jx3box:analytics:traffic:queue:v1`，不会读取或改写公共 `jx3box:analytics:queue:v1` 中的 Tracking/multi-sink Journal。队列仍把无 delivery ownership 的旧数据视为 `tracking`，不会误发到 Traffic。
+
+后端协议已提供 Traffic config 和逐 ID ACK。本适配器当前通过 9.5.2 fixture 验证；若目标环境仍是旧部署、响应缺字段或网络不可用，会安全保留或拒绝事件。构建与 fixture 测试不代表线上部署及真实链路已经验证。

package/index.js

@@ -43,6 +43,7 @@ import {
     setJx3boxUiLocale,
 } from "./i18n";
 import i18nMixin from "./i18n/mixin";
+import { createJx3boxTrafficAnalytics } from "./src/utils/traffic-analytics";
 
 const components = {
     CommonHeader,
@@ -93,4 +94,5 @@ export {
     mergeJx3boxUiMessages,
     getJx3boxUiAvailableLocales,
     setJx3boxUiLocale,
+    createJx3boxTrafficAnalytics,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jx3box/jx3box-ui",
-    "version": "2.4.2",
+    "version": "2.4.3",
     "description": "JX3BOX Vue3 UI",
     "main": "index.js",
     "scripts": {
@@ -13,6 +13,7 @@
         "build:dev": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service build --mode development",
         "build:prod": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vue-cli-service build --mode production",
         "lint": "vue-cli-service lint",
+        "test:traffic": "node --test tests/traffic-analytics-contract.test.js",
         "test:i18n": "node --test tests/wiki-i18n-contract.test.js",
         "update": "npm --registry https://registry.npmjs.org install @jx3box/jx3box-common@latest @jx3box/jx3box-data@latest @jx3box/jx3box-editor@latest @jx3box/jx3box-emotion@latest @jx3box/jx3box-macro@latest @jx3box/jx3box-talent@latest"
     },
@@ -33,7 +34,7 @@
     },
     "dependencies": {
         "@element-plus/icons-vue": "^2.3.2",
-        "@jx3box/jx3box-common": "^9.2.9",
+        "@jx3box/jx3box-common": "9.5.2",
         "@jx3box/jx3box-data": "^3.9.6",
         "@jx3box/jx3box-editor": "^3.2.13",
         "@jx3box/jx3box-emotion": "^1.3.2",

package/src/utils/traffic-analytics.js

@@ -0,0 +1,443 @@
+import {
+    createAnalyticsCore,
+    createCompositeRuleResolver,
+    createEventQueue,
+    createIdentity,
+    createQueueStorage,
+    createRemoteRuleResolver,
+    createTrafficSink,
+    defaultAckDecoder,
+    installVueRouterAnalytics,
+} from "@jx3box/jx3box-common/js/analytics.js";
+
+const DEFAULT_CONFIG_ENDPOINT = "/api/cms/system/traffic/config";
+const DEFAULT_BATCH_ENDPOINT = "/api/cms/system/traffic/visits/batch";
+const DEFAULT_QUEUE_STORAGE_KEY = "jx3box:analytics:traffic:queue:v1";
+const DEFAULT_BLOCK_STORAGE_KEY = "jx3box:analytics:traffic:block:v1";
+const EMBEDDED_SURFACES = new Set(["app", "miniprogram", "pc_game", "mobile_game"]);
+
+function safeReason(value, fallback) {
+    const reason = String(value || fallback || "traffic_disabled")
+        .trim()
+        .slice(0, 128);
+    return /^[a-zA-Z0-9][a-zA-Z0-9_.:-]*$/.test(reason) ? reason : "traffic_disabled";
+}
+
+function safeStorage(storage) {
+    if (!storage || typeof storage.getItem !== "function") return null;
+    return storage;
+}
+
+function normalizeRecipientDomain(domain, surface) {
+    const normalizedSurface = String(surface || "")
+        .trim()
+        .toLowerCase();
+    if (EMBEDDED_SURFACES.has(normalizedSurface)) return "embedded";
+    const normalizedDomain = String(domain || "")
+        .trim()
+        .toLowerCase()
+        .slice(0, 253);
+    return /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(normalizedDomain) ? normalizedDomain : "";
+}
+
+function createBlockStorage(storage, key, now) {
+    const target = safeStorage(storage);
+    let loaded = false;
+    let currentBlock = null;
+
+    function read() {
+        if (loaded) return currentBlock ? Object.assign({}, currentBlock) : null;
+        loaded = true;
+        if (!target) return null;
+        try {
+            const value = JSON.parse(target.getItem(key) || "null");
+            if (!value || value.blocked !== true) return null;
+            currentBlock = {
+                reason: safeReason(value.reason),
+                clear: true,
+            };
+            return Object.assign({}, currentBlock);
+        } catch (error) {
+            return null;
+        }
+    }
+
+    function write(reason) {
+        const block = {
+            blocked: true,
+            reason: safeReason(reason),
+            blocked_at: typeof now === "function" ? now() : Date.now(),
+        };
+        loaded = true;
+        currentBlock = { reason: block.reason, clear: true };
+        if (target) {
+            try {
+                target.setItem(key, JSON.stringify(block));
+            } catch (error) {
+                // Privacy controls remain effective in memory when storage is unavailable.
+            }
+        }
+        return Object.assign({}, currentBlock);
+    }
+
+    function clear() {
+        loaded = true;
+        currentBlock = null;
+        if (!target) return;
+        try {
+            target.removeItem(key);
+        } catch (error) {
+            // Best effort only. The current queue is still explicitly unblocked below.
+        }
+    }
+
+    return { clear, read, write };
+}
+
+function normalizeTrafficPermission(value) {
+    if (value === true) return { known: true, allow: true };
+    if (value === false) {
+        return { known: true, allow: false, reason: "traffic_disabled" };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { known: false, allow: false };
+    }
+
+    const source = value.data && typeof value.data === "object" ? value.data : value;
+    const rawBlock = source.blocked || source.block;
+    const blockReason = typeof rawBlock === "string" ? rawBlock : rawBlock && (rawBlock.reason || rawBlock.code);
+    if (blockReason || source.is_robot === true) {
+        return {
+            known: true,
+            allow: false,
+            reason: safeReason(blockReason || "robot"),
+        };
+    }
+
+    const allowed =
+        typeof source.traffic_allowed === "boolean"
+            ? source.traffic_allowed
+            : typeof source.allowed === "boolean"
+            ? source.allowed
+            : source.allow;
+    if (allowed === true) return { known: true, allow: true };
+    if (allowed === false) {
+        return {
+            known: true,
+            allow: false,
+            reason: safeReason(
+                source.collection_blocked_reason || source.block_reason || source.reason || "traffic_disabled"
+            ),
+        };
+    }
+    return { known: false, allow: false };
+}
+
+/**
+ * Creates an inert, headless Traffic collector. Hosts must explicitly call
+ * `init()` after their router and heartbeat permission are ready.
+ */
+function createJx3boxTrafficAnalytics(options) {
+    const settings = options || {};
+    const runtime = settings.runtime || (typeof window !== "undefined" ? window : {});
+    const now = typeof settings.now === "function" ? settings.now : Date.now;
+    const recipientDomain = normalizeRecipientDomain(
+        settings.domain || (runtime.location && runtime.location.hostname),
+        settings.surface
+    );
+    const blockStorage = createBlockStorage(
+        settings.blockStorage || runtime.localStorage,
+        settings.blockStorageKey || DEFAULT_BLOCK_STORAGE_KEY,
+        now
+    );
+    const permissionProvider =
+        settings.resolveTrafficPermission !== undefined ? settings.resolveTrafficPermission : settings.trafficAllowed;
+    let hasPermissionOverride = false;
+    let permissionOverride;
+    let client = null;
+    let queue = null;
+    let routerHandle = null;
+    let initPromise = null;
+    let initialized = false;
+    let destroyed = false;
+
+    function resolvePermissionInput() {
+        if (hasPermissionOverride) return Promise.resolve(permissionOverride);
+        if (typeof permissionProvider === "function") {
+            try {
+                return Promise.resolve(permissionProvider()).catch(function () {
+                    return undefined;
+                });
+            } catch (error) {
+                return Promise.resolve(undefined);
+            }
+        }
+        return Promise.resolve(permissionProvider);
+    }
+
+    function persistAndBlock(reason) {
+        const block = blockStorage.write(reason);
+        if (client) client.block(block, { clear: true, cancelInflight: true });
+        return block;
+    }
+
+    function applyPermission(value) {
+        const permission = normalizeTrafficPermission(value);
+        if (!permission.known) {
+            // Unknown heartbeat/consent state is a transient fail-closed pause.
+            // Keep already-sanitized Journal entries for a later explicit allow,
+            // but cancel any request that may have started under an older grant.
+            if (client) {
+                client.block(
+                    { reason: "traffic_permission_unknown", clear: false },
+                    {
+                        clear: false,
+                        cancelInflight: true,
+                    }
+                );
+            }
+            return permission;
+        }
+        if (!permission.allow) {
+            persistAndBlock(permission.reason);
+            return permission;
+        }
+        blockStorage.clear();
+        if (client) client.unblock();
+        return permission;
+    }
+
+    async function guardBeforeFlush(context) {
+        const permission = applyPermission(await resolvePermissionInput());
+        if (!permission.known) return { allow: false };
+        if (!permission.allow) {
+            return {
+                blocked: { reason: permission.reason, clear: true },
+                clear: true,
+                cancelInflight: true,
+            };
+        }
+        if (typeof settings.beforeFlush !== "function") return { allow: true };
+        const result = await settings.beforeFlush(context);
+        if (result && typeof result === "object" && (result.blocked || result.block)) {
+            const blocked = normalizeTrafficPermission(result);
+            if (!blocked.allow) persistAndBlock(blocked.reason);
+        }
+        return result;
+    }
+
+    function buildClient() {
+        if (!settings.router || typeof settings.router.afterEach !== "function") {
+            throw new Error("jx3box traffic analytics requires a Vue Router instance");
+        }
+        if (!settings.project || !settings.surface || !settings.client || !settings.gameClient) {
+            throw new Error("jx3box traffic analytics requires project, surface, client and gameClient");
+        }
+
+        const identity =
+            settings.identity ||
+            createIdentity({
+                runtime,
+                now,
+                instanceId: settings.instanceId,
+                sessionNamespace: settings.sessionNamespace || "analytics",
+                sessionTimeoutMs: settings.sessionTimeoutMs,
+            });
+        const baseAckDecoder = typeof settings.ackDecoder === "function" ? settings.ackDecoder : defaultAckDecoder;
+        const trafficSink = createTrafficSink({
+            runtime,
+            endpoint: settings.batchEndpoint || DEFAULT_BATCH_ENDPOINT,
+            fetch: settings.fetch,
+            navigator: settings.navigator,
+            credentials: settings.credentials,
+            headersProvider: settings.headersProvider,
+            ackDecoder: function (payload, context) {
+                const decoded = baseAckDecoder(payload, context);
+                if (decoded && typeof decoded === "object" && (decoded.blocked || decoded.block)) {
+                    const blocked = normalizeTrafficPermission(decoded);
+                    if (!blocked.allow) blockStorage.write(blocked.reason);
+                }
+                return decoded;
+            },
+            retryPolicy: settings.retryPolicy,
+        });
+        const storage = createQueueStorage({
+            storage: settings.queueStorage || runtime.localStorage,
+            key: settings.queueStorageKey || DEFAULT_QUEUE_STORAGE_KEY,
+            maxEvents: settings.maxPersistedEvents || 200,
+            maxBytes: settings.maxPersistedBytes || 256 * 1024,
+            ttlMs: settings.persistTtlMs || 7 * 24 * 60 * 60 * 1000,
+            now,
+        });
+        queue = createEventQueue({
+            runtime,
+            storage,
+            sinks: [trafficSink],
+            // A v1 entry has no sink ownership. It belongs to legacy Tracking;
+            // since this adapter deliberately has no Tracking sink, it is dropped.
+            legacySinkKey: "tracking",
+            beforeFlush: guardBeforeFlush,
+            batchSize: settings.batchSize || 20,
+            maxEvents: settings.maxQueueEvents || 200,
+            maxBatchBytes: settings.maxBatchBytes || 60 * 1024,
+            flushIntervalMs: settings.flushIntervalMs || 10000,
+            maxRetries: settings.maxRetries === undefined ? 5 : settings.maxRetries,
+            retryBaseMs: settings.retryBaseMs || 1000,
+            now,
+            random: settings.random,
+            setTimeout: settings.queueSetTimeout,
+            clearTimeout: settings.queueClearTimeout,
+            onDrop: settings.onDrop,
+        });
+        const trafficRuleResolver =
+            settings.trafficRuleResolver ||
+            createRemoteRuleResolver({
+                runtime,
+                endpoint: settings.configEndpoint || DEFAULT_CONFIG_ENDPOINT,
+                fetch: settings.fetch,
+                credentials: settings.credentials,
+            });
+        const compositeRuleResolver = createCompositeRuleResolver({ traffic: trafficRuleResolver });
+        const ruleResolver = {
+            resolve: async function (input) {
+                const resolved = await compositeRuleResolver.resolve(
+                    Object.assign({}, input || {}, { domain: recipientDomain })
+                );
+                return resolved ? Object.assign({}, resolved, { domain: recipientDomain }) : null;
+            },
+        };
+        client = createAnalyticsCore({
+            runtime,
+            identity,
+            queue,
+            ruleResolver,
+            now,
+            product: settings.product || "jx3box",
+            project: settings.project,
+            client: settings.client,
+            surface: settings.surface,
+            gameClient: settings.gameClient,
+            platform: settings.platform,
+            channel: settings.channel,
+            appVersion: settings.appVersion,
+            appBuild: settings.appBuild,
+            webVersion: settings.webVersion,
+            displayMode: settings.displayMode || "browser",
+            sampleSalt: settings.sampleSalt || "jx3box-analytics-v2",
+        });
+    }
+
+    async function init() {
+        if (destroyed) throw new Error("jx3box traffic analytics has been destroyed");
+        if (initialized) return api;
+        if (initPromise) return initPromise;
+        initPromise = Promise.resolve()
+            .then(async function () {
+                buildClient();
+                const persistedBlock = blockStorage.read();
+                if (persistedBlock) client.block(persistedBlock, { clear: true, cancelInflight: true });
+                const permission = await resolvePermissionInput();
+                if (destroyed) {
+                    if (client) client.destroy();
+                    throw new Error("jx3box traffic analytics has been destroyed");
+                }
+                applyPermission(permission);
+                routerHandle = installVueRouterAnalytics(client, settings.router, {
+                    runtime,
+                    captureInitial: settings.captureInitial !== false,
+                    flushBeaconOnPagehide: settings.flushBeaconOnPagehide !== false,
+                    project: settings.project,
+                    product: settings.product || "jx3box",
+                    client: settings.client,
+                    surface: settings.surface,
+                    gameClient: settings.gameClient,
+                    domain: settings.domain,
+                });
+                initialized = true;
+                return api;
+            })
+            .catch(function (error) {
+                if (routerHandle) routerHandle.destroy();
+                else if (client) client.destroy();
+                routerHandle = null;
+                client = null;
+                queue = null;
+                initPromise = null;
+                throw error;
+            });
+        return initPromise;
+    }
+
+    function setTrafficPermission(value) {
+        hasPermissionOverride = true;
+        permissionOverride = value;
+        if (destroyed) return normalizeTrafficPermission(value);
+        return applyPermission(value);
+    }
+
+    function block(reason) {
+        return setTrafficPermission({
+            traffic_allowed: false,
+            collection_blocked_reason: safeReason(reason, "host_block"),
+        });
+    }
+
+    function unblock() {
+        return setTrafficPermission({ traffic_allowed: true });
+    }
+
+    function getState() {
+        return {
+            initialized,
+            destroyed,
+            permission_block: blockStorage.read(),
+            analytics: client ? client.getState() : null,
+        };
+    }
+
+    function destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        if (routerHandle) routerHandle.destroy();
+        if (client) client.destroy();
+        routerHandle = null;
+        client = null;
+        queue = null;
+        initialized = false;
+    }
+
+    const api = {
+        init,
+        destroy,
+        block,
+        unblock,
+        setTrafficPermission,
+        getState,
+        flush: function (optionsForFlush) {
+            return client ? client.flush(optionsForFlush) : Promise.resolve({ sent: 0, pending: 0 });
+        },
+        flushBeacon: function (optionsForFlush) {
+            return client ? client.flushBeacon(optionsForFlush) : false;
+        },
+        finalize: function (optionsForFinalize) {
+            return client ? client.finalizePage(optionsForFinalize) : false;
+        },
+        clear: function (reason) {
+            return client ? client.clear(reason || "host_clear") : 0;
+        },
+        cancelInflight: function (reason) {
+            return client ? client.cancelInflight(reason || "host_cancel") : 0;
+        },
+    };
+    return api;
+}
+
+export {
+    DEFAULT_BATCH_ENDPOINT,
+    DEFAULT_BLOCK_STORAGE_KEY,
+    DEFAULT_CONFIG_ENDPOINT,
+    DEFAULT_QUEUE_STORAGE_KEY,
+    createJx3boxTrafficAnalytics,
+    normalizeRecipientDomain,
+    normalizeTrafficPermission,
+};