从已定义的架构开始，而不是空仓库。

架构概览

四个阶段，依赖方向单一。中间两个是基础，第一个和最后一个属于您。

1. Stage 1

   站点数据、内容与资源

   标识、导航、语言、Markdown 内容和视觉素材 —— 采用方的输入，在被读取之前就完成校验。

2. Stage 2

   Foundation 衍生环境

   不依赖框架的领域概念，以及协调它们的应用服务，没有框架自身的导入。

3. Stage 3

   呈现、路由与集成点

   路由、布局组合、元数据，以及从配置连接预订、咨询、地图与分析的适配器工厂。

4. Stage 4

   部署

   面向静态生成的构建产物，从您自己的仓库部署到自己的托管账号。

依赖方向由测试证明而不是假设：核心不能导入 React、Next.js 或外层，应用层也不能进入具体适配器。

仓库中的 ARCHITECTURE.md

配置还是代码

这条边界是项目的核心。大多数业务特有的决策是数据；真正的扩展是代码，Foundation 会明确说明各自是什么。

工程契约

项目承诺的内容，以及拒绝主张的内容。

• 严格校验的配置

  单一 schema，拒绝未知键，失败信息可用，且配置只能通过加载器读取。

• 六边形边界

  纯净核心、端口与应用服务、工厂之后的适配器，以及轻薄的框架路由。

• 依赖强制执行

  架构测试遍历源码树，在出现被禁止的导入时失败，因此架构图无法与代码脱节。

• 服务端优先组合

  默认 React Server Components 与静态生成，客户端交互仅限真正需要的组件。

• 在真实浏览器中验证

  已提交的无头浏览器矩阵检查桌面、平板和移动宽度、键盘与指针交互、减少动态效果和深色模式，并在任何断言未通过时让运行失败。

• 架构与单元测试关卡

  边界测试与单元测试同资源检查、类型检查、lint 和生产构建一起运行。

• 能力主张的纪律

  文档化的主张会与项目自身的实现与验证记录对照，因此主张不会超出证据。

• 诚实的升级模型

  由于配置、内容和资源位于应用核心之外，平台改进可以被吸收，而不必覆盖您的工作。

Foundation 在哪里停下

同样的所有权分工的技术表述。Foundation 刻意在运营复杂性之前停下，并提供通往您所选服务的集成点。

扩展由外向内：新增服务商是适配器、工厂分支和 schema 枚举项；新增内容类型或语言是数据。真正新的能力属于平台工作。

采用流程

八个阶段。命令级的细节在仓库中，这里展示工作的形态。

1. 1

   获取 Foundation

   克隆或复刻公开仓库。

2. 2

   安装并运行

   安装依赖并在本地启动网站。

3. 3

   配置

   定义标识、语言、功能与服务商选择。

4. 4

   撰写内容与资源

   编写页面并替换品牌资源角色。

5. 5

   连接服务商

   把集成点指向真正使用的服务。

6. 6

   验证

   在本地运行项目自身的质量关卡。

7. 7

   部署

   从自己的仓库与账号构建并部署。

8. 8

   维护与升级

   吸收上游改进而不覆盖您自己的素材。

仓库中的手册覆盖每个阶段，包括排障。

权威文档

GitHub 是规范的技术来源。本站做概述，仓库给出操作步骤。

• Repository

  完整代码、许可证，以及项目对自身是什么与不是什么的声明。

• README.md

  项目内容、快速开始、仓库结构与许可立场。

• ARCHITECTURE.md

  架构风格、边界、依赖方向与集成模式。

• CUSTOMIZING.md

  面向下游使用者的指南与完整的配置参考。

• DEPLOYMENT.md

  发布运行手册与部署后检查清单。

• BRAND_ASSETS.md

  品牌资源替换契约：每个可替换的视觉角色。

• 手册

  采用、定制、品牌、内容、升级、校验、部署与排障流程。

以上每个目标都指向公开仓库，文档在那里维护。