交互式网站架构 是做什么的？
产出
创建一个面向生产环境的、以内容、叙事、视觉标识和交互质量为核心的 Next.js 公开站点。这是一种适用于内容主导型网站的通用架构：品牌和营销网站、SaaS 和产品网站、发布页面、社论、作品集、社区、会议、文档型网站以及沉浸式展示站点。
核心是固定的：
- 服务端渲染内容；
- 狭窄的客户端孤岛；
- 经过验证的内容契约；
- 共享的设计令牌和动效令牌；
- 原生浏览器行为；
- 服务端响应中的 SEO 和无障碍；
- 针对路由的性能预算。
选择产品所需的模块：
| 模块 | 使用场景 |
|---|---|
| 内容集合与详情 | 站点包含项目、文章、产品、人员、活动或类似记录 |
| 作品集或案例研究 | 组织需要通过成果来证明实力 |
| 沉浸式归档 | 视觉探索是主要的产品界面 |
| 商店 | 站点销售数字或实物产品 |
| CMS 适配器 | 编辑人员独立于发布流程之外进行内容维护 |
| 联系表单 | 邮件链接或日历功能不足以满足需求 |
不要将可选模块强行用于不需要它们的站点。
典型的站点配置会复用相同的核心：
- SaaS 或产品：落地页、宣传语、功能、内容集合、文档或更新日志。
- 品牌或发布：活动叙事、产品揭晓、候补名单、社会证明。
- 社论：集合索引、文章详情、作者、主题、搜索。
- 社区或会议：演讲者、日程、分会、场地、票务。
- 作品集：项目索引、案例详情、视觉归档、联系。
- 电商：目录、产品详情、结账、下载或履约。
行动前必读
- 每次构建、重新设计或架构变更前，阅读 references/architecture-contract.md。
- 在创建文件夹、契约、服务、适配器或服务端操作之前，阅读 references/code-architecture.md。
- 在安装、升级或移除依赖项之前，阅读 references/dependency-matrix.md。
- 对于新应用程序，遵循 references/build-playbook.md。
- 对于新路由、内容类型、孤岛、归档、商店产品或迁移，遵循 references/evolve-playbook.md。
- 在接受或发布之前，遵循 references/quality-gates.md。
可复用模板位于 assets/templates/ 下。仅在它们与所选架构匹配时才能使用。不要盲目复制每个模板。
不可妥协的不变原则
- 默认将页面组合和主要内容保留在服务端组件中。
- 将
use client限制在尽可能最小的叶子节点。尽可能通过客户端包装器来动画化服务端渲染的子组件。 - 将 TypeScript 数据契约视为每个内容实体、元数据记录、画廊和站点地图条目的真实来源。
- 为每个覆盖层交互提供一个真实的、无需客户端状态、JavaScript 或哈希即可工作的路由。
- 优先使用原生 HTML 行为：链接、按钮、表单、
<dialog>、焦点管理和浏览器历史记录。 - 将秘密保存在仅限服务端的模块中。只有公共标识符可以使用
NEXT_PUBLIC_*。 - 当存在电商功能时，将价格、授权决策、支付确认和受保护的下载保留在服务端。
- 尊重
prefers-reduced-motion、键盘导航、可见焦点、语义标题以及无脚本可读性。 - 确保一个路由的内容不出现在另一个路由的初始客户端包中。当客户端外壳需要计数或标签时，从服务端传递小摘要。
- 使用模块化单仓库，包含瘦路由适配器、自有功能模块、显式端口和单一组合边界。
- 优先使用稳定的依赖项。不要在 Canary 版本的 React 上启动新的生产应用程序。
默认技术栈
使用依赖矩阵中经过验证的精确版本，除非站点有文档记录的合理理由进行调整。
- Node 26 LTS 系列和 pnpm。
- Next.js App Router、React、React DOM、TypeScript。
- Tailwind CSS 4 用于令牌、重置和实用布局。
- CSS Modules 用于路由或组件特定的组合。
- Motion 用于 React 编排和手势。
- 原生 dialog、Canvas、SVG、CSS 和 Web Animations API 用于交互（当其足够时）。
- 按需导入的 Lucide 图标。
- Zod 用于内容和外部输入边界。
- Vercel 用于部署、分析和图片交付。
- Stripe Embedded Checkout 和服务端操作（当需要电商功能时）。
工作流程
- 盘点公共界面：落地页、内容索引、详情路由、转化路径、法律页面、搜索、归档和电商。
- 在实施之前冻结路由清单和客户端边界图。
- 在创建文件之前，分配功能所有者、端口、路由适配器和外部适配器。
- 在构建区块之前，对内容实体和所需媒体进行建模。
- 建立全局令牌、排版、间距、状态、减少动效行为和图片约定。
- 构建服务端外壳、导航、路由回退和 SEO 元数据。
- 一次添加一个客户端孤岛。记录为何每个孤岛必须是客户端侧。
- 使用原生 dialog 和 URL 状态构建覆盖层。同时添加规范页面路由。
- 在定义了复杂视觉的数据、回退、减少动效行为和性能边界之后，再添加复杂视觉。
- 仅在运营模式需要时才添加 CMS、电商、账户或持久化。
- 运行架构边界检查、结构审计、针对性测试、质量门和生产预览验收。
- 分别报告已实现的行为、已验证的依据和未经验证的限制。
决策规则
- 使用 CSS 过渡实现悬停、焦点、按下、显示、跑马灯和简单的状态变化。
- 使用 Motion 实现协调变体、布局过渡、拖拽、存在感和滚动关联编排。
- 仅当视觉效果无法通过 DOM、SVG 和 CSS 可靠表达时，才使用 Canvas 或 WebGL。添加可见性暂停、DPR 限制、清理、减少动效行为和静态回退。
- 保持内容集合服务端渲染。仅将计数、标签或选定的记录发送到客户端覆盖层外壳。
- 当相同内容也有规范页面时，使用原生
<dialog>实现预览和面板。对于深层、长篇幅或独立链接的内容，使用专用路由。 - 对于随着应用一起发布的小团队，使用经过验证的代码内容。当编辑需要独立发布权限时，在仓库适配器后面引入 CMS。
- 当商店仅需即时购买和下载时，使用无状态 Stripe 会话。当产品需要授权、退款、账户、订单历史或重试时，添加数据库和经过验证的 webhook。
- 仅在确定了需要托管的基本元素后，才添加 Radix、shadcn 或其他组件库。原生元素和站点自有基本元素是基线。
- 将作品集、归档和商店视为模块。它们复用核心的内容、路由、样式、动效和安全契约。
必需的构建产物
创建并维护以下站点级产物：
docs/architecture.md：路由图、客户端边界、内容所有权、外部服务和性能预算。src/features/*/domain和src/features/*/application：经过验证的契约和能力。src/platform/*：外部适配器和仅限服务端的组合根。src/shared/*：经过验证的跨功能契约和设计基本元素。src/components/*：具有显式名称的服务端组合和客户端孤岛。src/app/*：页面、布局、元数据、站点地图、robots 和路由处理器。.env.example：名称和用途，永不包含真实秘密。- 针对内容验证、客户端状态机、服务端操作和关键浏览器旅程的测试。
- 包含预览、浏览器、无障碍、性能、SEO 以及条件性电商证据的发布清单。
结构审计
在搭建脚手架之后、发布之前，运行架构边界检查和打包审计：
pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app
在 CI 中使用 --strict 让警告导致失败。该脚本检查依赖项存在性、路由和内容结构、客户端/服务端秘密风险、对话框和动效保护措施、测试、SEO 文件和源码映射暴露。它补充测试而非替代测试。
完成契约
只有在满足以下条件时，构建才算完成：
- 路由和边界图与实现匹配；
- 依赖图无环且
arch:check通过； - 路由使用功能的公共 API，组合根负责接线；
- 应用构建无 Canary 或对等依赖意外；
- 关键内容出现在服务端 HTML 中；
- 覆盖层、菜单和键盘路径工作正常并恢复焦点；
- 减少动效和无脚本回退已通过验证；
- 存在元数据、站点地图、robots、规范 URL 和社交图片；
- 初始路由 JS 和图片负载保持在记录的预算内；
- 当存在电商功能时，使用服务端所有的价格、服务端确认和受保护的下载；
- 预览和生产环境的证据分开记录。