# Novalon Website

四川睿新致远科技有限公司官方网站 - 企业数字化转型服务商

## 项目概述

本项目是四川睿新致远科技有限公司的企业官网，采用 Next.js 16 + React 19 + TypeScript 技术栈构建，提供现代化的企业展示、产品服务介绍、案例展示、新闻动态和在线咨询等功能。

### 核心功能

- **首页展示** - Hero 区域、核心业务、产品服务、成功案例、关于我们、新闻动态
- **服务详情** - 软件开发、云服务、数据分析、信息安全等服务详细介绍
- **产品展示** - 产品列表和详情页面
- **案例展示** - 成功案例列表和详情
- **新闻动态** - 公司新闻、产品发布、合作动态、行业资讯
- **在线咨询** - 联系表单、公司信息展示
- **响应式设计** - 完美适配桌面端、平板和移动设备
- **SEO 优化** - 结构化数据、元信息优化
- **CMS管理后台** - 内容管理、用户管理、配置中心、审计日志

## 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Next.js | 16.1.6 |
| UI 库 | React | 19.2.3 |
| 语言 | TypeScript | 5.x |
| 样式 | Tailwind CSS | 4.x |
| 组件库 | shadcn/ui (Radix UI) | - |
| 动画 | Framer Motion | 12.x |
| 图标 | Lucide React | 0.563.0 |
| 邮件服务 | Resend | 6.9.2 |
| 数据验证 | Zod | 4.3.6 |
| 图表 | @antv/g2 | 5.4.8 |
| 3D 效果 | Three.js | 0.183.1 |
| 数据库 | SQLite | - |
| ORM | Drizzle ORM | - |
| 认证 | NextAuth.js | 5.x beta |
| 富文本编辑 | Tiptap | - |

## 快速开始

### 环境要求

- Node.js 18+
- npm / yarn / pnpm / bun

### 安装依赖

```bash
npm install
```

### 环境变量配置

复制环境变量示例文件：

```bash
cp .env.example .env.local
```

配置必要的环境变量：

```env
# 邮件服务
RESEND_API_KEY=your_resend_api_key
COMPANY_EMAIL=contact@novalon.cn

# 数据库
DATABASE_URL=./data/novalon.db

# NextAuth.js
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000

# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760

# 管理员账号（首次运行时创建）
ADMIN_EMAIL=contact@novalon.cn
ADMIN_PASSWORD=your_secure_password
```

### 开发模式

```bash
npm run dev
```

访问 http://localhost:3000

### 构建生产版本

```bash
npm run build
```

输出目录: `dist/`

### 启动生产服务器

```bash
npm start
```

## 项目结构

```
novalon-website/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── (marketing)/         # 营销页面路由组
│   │   │   ├── page.tsx         # 首页
│   │   │   ├── about/           # 关于我们
│   │   │   ├── cases/           # 成功案例
│   │   │   ├── contact/         # 联系我们
│   │   │   ├── news/            # 新闻动态
│   │   │   ├── products/        # 产品服务
│   │   │   ├── services/        # 核心业务
│   │   │   └── solutions/       # 解决方案
│   │   ├── admin/               # 管理后台
│   │   │   ├── page.tsx         # 仪表盘
│   │   │   ├── login/           # 登录页面
│   │   │   ├── content/         # 内容管理
│   │   │   ├── users/           # 用户管理
│   │   │   ├── settings/        # 配置中心
│   │   │   └── logs/            # 审计日志
│   │   ├── api/                 # API 路由
│   │   │   ├── auth/            # 认证 API
│   │   │   ├── contact/         # 联系表单 API
│   │   │   └── admin/           # 管理 API
│   │   │       ├── content/     # 内容管理
│   │   │       ├── users/       # 用户管理
│   │   │       ├── config/      # 配置管理
│   │   │       ├── upload/      # 文件上传
│   │   │       └── logs/        # 审计日志
│   │   ├── layout.tsx           # 根布局
│   │   ├── error.tsx            # 错误页面
│   │   └── not-found.tsx        # 404 页面
│   ├── components/              # React 组件
│   │   ├── ui/                  # 基础 UI 组件
│   │   ├── layout/              # 布局组件
│   │   ├── sections/            # 页面区块组件
│   │   ├── effects/             # 视觉效果组件
│   │   ├── seo/                 # SEO 组件
│   │   ├── analytics/           # 分析组件
│   │   └── admin/               # 管理后台组件
│   ├── lib/                     # 工具函数
│   │   ├── auth/                # 认证相关
│   │   ├── db.ts                # 数据库连接
│   │   ├── audit.ts             # 审计日志
│   │   └── upload.ts            # 文件上传
│   ├── db/                      # 数据库相关
│   │   ├── schema.ts            # 数据库 Schema
│   │   ├── seed.ts              # 种子数据
│   │   └── migrations/          # 迁移文件
│   ├── hooks/                   # 自定义 Hooks
│   └── contexts/                # React Context
├── e2e/                         # E2E 测试
│   ├── src/
│   │   ├── tests/               # 测试用例
│   │   │   ├── smoke/           # 冒烟测试
│   │   │   ├── regression/      # 回归测试
│   │   │   ├── api/             # API 测试
│   │   │   ├── accessibility/   # 可访问性测试
│   │   │   ├── performance/     # 性能测试
│   │   │   ├── security/        # 安全测试
│   │   │   └── visual/          # 视觉回归测试
│   │   ├── pages/               # Page Object
│   │   ├── fixtures/            # 测试 Fixtures
│   │   └── config/              # 测试配置
│   └── playwright.config.ts
├── public/                      # 静态资源
├── uploads/                     # 上传文件存储
├── data/                        # SQLite 数据库文件
├── docs/                        # 项目文档
└── dist/                        # 构建输出
```

## 页面路由

| 路由 | 描述 |
|------|------|
| `/` | 首页 |
| `/about` | 关于我们 |
| `/services` | 核心业务列表 |
| `/services/[id]` | 业务详情 |
| `/products` | 产品服务列表 |
| `/products/[id]` | 产品详情 |
| `/cases` | 成功案例列表 |
| `/cases/[id]` | 案例详情 |
| `/news` | 新闻动态列表 |
| `/news/[slug]` | 新闻详情 |
| `/contact` | 联系我们 |
| `/privacy` | 隐私政策 |
| `/terms` | 服务条款 |
| `/admin` | 管理后台仪表盘 |
| `/admin/login` | 管理员登录 |
| `/admin/content` | 内容管理 |
| `/admin/content/[id]` | 内容编辑 |
| `/admin/users` | 用户管理 |
| `/admin/settings` | 配置中心 |
| `/admin/logs` | 审计日志 |

## NPM 脚本

| 命令 | 描述 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm start` | 启动生产服务器 |
| `npm run lint` | 运行 ESLint 检查 |
| `npm run test` | 运行 E2E 测试 |
| `npm run test:smoke` | 运行冒烟测试 |
| `npm run check:contrast` | 检查颜色对比度 |
| `npm run check:headings` | 检查标题层级 |
| `npm run db:generate` | 生成数据库迁移文件 |
| `npm run db:migrate` | 执行数据库迁移 |
| `npm run db:seed` | 填充数据库种子数据 |
| `npm run db:studio` | 启动 Drizzle Studio |

## 测试

项目使用 Playwright 进行 E2E 测试，测试框架位于 `e2e/` 目录。

### 测试类型

- **冒烟测试** - 基础功能验证
- **回归测试** - 功能完整性验证
- **API测试** - 后端API接口测试
- **性能测试** - Core Web Vitals
- **响应式测试** - 多设备适配
- **可访问性测试** - WCAG 合规
- **安全测试** - XSS、CSRF 防护
- **视觉回归测试** - UI 一致性

### 运行测试

```bash
cd e2e
npm install
npm run test
```

## 管理后台

### 功能模块

#### 内容管理
- 支持新闻、产品、服务、案例四种内容类型
- 富文本编辑器（支持图片上传）
- 内容版本管理
- 草稿/发布/归档状态管理

#### 用户管理
- 用户创建、编辑、删除
- 角色权限控制（管理员、编辑、查看者）
- 密码加密存储

#### 配置中心
- 网站基本信息配置
- SEO配置
- 联系信息配置
- 分类管理

#### 审计日志
- 操作记录追踪
- 按操作类型、资源类型筛选
- 分页查询

### 权限说明

| 角色 | 内容管理 | 用户管理 | 配置管理 | 审计日志 |
|------|---------|---------|---------|---------|
| admin | 全部权限 | 全部权限 | 全部权限 | 查看权限 |
| editor | 创建、编辑、发布 | 无权限 | 查看权限 | 查看权限 |
| viewer | 查看权限 | 无权限 | 查看权限 | 查看权限 |

### API 接口

#### 认证接口
- `POST /api/auth/signin` - 登录
- `POST /api/auth/signout` - 登出
- `GET /api/auth/session` - 获取会话信息

#### 内容管理接口
- `GET /api/admin/content` - 获取内容列表
- `POST /api/admin/content` - 创建内容
- `GET /api/admin/content/[id]` - 获取内容详情
- `PUT /api/admin/content/[id]` - 更新内容
- `DELETE /api/admin/content/[id]` - 删除内容

#### 用户管理接口
- `GET /api/admin/users` - 获取用户列表
- `POST /api/admin/users` - 创建用户
- `GET /api/admin/users/[id]` - 获取用户详情
- `PUT /api/admin/users/[id]` - 更新用户
- `DELETE /api/admin/users/[id]` - 删除用户

#### 配置管理接口
- `GET /api/admin/config` - 获取配置列表
- `POST /api/admin/config` - 更新配置

#### 文件上传接口
- `POST /api/admin/upload` - 上传文件
- `DELETE /api/admin/upload` - 删除文件

#### 审计日志接口
- `GET /api/admin/logs` - 获取审计日志列表

## CI/CD

项目使用 Woodpecker CI 进行持续集成，配置文件为 `.woodpecker/` 目录。

CI 流水线包括：
- **CI 工作流** (`.woodpecker/ci.yml`) - 代码检查、测试、构建
- **部署工作流** (`.woodpecker/deploy.yml`) - 生产环境部署
- **质量门禁** (`.woodpecker/quality-gate.yml`) - 代码质量检查

### CI 触发条件

- 分支：`main`、`develop`
- 事件：`push`、`pull_request`

### 质量门禁标准

- ESLint 检查通过
- TypeScript 类型检查通过
- 单元测试覆盖率 ≥ 70%
- E2E 测试通过率 ≥ 95%

## 监控和告警

### Sentry 错误监控

项目集成了 Sentry 错误监控，用于追踪生产环境中的错误。

**配置环境变量：**

```env
NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
```

**监控内容：**
- JavaScript 错误
- API 错误
- 性能追踪
- 用户会话回放

### 健康检查

健康检查 API：`GET /api/health`

**返回信息：**
- 应用状态
- 运行时间
- 内存使用
- 数据库连接状态
- 请求统计

### 性能监控

项目内置性能监控工具，记录关键指标：
- 响应时间（平均值、P50、P95、P99）
- 请求计数
- 内存使用率

**查看性能数据：**

```bash
curl http://localhost:3000/api/health
```

## 备份和恢复

### 备份

使用备份脚本定期备份数据：

```bash
./scripts/backup.sh
```

**备份内容包括：**
- SQLite 数据库文件
- 上传文件
- 环境配置

**备份文件位置：** `./backups/backup_YYYYMMDD_HHMMSS.tar.gz`

**自动清理：** 保留最近 7 天的备份

### 恢复

使用恢复脚本从备份中恢复数据：

```bash
./scripts/restore.sh <backup_file.tar.gz>
```

**注意事项：**
- 恢复操作会覆盖当前数据
- 恢复后需要重启应用
- 建议在恢复前先备份当前数据

## 性能测试

项目使用 k6 进行性能测试。

### 负载测试

模拟正常用户访问模式，测试系统在预期负载下的表现。

```bash
npm run test:performance
```

**测试场景：**
- 逐步增加用户数（100 → 200）
- 访问主要页面
- 提交联系表单

**性能指标：**
- P95 响应时间 < 500ms
- P99 响应时间 < 1000ms
- 错误率 < 1%

### 压力测试

测试系统在极端负载下的表现和极限。

```bash
npm run test:stress
```

**测试场景：**
- 快速增加用户数（50 → 300）
- 持续高负载
- 快速下降

**性能指标：**
- P95 响应时间 < 1000ms
- P99 响应时间 < 2000ms
- 错误率 < 5%

**测试报告：** `tests/performance/load-test-summary.json`

## 安全测试

项目使用 k6 进行安全测试。

### SQL 注入测试

测试系统对 SQL 注入攻击的防护能力。

```bash
npm run test:sql-injection
```

**测试内容：**
- 常见 SQL 注入 payload
- UNION 查询注入
- 盲注攻击
- 时间注入

**防护措施：**
- 使用参数化查询（Drizzle ORM）
- 输入验证和过滤
- 错误信息脱敏

### XSS 防护测试

测试系统对跨站脚本攻击的防护能力。

```bash
npm run test:xss
```

**测试内容：**
- Script 标签注入
- 事件处理器注入
- JavaScript 伪协议
- 外部资源引用

**防护措施：**
- 输入转义（DOMPurify）
- CSP 策略
- HTTPOnly Cookie

### 完整安全测试

运行所有安全测试：

```bash
npm run test:security
```

## Docker 部署

项目提供 Docker 部署方案。

### 构建镜像

```bash
docker build -t novalon-website .
```

### 使用 Docker Compose

```bash
cp .env.production.example .env.production
docker-compose -f docker-compose.prod.yml up -d
```

### 健康检查

Docker 容器配置了健康检查：

```yaml
healthcheck:
  test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

## 生产环境配置

### 环境变量

生产环境需要配置以下变量：

```env
# 数据库
DATABASE_URL=file:./data/prod.db

# NextAuth
NEXTAUTH_URL=https://novalon.cn
NEXTAUTH_SECRET=your-production-secret-here

# 管理员
ADMIN_EMAIL=admin@novalon.cn
ADMIN_PASSWORD=your-secure-password

# Sentry
NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx

# 邮件服务
RESEND_API_KEY=your_resend_api_key
COMPANY_EMAIL=contact@novalon.cn

# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760

# 站点 URL
NEXT_PUBLIC_SITE_URL=https://novalon.cn
```

### 部署流程

1. **准备环境**
   ```bash
   cp .env.production.example .env.production
   # 编辑 .env.production 配置生产环境变量
   ```

2. **构建应用**
   ```bash
   npm run build
   ```

3. **初始化数据库**
   ```bash
   npm run db:push
   npm run db:seed
   ```

4. **启动服务**
   ```bash
   npm start
   # 或使用 Docker
   docker-compose -f docker-compose.prod.yml up -d
   ```

5. **验证部署**
   ```bash
   curl http://localhost:3000/api/health
   ```

6. **配置监控**
   - 在 Sentry 创建项目并配置 DSN
   - 配置告警规则

7. **设置定时备份**
   ```bash
   # 添加到 crontab
   0 2 * * * /path/to/scripts/backup.sh
   ```

## 文档

详细文档位于 `docs/` 目录：

- [架构文档](docs/architecture.md) - 系统架构设计
- [组件文档](docs/components.md) - 组件使用指南
- [API 文档](docs/api.md) - API 接口说明
- [测试文档](docs/testing.md) - 测试策略和指南
- [部署文档](docs/deployment.md) - 部署流程说明
- [CMS文档](docs/cms.md) - CMS系统使用指南

## 许可证

Copyright © 2026 四川睿新致远科技有限公司