Merge pull request #1109 from GuangYiDing/feat/subscription-guide

feat(subscriptions): 订阅管理页面添加教程指南弹窗

frontend/src/i18n/locales/en.ts

@@ -1759,7 +1759,37 @@ export default {
       pleaseSelectGroup: 'Please select a group',
       validityDaysRequired: 'Please enter a valid number of days (at least 1)',
       revokeConfirm:
-        "Are you sure you want to revoke the subscription for '{user}'? This action cannot be undone."
+        "Are you sure you want to revoke the subscription for '{user}'? This action cannot be undone.",
+      guide: {
+        title: 'Subscription Management Guide',
+        subtitle: 'Subscription mode lets you assign time-based usage quotas to users, with daily/weekly/monthly limits. Follow these steps to get started.',
+        showGuide: 'Usage Guide',
+        step1: {
+          title: 'Create a Subscription Group',
+          line1: 'Go to "Group Management" page, click "Create Group"',
+          line2: 'Set billing type to "Subscription", configure daily/weekly/monthly quota limits',
+          line3: 'Save the group and ensure its status is "Active"',
+          link: 'Go to Group Management'
+        },
+        step2: {
+          title: 'Assign Subscription to User',
+          line1: 'Click the "Assign Subscription" button in the top right',
+          line2: 'Search for a user by email and select them',
+          line3: 'Choose a subscription group, set validity days, then click "Assign"'
+        },
+        step3: {
+          title: 'Manage Existing Subscriptions'
+        },
+        actions: {
+          adjust: 'Adjust',
+          adjustDesc: 'Extend or shorten the subscription validity period',
+          resetQuota: 'Reset Quota',
+          resetQuotaDesc: 'Reset daily/weekly/monthly usage to zero',
+          revoke: 'Revoke',
+          revokeDesc: 'Immediately terminate the subscription (irreversible)'
+        },
+        tip: 'Tip: Only groups with billing type "Subscription" and status "Active" appear in the group dropdown. If no options are available, create one in Group Management first.'
+      }
     },
 
     // Accounts

frontend/src/i18n/locales/zh.ts

@@ -1838,7 +1838,37 @@ export default {
       pleaseSelectUser: '请选择用户',
       pleaseSelectGroup: '请选择分组',
       validityDaysRequired: '请输入有效的天数（至少1天）',
-      revokeConfirm: "确定要撤销 '{user}' 的订阅吗？此操作无法撤销。"
+      revokeConfirm: "确定要撤销 '{user}' 的订阅吗？此操作无法撤销。",
+      guide: {
+        title: '订阅管理教程',
+        subtitle: '订阅模式允许你按时间周期为用户分配使用额度，支持日/周/月配额限制。按照以下步骤即可完成配置。',
+        showGuide: '使用指南',
+        step1: {
+          title: '创建订阅分组',
+          line1: '前往「分组管理」页面，点击「创建分组」',
+          line2: '将计费类型设为「订阅」，配置日/周/月额度限制',
+          line3: '保存分组，确保状态为「正常」',
+          link: '前往分组管理'
+        },
+        step2: {
+          title: '分配订阅给用户',
+          line1: '点击本页右上角「分配订阅」按钮',
+          line2: '在弹窗中搜索用户邮箱并选择目标用户',
+          line3: '选择订阅分组、设置有效期天数，点击「分配」'
+        },
+        step3: {
+          title: '管理已有订阅'
+        },
+        actions: {
+          adjust: '调整',
+          adjustDesc: '延长或缩短订阅有效期',
+          resetQuota: '重置配额',
+          resetQuotaDesc: '将日/周/月用量归零，重新开始计算',
+          revoke: '撤销',
+          revokeDesc: '立即终止该用户的订阅，不可恢复'
+        },
+        tip: '提示：订阅分组下拉列表中只会显示计费类型为「订阅」且状态为「正常」的分组。如果没有可选项，请先到分组管理中创建。'
+      }
     },
 
     // Accounts Management

frontend/src/views/admin/SubscriptionsView.vue

@@ -144,6 +144,13 @@
                 </div>
               </div>
             </div>
+            <button
+              @click="showGuideModal = true"
+              class="btn btn-secondary"
+              :title="t('admin.subscriptions.guide.showGuide')"
+            >
+              <Icon name="questionCircle" size="md" />
+            </button>
             <button @click="showAssignModal = true" class="btn btn-primary">
               <Icon name="plus" size="md" class="mr-2" />
               {{ t('admin.subscriptions.assignSubscription') }}
@@ -638,6 +645,85 @@
       @confirm="confirmResetQuota"
       @cancel="showResetQuotaConfirm = false"
     />
+    <!-- Subscription Guide Modal -->
+    <teleport to="body">
+      <transition name="modal">
+        <div v-if="showGuideModal" class="fixed inset-0 z-50 flex items-center justify-center p-4" @mousedown.self="showGuideModal = false">
+          <div class="fixed inset-0 bg-black/50" @click="showGuideModal = false"></div>
+          <div class="relative max-h-[85vh] w-full max-w-2xl overflow-y-auto rounded-xl bg-white p-6 shadow-2xl dark:bg-dark-800">
+            <button type="button" class="absolute right-4 top-4 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200" @click="showGuideModal = false">
+              <svg class="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" /></svg>
+            </button>
+
+            <h2 class="mb-4 text-lg font-bold text-gray-900 dark:text-white">{{ t('admin.subscriptions.guide.title') }}</h2>
+            <p class="mb-5 text-sm text-gray-500 dark:text-gray-400">{{ t('admin.subscriptions.guide.subtitle') }}</p>
+
+            <!-- Step 1 -->
+            <div class="mb-5">
+              <h3 class="mb-2 flex items-center gap-2 text-sm font-semibold text-gray-900 dark:text-white">
+                <span class="flex h-6 w-6 items-center justify-center rounded-full bg-primary-100 text-xs font-bold text-primary-700 dark:bg-primary-900/40 dark:text-primary-300">1</span>
+                {{ t('admin.subscriptions.guide.step1.title') }}
+              </h3>
+              <ol class="ml-8 list-decimal space-y-1 text-sm text-gray-600 dark:text-gray-300">
+                <li>{{ t('admin.subscriptions.guide.step1.line1') }}</li>
+                <li>{{ t('admin.subscriptions.guide.step1.line2') }}</li>
+                <li>{{ t('admin.subscriptions.guide.step1.line3') }}</li>
+              </ol>
+              <div class="ml-8 mt-2">
+                <router-link
+                  to="/admin/groups"
+                  @click="showGuideModal = false"
+                  class="inline-flex items-center gap-1 text-sm font-medium text-primary-600 hover:text-primary-700 dark:text-primary-400 dark:hover:text-primary-300"
+                >
+                  {{ t('admin.subscriptions.guide.step1.link') }}
+                  <Icon name="arrowRight" size="xs" />
+                </router-link>
+              </div>
+            </div>
+
+            <!-- Step 2 -->
+            <div class="mb-5">
+              <h3 class="mb-2 flex items-center gap-2 text-sm font-semibold text-gray-900 dark:text-white">
+                <span class="flex h-6 w-6 items-center justify-center rounded-full bg-primary-100 text-xs font-bold text-primary-700 dark:bg-primary-900/40 dark:text-primary-300">2</span>
+                {{ t('admin.subscriptions.guide.step2.title') }}
+              </h3>
+              <ol class="ml-8 list-decimal space-y-1 text-sm text-gray-600 dark:text-gray-300">
+                <li>{{ t('admin.subscriptions.guide.step2.line1') }}</li>
+                <li>{{ t('admin.subscriptions.guide.step2.line2') }}</li>
+                <li>{{ t('admin.subscriptions.guide.step2.line3') }}</li>
+              </ol>
+            </div>
+
+            <!-- Step 3 -->
+            <div class="mb-5">
+              <h3 class="mb-2 flex items-center gap-2 text-sm font-semibold text-gray-900 dark:text-white">
+                <span class="flex h-6 w-6 items-center justify-center rounded-full bg-primary-100 text-xs font-bold text-primary-700 dark:bg-primary-900/40 dark:text-primary-300">3</span>
+                {{ t('admin.subscriptions.guide.step3.title') }}
+              </h3>
+              <div class="ml-8 overflow-hidden rounded-lg border border-gray-200 dark:border-dark-600">
+                <table class="w-full text-sm">
+                  <tbody>
+                    <tr v-for="(row, i) in guideActionRows" :key="i" class="border-b border-gray-100 dark:border-dark-700 last:border-0">
+                      <td class="whitespace-nowrap bg-gray-50 px-3 py-2 font-medium text-gray-700 dark:bg-dark-700 dark:text-gray-300">{{ row.action }}</td>
+                      <td class="px-3 py-2 text-gray-600 dark:text-gray-400">{{ row.desc }}</td>
+                    </tr>
+                  </tbody>
+                </table>
+              </div>
+            </div>
+
+            <!-- Tip -->
+            <div class="rounded-lg bg-blue-50 p-3 text-xs text-blue-700 dark:bg-blue-900/20 dark:text-blue-300">
+              {{ t('admin.subscriptions.guide.tip') }}
+            </div>
+
+            <div class="mt-4 text-right">
+              <button type="button" class="btn btn-primary btn-sm" @click="showGuideModal = false">{{ t('common.close') }}</button>
+            </div>
+          </div>
+        </div>
+      </transition>
+    </teleport>
   </AppLayout>
 </template>
 
@@ -674,6 +760,15 @@ interface GroupOption {
   rate: number
 }
 
+// Guide modal state
+const showGuideModal = ref(false)
+
+const guideActionRows = computed(() => [
+  { action: t('admin.subscriptions.guide.actions.adjust'), desc: t('admin.subscriptions.guide.actions.adjustDesc') },
+  { action: t('admin.subscriptions.guide.actions.resetQuota'), desc: t('admin.subscriptions.guide.actions.resetQuotaDesc') },
+  { action: t('admin.subscriptions.guide.actions.revoke'), desc: t('admin.subscriptions.guide.actions.revokeDesc') }
+])
+
 // User column display mode: 'email' or 'username'
 const userColumnMode = ref<'email' | 'username'>('email')
 const USER_COLUMN_MODE_KEY = 'subscription-user-column-mode'