Files
novalon-website/README.md
T
zhangxiang 11afb2cc9f docs(sync): 按 AGENTS.md §6 把本轮五条裁定与三台新闸写回四份文档
- CLAUDE.md:新增 type-check:e2e 与 check:package-keys 两条命令及其存在理由。
- CONTEXT.md 关键决策表:追加 5 行(缓存失效单一真源 / 产品线色相受控例外 /
  动效时长按用途在消费点判 / 案例发布门槛 / e2e 与 scripts 的静态口径)。
- README.md:把「本批遗留待拍/待授权」整句换成 §12 轮的实际处置,含
  DEC-N2 被证伪一事;test:all 的描述由「原文七段」改为现取十段。
- quality-gates.md:新增「§12 轮新增/改写的门禁」表,每行都带自证或负对照读数,
  并写明仍未并入 test:all 的两项与 axe 的 :3100 编排口径。
- package.json:check:package-keys 入 test:all(十段),键唯一性由守卫自证 EXIT=0。
2026-10-17 08:19:10 +08:00

379 lines
29 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-01~UJ-11)/ 官网产品模块品牌矩阵定位(产品外链独立站)/ 结构性文案全站 CMS 化(`page-copy`)/ 信任证据阶段 0(成立 <1 年策略)
- **2026-08-20**:生产部署上线 + 生产目录 Drizzle 残留归档清理
详细历史里程碑、测试验收报告见 [docs/deployment.md](docs/deployment.md) 与 [docs/testing](docs/testing) 目录。
## 项目进度
- [x] 首页/关于/产品/新闻等核心页面可访问性修复
- [x] JWT、中间件、表单、CMS 接口安全加固
- [x] CMS 全覆盖:法律页、新闻、团队、案例、服务、方案、产品、独立产品、首页运营位(ContentZone)、RBAC/工作流/媒体/通知全部从 CMS 读取并启用 ISR(3600s)
- [x] CMS 管理后台:角色权限界面(`/admin/roles`)、内容模型 × 操作权限矩阵、super_admin 锁定
- [x] 全量测试体系:单元 **134 suites / 1697 例** / 功能 E2E **1080 例**(270 例 × chromium + chromium-mobile + firefox + webkit 四个 project)/ 视觉回归 **125 例**(25 例 × 桌面·平板·移动·firefox·webkit 五个 project)/ 用户旅程 UJ-01~UJ-11 / Lighthouse / k6 负载压力 / 安全扫描。**本条不声明「全部通过」**:单元与真库集成层在封版树 `a0328a6` 上全绿(`npm run test:coverage`、`npm run test:integration:real`);**视觉回归在 2026-10-08 补齐并逐张追认 38 张参照后,独立只读复跑 125 passed / 0 failed / EXIT=0**(AUTH-D3 就此闭合;此前封版树实测 94/31 = 20 例缺参照 + 11 例已过时,已逐条归因,非像素级产品缺陷);生产目标 E2E 实测 **91 passed / 1 failed**(唯一红为 firefox 并发墙钟);`check:motion` 判红数见 `docs/development/quality-gates.md` §5.1(2026-10-17 本树复测为 8 处,未并入伞形门禁)。**计数一律不在此复制**:以 `npm run test:coverage`、`cd e2e && npx playwright test --list`、`docs/acceptance/2026-09-30-seal/final-verdict.md` §1 表与 `docs/acceptance/qa-tracker.md` §9 为现取入口
- [x] **官网产品模块定位(IHG/字节式品牌矩阵,2026-08-19)**:官网品牌宣传为主,产品矩阵页为聚合入口;成熟产品 `externalUrl` 外链独立站(NovaVis → novavis.p.novalon.cn);未成熟产品详情页占位,独立站上线后切换外链
- [x] **结构性文案全站 CMS 化(2026-08-19)**:新增 `page-copy` 内容模型承载全部营销页面章节标题/眉标/描述/CTA/空状态(首页 + 服务/方案/产品/案例/新闻列表页),「CMS 优先 + 硬编码兜底」不白屏;seed 写入 6 条,本地 db:seed 已生效
- [x] **信任证据补齐·阶段 0(成立 <1 年策略,2026-08-20)**:信任策略从「结果证据」转向「可验证的过程 + 能力 + 治理证据」——首页「首批客户共创计划」板块(共创进行中/产品内测中/成果授权公开三档如实状态 + 招募 CTA)+ 关于页资质「建设中」如实空态,零编造
- [x] **生产部署上线(2026-08-20)**:`deploy.sh deploy`(本地 dist → 远端容器重建)+ 生产库 seed(page-copy/methodology 数据)完成;生产目录 Drizzle 残留源码归档清理;站点全路由 200、生产库 Prisma 结构
- [x] **数字口径结构强制(2026-09-20,critique P0 收尾)**:共享数字样式渲染的指标(`metrics`/`outcomes`/`dataProofs`)统一携带 `basis: target|team-history|verified`,渲染端自动附口径角注、未声明保守回落 `target`;CMS 新增 `basis` select 录入字段;删除产品详情页「每一项指标都源自真实客户案例」「经实际场景验证」等虚构佐证并补注角注;`metrics-basis.test.ts` 机械校验声明完整性并拦截虚构佐证禁词
- [x] **五轮系统性 QA 封版(2026-09-21…28 修复,2026-09-30 封版)**:Q-1…Q-10 / S-1…S-24 共 30 处缺陷修复入库(假登出清服务端令牌、登录 IP 限流、停用令牌 fail-closed 收口、workflow 状态+审计交互式 `$transaction` 原子化、编辑器 richtext 防换行静默损毁、`StaggerReveal` 吞网格类致详情页塌成单列、首页 CMS 数组逐条守卫、about/contact/erp-upgrade 补 ISR=3600 等),每处带判别性 RED→GREEN 测试。跨周期台账 `docs/acceptance/qa-tracker.md`(§9 为现行段落),封版判定书与全部原始门禁输出见 `docs/acceptance/2026-09-30-seal/`。**判定 = 封版通过(含例外清单)**:例外为「待业务口径」(4 条互斥 SLA、erp-upgrade 无 basis 数字)与「待授权项」(写库 E2E 11 例、全量变异、生产 `db:seed`、`check:motion` 23 处)——视觉基线追认已于 2026-10-08 闭合,见下条;均非代码质量问题
- [x] **作者侧 agentic 工具化 + 视觉基线闭合(2026-10-08)**:① 选型判定采用 Playwright 1.60 自带 Test Agents(planner/generator/healer,`.claude/agents/*.md` + `.mcp.json`,**未新增依赖、运行期零模型**),淘汰 `tester-army/e2e` 等的判据全表见 `docs/testing/agentic-test-authoring.md`;② 补主导航键盘契约 `e2e/nav-keyboard.spec.ts`(4 例 `@a11y`,dev 10/6、production 10/2、稳定性 24/24,并定性两条引擎/目标差异);③ **AUTH-D3 视觉基线闭合**:写入 38 张(25 新 + 13 覆盖,逐张读图追认)后独立只读复跑 **125/0 / EXIT=0**,取证 `docs/acceptance/2026-10-08-baselines/`;④ 台账 §9 + `docs/lessons-learned.md` §5.33(基线判红须对「采集树 vs 当前树」,本轮内作废了自己一条「运行期漂移」错判)
- [x] **对标语法批:Bain / Porsche Consulting 实测驱动的 UI·UE·UX 重构(2026-10-17,tracer-bullet 一批)**:对标取证不是二手描述——Bain 走 archive.org 快照 2026-08-31(1600×846)绕开 Cloudflare、Porsche 取 live 国际站,逐元素 `getComputedStyle` 抽样。实测**证伪了 ADR-0004 的两条视觉判据**(决策四「关键数字 = 超大字号 + 品牌色」:Bain 成果数字实为 40px / 字重 500 / 纯黑;决策一「4px 色条为辅」:两家都不用颜色给内容分类),已在同一笔里改文档。四项裁定与落地见 [ADR-0008](docs/adr/0008-benchmark-grammar-takeover.md):① **借语法不借色相** —— radius 收进 0–4px 记档 + 新增 `--radius-cta: 0`(CTA 由 pill 改直角)、彩色阴影 `--shadow-brand/-brand-hover/-glow` 退役、`.bain-card` hover 去抬升,**`--radius-full` 保持 9999px**(承载 avatar/switch/slider/radio/progress 的功能性真圆,一并归零即方角化后台所有旋钮);② **一级导航改行业 × 能力 + 洞察双轴**,「产品」退出一级(入口降为能力面板里的产品矩阵总览),且把导航真源**从 DB 行反转为代码**(CMS 行须满足 IA 契约才采纳,否则 fail closed —— 实测复现过「一条自洽的旧行」让页脚各列静默变空);③ **信任层走零编造透明路线**:`ResultsSlot` 可判别空态 + `casePublishBlockers()` 反伪造不变量 + L3 替代信号槽,承诺条款收进 `commitments.ts` 单一真源;④ **范围只到首页 + 一条承载详情页**,其余模板待验收。新增三台可失败仪器并常驻门禁:`check:grammar`(R1–R11,含 R2 正向守卫、R9 双向、R10 递减棘轮、R11 僵尸令牌守卫)、`check:accents`(营销面类名通道,豁免按名登记且**豁免腐化亦判红**)、`check:dead`(import 闭包可达性);`check:visual` 已并入 `test:all` 且**自证先跑**(自证失败即宣布绿灯作废)。证据与台账见 `docs/acceptance/qa-tracker.md` §11、探针 7 份存 `docs/acceptance/2026-10-17-ia-e2e/`;经验教训 `docs/lessons-learned.md` §5.38–§5.41(含「`npm run lint | tail` 吞掉 2 个 error」与「注释写在 JSX children 位会渲染成页面文字,而 type-check/1747 例单测/build 三道全绿」)。**§12 轮(2026-10-17)对这批待拍的处置**:`DEC-N5` 后台发布/更新/删除已接上缓存失效(新增 `src/lib/cms/revalidation.ts` 单一真源);`DEC-N3` `check:motion` 8 处归零,且时长判据从令牌声明移到消费点;`DEC-N4` 授权+basis 门槛下沉成 `case-publish-gate.ts` 供三处共用(实测门槛下隐藏条目 0 条,属前瞻加固);`DEC-N1` 彩色编码**第二条通道已收进 `check:accents` 判据 B**(产品线色相保留为受控例外:按 文件+色值 登记、棘轮 7、豁免腐化亦判红),落盘即抓到一条绕开真源抄主题的真漂移;`DEC-N6` e2e 进类型口径(`type-check:e2e` 并入 `test:all`)+ `.husky/pre-commit` 索引位 100755 + axe 证据按轮次落盘;**`DEC-N2` 被证伪**:`staggerDelay` 默认一直是 0.05(50ms),`git log -S` 查「0.15」在该文件历史里无任何提交 ⇒ 台账里那个数是叙述抄本而非仪器读数;**AUTH-VISUAL** 基线重采与 `--radius-cta` 负对照的证据落 `docs/acceptance/2026-10-17-final/`;**AUTH-NAV**(CMS navigation 行改写)仍未执行 —— 现行由代码 fail-closed 供数,不改库也能上线。
- [ ] **信任证据补齐·阶段 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
### 安装依赖
```bash
npm install
```
### 开发模式
```bash
npm run dev
```
访问 http://localhost:3000
### 构建生产版本
```bash
npm run build
```
输出目录: `dist/`
### 预览生产版本
```bash
npm run build # 先产出 dist/
npm run preview # == npm run start == `next start -p 3000`(不是 `npx serve`)
```
`preview` 是 `start` 的同义别名,两者都是 `next start -p 3000`。项目为 `output: 'standalone'`,Next 16 在此组合下会打印
`"next start" does not work with "output: standalone" configuration. Use "node .next/standalone/server.js" instead.`
——这是**警告而非抛错**,服务仍会起来,但走的是**不受支持的降级路径**,因此它已不再被任何门禁当作产物口径:
- 受支持的启动方式是 `node dist/standalone/server.js`(静态资源由 `package.json:9` 的 `postbuild` 在 `npm run build` 末尾自动拷入 `dist/standalone/`,standalone 产物本身不含 `dist/static` 与 `public`,缺了它们 `/_next/static/**` 全 404)。该启动方式**尚未做成 npm script**,目前由 `check:axe`、`check:headings`、`e2e/playwright.config.ts:134`(`E2E_TARGET=production`)与 `Jenkinsfile` 各自直接 `node` 起。
- `npm run test:e2e:prod` 走的是上面这条受支持路径(`e2e/playwright.config.ts:132-135`),**不是** `next start`。
- `npm run check:headings` 存在产物时直起 standalone,仅在产物缺失时回退 `npm run preview` 并打印告警(`scripts/utils/check-heading-hierarchy.ts:52-67`,验收 N-24③)。
详见 `CLAUDE.md`「Build & Preview」。
## 项目结构
```
novalon-website/
├── src/ # 源代码
│ ├── app/ # Next.js App Router
│ │ ├── (marketing)/ # 营销页面路由组
│ │ │ ├── page.tsx # 首页
│ │ │ ├── home-content-v15.tsx # 首页内容装配(V1.5)
│ │ │ ├── about/ # 关于我们
│ │ │ ├── team/ # 团队
│ │ │ ├── cases/ # 成功案例
│ │ │ ├── contact/ # 联系我们
│ │ │ ├── methodology/ # 方法论
│ │ │ ├── news/ # 新闻动态
│ │ │ ├── products/ # 产品服务
│ │ │ ├── services/ # 核心业务
│ │ │ └── solutions/ # 解决方案
│ │ ├── admin/ # CMS 管理后台
│ │ ├── api/ # 服务端接口(表单、CMS、鉴权)
│ │ ├── privacy/ # 隐私政策
│ │ ├── terms/ # 服务条款
│ │ ├── layout.tsx # 根布局
│ │ ├── error.tsx # 根段错误页面
│ │ ├── global-error.tsx # 全局错误边界
│ │ └── not-found.tsx # 404 页面
│ ├── components/ # React 组件
│ │ ├── ui/ # 基础 UI 组件
│ │ ├── layout/ # 布局组件
│ │ ├── sections/ # 页面区块组件
│ │ ├── content/ # 内容渲染组件(`sections.tsx`)
│ │ ├── detail/ # 详情页组件
│ │ ├── admin/ # 后台组件
│ │ ├── theme/ # 主题组件
│ │ ├── seo/ # SEO 组件
│ │ └── analytics/ # 分析组件
│ ├── hooks/ # 自定义 Hooks
│ ├── lib/ # 工具与领域逻辑(含 `cms/`、`constants/`、`media/`)
│ └── types/ # 类型声明
├── e2e/ # Playwright E2E + 视觉回归(**无独立 package.json**,依赖装在根目录)
├── tests/ # 非 Playwright 资产
│ ├── performance/ # k6 负载/压力脚本(由 k6 CLI 跑,不在 npm scripts 内)
│ ├── lib/ # 集成测试
│ ├── styles/ # 样式测试
│ └── screenshots/ # 截图基线
├── 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:`test:functional`(4 project ⇒ **1080 实例**)→ `test:visual:all`(5 project ⇒ **125 实例**)串行,`--list` 合计 **1205**。**webServer 默认是 dev server**,见 `test:e2e:prod` |
| `npm run test:unit` | 运行单元测试(Jest,2026-09-23 本树复跑实测 **134 suites / 1697 tests**) |
| `npm run test:coverage` | 运行测试覆盖率。**阈值**单一真源 `config/test/jest.config.js` 的 `coverageThreshold`(全局 statements/lines/functions ≥ 75%、branches ≥ 82%);**实测值**单一记录位见 [docs/development/quality-gates.md](docs/development/quality-gates.md) §3,本文件不再复制百分比以免再次互斥 |
| `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:prod` | **产物目标** E2E(`E2E_TARGET=production` → harness 新起 `node dist/standalone/server.js`,**不是** `npm run start`——standalone 下 `next start` 不受支持;`@smoke\|@critical\|@journey` × 4 project)。**只有 GA4 的 16 例在这里真正断言**;生产响应头不在此 grep 集合内(它属 `@security` 标签与 `test:security:headers`,勿混)(2026-09-23 实测:排除 2 个写库 spec 后 92 例通过、0 skipped);须先 `npm run build`(`postbuild` 负责装配 `dist/static` + `public`) |
| `npm run test:e2e:mobile` | 运行移动端 E2E 测试(`@mobile` 标签:**55 个用例**(16 `mobile.spec.ts` + 5 `mobile-user-journeys.spec.ts` + 14 `mobile-accessibility.spec.ts` + 18 `mobile-performance.spec.ts` + 2 `uj-11-home-conversion.spec.ts`),4 个功能 project 全跑 ⇒ **220 个实例**;`cd e2e && npx playwright test --list --grep @mobile` 实测 `Total: 220 tests in 5 files`) |
| `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,评估测试质量)。**分数不在此声明**:全量轮耗时以十分钟计且 `--inPlace` 会改动工作树,本轮未复跑;最近一次落盘记录为整体 **36.98%**(`docs/test-strategy-plan.md` P4.5 / 验收清单条目,2026-08 轮次),引用时须附该出处与 `npm run test:mutation` 复算命令 |
| `npm run test:mutation:quick` | 快速变异测试(`--mutate 'src/lib/utils.ts'`,同一落盘记录 **91.18%**,出处同上) |
| `npm run test:security` | 安全扫描(npm audit + 安全响应头检查) |
| `npm run test:security:headers` | 安全响应头检查(X-Content-Type-Options, CSP, HSTS 等) |
| `npm run check:a11y` | 可访问性静态门禁伞:`check:contrast`(令牌对比度,只读 `globals.css`)+ `check:headings`(标题层级,有产物直起 standalone、缺产物才回退 preview)+ `check:brand-token`(双通道红) |
| `npm run check:axe:routes` | 生成全站路由清单:sitemap ∪ 预渲染产物 ∪ 站内链接 BFS → `/tmp/axe-routes.xml`(`scripts/accessibility/crawl-routes.mjs`;退出码 0/2) |
| `npm run check:axe` | 双引擎 × 双主题逐页 axe **节点计数** + 三条规则级通道的分母断言(`scripts/accessibility/axe-node-count.mjs`);退出码 0 通过 / 1 判红 / 2 清单缺失。**需先有 `node dist/standalone/server.js` 在 :3100**;不在 `test:all` 内,CI 由 `Jenkinsfile`「♿♿」阶段(仅 main)执行 |
| `npm run test:all` | 全量门禁检查,现取十段:`type-check` + **`check:package-keys`**(JSON 重复键)+ **`type-check:e2e`**(e2e 静态口径)+ `lint` + `test:coverage` + **`test:integration:real`** + `check:a11y` + `check:visual` + fast E2E + security headers;其 E2E 段仍是 dev 目标,GA4 `@critical` 在其中 skipped,需另跑 `test:e2e:prod` |
| `npm run lighthouse` | 运行 Lighthouse 性能测试 |
## 代码质量门禁
项目配置了自动化质量门禁,确保代码提交前通过所有质量检查:
- **ESLint**: 代码风格检查(pre-commit 经 husky + lint-staged 跑 `eslint --fix`,CI 跑全仓 `npm run lint`;判定口径 0 error,warning 不判红)
- **commitlint**: 提交信息规范(`.husky/commit-msg`)
- **Jest**: 代码覆盖率检查(阈值单一真源 `config/test/jest.config.js`)
- **可访问性**: `npm run check:a11y`(对比度 / 标题层级 / 双通道红),CI 在「♿ 可访问性门禁」阶段逐条执行同一组
- **TypeScript**: `npm run type-check` —— **不在 pre-commit**(`.lintstagedrc.json` 只跑 `eslint --fix`),推送前须自行执行
- **E2E 目标**: `npm run test` 打 dev server;GA4 的 16 个 `@critical` 实例在该轮为 skipped,产物口径见 `npm run test:e2e:prod`(详见 [docs/development/quality-gates.md](docs/development/quality-gates.md) §5–§7)
### 提交规范
使用 Conventional Commits 规范:
```
<type>(<scope>): <subject>
```
**提交类型**:
- `feat`: 新功能
- `fix`: 修复bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具相关
## 测试
项目采用多层测试策略,涵盖单元测试、集成测试、E2E 测试、用户旅程测试、视觉回归测试、变异测试等。
### 测试工具链
| 工具 | 用途 | 配置 |
|------|------|------|
| **Jest** | 单元测试(2026-09-23 本树复跑:134 suites / 1697 tests) | `config/test/jest.config.js` |
| **Playwright** | E2E / 视觉回归 / 用户旅程测试(`--list` 实测 1205 例 = 功能 1080 + 视觉 125) | `e2e/playwright.config.ts` |
| **Stryker** | 变异测试(评估测试质量) | `stryker.config.json` |
| **Allure** | 测试报告可视化 | Allure Playwright reporter |
| **k6** | 负载/压力/API 性能测试 | `tests/performance/` |
| **Lighthouse CI** | 性能/可访问性/SEO 审计 | `config/test/lighthouserc.json` |
### 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` | 移动端专项测试(55 个用例:16 基础 + 5 用户旅程 + 14 可访问性 + 18 性能 + 2 UJ-11c;× 4 project = 220 实例) | `npm run test:e2e:mobile` |
| (无标签) | 视觉回归:`@visual` 标签**并不存在**(`e2e/` 全量 grep 为 0 命中),视觉用例由 5 个 `visual-*` project 通过 `testMatch` 选中,且只跑 `visual-regression.spec.ts`(25 例 × 5 project = 125 实例) | `npm run test:visual:all` |
### 运行测试
```bash
# 单元测试
npm run test:unit # 134 suites / 1697 tests(2026-09-23 本树复跑)
# 测试覆盖率
npm run test:coverage # 阈值: 全局 statements/lines/functions ≥75%、branches ≥82%
# 实测值见 docs/development/quality-gates.md §3(此处不复制百分比)
# E2E 测试
npm run test # 全量 E2E = 功能 1080 + 视觉 125 = 1205 实例
# 落盘通过数引自 docs/acceptance/2026-09-21-gates/skipped-tests-final-tree.json
# (totalResults 1195 = 1167 passed / 28 skipped,生成于 2026-09-22 的 chain6 最终树);
# 本轮未重跑全量 E2E(需 dev server + 4 引擎 + 视觉基线,且 28 条 skip 需按该文件逐条解释)
npm run test:e2e:fast # 快速回归(@smoke + @critical)
npm run test:e2e:standard # 标准回归(@regression)
npm run test:e2e:journey # 用户旅程(@journey)
# 移动端测试
npm run test:e2e:mobile # 全量移动端(55 个 @mobile 用例 × 4 project = 220 实例)
npm run test:e2e:mobile:performance # 移动端性能基线
npm run test:e2e:mobile:accessibility # 移动端可访问性
# 变异测试(分数只引 docs/test-strategy-plan.md 的落盘记录,本仓未复跑)
npm run test:mutation # 全量变异测试
npm run test:mutation:quick # 快速变异(仅 utils.ts)
# 全量门禁检查
npm run test:all # type-check + lint + coverage + integration:real + check:a11y + fast E2E(dev 目标) + security headers
```
## 部署
### 统一发布脚本(推荐)
项目发布统一通过 `scripts/deploy.sh` 完成,包含构建、发布、回滚、状态查看:
```bash
# 构建产物(`next build`,output=standalone;脚本再把 public/ 同步进 dist、把 dist/static 复制为 dist/_next/static 供 Nginx 直服)
./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
```
常用选项:
```bash
./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/`:
```bash
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`
```bash
# 本地构建
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/` 目录:
- [架构文档](docs/architecture.md) - 系统架构设计
- [组件文档](docs/components.md) - 组件使用指南
- [测试文档](docs/testing.md) - 测试策略和指南
- [部署文档](docs/deployment.md) - 部署流程说明
- [经验教训](docs/lessons-learned.md) - 跨任务经验教训汇总,避免重复踩坑
- [问题排查](docs/troubleshooting.md) - 常见问题快速索引与解决方案
## 许可证
Copyright © 2026 四川睿新致远科技有限公司