novalon/novalon-website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f543e478e3a6be8399df0fddc5819804420d6ab9
novalon-website/README.md
T
zhangxiang 3ed3afd819 fix(metrics): 数字口径 basis 结构强制，删除详情页虚构佐证 
复评 P0 收尾：把「每个数字带口径」从个别页自觉升级为结构性强制。
- metrics-basis.ts：METRIC_BASES / METRIC_BASIS_NOTES + resolveMetricBasis
  （缺失·非法·大小写错一律回落最弱 target）+ weakestBasis（一组数字取最弱者聚合）
  + FORBIDDEN_PROOF_PHRASES；MetricsBasisNote 收 basis prop
- 类型层 Product.metrics / DataProof / ServiceMetric / Solution.outcomes /
  DataMetric / about keyMetrics 全部加 basis?；9 处调用点改为 basis 驱动
- content-types.ts 新增共享 metricBasisField（select）展开进 9 处字段定义；
  trustSignals 有意跳过（已有自己的 source）。seed 显式声明 55 条 target
- 删除字面虚构佐证：详情页「每一项指标都源自真实客户案例」、「经过实战验证」×3、
  「来自真实客户的使用数据」、「经实际场景验证」；给此前完全裸奔的 3 个共享
  数字渲染器（DataProofSection / detail-trust / detail-product-value）补上角注
- metrics-basis.test 3→16 例：basis 解析正控制、weakestBasis 次序、seed 全量
  显式声明 + 覆盖证明（防空跑假绿）+ 禁任何条目自称 verified + 禁词全源码扫描
- 文档同源：DESIGN.md 立 The Declared-Basis Rule；PRODUCT.md 常驻禁令；
  CONTEXT.md 记决策并警示 admin 字段需重跑 seed 才激活

边界：CMS 字段定义存 ContentModel.fields（DB 内 JSON），basis 下拉须重跑 seed
才会出现在 admin 表单；本次 DB 与 seed 数据值零改动，渲染端对缺 basis 兜底 target。

Gates: type-check 0 · jest 1594/132 · contrast 7/7 · headings 10/10
lint 0e/128w（与 stash 基线逐行比对，零新增告警）
2026-09-20 10:38:23 +08:00

342 lines
15 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] 全量测试体系：单元 ~1600 / 功能 E2E ~800 / 视觉回归三端 / 用户旅程 UJ-01~UJ-11 / Lighthouse / k6 负载压力 / 安全扫描，全部通过
- [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` 机械校验声明完整性并拦截虚构佐证禁词
- [ ] **信任证据补齐·阶段 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 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`: 修复bug
- `docs`: 文档更新
- `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` |
### 运行测试
```bash
# 单元测试
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` 完成，包含构建、发布、回滚、状态查看：
```bash
# 构建静态产物
./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 四川睿新致远科技有限公司
Reference in New Issue View Git Blame Copy Permalink