张翔
369 lines
12 KiB
Markdown
369 lines
12 KiB
Markdown
# 系统架构文档
|
|
|
|
## 架构概述
|
|
|
|
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 (
|
|
<div className="min-h-screen flex flex-col">
|
|
<Header />
|
|
<ErrorBoundary>
|
|
<main className="flex-1">{children}</main>
|
|
</ErrorBoundary>
|
|
<Footer />
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
#### 动态路由
|
|
|
|
支持动态路由参数，如服务详情、产品详情、案例详情、新闻详情：
|
|
|
|
```tsx
|
|
// src/app/(marketing)/services/[id]/page.tsx
|
|
export default function ServiceDetailPage({ params }) {
|
|
return <ServiceDetailClient id={params.id} />;
|
|
}
|
|
```
|
|
|
|
### 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';
|
|
|
|
<Button className={cn('base-classes', conditional && 'active-class')} />
|
|
```
|
|
|
|
### 5. 动画系统
|
|
|
|
#### Framer Motion 集成
|
|
|
|
- 页面过渡动画
|
|
- 滚动触发动画
|
|
- 手势交互
|
|
- 列表动画
|
|
|
|
#### 性能优化
|
|
|
|
- 使用 `dynamic` 动态导入大型动画组件
|
|
- `AnimatePresence` 处理组件卸载动画
|
|
- `will-change` CSS 属性优化
|
|
|
|
## 性能优化策略
|
|
|
|
### 1. 代码分割
|
|
|
|
```tsx
|
|
// 动态导入非首屏组件
|
|
const ServicesSection = dynamic(
|
|
() => import('@/components/sections/services-section'),
|
|
{ loading: () => <SectionSkeleton />, ssr: false }
|
|
);
|
|
```
|
|
|
|
### 2. 图片优化
|
|
|
|
- 使用 Next.js Image 组件
|
|
- 支持 WebP/AVIF 格式
|
|
- 响应式图片尺寸
|
|
- 懒加载
|
|
|
|
### 3. 字体优化
|
|
|
|
```tsx
|
|
// Google Fonts 优化配置
|
|
const notoSansSC = Noto_Sans_SC({
|
|
weight: ['400', '500', '700'],
|
|
variable: '--font-noto-sans-sc',
|
|
subsets: ['latin'],
|
|
display: 'swap',
|
|
preload: true,
|
|
});
|
|
```
|
|
|
|
### 4. 静态导出
|
|
|
|
```tsx
|
|
// next.config.ts
|
|
const nextConfig = {
|
|
output: 'export',
|
|
distDir: 'dist',
|
|
images: { unoptimized: true },
|
|
};
|
|
```
|
|
|
|
## 安全设计
|
|
|
|
### 1. XSS 防护
|
|
|
|
- 使用 DOMPurify 清理用户输入
|
|
- React 自动转义
|
|
- Content Security Policy
|
|
|
|
### 2. CSRF 防护
|
|
|
|
- 表单包含 CSRF Token
|
|
- 验证请求来源
|
|
|
|
### 3. 邮件表单安全
|
|
|
|
- 蜜罐字段检测机器人
|
|
- 提交时间验证
|
|
- 数学验证码
|
|
|
|
## SEO 优化
|
|
|
|
### 1. 元数据配置
|
|
|
|
```tsx
|
|
export const metadata: Metadata = {
|
|
title: { default: '...', template: '%s | ...' },
|
|
description: '...',
|
|
keywords: ['...'],
|
|
openGraph: { ... },
|
|
twitter: { ... },
|
|
};
|
|
```
|
|
|
|
### 2. 结构化数据
|
|
|
|
```tsx
|
|
// Organization Schema
|
|
<OrganizationSchema />
|
|
|
|
// Website Schema
|
|
<WebsiteSchema />
|
|
```
|
|
|
|
### 3. 语义化 HTML
|
|
|
|
- 正确的标题层级 (h1-h6)
|
|
- 语义化标签 (header, main, footer, nav, article)
|
|
- ARIA 属性
|
|
|
|
## 可访问性设计
|
|
|
|
### WCAG 2.1 AA 合规
|
|
|
|
- 颜色对比度 ≥ 4.5:1
|
|
- 键盘导航支持
|
|
- 屏幕阅读器兼容
|
|
- 焦点管理
|
|
- 跳过链接
|
|
|
|
### 焦点陷阱
|
|
|
|
```tsx
|
|
// 移动端菜单焦点陷阱
|
|
const focusTrapRef = useFocusTrap<HTMLDivElement>(isOpen);
|
|
```
|
|
|
|
## 扩展性设计
|
|
|
|
### 1. 组件可复用
|
|
|
|
- UI 组件与业务逻辑分离
|
|
- Props 接口设计
|
|
- 组合模式
|
|
|
|
### 2. 配置驱动
|
|
|
|
```tsx
|
|
// src/lib/constants.ts
|
|
export const NAVIGATION: NavigationItem[] = [
|
|
{ id: 'home', label: '首页', href: '/' },
|
|
// ...
|
|
];
|
|
```
|
|
|
|
### 3. 类型安全
|
|
|
|
```tsx
|
|
// 类型定义
|
|
export interface NewsItem {
|
|
id: string;
|
|
title: string;
|
|
excerpt: string;
|
|
date: string;
|
|
category: NewsCategory;
|
|
image: string;
|
|
content: string;
|
|
}
|
|
```
|