oadmin/sub2api
1
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

feat(frontend): 实现新手引导功能

Browse Source 
- 添加 Guide 组件和引导步骤配置
- 实现 useOnboardingTour 和 useTourStepDescription composables
- 添加 onboarding store 管理引导状态
- 更新多个视图和组件以支持引导功能
- 添加国际化支持（中英文）
- 删除旧的实现指南文档
This commit is contained in:
IanShaw027
2025-12-29 15:21:05 +08:00
parent c01db6b180
commit dd247e55e9
30 changed files with 3968 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
frontend/src/components/Guide/TourDescription.vue Normal file
View File

@@ -0,0 +1,157 @@
<template>
<div class="tour-description">
<!-- 主要段落 -->
<p v-if="mainText" class="main-text">{{ mainText }}</p>
<!-- 特性列表 -->
<div v-if="features && features.length > 0" class="features-section">
<p v-if="featuresTitle" class="section-title">{{ featuresTitle }}</p>
<ul class="features-list">
<li v-for="(feature, index) in features" :key="index">
<span v-if="feature.icon" class="feature-icon">{{ feature.icon }}</span>
<span v-if="feature.label" class="feature-label">{{ feature.label }}</span>
<span class="feature-text">{{ feature.text }}</span>
</li>
</ul>
</div>
<!-- 提示框 -->
<div v-if="tip" :class="['tip-box', `tip-${tip.type || 'info'}`]">
<span v-if="tip.label" class="tip-label">{{ tip.label }}</span>
<div v-if="tip.text" class="tip-text">{{ tip.text }}</div>
<ul v-if="tip.items && tip.items.length > 0" class="tip-list">
<li v-for="(item, index) in tip.items" :key="index">{{ item }}</li>
</ul>
</div>
<!-- 行动提示 -->
<p v-if="action" class="action-text">{{ action }}</p>
<!-- 额外说明 -->
<p v-if="note" class="note-text">{{ note }}</p>
</div>
</template>
<script setup lang="ts">
export interface TourFeature {
icon?: string
label?: string
text: string
}
export interface TourTip {
type?: 'info' | 'success' | 'warning' | 'example'
label?: string
text?: string
items?: string[]
}
export interface TourDescriptionProps {
mainText?: string
featuresTitle?: string
features?: TourFeature[]
tip?: TourTip
action?: string
note?: string
}
defineProps<TourDescriptionProps>()
</script>
<style scoped>
.tour-description {
line-height: 1.7;
font-size: 14px;
}
.main-text {
margin-bottom: 12px;
color: #374151;
}
.section-title {
margin-bottom: 8px;
font-weight: 600;
color: #1f2937;
}
.features-section {
margin-bottom: 12px;
}
.features-list {
margin-left: 20px;
font-size: 13px;
}
.features-list li {
margin-bottom: 6px;
}
.feature-icon {
margin-right: 4px;
}
.feature-label {
font-weight: 600;
margin-right: 4px;
}
.tip-box {
padding: 8px 12px;
border-radius: 4px;
border-left: 3px solid;
font-size: 13px;
margin-bottom: 12px;
}
.tip-info {
background: #eff6ff;
border-left-color: #3b82f6;
}
.tip-success {
background: #f0fdf4;
border-left-color: #10b981;
}
.tip-warning {
background: #fef3c7;
border-left-color: #f59e0b;
}
.tip-example {
background: #f0fdf4;
border-left-color: #10b981;
}
.tip-label {
font-weight: 600;
display: block;
margin-bottom: 4px;
}
.tip-text {
margin-bottom: 4px;
}
.tip-list {
margin: 8px 0 0 16px;
}
.tip-list li {
margin-bottom: 4px;
}
.action-text {
margin-top: 12px;
color: #10b981;
font-weight: 600;
}
.note-text {
font-size: 13px;
color: #6b7280;
margin-top: 8px;
}
</style>

20
frontend/src/components/Guide/TourStepDescriptions/TourStepDescription.vue Normal file
View File

@@ -0,0 +1,20 @@
<template>
<section
class="tour-step-description"
:lang="locale"
:data-step-key="stepKey"
>
<slot />
</section>
</template>
<script setup lang="ts">
import type { TourStepKey } from '@/composables/useTourStepDescription'
interface TourStepDescriptionProps {
stepKey: TourStepKey
locale: string
}
defineProps<TourStepDescriptionProps>()
</script>

1
frontend/src/components/Guide/TourStepDescriptions/index.ts Normal file
View File

@@ -0,0 +1 @@
export { default as TourStepDescription } from './TourStepDescription.vue'

289
frontend/src/components/Guide/steps.ts Normal file
View File

@@ -0,0 +1,289 @@
import { DriveStep } from 'driver.js'
/**
* 管理员完整引导流程
* 交互式引导：指引用户实际操作
*/
export const getAdminSteps = (t: (key: string) => string): DriveStep[] => [
// ========== 欢迎介绍 ==========
{
popover: {
title: t('onboarding.admin.welcome.title'),
description: t('onboarding.admin.welcome.description'),
align: 'center',
nextBtnText: t('onboarding.admin.welcome.nextBtn'),
prevBtnText: t('onboarding.admin.welcome.prevBtn')
}
},
// ========== 第一部分：创建分组 ==========
{
element: '#sidebar-group-manage',
popover: {
title: t('onboarding.admin.groupManage.title'),
description: t('onboarding.admin.groupManage.description'),
side: 'right',
align: 'center',
showButtons: ['close'],
}
},
{
element: '[data-tour="groups-create-btn"]',
popover: {
title: t('onboarding.admin.createGroup.title'),
description: t('onboarding.admin.createGroup.description'),
side: 'bottom',
align: 'end',
showButtons: ['close']
}
},
{
element: '[data-tour="group-form-name"]',
popover: {
title: t('onboarding.admin.groupName.title'),
description: t('onboarding.admin.groupName.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="group-form-platform"]',
popover: {
title: t('onboarding.admin.groupPlatform.title'),
description: t('onboarding.admin.groupPlatform.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="group-form-multiplier"]',
popover: {
title: t('onboarding.admin.groupMultiplier.title'),
description: t('onboarding.admin.groupMultiplier.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="group-form-exclusive"]',
popover: {
title: t('onboarding.admin.groupExclusive.title'),
description: t('onboarding.admin.groupExclusive.description'),
side: 'top',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="group-form-submit"]',
popover: {
title: t('onboarding.admin.groupSubmit.title'),
description: t('onboarding.admin.groupSubmit.description'),
side: 'left',
align: 'center',
showButtons: ['close']
}
},
// ========== 第二部分：创建账号授权 ==========
{
element: '#sidebar-channel-manage',
popover: {
title: t('onboarding.admin.accountManage.title'),
description: t('onboarding.admin.accountManage.description'),
side: 'right',
align: 'center',
showButtons: ['close']
}
},
{
element: '[data-tour="accounts-create-btn"]',
popover: {
title: t('onboarding.admin.createAccount.title'),
description: t('onboarding.admin.createAccount.description'),
side: 'bottom',
align: 'end',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-name"]',
popover: {
title: t('onboarding.admin.accountName.title'),
description: t('onboarding.admin.accountName.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-platform"]',
popover: {
title: t('onboarding.admin.accountPlatform.title'),
description: t('onboarding.admin.accountPlatform.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-type"]',
popover: {
title: t('onboarding.admin.accountType.title'),
description: t('onboarding.admin.accountType.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-priority"]',
popover: {
title: t('onboarding.admin.accountPriority.title'),
description: t('onboarding.admin.accountPriority.description'),
side: 'top',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-groups"]',
popover: {
title: t('onboarding.admin.accountGroups.title'),
description: t('onboarding.admin.accountGroups.description'),
side: 'top',
align: 'center',
showButtons: ['close']
}
},
{
element: '[data-tour="account-form-submit"]',
popover: {
title: t('onboarding.admin.accountSubmit.title'),
description: t('onboarding.admin.accountSubmit.description'),
side: 'left',
align: 'center',
showButtons: ['close']
}
},
// ========== 第三部分：创建API密钥 ==========
{
element: '[data-tour="sidebar-my-keys"]',
popover: {
title: t('onboarding.admin.keyManage.title'),
description: t('onboarding.admin.keyManage.description'),
side: 'right',
align: 'center',
showButtons: ['close']
}
},
{
element: '[data-tour="keys-create-btn"]',
popover: {
title: t('onboarding.admin.createKey.title'),
description: t('onboarding.admin.createKey.description'),
side: 'bottom',
align: 'end',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-name"]',
popover: {
title: t('onboarding.admin.keyName.title'),
description: t('onboarding.admin.keyName.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-group"]',
popover: {
title: t('onboarding.admin.keyGroup.title'),
description: t('onboarding.admin.keyGroup.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-submit"]',
popover: {
title: t('onboarding.admin.keySubmit.title'),
description: t('onboarding.admin.keySubmit.description'),
side: 'left',
align: 'center',
showButtons: ['close']
}
}
]
/**
* 普通用户引导流程
*/
export const getUserSteps = (t: (key: string) => string): DriveStep[] => [
{
popover: {
title: t('onboarding.user.welcome.title'),
description: t('onboarding.user.welcome.description'),
align: 'center',
nextBtnText: t('onboarding.user.welcome.nextBtn'),
prevBtnText: t('onboarding.user.welcome.prevBtn')
}
},
{
element: '[data-tour="sidebar-my-keys"]',
popover: {
title: t('onboarding.user.keyManage.title'),
description: t('onboarding.user.keyManage.description'),
side: 'right',
align: 'center',
showButtons: ['close']
}
},
{
element: '[data-tour="keys-create-btn"]',
popover: {
title: t('onboarding.user.createKey.title'),
description: t('onboarding.user.createKey.description'),
side: 'bottom',
align: 'end',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-name"]',
popover: {
title: t('onboarding.user.keyName.title'),
description: t('onboarding.user.keyName.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-group"]',
popover: {
title: t('onboarding.user.keyGroup.title'),
description: t('onboarding.user.keyGroup.description'),
side: 'right',
align: 'start',
showButtons: ['close']
}
},
{
element: '[data-tour="key-form-submit"]',
popover: {
title: t('onboarding.user.keySubmit.title'),
description: t('onboarding.user.keySubmit.description'),
side: 'left',
align: 'center',
showButtons: ['close']
}
}
]

27
frontend/src/components/account/CreateAccountModal.vue
View File

@@ -53,13 +53,14 @@
required
class="input"
:placeholder="t('admin.accounts.enterAccountName')"
data-tour="account-form-name"
/>
</div>
<!-- Platform Selection - Segmented Control Style -->
<div>
<label class="input-label">{{ t('admin.accounts.platform') }}</label>
<div class="mt-2 flex rounded-lg bg-gray-100 p-1 dark:bg-dark-700">
<div class="mt-2 flex rounded-lg bg-gray-100 p-1 dark:bg-dark-700" data-tour="account-form-platform">
<button
type="button"
@click="form.platform = 'anthropic'"
@@ -141,7 +142,7 @@
<!-- Account Type Selection (Anthropic) -->
<div v-if="form.platform === 'anthropic'">
<label class="input-label">{{ t('admin.accounts.accountType') }}</label>
<div class="mt-2 grid grid-cols-2 gap-3">
<div class="mt-2 grid grid-cols-2 gap-3" data-tour="account-form-type">
<button
type="button"
@click="accountCategory = 'oauth-based'"
@@ -231,7 +232,7 @@
<!-- Account Type Selection (OpenAI) -->
<div v-if="form.platform === 'openai'">
<label class="input-label">{{ t('admin.accounts.accountType') }}</label>
<div class="mt-2 grid grid-cols-2 gap-3">
<div class="mt-2 grid grid-cols-2 gap-3" data-tour="account-form-type">
<button
type="button"
@click="accountCategory = 'oauth-based'"
@@ -313,7 +314,7 @@
<!-- Account Type Selection (Gemini) -->
<div v-if="form.platform === 'gemini'">
<label class="input-label">{{ t('admin.accounts.accountType') }}</label>
<div class="mt-2 grid grid-cols-2 gap-3">
<div class="mt-2 grid grid-cols-2 gap-3" data-tour="account-form-type">
<button
type="button"
@click="accountCategory = 'oauth-based'"
@@ -959,18 +960,21 @@
</div>
<div>
<label class="input-label">{{ t('admin.accounts.priority') }}</label>
<input v-model.number="form.priority" type="number" min="1" class="input" />
<input
v-model.number="form.priority"
type="number"
min="1"
class="input"
data-tour="account-form-priority"
/>
<p class="input-hint">{{ t('admin.accounts.priorityHint') }}</p>
</div>
</div>
<!-- Group Selection - 仅标准模式显示 -->
<GroupSelector
v-if="!authStore.isSimpleMode"
v-model="form.group_ids"
:groups="groups"
:platform="form.platform"
/>
<div v-if="!authStore.isSimpleMode" data-tour="account-form-groups">
<GroupSelector v-model="form.group_ids" :groups="groups" :platform="form.platform" />
</div>
</form>
@@ -1005,6 +1009,7 @@
form="create-account-form"
:disabled="submitting"
class="btn btn-primary"
data-tour="account-form-submit"
>
<svg
v-if="submitting"

20
frontend/src/components/account/EditAccountModal.vue
View File

@@ -13,7 +13,7 @@
>
<div>
<label class="input-label">{{ t('common.name') }}</label>
<input v-model="form.name" type="text" required class="input" />
<input v-model="form.name" type="text" required class="input" data-tour="edit-account-form-name" />
</div>
<!-- API Key fields (only for apikey type) -->
@@ -457,7 +457,13 @@
</div>
<div>
<label class="input-label">{{ t('admin.accounts.priority') }}</label>
<input v-model.number="form.priority" type="number" min="1" class="input" />
<input
v-model.number="form.priority"
type="number"
min="1"
class="input"
data-tour="account-form-priority"
/>
</div>
</div>
@@ -467,12 +473,9 @@
</div>
<!-- Group Selection - 仅标准模式显示 -->
<GroupSelector
v-if="!authStore.isSimpleMode"
v-model="form.group_ids"
:groups="groups"
:platform="account?.platform"
/>
<div v-if="!authStore.isSimpleMode" data-tour="account-form-groups">
<GroupSelector v-model="form.group_ids" :groups="groups" :platform="account?.platform" />
</div>
</form>
@@ -486,6 +489,7 @@
form="edit-account-form"
:disabled="submitting"
class="btn btn-primary"
data-tour="account-form-submit"
>
<svg
v-if="submitting"

16
frontend/src/components/layout/AppHeader.vue
View File

@@ -200,6 +200,14 @@
</div>
<div class="border-t border-gray-100 py-1 dark:border-dark-700">
<button @click="handleReplayGuide" class="dropdown-item w-full">
<svg class="h-4 w-4" fill="currentColor" viewBox="0 0 24 24">
<path
d="M12 2a10 10 0 100 20 10 10 0 000-20zm0 14a1 1 0 110 2 1 1 0 010-2zm1.07-7.75c0-.6-.49-1.25-1.32-1.25-.7 0-1.22.4-1.43 1.02a1 1 0 11-1.9-.62A3.41 3.41 0 0111.8 5c2.02 0 3.25 1.4 3.25 2.9 0 2-1.83 2.55-2.43 3.12-.43.4-.47.75-.47 1.23a1 1 0 01-2 0c0-1 .16-1.82 1.1-2.7.69-.64 1.82-1.05 1.82-2.06z"
/>
</svg>
{{ $t('onboarding.restartTour') }}
</button>
<button
@click="handleLogout"
class="dropdown-item w-full text-red-600 hover:bg-red-50 dark:text-red-400 dark:hover:bg-red-900/20"
@@ -232,7 +240,7 @@
import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import { useI18n } from 'vue-i18n'
import { useAppStore, useAuthStore } from '@/stores'
import { useAppStore, useAuthStore, useOnboardingStore } from '@/stores'
import LocaleSwitcher from '@/components/common/LocaleSwitcher.vue'
import SubscriptionProgressMini from '@/components/common/SubscriptionProgressMini.vue'
@@ -241,6 +249,7 @@ const route = useRoute()
const { t } = useI18n()
const appStore = useAppStore()
const authStore = useAuthStore()
const onboardingStore = useOnboardingStore()
const user = computed(() => authStore.user)
const dropdownOpen = ref(false)
@@ -300,6 +309,11 @@ async function handleLogout() {
await router.push('/login')
}
function handleReplayGuide() {
closeDropdown()
onboardingStore.replay()
}
function handleClickOutside(event: MouseEvent) {
if (dropdownRef.value && !dropdownRef.value.contains(event.target as Node)) {
closeDropdown()

25
frontend/src/components/layout/AppLayout.vue
View File

@@ -23,11 +23,34 @@
</template>
<script setup lang="ts">
import { computed } from 'vue'
import '@/styles/onboarding.css'
import { computed, onMounted } from 'vue'
import { useI18n } from 'vue-i18n'
import { useAppStore } from '@/stores'
import { useAuthStore } from '@/stores/auth'
import { useOnboardingTour } from '@/composables/useOnboardingTour'
import { getAdminSteps, getUserSteps } from '@/components/Guide/steps'
import { useOnboardingStore } from '@/stores/onboarding'
import AppSidebar from './AppSidebar.vue'
import AppHeader from './AppHeader.vue'
const appStore = useAppStore()
const authStore = useAuthStore()
const { t } = useI18n()
const sidebarCollapsed = computed(() => appStore.sidebarCollapsed)
const isAdmin = computed(() => authStore.user?.role === 'admin')
const { replayTour } = useOnboardingTour({
steps: isAdmin.value ? getAdminSteps(t) : getUserSteps(t),
storageKey: isAdmin.value ? 'admin_guide' : 'user_guide',
autoStart: true
})
const onboardingStore = useOnboardingStore()
onMounted(() => {
onboardingStore.setReplayCallback(replayTour)
})
defineExpose({ replayTour })
</script>

34
frontend/src/components/layout/AppSidebar.vue
View File

@@ -36,7 +36,16 @@
class="sidebar-link mb-1"
:class="{ 'sidebar-link-active': isActive(item.path) }"
:title="sidebarCollapsed ? item.label : undefined"
@click="handleMenuItemClick"
:id="
item.path === '/admin/accounts'
? 'sidebar-channel-manage'
: item.path === '/admin/groups'
? 'sidebar-group-manage'
: item.path === '/admin/redeem'
? 'sidebar-wallet'
: undefined
"
@click="handleMenuItemClick(item.path)"
>
<component :is="item.icon" class="h-5 w-5 flex-shrink-0" />
<transition name="fade">
@@ -59,7 +68,8 @@
class="sidebar-link mb-1"
:class="{ 'sidebar-link-active': isActive(item.path) }"
:title="sidebarCollapsed ? item.label : undefined"
@click="handleMenuItemClick"
:data-tour="item.path === '/keys' ? 'sidebar-my-keys' : undefined"
@click="handleMenuItemClick(item.path)"
>
<component :is="item.icon" class="h-5 w-5 flex-shrink-0" />
<transition name="fade">
@@ -79,7 +89,8 @@
class="sidebar-link mb-1"
:class="{ 'sidebar-link-active': isActive(item.path) }"
:title="sidebarCollapsed ? item.label : undefined"
@click="handleMenuItemClick"
:data-tour="item.path === '/keys' ? 'sidebar-my-keys' : undefined"
@click="handleMenuItemClick(item.path)"
>
<component :is="item.icon" class="h-5 w-5 flex-shrink-0" />
<transition name="fade">
@@ -136,7 +147,7 @@
import { computed, h, ref } from 'vue'
import { useRoute } from 'vue-router'
import { useI18n } from 'vue-i18n'
import { useAppStore, useAuthStore } from '@/stores'
import { useAppStore, useAuthStore, useOnboardingStore } from '@/stores'
import VersionBadge from '@/components/common/VersionBadge.vue'
const { t } = useI18n()
@@ -144,6 +155,7 @@ const { t } = useI18n()
const route = useRoute()
const appStore = useAppStore()
const authStore = useAuthStore()
const onboardingStore = useOnboardingStore()
const sidebarCollapsed = computed(() => appStore.sidebarCollapsed)
const mobileOpen = computed(() => appStore.mobileOpen)
@@ -465,12 +477,24 @@ function closeMobile() {
appStore.setMobileOpen(false)
}
function handleMenuItemClick() {
function handleMenuItemClick(itemPath: string) {
if (mobileOpen.value) {
setTimeout(() => {
appStore.setMobileOpen(false)
}, 150)
}
// Map paths to tour selectors
const pathToSelector: Record<string, string> = {
'/admin/groups': '#sidebar-group-manage',
'/admin/accounts': '#sidebar-channel-manage',
'/keys': '[data-tour="sidebar-my-keys"]'
}
const selector = pathToSelector[itemPath]
if (selector && onboardingStore.isCurrentStep(selector)) {
onboardingStore.nextStep(500)
}
}
function isActive(path: string): boolean {