@jx3box/jx3box-ui 2.4.0 → 2.4.1

package/docs/agents/client-stat.md

@@ -3,11 +3,14 @@
 `CommonHeader` 为引用公共头的普通 PC 项目接入新版客户端实例 heartbeat。
 
 - 接口：`POST /api/cms/system/stat/heartbeat`。
-- SDK 版本：当前固定为 `v0.0.1`，只在统计组件协议升级时调整。
+- SDK 版本：当前固定为 `v0.0.2`，只在统计组件协议升级时调整。
 - 实例 ID：复用本地 `jx3box:device_id` 随机 UUID；不使用硬件指纹。
 - 普通桌面浏览器为 `client=pc_web`；手机浏览器访问 PC 页面为 `client=mobile_web`。
 - 小程序和 App 容器按统一客户端枚举识别；游戏内页面的 `pc_game/mobile_game` 由对应页面以后主动指定，不在公共头推断。
+- 通用客户端识别与 JX3BOX 业务规则分离：`src/utils/client-stat-business.js` 负责项目专属覆盖；UA 包含 `jianghudaily` 时不区分大小写地上报 `mobile_game`，以后抽公共包时以业务适配器注入。
 - UID 不进入 payload，由 service-cms 从可选 JWT 中读取；IP 同样由服务端反代请求头读取。
 - 生产环境启动后随机延迟 3～15 秒，同一北京时间日期、UID 和 Web 版本只成功上报一次。
+- Web 版本按 `window.__APP_VERSION__`、`process.env.VUE_APP_VERSION`、`process.env.VITE_APP_VERSION` 依次降级读取；均不存在时使用 `unknown` 参与本地签名，并省略 heartbeat payload 中的 `web_version`。
 - 页面恢复可见时补检；请求失败不写成功标记，也不影响公共头和宿主页面。
 - localhost 每次公共头重新创建都强制上报，方便联调。
+- UA 命中 ArkWeb/HarmonyOS/OpenHarmony 时识别为 `platform=harmony`；明确的 `Phone/Tablet; OpenHarmony x.x` 会在上报前规范为 `os_name=OpenHarmony`、对应版本和设备类型，不保留设备型号或完整固件展示串。

package/package.json

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

package/src/utils/client-stat.js

@@ -1,11 +1,12 @@
 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";
+import { applyJx3boxClientStatRules } from "./client-stat-business";
 
 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 STAT_SDK_VERSION = "v0.0.2";
 const STARTUP_DELAY_MIN = 3 * 1000;
 const STARTUP_DELAY_MAX = 15 * 1000;
 
@@ -69,6 +70,7 @@ function resolveChannel() {
 }
 
 function resolvePlatform(userAgent, navigatorPlatform) {
+    if (/ArkWeb|HarmonyOS|OpenHarmony/i.test(userAgent)) return "harmony";
     if (/iPhone|iPad|iPod/i.test(userAgent)) return "ios";
     if (/Android/i.test(userAgent)) return "android";
     if (/Windows/i.test(userAgent)) return "windows";
@@ -77,6 +79,16 @@ function resolvePlatform(userAgent, navigatorPlatform) {
     return "unknown";
 }
 
+function normalizeHarmonySystem(platform, userAgent) {
+    if (platform !== "harmony") return { os_name: platform, os_version: null };
+    const openHarmony = String(userAgent || "").match(/\b(?:Phone|Tablet);\s*OpenHarmony\s+([0-9]+(?:\.[0-9]+)*)\b/i);
+    if (openHarmony) return { os_name: "OpenHarmony", os_version: openHarmony[1] };
+    return {
+        os_name: /HarmonyOS/i.test(userAgent) ? "HarmonyOS" : "OpenHarmony",
+        os_version: null,
+    };
+}
+
 function resolveClient(platform, userAgent) {
     if (isApp()) return "app";
     if (isMiniProgram() || /miniprogram/i.test(userAgent)) return "miniprogram";
@@ -130,13 +142,7 @@ function resolveDisplayMode() {
 }
 
 function resolveWebVersion() {
-    return (
-        window.__JX3BOX_VERSION__ ||
-        window.__APP_VERSION__ ||
-        process.env.VUE_APP_VERSION ||
-        process.env.VUE_APP_BUILD_VERSION ||
-        null
-    );
+    return window.__APP_VERSION__ || process.env.VUE_APP_VERSION || process.env.VITE_APP_VERSION || null;
 }
 
 export function buildClientStatPayload(instanceId) {
@@ -145,20 +151,25 @@ export function buildClientStatPayload(instanceId) {
     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 context = applyJx3boxClientStatRules(
+        { platform, client: resolveClient(platform, userAgent) },
+        { userAgent }
+    );
     const browser = parseBrowser(userAgent);
+    const system = normalizeHarmonySystem(context.platform, userAgent);
 
     return compactPayload({
         instance_id: instanceId,
         product: "jx3box",
-        client,
-        platform,
+        client: context.client,
+        platform: context.platform,
         domain: window.location.hostname,
         channel: resolveChannel(),
         web_version: resolveWebVersion(),
         sdk_version: STAT_SDK_VERSION,
 
-        os_name: platform,
+        os_name: system.os_name,
+        os_version: system.os_version,
         device_type: ["ios", "android"].includes(platform) ? (/iPad|Tablet/i.test(userAgent) ? "tablet" : "phone") : "desktop",
         architecture: /arm64|aarch64/i.test(userAgent)
             ? "arm64"

package/tests/client-stat.test.js

@@ -4,6 +4,7 @@ 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");
+const clientStatBusiness = fs.readFileSync(path.join(root, "src/utils/client-stat-business.js"), "utf8");
 
 function assert(condition, message) {
     if (!condition) throw new Error(message);
@@ -16,9 +17,25 @@ assert(
 );
 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('const STAT_SDK_VERSION = "v0.0.2"'), "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("applyJx3boxClientStatRules"),
+    "generic client detection should pass through the JX3BOX business rule adapter"
+);
+assert(clientStatBusiness.includes("/jianghudaily/i"), "Jianghu Daily UA matching should be case-insensitive");
+assert(clientStatBusiness.includes('client: "mobile_game"'), "Jianghu Daily should report mobile_game");
+assert(
+    clientStat.includes("/ArkWeb|HarmonyOS|OpenHarmony/i") && clientStat.includes('os_name: "OpenHarmony"'),
+    "PC statistics should normalize OpenHarmony before reporting"
+);
+assert(
+    clientStat.includes("window.__APP_VERSION__ || process.env.VUE_APP_VERSION || process.env.VITE_APP_VERSION"),
+    "web version should use the shared app version fallback chain"
+);
+assert(!clientStat.includes("__JX3BOX_VERSION__"), "shared statistics must not depend on a JX3BOX-specific version global");
+assert(!clientStat.includes("VUE_APP_BUILD_VERSION"), "web version should not use the deprecated build-version fallback");
 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(