@jx3box/jx3box-ui 2.3.9 → 2.3.10

package/docs/agents/global-config-cdn.md

@@ -0,0 +1,30 @@
+# 全局配置 CDN 读取约定
+
+## 背景
+
+`/api/cms/config` 中有一批低频更新的全局配置，后端会构建到 CDN JSON：
+
+```txt
+https://cdn.jx3box.com/config/global.json
+```
+
+这类配置在公共组件库和其它魔盒前端项目中应优先读取 CDN 静态 JSON，减少页面内多组件重复请求 config 接口。
+
+## 实现原则
+
+- 在项目服务层封装统一 helper，不要让具体组件直接请求 CDN。
+- helper 优先读取内存缓存，再读 `sessionStorage`，没有缓存时请求 `global.json`。
+- 同一页面生命周期内要复用 pending promise，避免多个组件并发触发多次请求。
+- 对旧调用保持返回结构兼容，比如继续返回 `{ key, val }` 或数组，减少组件改动面。
+- CDN 请求失败、缺少目标 key、或查询不适合静态 JSON 时，fallback 到旧 `/api/cms/config`。
+- 公共头可以预热全局配置，但其它组件不能隐式依赖公共头加载顺序。
+
+## 本仓落点
+
+- `service/header.js`：`getGlobalConfig()` 负责读取 CDN JSON，并做内存缓存、`sessionStorage` 缓存、TTL 和 pending promise 复用。
+- `service/cms.js`：`getConfig()` 优先从 `getGlobalConfig()` 合成旧接口兼容结构，失败时回退旧接口。
+- `service/thx.js`：`getBoxcoinStatus()` 走统一 `getConfig({ key: "boxcoin" })`。
+
+## 适用范围
+
+后续其它魔盒项目如果提到“全局配置读取换 CDN”或“config 改成读 `global.json`”，默认按本约定处理：优先服务层兼容改造，组件侧尽量少动，迁移期保留旧接口 fallback。

package/package.json

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

package/service/cms.js

@@ -1,6 +1,10 @@
 import { $cms } from "@jx3box/jx3box-common/js/api";
 import axios from "axios";
 import JX3BOX from "@jx3box/jx3box-common/data/jx3box.json";
+import { getGlobalConfig } from "./header";
+
+const APP_CONFIG_KEYS = ["android_apk", "android_versions", "app_logo", "app_version_desc", "apple_url", "harmony_url"];
+
 function getPostAuthors(post_id) {
     return $cms({ mute: true }).get(`/api/cms/post/${post_id}/authors`);
 }
@@ -80,8 +84,7 @@ function getTopicBucket(params) {
     return $cms().get(`/api/cms/topic/bucket`, { params });
 }
 
-// 获取config
-function getConfig(params) {
+function getLegacyConfig(params) {
     return $cms()
         .get(`/api/cms/config`, { params })
         .then((res) => {
@@ -89,6 +92,51 @@ function getConfig(params) {
         });
 }
 
+function normalizeConfigItem(key, value, subtype = "") {
+    return {
+        key,
+        val: value,
+        subtype,
+    };
+}
+
+function getConfigFromGlobal(params = {}) {
+    return getGlobalConfig().then((config) => {
+        if (!config || typeof config !== "object") return null;
+
+        if (params.key) {
+            const keys = String(params.key)
+                .split(",")
+                .map((key) => key.trim())
+                .filter(Boolean);
+
+            if (!keys.length) return null;
+            if (!keys.every((key) => Object.prototype.hasOwnProperty.call(config, key))) return null;
+
+            const items = keys.map((key) => normalizeConfigItem(key, config[key]));
+            return keys.length === 1 ? items[0] : items;
+        }
+
+        if (params.subtype === "app") {
+            if (!APP_CONFIG_KEYS.every((key) => Object.prototype.hasOwnProperty.call(config, key))) return null;
+            return APP_CONFIG_KEYS.map((key) => normalizeConfigItem(key, config[key], "app"));
+        }
+
+        return null;
+    });
+}
+
+// 获取config
+function getConfig(params = {}) {
+    return getConfigFromGlobal(params)
+        .then((data) => {
+            return data || getLegacyConfig(params);
+        })
+        .catch(() => {
+            return getLegacyConfig(params);
+        });
+}
+
 // 获取用户config
 function getUserConfig(params) {
     return $cms()

package/service/header.js

@@ -2,6 +2,47 @@ import axios from "axios";
 import { $cms, $next } from "@jx3box/jx3box-common/js/api";
 import JX3BOX from "@jx3box/jx3box-common/data/jx3box.json";
 
+const GLOBAL_CONFIG_STORAGE_KEY = "jx3box:global-config";
+const GLOBAL_CONFIG_TTL = 6 * 60 * 60 * 1000;
+let globalConfigCache = null;
+let globalConfigPending = null;
+
+function getGlobalConfigUrl() {
+    const root = JX3BOX.__ossRoot || "https://cdn.jx3box.com/";
+    return `${root.replace(/\/?$/, "/")}config/global.json`;
+}
+
+function getNow() {
+    return Date.now ? Date.now() : new Date().getTime();
+}
+
+function readGlobalConfigStorage() {
+    if (typeof sessionStorage === "undefined") return null;
+    try {
+        const raw = sessionStorage.getItem(GLOBAL_CONFIG_STORAGE_KEY);
+        if (!raw) return null;
+        const cache = JSON.parse(raw);
+        if (!cache?.data || !cache?.time) return null;
+        if (getNow() - cache.time > GLOBAL_CONFIG_TTL) return null;
+        return cache.data;
+    } catch (e) {
+        return null;
+    }
+}
+
+function writeGlobalConfigStorage(data) {
+    if (typeof sessionStorage === "undefined") return;
+    try {
+        sessionStorage.setItem(
+            GLOBAL_CONFIG_STORAGE_KEY,
+            JSON.stringify({
+                time: getNow(),
+                data,
+            })
+        );
+    } catch (e) {}
+}
+
 function getLetter() {
     return $next({ mute: true }).get("/api/letter/unread/count");
 }
@@ -34,9 +75,28 @@ function getGames() {
 
 // 获取全局配置
 function getGlobalConfig() {
-    return axios.get(`${JX3BOX.__ossRoot}config/global.json`).then((res) => {
-        return res.data;
-    });
+    if (globalConfigCache) return Promise.resolve(globalConfigCache);
+
+    const storageConfig = readGlobalConfigStorage();
+    if (storageConfig) {
+        globalConfigCache = storageConfig;
+        return Promise.resolve(globalConfigCache);
+    }
+
+    if (!globalConfigPending) {
+        globalConfigPending = axios
+            .get(getGlobalConfigUrl())
+            .then((res) => {
+                globalConfigCache = res.data || {};
+                writeGlobalConfigStorage(globalConfigCache);
+                return globalConfigCache;
+            })
+            .finally(() => {
+                globalConfigPending = null;
+            });
+    }
+
+    return globalConfigPending;
 }
 
 export { getLetter, getMsg, getNav, getPanel, getBox, getMenu, getGames, getGlobalConfig };

package/service/thx.js

@@ -1,4 +1,5 @@
-import { $pay, $cms } from "@jx3box/jx3box-common/js/api";
+import { $pay } from "@jx3box/jx3box-common/js/api";
+import { getConfig } from "./cms";
 
 function getPostBoxcoinRecords(postType, postId, params) {
     return $pay().get(`/api/inspire/article/${postType}/${postId}/history`, {
@@ -23,10 +24,12 @@ function getPostBoxcoinConfig(postType) {
 }
 
 function getBoxcoinStatus() {
-    return $cms().get(`/api/cms/config`, {
-        params: {
-            key: "boxcoin",
-        },
+    return getConfig({ key: "boxcoin" }).then((data) => {
+        return {
+            data: {
+                data,
+            },
+        };
     });
 }