# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Common Commands

```bash
# Development
npm run dev                    # Start dev server on port 3000
npm run dev:clean              # Clean .next/dist then start dev server

# Build & Preview
npm run build                  # Build production files to dist/
npm run build:clean            # Clean then build
npm run start                  # next start -p 3000 — serve the built output
npm run preview                # ALIAS of `start` (identical `next start -p 3000`); it is NOT `npx serve`

# 说明（2026-09-23 文档同步轮核实）：`next start` 与 `output: 'standalone'` 组合下 Next 16 会打印
# `"next start" does not work with "output: standalone" configuration. Use "node .next/standalone/server.js"
# instead.`（实测见 `docs/acceptance/2026-09-21-gates/ga4-production-run.txt`；抛出点
# `node_modules/next/dist/server/next.js` 的 `getServer()`）。它是 **warn 而非 throw**——服务照常起来，
# 但走的是不受支持的降级路径，所以门禁脚本正逐步脱离 `next start`：`test:e2e:prod` 已改为直接
# `node dist/standalone/server.js`（`e2e/playwright.config.ts:132-135`）；`check:headings` 也已脱离
# `next start` —— `scripts/utils/check-heading-hierarchy.ts:55-66` 现为「存在 dist/standalone/server.js 就直接
# 起 standalone（注入 HOSTNAME/PORT/NODE_ENV），仅当产物缺失才回退 `npm run preview` 并打印告警」，
# 见验收报告 N-24③。至此门禁脚本不再依赖不受支持的 `next start` 路径。
# standalone 的受支持启动方式是 `node dist/standalone/server.js`，且服务启动前 `public/`
# 与 `dist/static` 必须已在 standalone 根目录下（server.js 启动时缓存静态索引，缺资源会让
# /_next/static/** 全 404）。**这一步由 `package.json:9` 的 `postbuild` 自动完成**（`npm run build`
# 结尾 `rm -rf` + `cp -R dist/static → dist/standalone/dist/static`、`cp -R public → dist/standalone/public`），
# 所以正常路径下"先 build 再起 standalone"即可，不必手工拷；仅当产物来自别处或要复用旧 dist 时才参照
# `Jenkinsfile:353-355`（axe 阶段复用上一阶段产物时的同套拷贝）与 `scripts/deploy.sh:162-175`
# （发布侧把 `public/` 与 `dist/static → dist/_next/static` 同步进 Nginx 站点根）。npm 侧没有包一层的启动脚本。

# Deploy (统一发布脚本)
./scripts/deploy.sh build                 # 构建静态产物
./scripts/deploy.sh deploy                # 构建并发布到生产服务器
./scripts/deploy.sh deploy --skip-build   # 使用现有 dist/ 直接发布
./scripts/deploy.sh rollback              # 回滚到最近一次远程备份
./scripts/deploy.sh status                # 查看生产环境发布状态

# Linting & Type Checking
npm run lint                   # ESLint flat config at repo root (`eslint.config.mjs`; `config/lint/.eslintrc.json` no longer exists)
npm run type-check             # tsc --noEmit

# E2E Testing (Playwright)
npm run test                   # 全链路 E2E：先 test:functional（4 功能 project），再 test:visual:all（5 视觉 project），串行以免写库用例与截图并发污染基线
npm run test:functional        # 仅功能 project（chromium / chromium-mobile / firefox / webkit）
npm run test:e2e               # Same as test:functional
npm run test:smoke             # Only @smoke-tagged tests
npm run test:e2e:prod          # @smoke+@critical+@journey 打构建产物（E2E_TARGET=production → node dist/standalone/server.js，CI 门禁）
npm run test:visual            # Visual regression (Desktop Chrome)
npm run test:visual:all        # Visual regression (all projects)
npm run test:visual:update     # Update visual snapshots
npx playwright test --grep "test name"   # Run a single E2E test by name

# ⚠ E2E 目标口径（默认跑的是 dev server，不是产物）
# `npm run test` / `test:functional` 的 webServer 是 `npm run dev`（`e2e/playwright.config.ts:132-135`），
# 因此 **16 个 @critical GA4 用例（TC-GA4-001..004 × 4 project）在这一轮里是 skipped，不是 passed**：
# `NEXT_PUBLIC_GA_MEASUREMENT_ID` 只写在 `.env.production`，dev 读不到 → `GoogleAnalytics.tsx:81,119`
# 提前 return null → 用例内 `test.skip(measurementId === null, …)` 触发。证据：
# `docs/acceptance/2026-09-21-gates/skipped-tests-final-tree.json`（28 skipped 中该组恰为 16）。
# 它们真正断言的唯一入口是 `npm run test:e2e:prod`（`E2E_TARGET=production` → 直接
# `HOSTNAME=localhost PORT=3000 node dist/standalone/server.js`，非 `next start`；须先 `npm run build`
# 并把 `dist/static` + `public` 并入 standalone 根目录，见 Build & Preview 段的装配口径），
# 见同目录 `ga4-production-run.txt` 的 4 passed。故「`npm run test` 全绿」不等于 GA4 覆盖已验证。

# Unit Testing (Jest)
npm run test:unit              # Run all unit tests
npm run test:coverage          # Coverage report（阈值以 jest.config.js 的 coverageThreshold 为准；根配置 re-export config/test/jest.config.js 以免双份漂移）
npx jest --testPathPattern="button"      # Run a single test file matching pattern

# Quality Checks
npm run check:a11y             # 可访问性静态门禁伞（= check:contrast + check:headings + check:brand-token，已并入 test:all）
npm run check:contrast         # 令牌对比度审计（读 globals.css 令牌表，浅色+暗色双主题、含 alpha 组，缺令牌即红）
npm run check:headings         # 标题层级审计（有 dist/standalone/server.js 时直起 standalone；产物缺失才回退 `npm run preview` 并打印告警 —— scripts/utils/check-heading-hierarchy.ts:52-67）
npm run check:brand-token      # 品牌红文字必须走 text-brand-ink* 令牌（DESIGN.md 双通道红规则）
npm run check:motion           # 动效契约门禁（N-29 收口）：R1 令牌档位（instant 100ms / fast·normal 180–280ms，CONTEXT.md:76）、
                               # R2 时长 ≤700ms（CSS 声明、framer transition 对象的 duration、Tailwind duration-* 类、tailwind.config 的 animation；
                               # infinite 循环与 *-delay 豁免）、R3 transition 时长必须走 var(--transition-*)、
                               # R4 写死的 cubic-bezier 必须属于令牌层 --ease-*（允许集合从 CSS 解析，不硬编码）且 --ease-ink==[0.22,1,0.36,1]。
                               # 退出码 0 干净 / 1 违规 / 2 未能度量（空扫描、缺令牌文件）—— 空扫描不读作干净。
                               # ⚠ 当前树 23 处违规（EXIT=1），故**尚未**并入 check:a11y，详见 docs/development/quality-gates.md §5.1
npm run check:motion:test      # 上述门禁的自证伪测试（19 例，双向：合规夹具判 0 + 违规夹具判对应规则红）；
                               # 测试在 scripts/ 下，jest 默认 roots 只含 src，故该脚本显式传 --roots
npm run check:axe:routes       # 全站路由清单（sitemap ∪ 预渲染产物 ∪ 站内链接 BFS）→ /tmp/axe-routes.xml
                               # 同样需要 :3100 的生产服务（SEED 默认取 ${BASE}/sitemap.xml）
npm run check:axe              # 双引擎(chromium/firefox)×双主题(light/dark)逐页 axe 节点计数 + 三条规则级
                               # 规则(autocomplete-valid/presentation-role-conflict/svg-img-alt)的分母断言；
                               # 退出码 0 通过 / 1 判红 / 2 清单缺失或 0 条（假绿熔断）。证据落
                               # docs/acceptance/2026-09-21-axe/axe-evidence.json。需一个生产服务在 :3100：
                               # PORT=3100 HOSTNAME=127.0.0.1 node dist/standalone/server.js（先拷 dist/static 与 public，见上文）
                               # CI 侧由 Jenkinsfile「♿♿ 全站 axe 节点计数」阶段（仅 main）自动串起
npm run test:all               # type-check + lint + test:coverage + test:integration:real + check:a11y + test:e2e:fast + test:security:headers
npm run test:e2e:prod          # E2E_TARGET=production（构建产物目标）；harness **不代跑构建**，须先 `npm run build`
                               # （standalone 根目录的 dist/static + public 由 postbuild 自动装配，见上文）
npm run lighthouse             # Lighthouse CI（配置 config/test/lighthouserc.json；axe critical/serious 逐条 minScore:1；inspector-issues 亦判红——CSP/弃用类问题只走 DevTools issue 通道，errors-in-console 与 0.9 分类阈值都看不见它；报告落 lighthouse-reports/）

# Database (Prisma + SQLite)
npm run db:seed                # Seed the dev database
npm run db:reset               # Reset database with migrations
```

## Architecture

### Tech Stack
- **Next.js 16.3**（App Router）混合渲染 — SSG/ISR 静态页 + API routes；`output: 'standalone'`（`next.config.mjs:44`）、`distDir: 'dist'`（`:46`）。standalone 入口是 `node dist/standalone/server.js`，需另拷 `dist/static` 与 `public`；`npm run start`（= `next start`）在 standalone 下只算不受支持的降级路径，见下文 Build Output
- **中间件命名为 `proxy.ts`**（Next 16 起 `middleware.ts` 更名）；其 matcher 排除 `/api/*`，因此每个 API 路由必须自行做鉴权
- **React 18**, **TypeScript 5** (strict mode with `noUncheckedIndexedAccess`)
- **Tailwind CSS 3** with design tokens exposed as CSS custom properties (all tokenized via `var()` references in `tailwind.config.js`)
- **Framer Motion** for animations, **Lucide React** for icons, **Zod** for validation
- **shadcn/ui** pattern (Radix UI + class-variance-authority + tailwind-merge)
- **Prisma** with SQLite for backend data (admin, auth, CMS)

### Path Alias
`@/` maps to `src/` — configured in both `tsconfig.json` (`paths`) and `jest.config.js` (`moduleNameMapper`).

### TypeScript Strictness
Beyond `strict: true`, the project enables:
- `noUncheckedIndexedAccess: true` — array/object index access returns `T | undefined`, requiring null checks. This is a significant constraint to be aware of when writing code.
- `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`, `noUnusedParameters`

### Route Structure (App Router)
```
src/app/
├── layout.tsx                  # Root layout: fonts, metadata, theme, analytics, SEO schemas
├── (marketing)/                # Route group — all public marketing pages
│   ├── layout.tsx              # Shared: Header + Footer + PageTransition + ErrorBoundary
│   ├── page.tsx                # Home: server component, CMS zones via `lib/cms/data-server` → `home-content-v15.tsx`
│   ├── about/                  # About page (client.tsx)
│   ├── news/                   # News list + [slug] detail
│   ├── contact/                # Contact form
│   ├── products/               # Products hub (HSI model)
│   │   ├── page.tsx            # Product listing (enterprise suites + standalone)
│   │   ├── [id]/               # Product detail (four-layer narrative)
│   │   ├── standalone/[id]/    # Standalone product detail
│   │   ├── erp-upgrade/        # Specific product landing pages
│   │   └── erp-upgrade-v3/
│   ├── services/               # Services list + [id] detail
│   ├── solutions/              # Solutions list + [id] detail (cross-references products)
│   ├── cases/                  # Case studies
│   └── team/                   # Team page
├── api/
│   ├── admin/                  # Admin API
│   ├── auth/                   # Authentication API
│   ├── cms/                    # CMS API routes (draft mode, revalidation)
│   └── contact/                # Contact form submission
├── privacy/, terms/            # Legal pages
└── fonts/                      # Local font files (Geist Sans/Mono)
```

### Archiving Convention
When replacing a page or component with a new version, move the old one to an `_archive/` subdirectory (e.g., `src/app/(marketing)/_archive/` for old homepage iterations). The archive is excluded from TypeScript compilation via `tsconfig.json`.

### Dark Mode
Dark mode uses the `data-theme="dark"` HTML attribute (not Tailwind's `dark:` class). Tailwind is configured with `darkMode: ['variant', '[data-theme="dark"] &']` — use the **variant** form, not `['selector', ...]`, because the selector form is accepted by the config but JIT emits zero `dark:` rules under Turbopack + Next.js 16.

**Three-state preference model** (`src/lib/theme.ts` is the single source of truth):

| Stored value (`localStorage['novalon-theme']`) | Meaning |
|---|---|
| `'light'` / `'dark'` | Explicit user choice — always wins over the OS |
| `'system'` / absent | Follow OS `prefers-color-scheme` (**default for new visitors**) |

- `src/app/layout.tsx` has an inline `<script>` in `<head>` that resolves the preference and sets `data-theme` **before first paint** (FOUC prevention). It must stay semantically in sync with `src/lib/theme.ts` — change both together.
- `src/components/theme/theme-toggle.tsx` cycles `跟随系统 → 浅色 → 深色`. It listens to `matchMedia('(prefers-color-scheme: dark)')` for live OS changes (only effective in the `system` state) and to `storage` events for cross-tab sync.
- `html[data-theme]` is an **output** of preference resolution — never read it back as the user's preference, or the `system` state collapses into `dark` on dark-OS machines and the cycle deadlocks.

### HSI Information Architecture
The site follows a **Hub-Spoke-Independent** model (see `CONTEXT.md` and ADR-0002):
- **Hub**: `/products` — product catalog, split into "企业套装" (6 enterprise products) and "专业产品" (standalone)
- **Spoke**: `/solutions` — industry scenarios, each recommending product combinations from the Hub
- **Independent**: Standalone products in the specialized zone have their own narrative path

### Four-Layer Narrative Model
Every detail page (product/service/solution/standalone) follows the same four-layer structure:
1. **L1 Hero**: Emotional entry with visual, title, value prop, status badge
2. **L2 Value Rationale**: Product-specific — features/benefits for products, pain-points→architecture for solutions, challenges→results for services
3. **L3 Trust Proof**: Case studies, data proofs, certifications, testimonials (currently stubbed — company is pre-launch)
4. **L4 CTA Conversion**: Primary action + secondary action + cross-recommendations

The detail components implementing this live in `src/components/detail/`:
- `detail-hero.tsx`, `detail-product-value.tsx`, `detail-trust-section.tsx`, `detail-cta-section.tsx`
- `solution-value.tsx`, `service-value.tsx` (type-specific L2 variants)
- `detail-cross-recommend.tsx` (cross-links between products↔solutions↔services)

### CMS Content Architecture
`src/lib/cms/` is a **real, server-side CMS layer over Prisma** — there is no mock layer and no client-side CMS SDK (the historical names `mock-home.ts`, `ContentZoneRenderer.tsx`, `component-registry.ts`, `src/components/cms/` do not exist in the tree; do not look for them):
- `types.ts` — `FieldType`/`FieldDefinition`, `ContentModel`, `ContentStatus`, `ContentItem`, `ContentZone`, `ThemeConfig` definitions
- `content-types.ts` — `CONTENT_TYPE_CONFIGS` + `registerAllContentTypes()`: the per-model field schemas the admin form and the validator both read
- `data-server.ts` — the read path: `getPublishedItems` (`:37`), `getPublishedItemBySlug` (`:48`), `getPageZones` (`:70`), `getZone` (`:85`), `getHomePageCopy` (`:171`), each wrapped in React `cache` so a render pass hits the DB once
- `workflow.ts` / `validate-content-data.ts` / `notifications.ts` — status state machine, field validation, in-app notifications (status changes only through `workflow.ts`; see `docs/cms/api-contract.md` §10.5)
- `index.ts` — re-exports the types plus `CONTENT_TYPE_CONFIGS`

The homepage is `src/app/(marketing)/page.tsx` (server component, `export const revalidate = 3600` at `:5`): it resolves the home zones with `getResolvedHomeZones()` (`:8`) and, when the CMS has nothing configured, falls back to per-model `getPublishedItems(...)` calls (`:23-29`); the markup lives in `home-content-v15.tsx`. Earlier documents calling it `home-content-cms.tsx` are stale.

### Design Token System
All visual tokens are defined as **CSS custom properties** in `src/app/globals.css` (`:root` block) and mapped into Tailwind's config via `var()` references:
- **Colors**: `--color-ink` (deep charcoal #0A0E14), `--color-brand` (vermilion #C41E3A), accent colors for service-coding (blue, teal, amber, purple), functional colors (success, warning, error, info), dark-section overrides
- **Typography**: `--font-size-*`, `--line-height-*`, `--letter-spacing-*` all mapped to Tailwind's `fontSize`/`lineHeight`/`letterSpacing` scales
- **Spacing, radius, shadows** all tokenized through CSS variables
- **Transitions**: `--transition-fast/normal/slow`, `--ease-ink` (cubic-bezier), `--ease-sharp`（`--ease-spring*` 死令牌已于 2026-09-19 polish 删除）
- **Dark mode**: `data-theme="dark"` attribute (set via inline script before paint to prevent flash); flipped by the `[data-theme='dark']` override block in `globals.css`, which only re-maps CSS variables — components do not restyle per element
- **Opacity**: use theme tokens (`bg-brand/20`, `border-ink/30`) — they resolve through `rgb(var(--x-rgb) / <alpha-value>)`. The arbitrary-value form `bg-[var(--color-brand)]/20` is **accepted by the parser but emits no CSS** (Tailwind v3 cannot apply an alpha modifier to a plain-hex custom property; see `tailwind.config.js:12-15`), so it fails silently. Verify any "is this style live?" claim against the compiled stylesheet, not against the source class list.
- **Two-channel red**: `--color-brand` (#C41E3A) is for surfaces only and does not flip in dark mode; text must use `text-brand-ink` (flips to #F87171). Enforced by `scripts/utils/check-brand-text-token.ts` on the text channel.
- **Hover / translucent states are unguarded**: axe skips `:hover` and `check:contrast` only asserts declared token *pairs*, so a hover background nobody noticed was dead becomes a live AA failure the moment you fix it. Composite it yourself — a semi-transparent layer **replaces** the element's own base color: `alpha*brand + (1-alpha)*pageBg`; at 20% that yields 4.18:1 against `text-brand-ink` in light theme (fail), at the `brand-soft` 12% token 4.80:1 (pass).

- **Motion tokens are gated, and the gate is currently RED**: `scripts/utils/check-motion-constraints.ts` (`npm run check:motion`, 配套 `npm run check:motion:test`) enforces the `CONTEXT.md` §动效设计四原则 bands (entrance 180–280ms, ≤700ms ceiling, durations must flow through `--transition-*` tokens, bezier allow-list **parsed from the CSS `--ease-*` tokens** — `--ease-out` is an alias of `ease-ink`, and the token layer deliberately carries 5 further curves). It is deliberately **not** part of `check:a11y`: the tree measures 23 violations / 13 files, so wiring it in would make the aggregate permanently red. `scripts/**` is eslint-ignored, so adding it did not move the lint baseline.

### Design DNA Framework
The site follows a three-dimensional design system (see `CONTEXT.md`):
- **Dimension 1 — Design System**: Quantifiable tokens (colors, typography, spacing, radius, shadows, motion, components)
- **Dimension 2 — Design Style**: Qualitative perception (atmosphere, visual language, composition, imagery, brand tone)
- **Dimension 3 — Visual Effects**: Scroll animations, micro-interactions, parallax, SVG effects

The **Consulting Professional** aesthetic (inspired by Accenture + Bain) is the primary skeleton. **Ink cultural elements** (水墨) are secondary decorations limited to ≤6 locations (logo, dividers, transition animations, footer texture).

**Brand red (#C41E3A) usage rule**: Every page must have ≥3 brand-red touchpoints. It must never be used as paragraph text color, as a large background, or alongside accent colors in the same card. Area ≤10%. Exception: full-bleed dark-red statement/CTA blocks use the separate `crimson-veil` (#8B1530) token — see DESIGN.md「Crimson Veil」(rule clarified 2026-09-19 critique to resolve this apparent contradiction).

**Motion design**: Animations are purposeful (not decorative). Durations come from tokens, **not** from a free-form "150-300ms" range — that phrasing conflicted with `CONTEXT.md`「动效设计四原则」and is replaced by its three tiers: **入场 180–280ms**（`--transition-fast: 180ms` … `--transition-normal: 280ms`，`src/app/globals.css:264-265`）· **hover 150ms** · **反馈 100ms**；`--transition-slow: 450ms` / `--transition-slower: 700ms` 只用于揭示型动效。`ease-ink` `[0.22, 1, 0.36, 1]`（`globals.css:280`）为默认缓动，children stagger 30-60ms、Section 间 stagger 100-150ms。No continuous looping animations except `pulse-soft` for skeletons. No spring easings for content entry（spring 仅用于按钮按压反馈）. **No entry animations >700ms.** Note that `duration-300` 一类的 Tailwind 预设时长绕过令牌、且 300ms 不属任何档位（残留清点见 `CONTEXT.md`「duration-300 → 动效令牌」行，该项 in flight，勿引用其计数）。

### Data Layer
Most structured marketing content is still `src/lib/constants/` TypeScript constants, and the pages render from them; on top of that, published CMS items now override specific slots — the home page's hero/services/cases/stats/news data comes from `lib/cms/data-server` (Prisma) and only falls back to constants when the CMS has nothing configured (`src/app/(marketing)/page.tsx:8-36`), and per-section copy comes from `getHomePageCopy()` with in-component fallbacks. "Marketing content has no database" is therefore no longer true:
- `products.ts` — 6 enterprise products (ERP, CRM, CMS, BI, SDS, OA) + standalone products (NovaVis)
- `services.ts`, `solutions.ts` — Service and solution definitions
- `cases.ts` — Case studies with industry filtering
- `navigation.ts` — Nav structure + mega dropdown data
- `company.ts`, `stats.ts`, `team.ts`, `news.ts`, `methodology.ts`
- `hero-themes.ts` — Per-product hero visual theme variants
- `cross-references.ts` — Cross-links between products/solutions/services

Each product/solution/service implements the `Product`/`Solution`/`Service` interface which includes `caseStudies[]`, `dataProofs[]`, `certifications[]`, etc. for the four-layer narrative.

### Backend Layer (Prisma + API Routes)
The project has a backend layer for admin/auth/CMS functionality:
- **Prisma** with SQLite (`prisma/dev.db`) for admin user data, auth, and CMS content management
- API routes at `src/app/api/admin/`, `auth/`, `cms/`, `contact/`
- The marketing read path and the admin write path share this backend: pages fetch published items through `src/lib/cms/data-server.ts`, while `api/admin/*` writes drafts and `api/cms/*` (`draft/enable`, `draft/disable`, `revalidate`) handles preview cache invalidation

### Error Monitoring (Sentry)
`@sentry/nextjs@10` is wired through `src/instrumentation.ts` (server/edge, incl. `onRequestError`) and `src/instrumentation-client.ts` (client init + `onRouterTransitionStart`); `next.config.mjs` exports `withSentryConfig(nextConfig)`. **This Next 16 build defaults to Turbopack, which never loads the root `sentry.client.config.ts`** — client init therefore lives in `instrumentation-client.ts`, and the old file is kept as an empty stub solely to prevent a double `Sentry.init` on the `--webpack` path. Everything is gated on `NEXT_PUBLIC_SENTRY_DSN`: absent it, `Sentry.init` is skipped, both hooks no-op, **and the CSP is byte-identical** (`connect-src`/`worker-src` only gain the DSN's `protocol//host` when a valid DSN is present, `next.config.mjs:17-26`). Verify "is this inert?" by building without a DSN and diffing the emitted header, not by reading the source.

### Component Organization
```
src/components/
├── ui/              # Base: Button, Card, Input, Badge, ScrollReveal, AnimatedCounter, etc.
├── layout/          # Header, Footer, MobileTabBar, Breadcrumb, MegaDropdown（MobileMenu 已删除，抽屉内置于 Header）
├── sections/        # Page section components: HeroSectionV2, ServiceGrid, CTASection, etc.
├── detail/          # Four-layer narrative: DetailHero, ProductValueSection, DetailTrustSection, etc.
├── content/         # 仅 sections.tsx（+ 同名 .test.tsx）
├── admin/           # admin-layout.tsx、auth-context.tsx（React Context 在此，不在 src/contexts/）
├── theme/           # theme-toggle.tsx
├── seo/             # Structured data (OrganizationSchema, WebsiteSchema, etc.)
└── analytics/       # GA4, error tracking, cookie consent, scroll depth, outbound links
```
> 口径核对（2026-09-23，验收 N-33「不存在的目录」一项）：`cms/`、`providers/`、`effects/` 三个目录在工作树与 `git ls-tree -r HEAD` 中**均不存在**，旧图里的对应条目是残留。`ContentRenderer` / `SectionRenderer` / `FieldRenderer` 三个标识符在 `src/**/*.{ts,tsx}` 中零命中，CMS 区块渲染实际由 `src/components/content/sections.tsx` + `src/lib/cms/` 承担；`effects/` 一族已在提交 `37296b5`（2026-05-10）删除，见 `CONTEXT.md`「特效组件」。

### Testing Setup
- **Jest** (unit): Tests alongside source in `src/**/*.test.{ts,tsx}`, coverage **thresholds** live in `config/test/jest.config.js` (global 75% stmts/lines/funcs, 82% branches) and are the single source of truth — root `jest.config.js` only re-exports it, never duplicate thresholds. **Measured values are recorded in exactly one place: `docs/development/quality-gates.md` §3** (2026-09-23 本树复跑：134 suites / 1697 tests / EXIT=0)；该文件顶部注释里的百分比是滞后快照，引用前先复跑。Uses `@/` path alias and ts-jest with `jsx: 'react-jsx'` transform (since tsconfig uses `'preserve'`). Run single tests with `npx jest --testPathPattern="component-name"`.
- **Playwright** (E2E): Tests in `e2e/`, config in `e2e/playwright.config.ts` — run from `cd e2e` (`npm run test` does this). webServer is `HOSTNAME=localhost PORT=3000 node dist/standalone/server.js` when `E2E_TARGET=production` (`e2e/playwright.config.ts:132-135` — build artifacts, real security headers; CI gate uses `npm run test:e2e:prod`, and `npm run build` + the `dist/static` / `public` copies must already exist because the harness never builds) and `npm run dev` otherwise; `reuseExistingServer` is disabled for production targets, so a busy :3000 aborts the run. Functional projects: chromium, chromium-mobile (iPhone 14, 390×844), firefox, webkit — plus 5 visual-regression projects at desktop/tablet/mobile breakpoints; snapshots in `e2e/visual-snapshots/`. `mobile-*.spec.ts` must pin their own viewport because they also execute under the desktop projects. Touch-target gate lives in `e2e/touch-targets.ts` (AA SC 2.5.8 ≥24px hard, AAA SC 2.5.5 44px advisory). Visual snapshots are server-target independent — every spec imports `test` from `e2e/fixtures.ts`, whose `context` fixture injects an init script that removes the `next dev`-only `<nextjs-portal>` devtools indicator (MutationObserver on `document`, because `documentElement` is still null at document start). The indicator's shadow-DOM `<footer class="error-overlay-footer">` is pierced by Playwright's CSS engine and made `locator('footer')` resolve to 2 elements (56 failures). `devIndicators: false` is *not* a fix here — measured: the CSP-blocked-`eval` dev error keeps the overlay mounted, so the portal survives; don't reintroduce that env gate. `visual-regression.spec.ts` additionally pins the cookie-consent state via `addInitScript` (constant timestamp) because the banner renders on a 2 s timer and the `visual-firefox-desktop` / `visual-webkit-desktop` projects use an empty storage state — without the pin, slower engines photograph the banner into the first viewport and faster ones don't (34 engine-specific failures). Client-component interactions must call `expectHydrated()` from `e2e/hydrated.ts` before hover/click — SSR HTML is visible ~1.7 s before React attaches handlers, and pointer events in that window are dropped without replay. Hover-driven UI additionally needs `expect(...).toPass()` re-driving the pointer, because a single `hover()` can land mid-layout-transition and `mouseenter` never re-fires. Run single tests with `npx playwright test --grep "test name"`.

### Build Output
The project builds to `dist/` (`distDir` in `next.config.mjs:46`) with **`output: 'standalone'`** (`next.config.mjs:44`) — this is a hybrid render model, *not* a static export (`output: 'export'` was dropped and the project has since moved on to standalone; `CONTEXT.md`「生产部署模式」records the 2026-08 switch). Concretely:

- **Prerendered/ISR**: the marketing pages, `privacy`, `terms`, `sitemap.ts`, `robots.ts`.
- **Runtime-backed**: `src/app/api/**` (20 route files — `admin/*`, `auth/*`, `cms/*`, `contact`), the `admin/` pages, and any ISR revalidation source. `proxy.ts` matchers exclude `/api/*`, so each API route authenticates itself.
- **Serving**: Nginx keeps a *disk copy* of the client static assets (`/_next/static/` with `try_files … @nextjs`, `nginx-static-production.conf:151-157`) plus `/uploads/` hardening, and proxies `/api/` (`:213`), `/admin` (`:226`) and everything else (`location /` `:238-240`, `@nextjs` `:249`) to the `nextjs_app` upstream running `dist/standalone/server.js`. Page HTML no longer has a static-file fast path — it was removed on purpose (`nginx-static-production.conf:20-25`), so "nginx serves the pages from `dist/`" is no longer true. `assetPrefix` is driven by `CDN_DOMAIN`. Container build is `Dockerfile.prod` + `docker-compose.server.yml`.
- **Images are unoptimized** (`next.config.mjs:48-61`, value at `:58`) because distribution goes through Nginx + CDN, and flipping it to `false` would require every environment to have a Node runtime taking over `/_next/image` (otherwise every image 404s). The reason is *deployment topology*, not a static-export limitation.
- **Boot command**: `npm run start` / `npm run preview` both run `next start -p 3000`, which Next 16 warns "does not work with output: standalone" (warning only — see the Build & Preview note above). The supported server is `dist/standalone/server.js`; `public/` and `dist/static` are copied into the standalone root **automatically by `package.json:9` 的 `postbuild`**，所以 `npm run build` 之后直接 `node dist/standalone/server.js` 即可。该启动方式仍没有包成 npm script —— CI 在 `Jenkinsfile:353-355` 复用产物时重做同套拷贝，发布侧由 `scripts/deploy.sh:162-175` 把 `public/` 与 `dist/static → dist/_next/static` 同步进 Nginx 站点根。

### Commit Convention
Uses Conventional Commits with commitlint (`@commitlint/config-conventional`). Husky + lint-staged enforces linting on pre-commit.

### Submission Flow (PR-First)
`dev`/`main` are only reached via feature branch + PR: sync `origin/dev` → rebase → push → PR gate → merge by **Rebase** (linear history, no merge commit).
`bash scripts/check-pr-checklist.sh <pr-description-file>` must pass before opening a PR — it verifies `.gitea/PULL_REQUEST_TEMPLATE.md` has the three required sections (全链路检查 / 测试分层检查 / 质量门禁) with ≥20 checklist items, and that every item in the PR body is checked (mark irrelevant ones as `N/A：<reason>`).
Rebase rewrites hashes: an already-pushed branch may only be updated with `--force-with-lease`. Always rebase onto `origin/dev`, never a possibly-stale local `dev`.

### Component Versioning History
The project has gone through multiple design iterations. Older component versions:
- `components/detail-v2/` — previous iteration (deleted per git status, migration to `detail/` completed)
- `components/detail-v3/` — another iteration (deleted, same reason)
- `home-content-v2.tsx` through `home-content-v11.tsx` — archived homepage iterations in `(marketing)/_archive/`
- The current canonical components are in `components/detail/` and `home-content-cms.tsx`