novalon/novalon-website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 整理文档结构并创建索引（任务 2.3/20）

Browse Source
This commit is contained in:
张翔
2026-04-12 16:24:51 +08:00
parent 1f52d47ed5
commit 5cd7d48bf2
33 changed files with 1140 additions and 1176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/STRUCTURE_PLAN.md
+263
View File
@@ -0,0 +1,263 @@
# 目录结构规范化方案
## 目标
建立清晰、规范的目录结构，符合Next.js最佳实践，提升代码可维护性和团队协作效率。
## 当前问题
### 1. 配置文件分散
- 环境配置文件：`.env.example`, `.env.production`, `.env.production.example`, `e2e/.env.example`, `e2e-tests/.env.example`
- CI/CD配置：`.github/workflows/`, `.woodpecker/`
- 测试配置：多个playwright配置文件
### 2. 文档文件杂乱
- 根目录文档：`README.md`, `DEPLOYMENT.md`, `IMPLEMENTATION-REPORT.md`, `README-TIERED-TESTING.md`, `SECURITY.md`, `TESTING_REPORT.md`
- 测试报告：`test-reports/`, `test-analysis/`, `performance/`
- 缺少docs目录结构
### 3. 脚本文件组织混乱
- scripts目录下有14个脚本文件，分类不清
- 脚本命名不统一（.sh, .ts, .js）
- 缺少脚本文档
### 4. 临时文件和构建产物
- `performance/`目录包含临时测试报告
- `test-reports/`和`test-analysis/`目录包含测试报告
- `.gitignore`中忽略了docs目录（已修复）
## 优化方案
### 1. 标准化目录结构
```
novalon-website/
├── src/ # 源代码目录
│ ├── app/ # Next.js App Router
│ ├── components/ # React组件
│ │ ├── ui/ # 基础UI组件
│ │ ├── layout/ # 布局组件
│ │ ├── sections/ # 页面区块组件
│ │ ├── effects/ # 视觉效果组件
│ │ ├── admin/ # 管理后台组件
│ │ └── analytics/ # 分析组件
│ ├── lib/ # 工具函数和库
│ ├── db/ # 数据库相关
│ ├── hooks/ # 自定义Hooks
│ ├── contexts/ # React Context
│ └── types/ # TypeScript类型定义
├── e2e/ # E2E测试（Playwright）
├── docs/ # 项目文档
│ ├── architecture/ # 架构文档
│ ├── development/ # 开发文档
│ ├── deployment/ # 部署文档
│ ├── testing/ # 测试文档
│ ├── api/ # API文档
│ └── guides/ # 使用指南
├── scripts/ # 脚本文件
│ ├── deployment/ # 部署脚本
│ ├── monitoring/ # 监控脚本
│ ├── testing/ # 测试脚本
│ ├── maintenance/ # 维护脚本
│ └── utils/ # 工具脚本
├── config/ # 配置文件
│ ├── ci/ # CI/CD配置
│ ├── lint/ # 代码检查配置
│ └── test/ # 测试配置
├── public/ # 静态资源
├── .github/ # GitHub配置
├── .woodpecker/ # Woodpecker配置
├── data/ # 数据文件
├── uploads/ # 上传文件
├── backups/ # 备份文件
└── reports/ # 测试报告
├── e2e/ # E2E测试报告
├── performance/ # 性能测试报告
└── coverage/ # 代码覆盖率报告
```
### 2. 文档目录结构
```
docs/
├── README.md # 文档导航
├── architecture/
│ ├── system-design.md # 系统设计
│ ├── database-schema.md # 数据库架构
│ └── api-architecture.md # API架构
├── development/
│ ├── getting-started.md # 快速开始
│ ├── coding-standards.md # 编码规范
│ ├── component-guide.md # 组件开发指南
│ └── debugging-guide.md # 调试指南
├── deployment/
│ ├── production.md # 生产环境部署
│ ├── docker.md # Docker部署
│ └── monitoring.md # 监控配置
├── testing/
│ ├── testing-strategy.md # 测试策略
│ ├── e2e-testing.md # E2E测试
│ ├── unit-testing.md # 单元测试
│ └── performance-testing.md # 性能测试
├── api/
│ ├── rest-api.md # REST API
│ └── admin-api.md # 管理API
└── guides/
├── cms-guide.md # CMS使用指南
├── authentication.md # 认证指南
└── troubleshooting.md # 故障排查
```
### 3. 脚本目录结构
```
scripts/
├── deployment/
│ ├── deploy-production.sh # 部署生产环境
│ ├── backup.sh # 备份数据
│ └── restore.sh # 恢复数据
├── monitoring/
│ ├── setup-monitoring.sh # 设置监控
│ ├── start-monitoring.sh # 启动监控
│ └── check-monitoring.sh # 检查监控
├── testing/
│ ├── test-contact-page.sh # 测试联系页面
│ └── verify-tiered-testing.sh # 验证分层测试
├── maintenance/
│ ├── fix-dev-server.sh # 修复开发服务器
│ └── fix-login-issue.sh # 修复登录问题
└── utils/
├── check-color-contrast.ts # 检查颜色对比度
├── check-heading-hierarchy.ts # 检查标题层级
├── validate-woodpecker-config.js # 验证Woodpecker配置
└── coverage-trend.js # 覆盖率趋势
```
### 4. 配置文件整合
```
config/
├── ci/
│ ├── github/ # GitHub Actions配置
│ └── woodpecker/ # Woodpecker配置
├── lint/
│ ├── .eslintrc.json # ESLint配置
│ ├── .prettierrc # Prettier配置
│ └── commitlint.config.js # Commitlint配置
└── test/
├── playwright.config.ts # Playwright配置
└── jest.config.js # Jest配置
```
## 迁移计划
### 阶段1：创建新目录结构
- [ ] 创建docs目录结构
- [ ] 创建scripts子目录
- [ ] 创建config目录
- [ ] 创建reports目录
### 阶段2：迁移文档文件
- [ ] 移动架构文档到docs/architecture/
- [ ] 移动开发文档到docs/development/
- [ ] 移动部署文档到docs/deployment/
- [ ] 移动测试文档到docs/testing/
- [ ] 移动API文档到docs/api/
### 阶段3：整理脚本文件
- [ ] 分类移动脚本文件到scripts子目录
- [ ] 统一脚本命名规范
- [ ] 为每个脚本添加文档说明
### 阶段4：整合配置文件
- [ ] 移动CI/CD配置到config/ci/
- [ ] 移动代码检查配置到config/lint/
- [ ] 移动测试配置到config/test/
### 阶段5：清理临时文件
- [ ] 移动测试报告到reports/
- [ ] 清理临时文件
- [ ] 更新.gitignore
### 阶段6：更新引用
- [ ] 更新所有文件引用路径
- [ ] 更新package.json脚本
- [ ] 更新CI/CD配置
## 注意事项
1. **保持向后兼容**: 迁移过程中确保所有功能正常工作
2. **分步执行**: 每个阶段完成后进行验证
3. **备份重要文件**: 迁移前备份重要配置和数据
4. **更新文档**: 及时更新相关文档
5. **团队沟通**: 重大变更需要团队review
## 预期效果
### 代码组织
- ✅ 清晰的目录结构
- ✅ 合理的文件分类
- ✅ 统一的命名规范
### 开发效率
- ✅ 快速定位文件
- ✅ 减少查找时间
- ✅ 提高开发效率
### 团队协作
- ✅ 统一的代码组织
- ✅ 清晰的文档结构
- ✅ 降低学习成本
### 维护性
- ✅ 易于维护
- ✅ 易于扩展
- ✅ 易于重构
## 实施时间
- 阶段1: 15分钟
- 阶段2: 20分钟
- 阶段3: 15分钟
- 阶段4: 10分钟
- 阶段5: 10分钟
- 阶段6: 15分钟
**总计: ~85分钟**
## 风险评估
### 高风险
- 更新文件引用路径可能导致构建错误
### 中风险
- 迁移配置文件可能影响CI/CD流程
### 低风险
- 创建新目录结构
- 移动文档文件
- 整理脚本文件
### 缓解措施
1. 逐步迁移，每步验证
2. 保留备份，便于回滚
3. 充分测试，确保功能正常
4. 团队review，减少错误
docs/architecture/architecture.md
+368
View File
@@ -0,0 +1,368 @@
# 系统架构文档
## 架构概述
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;
}
```