张翔
10404dbb36
同步工作区剩余变更，主要包括： - 营销页面组件与布局持续优化（about/news/services/solutions/team 等） - 详情页四层叙事组件、布局组件、UI 组件调整 - CMS 数据模型、API 路由、权限、工作流、站内通知、媒体管理扩展 - 新增/补充单元测试与 E2E 测试（cms-workflow.spec.ts 等） - ESLint 9 迁移、jest/tsconfig 配置更新、依赖调整 - 新增 ADR、CMS 评估文档、Release Review / Acceptance 报告 - 移除水墨装饰组件与大体积未使用字体文件
262 lines
11 KiB
Markdown
262 lines
11 KiB
Markdown
# Novalon Website
|
||
|
||
四川睿新致远科技有限公司官方网站 - 企业数字化转型服务商
|
||
|
||
## 项目概述
|
||
|
||
本项目是四川睿新致远科技有限公司的企业官网，采用 Next.js 16 + React 18 + TypeScript 技术栈构建，以静态生成（SSG）为主、混合渲染（SSR/ISR）为辅，提供现代化的企业展示、产品服务介绍、案例展示、新闻动态等功能。
|
||
|
||
### 核心功能
|
||
|
||
- **首页展示** - Hero 区域、核心业务、产品服务、成功案例、关于我们、新闻动态
|
||
- **服务详情** - 软件开发、云服务、数据分析、信息安全等服务详细介绍
|
||
- **产品展示** - 产品列表和详情页面
|
||
- **案例展示** - 成功案例列表和详情
|
||
- **新闻动态** - 公司新闻、产品发布、合作动态、行业资讯
|
||
- **响应式设计** - 完美适配桌面端、平板和移动设备
|
||
- **SEO 优化** - 结构化数据、元信息优化
|
||
|
||
## 项目规划
|
||
|
||
- 2026-07：完成 Bain 风格首页与详情页改版、四层级叙事组件重构
|
||
- 2026-07：完成安全加固（JWT、中间件、表单、CMS 接口）、可访问性修复
|
||
- 2026-07：完成全量测试基线建立（单元测试 705 条、E2E 618 条）与封版审查
|
||
- 2026-07：完成 CMS 数据模型扩展（locale、RBAC）、媒体管理、工作流引擎，并按页面类型全量迁移内容（基于 [docs/cms-evaluation.md](./docs/cms-evaluation.md)）
|
||
|
||
## 项目进度
|
||
|
||
- [x] 首页/关于/产品/新闻等核心页面可访问性修复
|
||
- [x] JWT、中间件、表单、CMS 接口安全加固
|
||
|
||
- [x] WCAG 2.1 AA、标题层级、色彩对比度检查全部通过
|
||
- [x] 生成 [RELEASE_REVIEW_REPORT.md](./RELEASE_REVIEW_REPORT.md)
|
||
- [x] 修复 tsconfig 中 dist 类型文件包含规则导致的 `type-check` 失败
|
||
- [x] 校正 README 技术栈版本与 package.json 一致
|
||
- [ ] 生产环境变量与 Nginx 安全头最终确认（上线前）
|
||
- [x] CMS 数据模型扩展：为 ContentItem 增加 locale 字段与唯一索引
|
||
- [x] CMS 数据模型扩展：RBAC 角色与权限中间件
|
||
- [x] CMS 内容状态机与工作流：draft/review/published/archived + AuditLog
|
||
- [x] CMS 媒体管理模块：上传、本地/S3 双写、缩略图/WebP/AVIF 派生格式
|
||
- [x] CMS 站内消息通知中心：提交/审核/归档时生成通知、未读计数、标记已读
|
||
- [x] Nginx 生产配置支持混合渲染（/api/*、/admin/* 代理 Next.js，ISR 回源）
|
||
- [x] CMS 法律页迁移：privacy/terms 从 CMS 读取内容并启用 ISR（3600s）
|
||
- [x] CMS 新闻页迁移：列表/详情从 CMS 读取并启用 ISR（3600s）
|
||
- [x] CMS 团队页迁移：/team 从 CMS 读取并启用 ISR（3600s）
|
||
- [x] CMS 案例页迁移：列表/详情从 CMS 读取并启用 ISR（3600s），保留行业过滤与指标/时间线结构
|
||
- [x] CMS 服务页迁移：列表/详情从 CMS 读取并启用 ISR（3600s），保留服务编号、色条编码、metrics 与四层叙事结构
|
||
- [x] CMS 方案页迁移：列表/详情从 CMS 读取并启用 ISR（3600s），保留行业、痛点、解决方案、价值主张、推荐产品组合与 HSI 交叉引用
|
||
- [x] CMS 产品页迁移：列表/详情/独立产品页从 CMS 读取并启用 ISR（3600s），保留四层叙事、技术规格与产品组合分类
|
||
- [x] CMS 独立产品页迁移：创建独立 `standalone-product` 内容模型，支持技术参数、合规认证等硬核字段；详情页从独立模型读取并启用 ISR（3600s）
|
||
- [x] CMS 首页运营位迁移：首页改为通过 `ContentZone` 读取 Hero、Stats、Services、Cases 等 Zone，支持后台调整 Zone 内容与排序；启用 ISR（3600s），相关模型更新时同步刷新首页
|
||
- [x] CMS 管理后台：构建角色权限管理界面（`/admin/roles`），支持角色列表、内容模型 × 操作权限矩阵配置、super_admin 锁定
|
||
- [x] CMS/RBAC/工作流测试覆盖：补充 zones/models/items/media/notifications/roles/workflow 路由与权限/状态机/数据访问单元测试；新增 `e2e/cms-workflow.spec.ts` 覆盖管理员单角色发布、非法状态拦截、多角色权限分离完整流程；新增 `e2e/storageState.json` 预置 Cookie 偏好，消除 Cookie 同意弹窗对 E2E 的遮挡；修复类型错误，单元测试 942 条、E2E 功能回归 520 条全部通过
|
||
- [x] 封版验收测试（2026-07-22）：完成静态门禁、E2E 回归、视觉回归、Lighthouse、k6 负载/压力、安全扫描全量执行，修复压力测试脚本与 Next.js 16 / ESLint 9 迁移问题，`npm audit` 0 漏洞，结论更新为通过，生成 [`RELEASE_ACCEPTANCE_REPORT.md`](./RELEASE_ACCEPTANCE_REPORT.md)
|
||
- [x] 首页 UI 设计优化（2026-07-23）：按 `impeccable` 默认流程完成 colorize/harden/layout/typeset/polish，落地 `home-content-v14.tsx`（克制白底 Hero、等宽三列服务卡片、紧凑案例快照、FALLBACK_SERVICES 兜底）；更新 chromium desktop/tablet/mobile 视觉基线；修复 `e2e/p5-edge-cases.spec.ts` header 选择器严格模式问题；type-check / lint / unit 942 条 / 视觉 63 条 / 功能 E2E 174 条全部通过
|
||
- [x] 顶部导航栏对齐修复（2026-07-23）：统一桌面端下拉项与普通链接的 wrapper 结构（`relative -mx-2 px-2 py-2`）与 `inline-flex items-center` 显示方式，修复顶部导航文字不在同一水平线的问题；同步更新 desktop/tablet/mobile/webkit/firefox 视觉基线；chromium/webkit 功能 E2E 与视觉回归全部通过
|
||
- [x] CMS / Admin 后台 dogfood 修复与回归（2026-07-25）：修复登录后无限重定向、内容保存 400/500、编辑提交 status、原生 confirm 阻塞自动化、表单可访问性、标签输入、操作 Toast 反馈、后台 Cookie 横幅、媒体库空状态等 9 项问题；生成 [`dogfood-cms-regression/report.md`](./dogfood-cms-regression/report.md)，19 步回归检查全部通过；type-check / lint（0 errors，172 既有 warnings）/ test:unit（71 suites / 943 tests）全部通过
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 框架 | Next.js | 16.2.11 |
|
||
| UI 库 | React | 18.3.1 |
|
||
| 语言 | TypeScript | 5.x |
|
||
| 样式 | Tailwind CSS | 3.4.17 |
|
||
| 代码检查 | ESLint | 9.25.1 |
|
||
| 组件库 | shadcn/ui (Radix UI) | - |
|
||
| 动画 | Framer Motion | 12.x |
|
||
| 图标 | Lucide React | 0.563.0 |
|
||
| 数据验证 | Zod | 4.3.6 |
|
||
| 图表 | @antv/g2 | 5.4.8 |
|
||
| 3D 效果 | Three.js | 0.183.1 |
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+
|
||
- npm / yarn / pnpm / bun
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 开发模式
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:3000
|
||
|
||
### 构建生产版本
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
输出目录: `dist/`
|
||
|
||
### 预览生产版本
|
||
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
novalon-website/
|
||
├── src/ # 源代码
|
||
│ ├── app/ # Next.js App Router
|
||
│ │ ├── (marketing)/ # 营销页面路由组
|
||
│ │ │ ├── page.tsx # 首页
|
||
│ │ │ ├── about/ # 关于我们
|
||
│ │ │ ├── cases/ # 成功案例
|
||
│ │ │ ├── contact/ # 联系我们
|
||
│ │ │ ├── news/ # 新闻动态
|
||
│ │ │ ├── products/ # 产品服务
|
||
│ │ │ ├── services/ # 核心业务
|
||
│ │ │ └── solutions/ # 解决方案
|
||
│ │ ├── privacy/ # 隐私政策
|
||
│ │ ├── terms/ # 服务条款
|
||
│ │ ├── layout.tsx # 根布局
|
||
│ │ ├── error.tsx # 错误页面
|
||
│ │ └── not-found.tsx # 404 页面
|
||
│ ├── components/ # React 组件
|
||
│ │ ├── ui/ # 基础 UI 组件
|
||
│ │ ├── layout/ # 布局组件
|
||
│ │ ├── sections/ # 页面区块组件
|
||
│ │ ├── effects/ # 视觉效果组件
|
||
│ │ ├── seo/ # SEO 组件
|
||
│ │ └── analytics/ # 分析组件
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ └── contexts/ # React Context
|
||
├── e2e/ # E2E 测试
|
||
├── tests/ # 测试文件
|
||
│ ├── performance/ # 性能测试
|
||
│ └── styles/ # 样式测试
|
||
├── docs/ # 项目文档
|
||
├── scripts/ # 脚本文件
|
||
├── config/ # 配置文件
|
||
├── public/ # 静态资源
|
||
└── dist/ # 构建输出
|
||
```
|
||
|
||
## 页面路由
|
||
|
||
| 路由 | 描述 |
|
||
|------|------|
|
||
| `/` | 首页 |
|
||
| `/about` | 关于我们 |
|
||
| `/services` | 核心业务列表 |
|
||
| `/services/[id]` | 业务详情 |
|
||
| `/products` | 产品服务列表 |
|
||
| `/products/[id]` | 产品详情 |
|
||
| `/cases` | 成功案例列表 |
|
||
| `/cases/[id]` | 案例详情 |
|
||
| `/news` | 新闻动态列表 |
|
||
| `/news/[slug]` | 新闻详情 |
|
||
| `/contact` | 联系我们 |
|
||
| `/privacy` | 隐私政策 |
|
||
| `/terms` | 服务条款 |
|
||
|
||
## NPM 脚本
|
||
|
||
| 命令 | 描述 |
|
||
|------|------|
|
||
| `npm run dev` | 启动开发服务器 |
|
||
| `npm run build` | 构建生产版本 |
|
||
| `npm start` | 启动生产服务器 |
|
||
| `npm run lint` | 运行 ESLint 检查 |
|
||
| `npm run type-check` | TypeScript 类型检查 |
|
||
| `npm run test` | 运行 E2E 测试 |
|
||
| `npm run test:unit` | 运行单元测试 |
|
||
| `npm run test:coverage` | 运行测试覆盖率 |
|
||
| `npm run lighthouse` | 运行 Lighthouse 性能测试 |
|
||
|
||
## 代码质量门禁
|
||
|
||
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查：
|
||
|
||
- **ESLint**: 代码风格检查
|
||
- **commitlint**: 提交信息规范
|
||
- **Jest**: 代码覆盖率检查
|
||
|
||
### 提交规范
|
||
|
||
使用 Conventional Commits 规范：
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
```
|
||
|
||
**提交类型**:
|
||
- `feat`: 新功能
|
||
- `fix`: 修复bug
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式调整
|
||
- `refactor`: 重构
|
||
- `perf`: 性能优化
|
||
- `test`: 测试相关
|
||
- `chore`: 构建/工具相关
|
||
|
||
## 测试
|
||
|
||
项目使用 Playwright 进行 E2E 测试，Jest 进行单元测试。
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# E2E 测试
|
||
npm run test
|
||
|
||
# 单元测试
|
||
npm run test:unit
|
||
|
||
# 测试覆盖率
|
||
npm run test:coverage
|
||
```
|
||
|
||
## 部署
|
||
|
||
### 静态部署
|
||
|
||
项目构建后生成纯静态文件，可部署到任何静态托管服务：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建产物位于 `dist/` 目录，可直接部署到：
|
||
- Nginx
|
||
- CDN
|
||
- Vercel
|
||
- Netlify
|
||
- GitHub Pages
|
||
|
||
### Docker 部署
|
||
|
||
```bash
|
||
docker build -t novalon-website .
|
||
docker run -p 3000:3000 novalon-website
|
||
```
|
||
|
||
## 文档
|
||
|
||
详细文档位于 `docs/` 目录：
|
||
|
||
- [架构文档](docs/architecture.md) - 系统架构设计
|
||
- [组件文档](docs/components.md) - 组件使用指南
|
||
- [测试文档](docs/testing.md) - 测试策略和指南
|
||
- [部署文档](docs/deployment.md) - 部署流程说明
|
||
- [经验教训](docs/lessons-learned.md) - 跨任务经验教训汇总，避免重复踩坑
|
||
- [问题排查](docs/troubleshooting.md) - 常见问题快速索引与解决方案
|
||
|
||
## 许可证
|
||
|
||
Copyright © 2026 四川睿新致远科技有限公司
|