zhangxiang
43d1a7af38
对齐 novavis AGENTS.md §27，逐项按本仓实测改写，不照抄不存在的命令： - scripts/check-pr-checklist.sh：三种模式（模板结构 / 单 PR 文件 / --pr-dir 扫描） 与退出码 0/1/2 保持同源；模板根改为按脚本自身位置解析并保留 AGENT_PROJECT_DIR 覆写；修上游 --pr-dir 的参数解析缺陷（for arg in "$@" 内 shift 不消费值， 目录会被再当成 PR 文件），改 while+shift - .gitea/PULL_REQUEST_TEMPLATE.md：30 项 checklist 全部换成本仓真实门禁命令 （type-check / lint / test:unit / test:coverage 阈值 / Playwright / visual / check:contrast / check:headings / lighthouse / test:security:headers），并补 CMS 字段-需重跑 seed 声明、:3000 旧预览不作数、暗黑 token、动效 180–280ms、 品牌红触达、数字 basis 口径等本仓专有约束 - 文档同源：docs/development/quality-gates.md 新增「提交与 PR 流程」权威副本 （AGENTS.md 被 .gitignore 排除，不可依赖）、CLAUDE.md 补 Submission Flow 节 门禁自检：脚本 bash -n 通过；11 个用例覆盖三模式 + 缺节/缺文件/子项不足/非 PR 文件/未知选項/--quiet 等负路径，均带正控制以防「匹配零的假绿」。
Novalon Website
四川睿新致远科技有限公司官方网站 - 企业数字化转型服务商
项目概述
本项目是四川睿新致远科技有限公司的企业官网，采用 Next.js 16 + React 18 + TypeScript 技术栈构建，以静态生成（SSG）为主、混合渲染（SSR/ISR）为辅，提供现代化的企业展示、产品服务介绍、案例展示、新闻动态等功能。
核心功能
- 首页展示 - Hero 区域、核心业务、产品服务、成功案例、关于我们、新闻动态
- 服务详情 - 软件开发、云服务、数据分析、信息安全等服务详细介绍
- 产品展示 - 产品列表和详情页面
- 案例展示 - 成功案例列表和详情
- 新闻动态 - 公司新闻、产品发布、合作动态、行业资讯
- 响应式设计 - 完美适配桌面端、平板和移动设备
- SEO 优化 - 结构化数据、元信息优化
项目规划
- 2026-07：UI 重构（四层叙事模型、咨询专业风）、CMS 全覆盖、安全加固、封版发布
v1.0.0-phase1 - 2026-08：全量测试基线建立（单元 ~1600 / E2E
800 / UJ-01UJ-11）/ 官网产品模块品牌矩阵定位（产品外链独立站）/ 结构性文案全站 CMS 化（page-copy）/ 信任证据阶段 0（成立 <1 年策略） - 2026-08-20：生产部署上线 + 生产目录 Drizzle 残留归档清理
详细历史里程碑、测试验收报告见 docs/deployment.md 与 docs/testing 目录。
项目进度
-
首页/关于/产品/新闻等核心页面可访问性修复
-
JWT、中间件、表单、CMS 接口安全加固
-
CMS 全覆盖：法律页、新闻、团队、案例、服务、方案、产品、独立产品、首页运营位（ContentZone）、RBAC/工作流/媒体/通知全部从 CMS 读取并启用 ISR（3600s）
-
CMS 管理后台：角色权限界面（
/admin/roles）、内容模型 × 操作权限矩阵、super_admin 锁定 -
全量测试体系：单元 ~1600 / 功能 E2E
800 / 视觉回归三端 / 用户旅程 UJ-01UJ-11 / Lighthouse / k6 负载压力 / 安全扫描，全部通过 -
官网产品模块定位（IHG/字节式品牌矩阵，2026-08-19）：官网品牌宣传为主，产品矩阵页为聚合入口；成熟产品
externalUrl外链独立站（NovaVis → novavis.p.novalon.cn）；未成熟产品详情页占位，独立站上线后切换外链 -
结构性文案全站 CMS 化（2026-08-19）：新增
page-copy内容模型承载全部营销页面章节标题/眉标/描述/CTA/空状态（首页 + 服务/方案/产品/案例/新闻列表页），「CMS 优先 + 硬编码兜底」不白屏；seed 写入 6 条，本地 db:seed 已生效 -
信任证据补齐·阶段 0（成立 <1 年策略，2026-08-20）：信任策略从「结果证据」转向「可验证的过程 + 能力 + 治理证据」——首页「首批客户共创计划」板块（共创进行中/产品内测中/成果授权公开三档如实状态 + 招募 CTA）+ 关于页资质「建设中」如实空态，零编造
-
生产部署上线（2026-08-20)：
deploy.sh deploy（本地 dist → 远端容器重建）+ 生产库 seed（page-copy/methodology 数据）完成；生产目录 Drizzle 残留源码归档清理；站点全路由 200、生产库 Prisma 结构 -
数字口径结构强制（2026-09-20，critique P0 收尾）：共享数字样式渲染的指标（
metrics/outcomes/dataProofs）统一携带basis: target|team-history|verified，渲染端自动附口径角注、未声明保守回落target；CMS 新增basisselect 录入字段；删除产品详情页「每一项指标都源自真实客户案例」「经实际场景验证」等虚构佐证并补注角注；metrics-basis.test.ts机械校验声明完整性并拦截虚构佐证禁词 -
信任证据补齐·阶段 1/2（待内测/试点客户素材）：如实披露「共创中/内测中/已交付」三档 + 经授权客户（脱敏）；有交付成果后经授权公示可量化结果（零编造原则）——口径字段与 admin 录入口已就绪，待真实数据把
basis从target升级为verified
技术栈
| 类别 | 技术 | 版本 |
|---|---|---|
| 框架 | 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
安装依赖
npm install
开发模式
npm run dev
构建生产版本
npm run build
输出目录: dist/
预览生产版本
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 |
运行单元测试（Jest，120 suites / 1509 tests） |
npm run test:coverage |
运行测试覆盖率（当前 Branches 82.38%, Lines 73.59%） |
npm run test:e2e:fast |
运行 E2E 快速测试（@smoke + @critical 标签） |
npm run test:e2e:standard |
运行 E2E 标准回归测试（@regression 标签） |
npm run test:smoke |
运行 E2E 冒烟测试（@smoke 标签） |
npm run test:critical |
运行 E2E 关键路径测试（@critical 标签） |
npm run test:e2e:journey |
运行用户旅程测试（@journey 标签，UJ-01/UJ-02） |
npm run test:e2e:mobile |
运行移动端 E2E 测试（@mobile 标签，53 个测试） |
npm run test:e2e:mobile:performance |
运行移动端性能基线测试（FCP/LCP/加载时间） |
npm run test:e2e:mobile:accessibility |
运行移动端可访问性测试（axe-core WCAG 2.1 AA） |
npm run test:mutation |
运行变异测试（Stryker，评估测试质量，当前 36.98%） |
npm run test:mutation:quick |
快速变异测试（仅 utils.ts，91.18%） |
npm run test:security |
安全扫描（npm audit + 安全响应头检查） |
npm run test:security:headers |
安全响应头检查（X-Content-Type-Options, CSP, HSTS 等） |
npm run test:all |
全量门禁检查（type-check + lint + coverage + fast E2E + security headers） |
npm run lighthouse |
运行 Lighthouse 性能测试 |
代码质量门禁
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查：
- ESLint: 代码风格检查
- commitlint: 提交信息规范
- Jest: 代码覆盖率检查
提交规范
使用 Conventional Commits 规范：
<type>(<scope>): <subject>
提交类型:
feat: 新功能fix: 修复bugdocs: 文档更新style: 代码格式调整refactor: 重构perf: 性能优化test: 测试相关chore: 构建/工具相关
测试
项目采用多层测试策略，涵盖单元测试、集成测试、E2E 测试、用户旅程测试、视觉回归测试、变异测试等。
测试工具链
| 工具 | 用途 | 配置 |
|---|---|---|
| Jest | 单元测试（120 suites / 1509 tests） | config/test/jest.config.js |
| Playwright | E2E / 视觉回归 / 用户旅程测试 | e2e/playwright.config.ts |
| Stryker | 变异测试（评估测试质量） | stryker.config.json |
| Allure | 测试报告可视化 | Allure Playwright reporter |
| k6 | 负载/压力/API 性能测试 | tests/performance/ |
| Lighthouse CI | 性能/可访问性/SEO 审计 | lighthouserc.js |
E2E 测试标签体系
| 标签 | 用途 | 执行命令 |
|---|---|---|
@smoke |
冒烟测试：核心功能 | npm run test:smoke |
@critical |
关键路径：CMS 工作流等 | npm run test:critical |
@smoke + @critical |
快速回归（<5min） | npm run test:e2e:fast |
@regression |
全量回归（<15min） | npm run test:e2e:standard |
@journey |
用户旅程（UJ-01/UJ-02） | npm run test:e2e:journey |
@mobile |
移动端专项测试（53 个：16 基础 + 5 用户旅程 + 14 可访问性 + 18 性能） | npm run test:e2e:mobile |
@visual |
视觉回归（105 snapshots × 5 browsers） | npm run test:visual:all |
运行测试
# 单元测试
npm run test:unit # 1509 tests
# 测试覆盖率
npm run test:coverage # Branches 82.38%, Lines 73.59%
# E2E 测试
npm run test # 全量 E2E（631 passed）
npm run test:e2e:fast # 快速回归（@smoke + @critical）
npm run test:e2e:standard # 标准回归（@regression）
npm run test:e2e:journey # 用户旅程（@journey）
# 移动端测试
npm run test:e2e:mobile # 全量移动端（53 个 @mobile 测试）
npm run test:e2e:mobile:performance # 移动端性能基线
npm run test:e2e:mobile:accessibility # 移动端可访问性
# 变异测试
npm run test:mutation # 全量变异测试
npm run test:mutation:quick # 快速变异（仅 utils.ts）
# 全量门禁检查
npm run test:all # type-check + lint + coverage + fast E2E
部署
统一发布脚本（推荐）
项目发布统一通过 scripts/deploy.sh 完成，包含构建、发布、回滚、状态查看：
# 构建静态产物
./scripts/deploy.sh build
# 构建并发布到生产服务器（默认命令，等价于 ./scripts/deploy.sh deploy）
./scripts/deploy.sh deploy
# 使用现有 dist/ 直接发布（跳过本地构建）
./scripts/deploy.sh deploy --skip-build
# 回滚到最近一次远程备份
./scripts/deploy.sh rollback
# 查看生产环境发布状态
./scripts/deploy.sh status
# 查看完整帮助
./scripts/deploy.sh help
常用选项：
./scripts/deploy.sh deploy --skip-build --auto-rollback
./scripts/deploy.sh deploy --server-ip 139.155.109.62 --project-name novalon-website
也可通过环境变量覆盖默认配置：SERVER_IP、SERVER_USER、DEPLOY_ROOT、PROJECT_NAME、NGINX_CONTAINER、DOMAIN、BACKUP_RETENTION_COUNT、DIST_DIR。
npm 快捷命令：npm run deploy、npm run deploy:skip-build、npm run deploy:rollback、npm run deploy:status。
混合渲染构建（当前）
项目当前使用 output: 'standalone'，构建产物位于 dist/：
npm run build
生产部署采用混合渲染：
- Nginx 直接托管
dist/中的公共静态资源（图片、字体、_next/static等） /api/*、/admin/*及 ISR/SSR 回源代理到 Next.js 容器novalon-website:3000- Next.js 容器通过
Dockerfile.prod+docker-compose.server.yml启动，SQLite 数据库挂载在./data
# 本地构建
npm run build
# 服务器构建并启动 Next.js 容器
cd /home/novalon/docker-app/novalon-website
docker-compose -f docker-compose.server.yml up -d --build
生产环境历史残留清理（Drizzle）
生产服务器 /home/novalon/docker-app/novalon-website 曾残留一套使用 Drizzle ORM 的历史源码（src/db/、drizzle/、drizzle.config.ts）。经核实，生产实际运行的环境为 Prisma CMS（容器从 dist/ standalone 构建，含 @prisma/client 与 prisma/seed.ts），上述 Drizzle 源码不参与任何构建/部署/运行。
2026-08-20 已将 Drizzle 专属残留归档至 archive-Drizzle-20260820_094628/（含 src/db/、drizzle/、drizzle.config.ts）。同批做了一次更大范围整理：将历史源码/测试/文档/旧备份归档至 archive-src-cleanup-20260820_095755/（含 src/、playwright-*、test-framework、tests、e2e、reports、docs、monitoring、html 等）与 archive-misc-20260820_095824/（含根 data.db、scripts.backup、test-results、旧 dist_backup_20260818_* 等）。生产确认保留运行时资产：dist/、public/、data/、uploads/、Dockerfile.prod、docker-compose.server.yml、.env*、deploy.sh、scripts/。生产站点与数据库均不受影响（容器 healthy、全路由 200、共创板块正常）。后续如需彻底移除归档目录（共约 908M），可在运行稳定数周后删除。
CI/CD
Jenkins Pipeline（Jenkinsfile）在部署阶段调用 ./scripts/deploy.sh deploy --skip-build，部署失败时自动调用 ./scripts/deploy.sh rollback 回滚。
文档
详细文档位于 docs/ 目录：
- 架构文档 - 系统架构设计
- 组件文档 - 组件使用指南
- 测试文档 - 测试策略和指南
- 部署文档 - 部署流程说明
- 经验教训 - 跨任务经验教训汇总，避免重复踩坑
- 问题排查 - 常见问题快速索引与解决方案
许可证
Copyright © 2026 四川睿新致远科技有限公司