@jx3box/jx3box-ui 2.3.30 → 2.4.0

package/docs/agents/client-stat.md

@@ -0,0 +1,13 @@
+# PC 公共头客户端统计
+
+`CommonHeader` 为引用公共头的普通 PC 项目接入新版客户端实例 heartbeat。
+
+- 接口：`POST /api/cms/system/stat/heartbeat`。
+- SDK 版本：当前固定为 `v0.0.1`，只在统计组件协议升级时调整。
+- 实例 ID：复用本地 `jx3box:device_id` 随机 UUID；不使用硬件指纹。
+- 普通桌面浏览器为 `client=pc_web`；手机浏览器访问 PC 页面为 `client=mobile_web`。
+- 小程序和 App 容器按统一客户端枚举识别；游戏内页面的 `pc_game/mobile_game` 由对应页面以后主动指定，不在公共头推断。
+- UID 不进入 payload，由 service-cms 从可选 JWT 中读取；IP 同样由服务端反代请求头读取。
+- 生产环境启动后随机延迟 3～15 秒，同一北京时间日期、UID 和 Web 版本只成功上报一次。
+- 页面恢复可见时补检；请求失败不写成功标记，也不影响公共头和宿主页面。
+- localhost 每次公共头重新创建都强制上报，方便联调。

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jx3box/jx3box-ui",
-    "version": "2.3.30",
+    "version": "2.4.0",
     "description": "JX3BOX Vue3 UI",
     "main": "index.js",
     "scripts": {

package/src/CommonHeader.vue

@@ -85,6 +85,7 @@ import miniprogram from "@jx3box/jx3box-common/data/miniprogram.json";
 import { getGlobalConfig } from "../service/header";
 import { getConfig, getMyAccountStatus } from "../service/cms";
 import { clearActiveAuthToken, refreshTokenIfNeeded } from "./utils/auth-token-refresh";
+import { checkClientStatOnVisible, installClientStatReporting } from "./utils/client-stat";
 import User from "@jx3box/jx3box-common/js/user.js";
 import JX3BOX from "@jx3box/jx3box-common/data/jx3box.json";
 
@@ -262,6 +263,7 @@ export default {
         handleVisibilityChange: function () {
             if (document.visibilityState === "visible") {
                 this.refreshAuthToken();
+                checkClientStatOnVisible();
             }
         },
 
@@ -446,6 +448,7 @@ export default {
     },
     created: function () {
         this.init();
+        installClientStatReporting();
         window.addEventListener("resize", this.updateScreen, { passive: true });
         document.addEventListener("visibilitychange", this.handleVisibilityChange);
 

package/src/utils/client-stat.js

@@ -0,0 +1,261 @@
+import { $cms } from "@jx3box/jx3box-common/js/api";
+import { isMiniProgram, isApp } from "@jx3box/jx3box-common/js/utils";
+import User from "@jx3box/jx3box-common/js/user";
+
+const INSTANCE_ID_KEY = "jx3box:device_id";
+const REPORT_DATE_KEY = "jx3box:client-stat-report-date";
+const REPORT_SIGNATURE_KEY = "jx3box:client-stat-report-signature";
+const STAT_SDK_VERSION = "v0.0.1";
+const STARTUP_DELAY_MIN = 3 * 1000;
+const STARTUP_DELAY_MAX = 15 * 1000;
+
+let reportTask = null;
+let scheduledTimer = null;
+
+function compactPayload(payload) {
+    return Object.fromEntries(
+        Object.entries(payload).filter(([, value]) => value !== undefined && value !== null && value !== "")
+    );
+}
+
+function rangedNumber(value, min, max, { integer = false } = {}) {
+    if (value === undefined || value === null || value === "") return null;
+    const result = Number(value);
+    if (!Number.isFinite(result) || result < min || result > max) return null;
+    if (integer && !Number.isInteger(result)) return null;
+    return result;
+}
+
+function createInstanceId() {
+    const browserCrypto = window.crypto;
+    if (typeof browserCrypto?.randomUUID === "function") return browserCrypto.randomUUID();
+
+    const bytes = new Uint8Array(16);
+    browserCrypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const value = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+
+export function ensureClientInstanceId() {
+    const current = localStorage.getItem(INSTANCE_ID_KEY);
+    if (current) return current;
+
+    const instanceId = createInstanceId();
+    localStorage.setItem(INSTANCE_ID_KEY, instanceId);
+    return instanceId;
+}
+
+function chinaDate(date = new Date()) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: "Asia/Shanghai",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(date);
+    const values = Object.fromEntries(parts.map((item) => [item.type, item.value]));
+    return `${values.year}-${values.month}-${values.day}`;
+}
+
+function resolveChannel() {
+    const sources = [window.location.search, String(window.location.hash || "").split("?")[1]];
+    for (const source of sources) {
+        if (!source) continue;
+        const value = new URLSearchParams(String(source).replace(/^\?/, "")).get("__from");
+        if (value?.trim()) return value.trim().slice(0, 64);
+    }
+    return null;
+}
+
+function resolvePlatform(userAgent, navigatorPlatform) {
+    if (/iPhone|iPad|iPod/i.test(userAgent)) return "ios";
+    if (/Android/i.test(userAgent)) return "android";
+    if (/Windows/i.test(userAgent)) return "windows";
+    if (/Macintosh|MacIntel/i.test(userAgent) || navigatorPlatform === "MacIntel") return "macos";
+    if (/Linux/i.test(userAgent)) return "linux";
+    return "unknown";
+}
+
+function resolveClient(platform, userAgent) {
+    if (isApp()) return "app";
+    if (isMiniProgram() || /miniprogram/i.test(userAgent)) return "miniprogram";
+    if (["ios", "android"].includes(platform) || /Mobile|Tablet/i.test(userAgent)) return "mobile_web";
+    if (["windows", "macos", "linux"].includes(platform)) return "pc_web";
+    return "unknown";
+}
+
+function parseBrowser(userAgent) {
+    const candidates = [
+        ["Edge", /EdgA?[\s/]([\d.]+)/i],
+        ["Chrome", /(?:Chrome|CriOS)[\s/]([\d.]+)/i],
+        ["Firefox", /(?:Firefox|FxiOS)[\s/]([\d.]+)/i],
+        ["Safari", /Version[\s/]([\d.]+).*Safari/i],
+    ];
+    const matched = candidates.find(([, pattern]) => pattern.test(userAgent));
+    const browserMatch = matched?.[1]?.exec(userAgent);
+    const webkit = /AppleWebKit[\s/]([\d.]+)/i.exec(userAgent);
+    const chromium = /(?:Chrome|Chromium|CriOS)[\s/]([\d.]+)/i.exec(userAgent);
+
+    return {
+        browser_name: matched?.[0] || null,
+        browser_version: browserMatch?.[1] || null,
+        engine_name: chromium ? "Blink" : webkit ? "WebKit" : null,
+        webview_version: /;\s*wv\)|Version\/4\.0/i.test(userAgent)
+            ? browserMatch?.[1] || chromium?.[1] || webkit?.[1] || null
+            : null,
+    };
+}
+
+function supportsWebGl() {
+    try {
+        const canvas = document.createElement("canvas");
+        return !!(canvas.getContext("webgl") || canvas.getContext("experimental-webgl"));
+    } catch (e) {
+        return false;
+    }
+}
+
+function resolveOrientation() {
+    const type = String(window.screen?.orientation?.type || "");
+    if (type.startsWith("portrait")) return "portrait";
+    if (type.startsWith("landscape")) return "landscape";
+    return window.innerWidth > window.innerHeight ? "landscape" : "portrait";
+}
+
+function resolveDisplayMode() {
+    if (document.fullscreenElement) return "fullscreen";
+    if (window.matchMedia?.("(display-mode: standalone)")?.matches) return "standalone";
+    return "browser";
+}
+
+function resolveWebVersion() {
+    return (
+        window.__JX3BOX_VERSION__ ||
+        window.__APP_VERSION__ ||
+        process.env.VUE_APP_VERSION ||
+        process.env.VUE_APP_BUILD_VERSION ||
+        null
+    );
+}
+
+export function buildClientStatPayload(instanceId) {
+    const nav = window.navigator || {};
+    const screen = window.screen || {};
+    const connection = nav.connection || nav.mozConnection || nav.webkitConnection || {};
+    const userAgent = String(nav.userAgent || "");
+    const platform = resolvePlatform(userAgent, nav.platform);
+    const client = resolveClient(platform, userAgent);
+    const browser = parseBrowser(userAgent);
+
+    return compactPayload({
+        instance_id: instanceId,
+        product: "jx3box",
+        client,
+        platform,
+        domain: window.location.hostname,
+        channel: resolveChannel(),
+        web_version: resolveWebVersion(),
+        sdk_version: STAT_SDK_VERSION,
+
+        os_name: platform,
+        device_type: ["ios", "android"].includes(platform) ? (/iPad|Tablet/i.test(userAgent) ? "tablet" : "phone") : "desktop",
+        architecture: /arm64|aarch64/i.test(userAgent)
+            ? "arm64"
+            : /x86_64|x64|Win64|x86-64/i.test(userAgent)
+              ? "x64"
+              : null,
+        hardware_concurrency: rangedNumber(nav.hardwareConcurrency, 1, 1024, { integer: true }),
+        device_memory_gb: rangedNumber(nav.deviceMemory, 0.1, 655.35),
+
+        screen_width_css: rangedNumber(screen.width, 1, 100000, { integer: true }),
+        screen_height_css: rangedNumber(screen.height, 1, 100000, { integer: true }),
+        screen_avail_width_css: rangedNumber(screen.availWidth, 1, 100000, { integer: true }),
+        screen_avail_height_css: rangedNumber(screen.availHeight, 1, 100000, { integer: true }),
+        viewport_width_css: rangedNumber(window.innerWidth, 1, 100000, { integer: true }),
+        viewport_height_css: rangedNumber(window.innerHeight, 1, 100000, { integer: true }),
+        device_pixel_ratio: rangedNumber(window.devicePixelRatio, 0.1, 20),
+        color_depth: rangedNumber(screen.colorDepth, 1, 128, { integer: true }),
+        orientation: resolveOrientation(),
+        display_mode: resolveDisplayMode(),
+        prefers_dark: !!window.matchMedia?.("(prefers-color-scheme: dark)")?.matches,
+        prefers_reduced_motion: !!window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches,
+
+        ...browser,
+        language: nav.languages?.find(Boolean) || nav.language || null,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || null,
+        touch_points: rangedNumber(nav.maxTouchPoints, 0, 100, { integer: true }),
+        capabilities: {
+            wasm: typeof WebAssembly !== "undefined",
+            service_worker: "serviceWorker" in nav,
+            webgl: supportsWebGl(),
+        },
+        network_type: String(connection.type || "unknown").toLowerCase(),
+        network_effective_type: String(connection.effectiveType || "unknown").toLowerCase(),
+    });
+}
+
+function getReportSignature() {
+    const uid = User.isLogin() ? Number(User.getInfo()?.uid || localStorage.getItem("uid") || 0) : 0;
+    return `${uid}:${resolveWebVersion() || "unknown"}`;
+}
+
+export async function reportClientStat({ force = false } = {}) {
+    if (reportTask) return reportTask;
+
+    reportTask = (async () => {
+        const today = chinaDate();
+        const signature = getReportSignature();
+        if (
+            !force &&
+            localStorage.getItem(REPORT_DATE_KEY) === today &&
+            localStorage.getItem(REPORT_SIGNATURE_KEY) === signature
+        ) {
+            return { reported: false, reason: "already_reported" };
+        }
+
+        const payload = buildClientStatPayload(ensureClientInstanceId());
+        const response = await $cms({ mute: true }).post("/api/cms/system/stat/heartbeat", payload, {
+            timeout: 10000,
+            skipForbiddenSessionClear: true,
+        });
+        localStorage.setItem(REPORT_DATE_KEY, today);
+        localStorage.setItem(REPORT_SIGNATURE_KEY, signature);
+        return { reported: true, data: response?.data?.data || null, payload };
+    })().finally(() => {
+        reportTask = null;
+    });
+
+    return reportTask;
+}
+
+function isLocalhost() {
+    return ["localhost", "127.0.0.1", "::1"].includes(window.location.hostname);
+}
+
+function startupDelay() {
+    if (process.env.NODE_ENV !== "production" || isLocalhost()) return 0;
+    return Math.floor(STARTUP_DELAY_MIN + Math.random() * (STARTUP_DELAY_MAX - STARTUP_DELAY_MIN));
+}
+
+export function scheduleClientStatReport({ force = false, delay = startupDelay() } = {}) {
+    if (scheduledTimer) {
+        if (!force) return;
+        window.clearTimeout(scheduledTimer);
+    }
+
+    scheduledTimer = window.setTimeout(() => {
+        scheduledTimer = null;
+        reportClientStat({ force }).catch(() => {
+            // 统计失败不影响公共头和宿主页面；未写成功标记时，下次恢复可见会继续尝试。
+        });
+    }, delay);
+}
+
+export function installClientStatReporting() {
+    scheduleClientStatReport({ force: isLocalhost() });
+}
+
+export function checkClientStatOnVisible() {
+    scheduleClientStatReport();
+}

package/tests/client-stat.test.js

@@ -0,0 +1,31 @@
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..");
+const commonHeader = fs.readFileSync(path.join(root, "src/CommonHeader.vue"), "utf8");
+const clientStat = fs.readFileSync(path.join(root, "src/utils/client-stat.js"), "utf8");
+
+function assert(condition, message) {
+    if (!condition) throw new Error(message);
+}
+
+assert(commonHeader.includes("installClientStatReporting()"), "CommonHeader should install client statistics");
+assert(
+    commonHeader.includes("checkClientStatOnVisible()") && commonHeader.includes("visibilitychange"),
+    "CommonHeader should retry statistics when the page becomes visible"
+);
+assert(clientStat.includes('const INSTANCE_ID_KEY = "jx3box:device_id"'), "PC should reuse the client instance id key");
+assert(clientStat.includes('product: "jx3box"'), "heartbeat should identify the JX3BOX product");
+assert(clientStat.includes('const STAT_SDK_VERSION = "v0.0.1"'), "statistics SDK version should remain explicit");
+assert(clientStat.includes('return "pc_web"'), "desktop browser traffic should report pc_web");
+assert(clientStat.includes('return "mobile_web"'), "mobile browsers visiting PC pages should report mobile_web");
+assert(clientStat.includes("/api/cms/system/stat/heartbeat"), "heartbeat should use the new statistics endpoint");
+assert(clientStat.includes("$cms({ mute: true })"), "heartbeat should reuse the authenticated CMS client");
+assert(
+    clientStat.indexOf("localStorage.setItem(REPORT_DATE_KEY") > clientStat.indexOf("await $cms"),
+    "successful report markers must only be stored after the request resolves"
+);
+assert(!clientStat.includes("current_uid:"), "heartbeat payload must not report uid");
+assert(!clientStat.includes("ip:"), "heartbeat payload must not report ip");
+
+console.log("client statistics checks passed");