官网系统前端开发指南

官网系统包含两个前端项目：前台官网（SSR）和管理后台（SPA）。

---

一、前台官网（jiudi-official-web）

技术栈

技术	版本	用途
Nuxt 3	^3.16.0	Vue 3 SSR 框架
Vue 3	^3.5.0	前端框架
TailwindCSS	^6.13.0	原子化 CSS
Pinia	^2.3.0	状态管理
Tabler Icons	3.x	图标库（CDN）
Lucide Static	latest	图标库（CDN）

项目结构

jiudi-official-web/
├── pages/                     # 页面路由
│   ├── index.vue              # 首页
│   ├── about.vue              # 关于我们
│   ├── contact.vue            # 联系我们
│   ├── demo.vue               # 演示中心
│   ├── trial.vue              # 免费体验
│   ├── download.vue           # 源码下载
│   ├── license.vue            # 授权查询
│   ├── help.vue               # 帮助中心
│   ├── login.vue              # 微信登录
│   ├── privacy.vue            # 隐私政策
│   ├── terms.vue              # 服务条款
│   ├── products/              # 产品中心
│   │   ├── index.vue          # 产品列表
│   │   └── [id].vue           # 产品详情
│   ├── solutions/             # 解决方案
│   │   ├── index.vue          # 方案列表
│   │   └── [id].vue           # 方案详情
│   └── user/
│       └── index.vue          # 用户中心
├── components/                # 通用组件
│   ├── Navbar.vue             # 顶部导航栏
│   ├── Footer.vue             # 页脚
│   ├── PageHero.vue           # 页面 Hero 区域
│   ├── SectionHeader.vue      # 章节标题
│   ├── CookieConsent.vue      # Cookie 同意弹窗
│   └── ui/Button.vue          # UI 按钮组件
├── composables/               # 组合式函数
│   ├── useApi.ts              # API 请求封装
│   └── useAnalytics.ts        # 埋点追踪封装
├── plugins/
│   └── analytics.client.ts    # 数据采集插件（客户端）
├── stores/
│   └── user.ts                # 用户状态管理
├── middleware/
│   └── auth.ts                # 认证中间件
├── layouts/
│   ├── default.vue            # 默认布局
│   └── blank.vue              # 空白布局
└── assets/css/
    └── main.css               # 全局样式

API 请求封装

所有前台请求通过 useApi.ts 的 request 函数统一发送，自动处理 Token 注入和响应解包：

export const useApi = () => {
  const config = useRuntimeConfig()
  const baseURL = config.public.apiBase + '/app-api/website'

  const request = async <T>(url: string, options?: any) => {
    const token = useCookie('token')
    const res = await $fetch<{ code: number; data: T; msg: string }>(url, {
      baseURL,
      headers: {
        ...(token.value ? { Authorization: `Bearer ${token.value}` } : {})
      },
      ...options
    })
    if (res.code !== 0) throw new Error(res.msg || '请求失败')
    return res.data  // 自动解包，仅返回 data
  }

  const get = <T>(url: string, params?: any) => request<T>(url, { method: 'GET', params })
  const post = <T>(url: string, body?: any) => request<T>(url, { method: 'POST', body })
  return { get, post, request, baseURL }
}

状态管理

使用 Pinia 管理用户状态，Token 通过 Cookie 持久化：

export const useUserStore = defineStore('user', {
  state: () => ({
    token: null as string | null,
    userInfo: null as any
  }),
  actions: {
    setToken(token: string) {
      this.token = token
      const tokenCookie = useCookie('token', { maxAge: 7 * 24 * 3600 })
      tokenCookie.value = token
    },
    logout() {
      this.token = null
      this.userInfo = null
      const tokenCookie = useCookie('token')
      tokenCookie.value = null
      navigateTo('/login')
    },
    initFromCookie() {
      const tokenCookie = useCookie('token')
      if (tokenCookie.value) this.token = tokenCookie.value
    }
  }
})

路由与认证

需要登录的页面通过 middleware/auth.ts 中间件保护：

export default defineNuxtRouteMiddleware((to) => {
  const token = useCookie('token')
  if (!token.value) return navigateTo('/login')
})

在页面中启用中间件：

<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
</script>

数据采集

通过 plugins/analytics.client.ts 实现客户端数据采集：

• PV 追踪：自动记录每个页面的访问
• 事件追踪：点击、下载、演示体验、表单提交等
• 心跳上报：每 30 秒上报页面停留时长
• 路径分析：记录用户访问路径序列
• 转化追踪：标记下载、登录等转化事件

页面中使用 useAnalytics composable：

const analytics = useAnalytics()
analytics.trackClick('download_btn', '产品下载')
analytics.trackDownload(productId, productName)

---

二、管理后台（Vben Admin）

技术栈

技术	用途
Vue 3 + TypeScript	前端框架
Vite 5.x	构建工具
Ant Design Vue 4.x	UI 组件库
VxeTable	表格组件
Pinia	状态管理
Vue Router	路由管理

后台页面结构

views/website/
├── category/              # 行业分类管理（树形结构）
│   ├── index.vue
│   └── modules/form.vue
├── solution/              # 解决方案产品管理
│   ├── index.vue
│   └── modules/form.vue
├── source/                # 源码包管理
│   ├── index.vue
│   └── modules/form.vue
├── demo/                  # 演示环境管理
│   ├── index.vue
│   └── modules/form.vue
├── downloadlog/           # 下载日志（只读）
│   └── index.vue
├── config/                # 站点配置（含可视化编辑器）
│   ├── index.vue
│   ├── modules/form.vue
│   └── components/        # 首页配置编辑器
│       ├── HeroEditor.vue
│       ├── BannersEditor.vue
│       ├── StatsEditor.vue
│       ├── AdvantagesEditor.vue
│       ├── CtaEditor.vue
│       ├── ImageUploader.vue
│       └── menu-editor.vue
├── about/                 # 关于我们管理
│   ├── company/index.vue
│   ├── contact/index.vue
│   ├── team/index.vue     # 含 form.vue
│   ├── preview/index.vue
│   └── review/            # 产品评价管理
│       ├── index.vue
│       └── modules/form.vue
├── policy/                # 政策文档管理
│   ├── index.vue
│   └── modules/form.vue
├── contact-message/       # 联系留言管理
│   ├── index.vue
│   └── ContactMessageModal.vue
└── analytics/             # 数据看板
    ├── index.vue
    ├── paths.vue
    ├── realtime.vue
    ├── screen.vue
    └── components/
        ├── TrendChart.vue
        ├── PieChart.vue
        ├── FunnelChart.vue
        └── SankeyChart.vue

开发规范

• 菜单通过后端 system_menu 表动态配置，前端无需手动注册路由
• 页面 component 字段对应 views/ 下的路径（如 website/category/index）
• 权限码通过菜单配置，前端使用 v-auth 指令控制按钮级别权限
• 表单提交使用统一的 buildSubmitData 处理数据构建
• 所有 API 定义集中在 api/website/ 目录下