@jx3box/jx3box-ui 2.3.10 → 2.3.12

package/.storybook/storybookMocks.js

@@ -48,10 +48,18 @@ function respond(config, data, status = 200) {
 }
 
 function mockCmsConfig(key) {
+    if (String(key || '').includes(',')) {
+        return String(key)
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean)
+            .map((item) => ({ key: item, ...mockCmsConfig(item) }));
+    }
     if (key === 'boxcoin') return { val: 1 };
     if (key === 'admin_boxcoin_visible') return { val: 1 };
     if (key === 'level_has_gift_permission') return { val: 0 };
     if (key === 'comment_strict') return { val: 0 };
+    if (key === 'user_profile_ready') return { val: 1 };
     return { val: '' };
 }
 
@@ -68,6 +76,99 @@ export function resolveStorybookMock(config) {
         return respond(config, { data: mockCmsConfig(params.key) });
     }
 
+    if (method === 'get' && path === '/api/cms/user/my/account/status') {
+        return respond(config, {
+            data: {
+                has_phone: false,
+                has_email: false,
+                email_verified: false,
+                has_verified_email: false,
+                has_password: false,
+            },
+        });
+    }
+
+    if (method === 'get' && path === '/api/letter/unread/count') {
+        return respond(config, { data: 0 });
+    }
+
+    if (method === 'get' && path === '/api/next2/userdata/messages/unread_total') {
+        return respond(config, { data: 0 });
+    }
+
+    if (method === 'get' && path === '/api/cms/user/conf') {
+        return respond(config, { data: null });
+    }
+
+    if (method === 'get' && path === '/api/cms/user/my/info') {
+        return respond(config, {
+            data: {
+                uid: 8,
+                name: 'Storybook用户',
+                group: 1,
+                token: 'storybook-token',
+                status: 0,
+                bind_wx: 0,
+                avatar: 'https://cdn.jx3box.com/upload/avatar/2022/3/2/8_9860765.png',
+            },
+        });
+    }
+
+    if (method === 'get' && path === '/api/cms/config/menu/panel') {
+        return respond(config, {
+            data: {
+                val: [
+                    {
+                        key: 'featureUpdate',
+                        label: '功能更新',
+                        link: '/notice',
+                        icon: 'notice.svg',
+                        remark: 'feature',
+                        meta: 'storybook-feature',
+                    },
+                    {
+                        key: 'manageCenter',
+                        label: '后台管理',
+                        link: '/os',
+                        icon: 'cube.svg',
+                        onlyAdmin: true,
+                    },
+                ],
+            },
+        });
+    }
+
+    if (method === 'get' && path === '/api/cms/user/my/meta') {
+        return respond(config, { data: null });
+    }
+
+    if (method === 'post' && path === '/api/cms/user/account/email/logout') {
+        return respond(config, { data: true });
+    }
+
+    if (method === 'post' && path === '/api/personal/task/everyday/sign-in') {
+        return respond(config, { code: 0, data: true });
+    }
+
+    if (method === 'get' && path === '/api/vip/i') {
+        return respond(config, {
+            data: {
+                was_vip: 0,
+                expire_date: '1970-02-02T16:00:00.000Z',
+                total_day: 0,
+                was_pro: 0,
+                pro_expire_date: '1970-02-02T16:00:00.000Z',
+                pro_total_day: 0,
+                rename_card_count: 0,
+                had_renamed: 0,
+                namespace_card_count: 0,
+                box_coin: 0,
+                points: 0,
+                experience: 0,
+            },
+        });
+    }
+
     if (method === 'get' && path.match(/^\/api\/cms\/post\/\d+\/authors$/)) {
         return respond(config, { data: mockCreators });
     }

package/docs/agents/auth-token-refresh.md

@@ -0,0 +1,56 @@
+# Auth token refresh
+
+PC 端自动续期挂在公共头 `src/CommonHeader.vue`。这个组件会被各 PC 页面引用，因此不要把 refresh 逻辑散到各业务页面。
+
+## Source of truth
+
+- 续期接口：`POST /api/cms/user/account/token/refresh`
+- service：`service/cms.js#refreshAuth`
+- 续期工具：`src/utils/auth-token-refresh.js`
+- 触发组件：`src/CommonHeader.vue`
+
+## 触发点
+
+- 公共头初始化时，如果 `User.isLogin()` 为 true，检查一次。
+- 页面从后台恢复可见时，监听 `visibilitychange`，在 `document.visibilityState === "visible"` 时检查一次。
+
+检查函数会先解析本地 JWT payload，未进入续期窗口时不会请求后端。
+
+## 续期窗口
+
+当前规则：
+
+- token 距离 `exp` 小于等于 7 天。
+- token 距离 `iat` 至少 1 天。
+- token 已经过期时不刷新。
+- 同一时间只允许一个 refresh 请求在飞。
+
+## PC 账号切换注意事项
+
+PC 公共库存在马甲切换：
+
+- 马甲缓存 key：`jx3box-alternate-{uid}`
+- 当前请求 token 读取优先级：`__token` 优先于 `token`
+
+因此 refresh 成功后必须同时更新：
+
+- `token`
+- `__token`
+- `created_at`
+- 当前激活账号的 `jx3box-alternate-{uid}` 记录
+
+否则用户切换马甲时可能拿回旧 token，或者后续请求继续优先使用旧 `__token`。
+
+## 自动续期开关
+
+默认开启。可通过 localStorage 关闭：
+
+```js
+localStorage.setItem("jx3box:auto_refresh_token", "false");
+```
+
+值为 `"false"` 或 `"0"` 时不自动续期；其它情况按默认开启处理。
+
+## 失败语义
+
+自动续期失败不主动登出，也不阻断公共头渲染。后续业务请求如果发现 token 过期或无权限，仍按宿主项目既有鉴权失败逻辑处理。

package/package.json

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

package/service/cms.js

@@ -167,7 +167,7 @@ function setUserMeta(key, data) {
 
 // 刷新凭证
 function refreshAuth() {
-    return $cms().post(`/api/cms/user/account/email/refresh`);
+    return $cms().post(`/api/cms/user/account/token/refresh`);
 }
 
 function getUserHonor(uid) {
@@ -202,6 +202,14 @@ function getUserPermission() {
     return $cms().get(`/api/cms/account/permission/i`);
 }
 
+function getMyAccountStatus() {
+    return $cms({ mute: true })
+        .get(`/api/cms/user/my/account/status`)
+        .then((res) => {
+            return res.data.data;
+        });
+}
+
 export {
     getPost,
     getPostAuthors,
@@ -227,6 +235,7 @@ export {
     uploadFile,
     refreshQQBotImage,
     getUserPermission,
+    getMyAccountStatus,
     getUserConfig,
     setUserConfig,
 };

package/src/CommonHeader.vue

@@ -26,11 +26,41 @@
                 :header-config="headerConfig"
                 :header-config-loaded="headerConfigLoaded"
                 :header-config-managed="true"
+                :account-ready-issues="accountReadyIssues"
+                :account-ready-incomplete="accountReadyIncomplete"
+                @open-account-ready="openAccountReadyDialog"
             />
         </div>
         <header-box v-if="isMobile" class="c-header__box c-header-jx3box" :overlayEnable="overlayEnable" />
         <header-box2 v-else class="c-header__box c-header__box--desktop" />
     </header>
+    <el-dialog
+        v-model="accountReadyDialogVisible"
+        class="c-header-account-ready"
+        width="min(92vw, 520px)"
+        title="⚠️ 完善账号安全信息"
+        append-to-body
+        @close="markAccountReadyDismissed"
+    >
+        <div class="c-header-account-ready__body">
+            <p class="u-desc">为了保障 App 登录、账号找回和卡密等功能正常使用，请先补全以下账号安全信息。</p>
+            <div class="u-list">
+                <div class="u-item" v-if="accountReadyIssues.includes('contact')">
+                    <div class="u-title">绑定邮箱和手机号</div>
+                    <div class="u-text">当前账号的邮箱或手机号尚未完善。请完成手机号绑定，并绑定且验证邮箱，否则后续可能无法找回账号。</div>
+                    <el-button type="primary" @click="goAccountReady('/dashboard/notice')">去绑定</el-button>
+                </div>
+                <div class="u-item" v-if="accountReadyIssues.includes('password')">
+                    <div class="u-title">设置登录密码</div>
+                    <div class="u-text">当前账号还没有设置密码。未设置密码时，可能无法使用卡密等功能，也无法在 App 中通过账号密码登录。</div>
+                    <el-button type="primary" @click="goAccountReady('/dashboard/pwd')">去设置</el-button>
+                </div>
+            </div>
+        </div>
+        <template #footer>
+            <el-button @click="accountReadyDialogVisible = false">7天后再说</el-button>
+        </template>
+    </el-dialog>
 </template>
 
 <script>
@@ -53,11 +83,15 @@ import miniprogram from "@jx3box/jx3box-common/data/miniprogram.json";
 
 // 数据
 import { getGlobalConfig } from "../service/header";
-import { getConfig } from "../service/cms";
+import { getConfig, getMyAccountStatus } from "../service/cms";
+import { refreshTokenIfNeeded } from "./utils/auth-token-refresh";
 import User from "@jx3box/jx3box-common/js/user.js";
 import JX3BOX from "@jx3box/jx3box-common/data/jx3box.json";
 
-const HEADER_CONFIG_KEYS = ["important_notice", "important_notice_url", "vip", "mall"];
+const HEADER_CONFIG_KEYS = ["important_notice", "important_notice_url", "vip", "mall", "user_profile_ready"];
+const ACCOUNT_READY_STORAGE_PREFIX = "jx3box:account-ready-dismissed-until";
+const ACCOUNT_READY_COMPLETE_STORAGE_PREFIX = "jx3box:account-ready-complete";
+const ACCOUNT_READY_DISMISS_INTERVAL = 7 * 24 * 60 * 60 * 1000;
 
 export default {
     name: "Header",
@@ -80,6 +114,10 @@ export default {
             asset: {},
             headerConfig: {},
             headerConfigLoaded: false,
+            accountReadyDialogVisible: false,
+            accountReadyIssues: [],
+            accountReadyIncomplete: false,
+            accountReadyChecking: false,
         };
     },
     computed: {
@@ -156,6 +194,8 @@ export default {
 
             if (User.isLogin()) {
                 this.loadAsset();
+                this.refreshAuthToken();
+                this.initAccountReadyState();
             }
 
             // 获取全局配置
@@ -196,6 +236,18 @@ export default {
             });
         },
 
+        refreshAuthToken: function () {
+            refreshTokenIfNeeded().catch(() => {
+                // 自动续期失败不影响公共头渲染，后续鉴权请求会按既有逻辑处理登录态。
+            });
+        },
+
+        handleVisibilityChange: function () {
+            if (document.visibilityState === "visible") {
+                this.refreshAuthToken();
+            }
+        },
+
         getUrlParam(name) {
             var reg = new RegExp("(^|&)" + name + "=([^&]*)(&|$)");
             var r = window.location.search.substr(1).match(reg);
@@ -225,6 +277,7 @@ export default {
                 })
                 .finally(() => {
                     this.headerConfigLoaded = true;
+                    this.checkAccountReadiness();
                 });
         },
         normalizeHeaderConfig: function (data) {
@@ -238,6 +291,138 @@ export default {
             }
             return data?.key ? { [data.key]: data } : {};
         },
+        getConfigValue: function (key) {
+            const config = this.headerConfig?.[key];
+            return config?.val ?? config;
+        },
+        isAccountReadyEnabled: function () {
+            return String(this.getConfigValue("user_profile_ready") || "").trim() === "1";
+        },
+        getAccountReadyUserId: function () {
+            const uid = User.getInfo()?.uid || localStorage.getItem("uid") || "0";
+            return uid || "0";
+        },
+        getAccountReadyStorageKey: function () {
+            return `${ACCOUNT_READY_STORAGE_PREFIX}:${this.getAccountReadyUserId()}`;
+        },
+        getAccountReadyCompleteStorageKey: function () {
+            return `${ACCOUNT_READY_COMPLETE_STORAGE_PREFIX}:${this.getAccountReadyUserId()}`;
+        },
+        isAccountReadyCompleted: function () {
+            try {
+                return !!localStorage.getItem(this.getAccountReadyCompleteStorageKey());
+            } catch (e) {
+                return false;
+            }
+        },
+        markAccountReadyCompleted: function () {
+            try {
+                localStorage.setItem(this.getAccountReadyCompleteStorageKey(), String(Date.now()));
+            } catch (e) {}
+            this.clearAccountReadyDismissed();
+        },
+        initAccountReadyState: function () {
+            this.accountReadyIncomplete = !this.isAccountReadyCompleted();
+        },
+        isAccountReadyDismissed: function () {
+            try {
+                const key = this.getAccountReadyStorageKey();
+                const until = Number(localStorage.getItem(key));
+                if (!until) return false;
+                if (Date.now() < until) return true;
+                localStorage.removeItem(key);
+            } catch (e) {}
+            return false;
+        },
+        markAccountReadyDismissed: function () {
+            if (!User.isLogin() || !this.accountReadyIssues.length) return;
+            try {
+                localStorage.setItem(this.getAccountReadyStorageKey(), String(Date.now() + ACCOUNT_READY_DISMISS_INTERVAL));
+            } catch (e) {}
+        },
+        buildAccountReadyIssues: function (status = {}) {
+            const issues = [];
+            if (!status.has_phone || !status.has_verified_email) {
+                issues.push("contact");
+            }
+            if (!status.has_password) {
+                issues.push("password");
+            }
+            return issues;
+        },
+        isAccountReadyTargetPage: function () {
+            return ["/dashboard/notice", "/dashboard/pwd"].some((path) => location.pathname.startsWith(path));
+        },
+        checkAccountReadiness: function () {
+            if (this.accountReadyChecking || !User.isLogin()) return;
+            if (this.isAccountReadyCompleted()) {
+                this.accountReadyIssues = [];
+                this.accountReadyIncomplete = false;
+                this.accountReadyDialogVisible = false;
+                return;
+            }
+
+            this.accountReadyChecking = true;
+            getMyAccountStatus()
+                .then((status) => {
+                    const issues = this.buildAccountReadyIssues(status);
+                    if (!issues.length) {
+                        this.accountReadyIssues = [];
+                        this.accountReadyIncomplete = false;
+                        this.accountReadyDialogVisible = false;
+                        this.markAccountReadyCompleted();
+                        return;
+                    }
+                    this.accountReadyIssues = issues;
+                    this.accountReadyIncomplete = true;
+                    if (this.isAccountReadyEnabled() && !this.isAccountReadyTargetPage() && !this.isAccountReadyDismissed()) {
+                        this.accountReadyDialogVisible = true;
+                    }
+                })
+                .catch(() => {})
+                .finally(() => {
+                    this.accountReadyChecking = false;
+                });
+        },
+        clearAccountReadyDismissed: function () {
+            try {
+                localStorage.removeItem(this.getAccountReadyStorageKey());
+            } catch (e) {}
+        },
+        openAccountReadyDialog: function (issues) {
+            if (Array.isArray(issues) && issues.length) {
+                this.accountReadyIssues = issues;
+            }
+            if (this.accountReadyIssues.length) {
+                this.accountReadyDialogVisible = true;
+                return;
+            }
+            if (!User.isLogin() || this.isAccountReadyCompleted()) return;
+
+            this.accountReadyChecking = true;
+            getMyAccountStatus()
+                .then((status) => {
+                    const freshIssues = this.buildAccountReadyIssues(status);
+                    if (!freshIssues.length) {
+                        this.accountReadyIssues = [];
+                        this.accountReadyIncomplete = false;
+                        this.accountReadyDialogVisible = false;
+                        this.markAccountReadyCompleted();
+                        return;
+                    }
+                    this.accountReadyIssues = freshIssues;
+                    this.accountReadyIncomplete = true;
+                    this.accountReadyDialogVisible = true;
+                })
+                .catch(() => {})
+                .finally(() => {
+                    this.accountReadyChecking = false;
+                });
+        },
+        goAccountReady: function (url) {
+            this.markAccountReadyDismissed();
+            window.open(url, "_blank", "noopener");
+        },
         updateScreen() {
             this.isMobile = window.innerWidth <= 768;
         },
@@ -245,6 +430,7 @@ export default {
     created: function () {
         this.init();
         window.addEventListener("resize", this.updateScreen, { passive: true });
+        document.addEventListener("visibilitychange", this.handleVisibilityChange);
 
         if (this.overlayEnable) {
             this.__overlayScrollHandler = _.throttle(() => {
@@ -256,6 +442,7 @@ export default {
     },
     beforeUnmount: function () {
         window.removeEventListener("resize", this.updateScreen);
+        document.removeEventListener("visibilitychange", this.handleVisibilityChange);
         if (this.__overlayScrollHandler) {
             window.removeEventListener("scroll", this.__overlayScrollHandler);
             this.__overlayScrollHandler.cancel && this.__overlayScrollHandler.cancel();
@@ -296,6 +483,62 @@ export default {
         .flex;
     }
 }
+
+.c-header-account-ready {
+    border-radius: 10px;
+
+    .el-dialog__header {
+        margin-right: 0;
+        padding: 24px 24px 10px;
+    }
+
+    .el-dialog__title {
+        font-weight: 700;
+        color: #222;
+    }
+
+    .el-dialog__body {
+        padding: 8px 24px 4px;
+    }
+
+    .el-dialog__footer {
+        padding: 12px 24px 22px;
+    }
+
+    &__body {
+        .u-desc {
+            margin: 0 0 16px;
+            color: #666;
+            line-height: 1.7;
+        }
+
+        .u-list {
+            display: flex;
+            flex-direction: column;
+            gap: 12px;
+        }
+
+        .u-item {
+            padding: 14px 16px;
+            border: 1px solid #e8edf5;
+            border-radius: 8px;
+            background: #f8fbff;
+        }
+
+        .u-title {
+            margin-bottom: 6px;
+            font-size: 15px;
+            font-weight: 700;
+            color: #1f2937;
+        }
+
+        .u-text {
+            margin-bottom: 12px;
+            color: #5f6b7a;
+            line-height: 1.7;
+        }
+    }
+}
 .c-header.isOverlay {
     background-color: rgba(0, 0, 0, 0.85);
 }

package/src/header/manage.vue

@@ -2,7 +2,7 @@
     <div class="c-header-panel c-header-manage" id="c-header-manage">
         <span class="u-post u-manage">
             <i class="u-icon u-icon-msg">
-                <i class="u-pop" style="display: none" v-show="showPop || !isAuth"></i>
+                <i class="u-pop" style="display: none" v-show="showPanelPop"></i>
                 <!-- <manageIcon class="u-add" /> -->
                 <img
                     class="u-add"
@@ -21,6 +21,16 @@
                         <span v-if="showPop" class="u-new">New!</span>
                         <span v-if="item.remark == 'auth' && !isAuth" class="u-new">New!</span>
                     </a>
+                    <a
+                        v-if="isFeaturePanelItem(item) && hasAccountReadyIssue"
+                        href="javascript:;"
+                        class="u-menu-item u-menu-item--account-ready"
+                        @click.prevent="openAccountReady"
+                    >
+                        <img :src="resolveImg(item.icon)" class="u-menu-icon" :alt="item.icon" />
+                        资料完善
+                        <span class="u-new u-new--important">重要</span>
+                    </a>
                 </li>
             </template>
             <template v-if="isTeammate">
@@ -86,7 +96,16 @@ export default {
             type: Boolean,
             default: false,
         },
+        accountReadyIssues: {
+            type: Array,
+            default: () => [],
+        },
+        accountReadyIncomplete: {
+            type: Boolean,
+            default: false,
+        },
     },
+    emits: ["open-account-ready"],
     computed: {
         userPanel: function () {
             return this.panel.filter((item) => {
@@ -101,6 +120,12 @@ export default {
         isAuth() {
             return User.isPhoneMember();
         },
+        hasAccountReadyIssue() {
+            return this.accountReadyIncomplete;
+        },
+        showPanelPop() {
+            return this.showPop || this.hasAccountReadyIssue;
+        },
     },
     mounted() {
         if (this.headerConfigLoaded) {
@@ -119,6 +144,9 @@ export default {
             if (item?.key) return this.$jx3boxT(`jx3boxUi.commonHeader.panel.${item.key}`, item.label || item.key);
             return item?.label || "";
         },
+        isFeaturePanelItem(item = {}) {
+            return item.remark === "feature" || !!item.meta || item.key === "featureUpdate" || item.label === "功能更新";
+        },
         loadPanel: async function () {
             try {
                 const panel = JSON.parse(sessionStorage.getItem("panel"));
@@ -172,6 +200,9 @@ export default {
                 this.showPop = false;
             }
         },
+        openAccountReady() {
+            this.$emit("open-account-ready", this.accountReadyIssues);
+        },
     },
 };
 </script>
@@ -240,5 +271,13 @@ export default {
         color: #fff;
         padding: 0px 6px;
     }
+
+    .u-new--important {
+        background-color: #f56c6c;
+    }
+
+    .u-menu-item--account-ready {
+        color: #f56c6c;
+    }
 }
 </style>

package/src/header/user.vue

@@ -23,6 +23,9 @@
                 :important-notice-url="headerConfig.important_notice_url"
                 :header-config-loaded="headerConfigLoaded"
                 :header-config-managed="headerConfigManaged"
+                :account-ready-issues="accountReadyIssues"
+                :account-ready-incomplete="accountReadyIncomplete"
+                @open-account-ready="$emit('open-account-ready', $event)"
             />
 
             <!-- 语言切换 -->
@@ -95,7 +98,16 @@ export default {
             type: Boolean,
             default: false,
         },
+        accountReadyIssues: {
+            type: Array,
+            default: () => [],
+        },
+        accountReadyIncomplete: {
+            type: Boolean,
+            default: false,
+        },
     },
+    emits: ["open-account-ready"],
     components: {
         message,
         publish,

package/src/stories/layout/CommonHeader.stories.js

@@ -37,3 +37,38 @@ export const Overlay = {
     },
     render: Default.render,
 };
+
+export const AccountReadyMock = {
+    args: {
+        overlayEnable: false,
+    },
+    render: (args) => ({
+        components: { CommonHeader },
+        setup() {
+            const now = Date.now();
+            localStorage.setItem('logged_in', 'true');
+            localStorage.setItem('created_at', String(now));
+            localStorage.setItem('token', 'storybook-token');
+            localStorage.setItem('uid', '8');
+            localStorage.setItem('group', '1');
+            localStorage.setItem('name', 'Storybook用户');
+            localStorage.setItem('status', '0');
+            localStorage.setItem('token_version', 'storybook');
+            localStorage.setItem('avatar', 'https://cdn.jx3box.com/upload/avatar/2022/3/2/8_9860765.png');
+            localStorage.removeItem('jx3box:account-ready-dismissed-until:8');
+            localStorage.removeItem('jx3box:account-ready-complete:8');
+            sessionStorage.removeItem('panel');
+
+            return { args };
+        },
+        template: `
+            <div style="min-height: 100vh; background: #f5f7fb;">
+                <CommonHeader v-bind="args" />
+                <main style="padding: 96px 32px;">
+                    <h1 style="margin: 0 0 12px; font-size: 28px;">公共头账号安全提醒 mock</h1>
+                    <p style="margin: 0; color: #666;">当前 mock 用户未绑定邮箱/手机，也未设置密码，公共头会自动弹出提醒。</p>
+                </main>
+            </div>
+        `,
+    }),
+};

package/src/utils/auth-token-refresh.js

@@ -0,0 +1,152 @@
+import User from "@jx3box/jx3box-common/js/user";
+import { refreshAuth } from "../../service/cms";
+
+const REFRESH_WINDOW_SECONDS = 7 * 24 * 60 * 60;
+const MIN_REFRESH_INTERVAL_SECONDS = 24 * 60 * 60;
+const AUTO_REFRESH_STORAGE_KEY = "jx3box:auto_refresh_token";
+
+let refreshTask = null;
+
+function canUseLocalStorage() {
+    return typeof localStorage !== "undefined";
+}
+
+function decodeBase64Url(value = "") {
+    const normalized = String(value).replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+
+    if (typeof atob === "function") {
+        return atob(padded);
+    }
+
+    return "";
+}
+
+export function parseJwtPayload(token = "") {
+    const parts = String(token || "").split(".");
+    if (parts.length < 2 || !parts[1]) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(decodeBase64Url(parts[1]));
+    } catch (e) {
+        return null;
+    }
+}
+
+export function isAutoTokenRefreshEnabled() {
+    if (!canUseLocalStorage()) {
+        return true;
+    }
+
+    const value = localStorage.getItem(AUTO_REFRESH_STORAGE_KEY);
+    return value !== "false" && value !== "0";
+}
+
+export function shouldRefreshToken(token = "", nowSeconds = Math.floor(Date.now() / 1000)) {
+    const payload = parseJwtPayload(token);
+    const exp = Number(payload?.exp || 0);
+    const iat = Number(payload?.iat || 0);
+
+    if (!exp || !iat) {
+        return false;
+    }
+
+    const remaining = exp - nowSeconds;
+    const tokenAge = nowSeconds - iat;
+
+    return remaining > 0 && remaining <= REFRESH_WINDOW_SECONDS && tokenAge >= MIN_REFRESH_INTERVAL_SECONDS;
+}
+
+function readCurrentToken() {
+    if (!canUseLocalStorage()) {
+        return User.getToken() || "";
+    }
+
+    return localStorage.getItem("__token") || localStorage.getItem("token") || User.getToken() || "";
+}
+
+function normalizeRefreshProfile(data = {}) {
+    const user = data.user || {};
+    const current = User.getInfo() || {};
+
+    return {
+        token: data.token || current.token || "",
+        uid: user.ID || user.id || data.uid || current.uid || 0,
+        group: user.user_group || user.group || data.group || current.group || 1,
+        name: user.display_name || user.name || data.name || current.name || "",
+        status: user.user_status || user.status || data.status || current.status || 0,
+        bind_wx: user.wechat_unionid ? 1 : data.bind_wx || current.bind_wx || 0,
+        avatar: user.user_avatar || user.avatar || data.avatar || current.avatar_origin || current.avatar || "",
+    };
+}
+
+function updateCurrentAlternate(profile = {}) {
+    if (!canUseLocalStorage() || !profile.uid || !profile.token) {
+        return;
+    }
+
+    const key = `jx3box-alternate-${profile.uid}`;
+    let alternate = {};
+
+    try {
+        alternate = JSON.parse(localStorage.getItem(key) || "{}") || {};
+    } catch (e) {
+        alternate = {};
+    }
+
+    localStorage.setItem(
+        key,
+        JSON.stringify({
+            ...alternate,
+            uid: profile.uid,
+            name: profile.name,
+            avatar: profile.avatar,
+            group: ~~profile.group,
+            bind_wx: ~~profile.bind_wx,
+            token: profile.token,
+            status: ~~profile.status,
+            created_at: Number(localStorage.getItem("created_at")) || Date.now(),
+        })
+    );
+}
+
+async function applyRefreshResult(data = {}) {
+    const profile = normalizeRefreshProfile(data);
+    if (!profile.token || !profile.uid) {
+        return false;
+    }
+
+    await User.update(profile);
+
+    // @jx3box/common User.update only writes token; keep __token in sync because common API reads it first.
+    localStorage.setItem("__token", profile.token);
+    updateCurrentAlternate(profile);
+    return true;
+}
+
+export async function refreshTokenIfNeeded(options = {}) {
+    const { force = false } = options;
+
+    if (!User.isLogin() || !isAutoTokenRefreshEnabled()) {
+        return false;
+    }
+
+    const token = readCurrentToken();
+    if (!token || (!force && !shouldRefreshToken(token))) {
+        return false;
+    }
+
+    if (refreshTask) {
+        return refreshTask;
+    }
+
+    refreshTask = refreshAuth()
+        .then((res) => applyRefreshResult(res?.data?.data || {}))
+        .finally(() => {
+            refreshTask = null;
+        });
+
+    return refreshTask;
+}

package/tests/auth-token-refresh.test.js

@@ -0,0 +1,52 @@
+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 cmsService = fs.readFileSync(path.join(root, "service/cms.js"), "utf8");
+const refreshUtil = fs.readFileSync(path.join(root, "src/utils/auth-token-refresh.js"), "utf8");
+const docs = fs.readFileSync(path.join(root, "docs/agents/auth-token-refresh.md"), "utf8");
+
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+
+assert(
+    cmsService.includes("/api/cms/user/account/token/refresh"),
+    "refreshAuth should use the token refresh endpoint"
+);
+
+assert(commonHeader.includes("refreshTokenIfNeeded"), "CommonHeader should trigger token refresh");
+
+assert(
+    commonHeader.includes("visibilitychange") && commonHeader.includes("handleVisibilityChange"),
+    "CommonHeader should check refresh on visibility restore"
+);
+
+assert(refreshUtil.includes("REFRESH_WINDOW_SECONDS = 7 * 24 * 60 * 60"), "refresh window should be 7 days");
+
+assert(
+    refreshUtil.includes("MIN_REFRESH_INTERVAL_SECONDS = 24 * 60 * 60"),
+    "minimum refresh interval should be 1 day"
+);
+
+assert(
+    refreshUtil.includes('localStorage.getItem("__token") || localStorage.getItem("token")'),
+    "refresh should read __token before token"
+);
+
+assert(
+    refreshUtil.includes("localStorage.setItem(\"__token\", profile.token)"),
+    "refresh should keep __token in sync"
+);
+
+assert(
+    refreshUtil.includes("jx3box-alternate-${profile.uid}"),
+    "refresh should update the current alternate account cache"
+);
+
+assert(docs.includes("PC 账号切换注意事项"), "docs should record PC account switching constraints");
+
+console.log("auth token refresh checks passed");