# 系统架构文档 ## 架构概述 Novalon Website 采用现代化的前端架构设计，基于 Next.js 16 的 App Router 模式，实现了一个高性能、可维护的企业官网系统。 ## 技术架构 ### 整体架构图 ``` ┌─────────────────────────────────────────────────────────────┐ │ 客户端 (Browser) │ ├─────────────────────────────────────────────────────────────┤ │ React 19 + TypeScript + Tailwind CSS + Framer Motion │ ├─────────────────────────────────────────────────────────────┤ │ Next.js 16 App Router │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Pages │ │ Layouts │ │ Loading │ │ │ │ (路由页面) │ │ (布局组件) │ │ (加载状态) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 组件层 (Components) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ UI 组件 │ │ 布局组件 │ │ 业务组件 │ │ │ │ (shadcn) │ │ (Layout) │ │ (Sections) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 服务层 (Services) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ API Routes │ │ Server │ │ Utilities │ │ │ │ (Next.js) │ │ Actions │ │ (lib) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 外部服务 (External) │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Resend │ │ CDN │ │ │ │ (邮件服务) │ │ (静态资源) │ │ │ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 技术选型理由 | 技术 | 选型理由 | |------|----------| | Next.js 16 | 支持 App Router、静态导出、SEO 优化、服务端渲染 | | React 19 | 最新特性、并发渲染、服务端组件支持 | | TypeScript | 类型安全、开发体验提升、代码可维护性 | | Tailwind CSS 4 | 原子化 CSS、快速开发、CSS-in-JS 零运行时 | | Framer Motion | 声明式动画、手势支持、性能优秀 | | shadcn/ui | 可定制、无依赖锁定、Radix UI 基础 | ## 目录结构设计 ### App Router 路由组织 ``` src/app/ ├── layout.tsx # 根布局 - 全局 Provider、字体、元数据 ├── error.tsx # 全局错误边界 ├── not-found.tsx # 404 页面 ├── globals.css # 全局样式 │ ├── (marketing)/ # 营销页面路由组 │ ├── layout.tsx # 营销布局 - Header + Footer │ ├── page.tsx # 首页 │ ├── about/ # 关于我们 │ ├── services/ # 核心业务 │ │ ├── page.tsx # 列表页 │ │ └── [id]/ # 详情页 (动态路由) │ ├── products/ # 产品服务 │ ├── cases/ # 成功案例 │ ├── news/ # 新闻动态 │ │ ├── page.tsx # 列表页 │ │ └── [slug]/ # 详情页 │ └── contact/ # 联系我们 │ ├── page.tsx # 页面 │ └── actions.ts # Server Actions │ ├── api/ # API 路由 │ └── contact/route.ts # 联系表单 API │ ├── privacy/ # 隐私政策 ├── terms/ # 服务条款 └── preview/ # 预览页面 ``` ### 组件目录组织 ``` src/components/ ├── ui/ # 基础 UI 组件 (shadcn/ui) │ ├── button.tsx # 按钮 │ ├── card.tsx # 卡片 │ ├── dialog.tsx # 对话框 │ ├── input.tsx # 输入框 │ ├── textarea.tsx # 文本域 │ ├── dropdown-menu.tsx # 下拉菜单 │ ├── toast.tsx # 提示 │ └── ... │ ├── layout/ # 布局组件 │ ├── header.tsx # 页头导航 │ ├── footer.tsx # 页脚 │ ├── mobile-menu.tsx # 移动端菜单 │ ├── mobile-tab-bar.tsx # 移动端底部导航 │ └── breadcrumb.tsx # 面包屑 │ ├── sections/ # 页面区块组件 │ ├── hero-section.tsx # Hero 区域 │ ├── services-section.tsx # 服务区块 │ ├── products-section.tsx # 产品区块 │ ├── cases-section.tsx # 案例区块 │ ├── about-section.tsx # 关于区块 │ ├── news-section.tsx # 新闻区块 │ └── contact-section.tsx # 联系区块 │ ├── effects/ # 视觉效果组件 │ ├── gradient-flow.tsx # 渐变流动 │ ├── data-particle-flow.tsx # 数据粒子 │ ├── geometric-shapes.tsx # 几何图形 │ ├── glow-effect.tsx # 发光效果 │ └── ... │ ├── seo/ # SEO 组件 │ └── structured-data.tsx # 结构化数据 │ └── analytics/ # 分析组件 └── web-vitals.tsx # Web Vitals 监控 ``` ## 核心模块设计 ### 1. 路由系统 #### 路由组 (Route Groups) 使用 `(marketing)` 路由组将营销相关页面组织在一起，共享相同的布局： ```tsx // src/app/(marketing)/layout.tsx export default function MarketingLayout({ children }) { return (
{children}
); } ``` #### 动态路由 支持动态路由参数，如服务详情、产品详情、案例详情、新闻详情： ```tsx // src/app/(marketing)/services/[id]/page.tsx export default function ServiceDetailPage({ params }) { return ; } ``` ### 2. 状态管理 #### Context 使用 - `ThemeProvider` - 主题状态管理 - `WebVitals` - 性能指标监控 #### 本地状态 组件内部使用 React Hooks 管理本地状态： - `useState` - 组件状态 - `useEffect` - 副作用处理 - `useCallback` - 回调优化 - `useRef` - DOM 引用 ### 3. 数据流 ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 用户交互 │ ──▶ │ 表单验证 │ ──▶ │ API 请求 │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ UI 更新 │ ◀── │ 状态更新 │ ◀── │ 响应处理 │ └─────────────┘ └─────────────┘ └─────────────┘ ``` ### 4. 样式系统 #### Tailwind CSS 配置 - CSS Variables 驱动主题 - 响应式断点：sm, md, lg, xl, 2xl - 自定义颜色变量 #### 类名管理 使用 `cn()` 工具函数合并类名： ```tsx import { cn } from '@/lib/utils';