From c256a5441a80a5aade3e54c255867c17db8bfa8c Mon Sep 17 00:00:00 2001
From: wucm667 <stevenwucongmin@gmail.com>
Date: Fri, 29 May 2026 20:57:29 +0800
Subject: [PATCH] =?UTF-8?q?feat(admin):=20=E8=B4=A6=E5=8F=B7=E7=94=A8?=
 =?UTF-8?q?=E9=87=8F=E7=AA=97=E5=8F=A3=205h/7d=20=E5=A2=9E=E5=8A=A0?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=20tooltip?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在账号管理列表"用量窗口"列表头增加一个说明性 HelpTooltip，
解释 5h / 7d 是上游账号（如 OpenAI ChatGPT、Claude）官方的滚动
用量窗口限制，由上游设定、非 sub2api 配置、与映射模型无关，且
窗口滚动到期后自动重置、无法在 sub2api 端解除。

复用现有 HelpTooltip 组件（teleport 到 body，避免表格裁剪），
单个 ⓘ 图标置于列表头，避免每行重复。新增 i18n key
admin.accounts.usageWindowsHint（zh/en 同步）。纯展示说明，
不改用量计算与后端逻辑。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 frontend/src/i18n/locales/en.ts               |   1 +
 frontend/src/i18n/locales/zh.ts               |   1 +
 frontend/src/views/admin/AccountsView.vue     |   7 +
 .../AccountsView.usageWindowsHint.spec.ts     | 164 ++++++++++++++++++
 4 files changed, 173 insertions(+)
 create mode 100644 frontend/src/views/admin/__tests__/AccountsView.usageWindowsHint.spec.ts

diff --git a/frontend/src/i18n/locales/en.ts b/frontend/src/i18n/locales/en.ts
index 6735029c7c3..2030ddf0510 100644
--- a/frontend/src/i18n/locales/en.ts
+++ b/frontend/src/i18n/locales/en.ts
@@ -3105,6 +3105,7 @@ export default {
         expiresAt: 'Expires At',
         actions: 'Actions'
       },
+      usageWindowsHint: '"5h / 7d" are the upstream account\'s official rolling usage windows (e.g. OpenAI ChatGPT, Claude). They are imposed by the upstream provider on the account itself — not configured by sub2api, and unrelated to the models you map. Usage resets automatically once each window rolls over, and the limit cannot be lifted from within sub2api.',
       allPrivacyModes: 'All Privacy States',
       privacyUnset: 'Unset',
       privacyTrainingOff: 'Training data sharing disabled',
diff --git a/frontend/src/i18n/locales/zh.ts b/frontend/src/i18n/locales/zh.ts
index abb8dff730e..6106aa5a501 100644
--- a/frontend/src/i18n/locales/zh.ts
+++ b/frontend/src/i18n/locales/zh.ts
@@ -3143,6 +3143,7 @@ export default {
         expiresAt: '过期时间',
         actions: '操作'
       },
+      usageWindowsHint: '“5h / 7d”是上游账号（如 OpenAI ChatGPT、Claude）官方的滚动用量窗口限制，由上游对账号设定，并非 sub2api 配置，也与你映射的模型无关。窗口滚动到期后用量会自动重置，无法在 sub2api 端解除该限制。',
       allPrivacyModes: '全部Privacy状态',
       privacyUnset: '未设置',
       privacyTrainingOff: '已关闭训练数据共享',
diff --git a/frontend/src/views/admin/AccountsView.vue b/frontend/src/views/admin/AccountsView.vue
index c602225c2a6..04b46a8de04 100644
--- a/frontend/src/views/admin/AccountsView.vue
+++ b/frontend/src/views/admin/AccountsView.vue
@@ -273,6 +273,12 @@
           <template #cell-groups="{ row }">
             <AccountGroupsCell :groups="row.groups" :max-display="4" />
           </template>
+          <template #header-usage="{ column }">
+            <div class="flex items-center">
+              <span>{{ column.label }}</span>
+              <HelpTooltip :content="t('admin.accounts.usageWindowsHint')" width-class="w-72" />
+            </div>
+          </template>
           <template #cell-usage="{ row }">
             <AccountUsageCell
               :account="row"
@@ -390,6 +396,7 @@ import { useTableSelection } from '@/composables/useTableSelection'
 import AppLayout from '@/components/layout/AppLayout.vue'
 import TablePageLayout from '@/components/layout/TablePageLayout.vue'
 import DataTable from '@/components/common/DataTable.vue'
+import HelpTooltip from '@/components/common/HelpTooltip.vue'
 import Pagination from '@/components/common/Pagination.vue'
 import ConfirmDialog from '@/components/common/ConfirmDialog.vue'
 import { CreateAccountModal, EditAccountModal, BulkEditAccountModal, SyncFromCrsModal, TempUnschedStatusModal } from '@/components/account'
diff --git a/frontend/src/views/admin/__tests__/AccountsView.usageWindowsHint.spec.ts b/frontend/src/views/admin/__tests__/AccountsView.usageWindowsHint.spec.ts
new file mode 100644
index 00000000000..81e7d87e0eb
--- /dev/null
+++ b/frontend/src/views/admin/__tests__/AccountsView.usageWindowsHint.spec.ts
@@ -0,0 +1,164 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+
+import AccountsView from '../AccountsView.vue'
+
+const {
+  listAccounts,
+  listWithEtag,
+  getBatchTodayStats,
+  getAllProxies,
+  getAllGroups
+} = vi.hoisted(() => ({
+  listAccounts: vi.fn(),
+  listWithEtag: vi.fn(),
+  getBatchTodayStats: vi.fn(),
+  getAllProxies: vi.fn(),
+  getAllGroups: vi.fn()
+}))
+
+vi.mock('@/api/admin', () => ({
+  adminAPI: {
+    accounts: {
+      list: listAccounts,
+      listWithEtag,
+      getBatchTodayStats,
+      delete: vi.fn(),
+      batchClearError: vi.fn(),
+      batchRefresh: vi.fn(),
+      toggleSchedulable: vi.fn()
+    },
+    proxies: {
+      getAll: getAllProxies
+    },
+    groups: {
+      getAll: getAllGroups
+    }
+  }
+}))
+
+vi.mock('@/stores/app', () => ({
+  useAppStore: () => ({
+    showError: vi.fn(),
+    showSuccess: vi.fn(),
+    showInfo: vi.fn()
+  })
+}))
+
+vi.mock('@/stores/auth', () => ({
+  useAuthStore: () => ({
+    token: 'test-token'
+  })
+}))
+
+vi.mock('vue-i18n', async () => {
+  const actual = await vi.importActual<typeof import('vue-i18n')>('vue-i18n')
+  return {
+    ...actual,
+    useI18n: () => ({
+      t: (key: string) => key
+    })
+  }
+})
+
+// Render the per-column header slots so we can assert the usage-window header hint.
+const DataTableStub = {
+  props: ['columns', 'data'],
+  template: `
+    <div data-test="data-table">
+      <template v-for="column in columns" :key="column.key">
+        <div v-if="column.key === 'usage'" data-test="usage-header">
+          <slot :name="'header-' + column.key" :column="column" />
+        </div>
+      </template>
+    </div>
+  `
+}
+
+// Expose the content passed to HelpTooltip without dealing with its <Teleport>.
+const HelpTooltipStub = {
+  props: ['content', 'widthClass'],
+  template: '<span data-test="usage-windows-hint">{{ content }}</span>'
+}
+
+function mountView() {
+  return mount(AccountsView, {
+    global: {
+      stubs: {
+        AppLayout: { template: '<div><slot /></div>' },
+        TablePageLayout: {
+          template: '<div><slot name="filters" /><slot name="table" /><slot name="pagination" /></div>'
+        },
+        DataTable: DataTableStub,
+        HelpTooltip: HelpTooltipStub,
+        Pagination: true,
+        ConfirmDialog: true,
+        AccountTableActions: { template: '<div><slot name="beforeCreate" /><slot name="after" /></div>' },
+        AccountTableFilters: { template: '<div></div>' },
+        AccountBulkActionsBar: true,
+        AccountActionMenu: true,
+        ImportDataModal: true,
+        ReAuthAccountModal: true,
+        AccountTestModal: true,
+        AccountStatsModal: true,
+        ScheduledTestsPanel: true,
+        SyncFromCrsModal: true,
+        TempUnschedStatusModal: true,
+        ErrorPassthroughRulesModal: true,
+        TLSFingerprintProfilesModal: true,
+        CreateAccountModal: true,
+        EditAccountModal: true,
+        BulkEditAccountModal: true,
+        PlatformTypeBadge: true,
+        AccountCapacityCell: true,
+        AccountStatusIndicator: true,
+        AccountTodayStatsCell: true,
+        AccountGroupsCell: true,
+        AccountUsageCell: true,
+        Icon: true
+      }
+    }
+  })
+}
+
+describe('admin AccountsView usage windows hint', () => {
+  beforeEach(() => {
+    localStorage.clear()
+
+    listAccounts.mockReset()
+    listWithEtag.mockReset()
+    getBatchTodayStats.mockReset()
+    getAllProxies.mockReset()
+    getAllGroups.mockReset()
+
+    listAccounts.mockResolvedValue({
+      items: [],
+      total: 0,
+      page: 1,
+      page_size: 20,
+      pages: 0
+    })
+    listWithEtag.mockResolvedValue({
+      notModified: true,
+      etag: null,
+      data: null
+    })
+    getBatchTodayStats.mockResolvedValue({ stats: {} })
+    getAllProxies.mockResolvedValue([])
+    getAllGroups.mockResolvedValue([])
+  })
+
+  it('renders an explanatory tooltip next to the usage windows column header', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+
+    const header = wrapper.find('[data-test="usage-header"]')
+    expect(header.exists()).toBe(true)
+    // Column label is still shown alongside the help icon.
+    expect(header.text()).toContain('admin.accounts.columns.usageWindows')
+
+    const hint = wrapper.find('[data-test="usage-windows-hint"]')
+    expect(hint.exists()).toBe(true)
+    expect(hint.text()).toBe('admin.accounts.usageWindowsHint')
+  })
+})