cms-website/SiteForge_网站工厂完整项目计划方案_V4.0.md

# SiteForge 网站工厂完整项目计划与实施方案

> 版本：V4.0  
> 编制日期：2026-10-21  
> 文档状态：产品、架构、研发、测试和试点实施的统一基线  
> 管理后台：Art Design Pro + Vue 3 + TypeScript + Element Plus  
> 核心定位：支持旧站迁移、旧内容换新模板、全新网站搭建的多站点静态网站生产工厂

---

## 0. 文档结论

SiteForge 不应只做“WordPress 静态迁移工具”，也不应做成另一个 WordPress。它应是一套由单一超级管理员使用的网站生产工厂：

```text
旧站或新数据
    ↓
采集 / 导入 / 手工录入
    ↓
统一内容模型与字段映射
    ↓
站点蓝图初始化网站结构
    ↓
主题 + 页面模板 + 板块组合完成展示
    ↓
冻结内容、路由、SEO、媒体和主题版本
    ↓
静态构建 → 自动验收 → 预览 → 发布 → 回滚
```

系统必须完整支持以下三条主业务路径：

1. **原样迁移**：导入旧站，尽量保持原内容、URL、SEO 和页面行为，输出纯静态站。
2. **迁移并改版**：导入旧内容，选择新蓝图或新主题重新组织展示，同时保留旧 URL，必要时生成受控跳转。
3. **全新建站**：不依赖任何旧网站，选择蓝图和主题，通过手工录入、CSV、JSON 或 API 导入新内容并生成新站。

此外支持第四条辅助路径：

4. **复制建站**：复制已有站点的结构、配置和可选内容，替换品牌、域名和数据后快速创建同类网站。

只有当以上四条路径共用同一套内容、蓝图、主题、构建和发布体系时，SiteForge 才真正是“网站工厂”。

---

## 1. 文档权威关系

### 1.1 当前权威文档

本文从 V4.0 起作为 SiteForge 的产品范围、目标架构、实施顺序和总体验收基线。

现有文档的关系如下：

| 文档 | 后续用途 | 权威性 |
|---|---|---|
| `SiteForge_网站工厂完整项目计划方案_V4.0.md` | 产品、架构和实施总基线 | 最高 |
| `docs/superpowers/specs/2026-10-20-siteforge-vertical-slice-design-v2.md` | 迁移切片中的数据、路由、构建、门禁细节参考 | 与 V4 冲突时以 V4 为准 |
| `cms现状与SiteForge差距分析_V2.0.md` | 旧 `D:\project\cms` 的复用和风险依据 | 事实参考 |
| `SiteForge_主题与板块设计方案_V1.0.md` | 主题、板块和组件设计参考 | 与 V4 冲突时以 V4 为准 |
| `SiteForge_完整项目计划方案_V3.0.md` | 历史总体方案 | 被 V4 取代 |
| `SiteForge_项目实施计划_V1.0.md` | 历史排期参考 | 被 V4 的阶段计划取代 |

### 1.2 代码库关系

- `D:\project\cms-one`：SiteForge 新架构和后续正式实现目录。
- `D:\project\cms`：旧项目和经验资产来源，默认只读，不在其中继续堆叠新架构。
- 旧项目可复用的是迁移规则、测试夹具、兼容经验和经过验证的局部实现，不是整套复制上线。
- 认证、发布、回滚、构建输入、站点隔离和主题体系必须按本文重新建立或严格改造。

---

## 2. 建设背景与问题定义

当前业务不是迁移一个网站，而是需要长期、重复地完成多种网站生产任务：

- 旧网站大多为 WordPress，也包含 PHP、自研 CMS、纯 HTML、数据库和接口数据。
- 不同网站的品牌、页面结构和视觉效果差异很大。
- 迁移站的历史 URL、SEO、媒体路径和外链资产不能随意丢失。
- 新网站不一定存在旧站，需要从模板、结构化数据或手工内容直接创建。
- 老内容有时要保留原外观，有时要进入全新设计。
- 网站上线后仍需发布产品、新闻、页面，调整菜单、SEO 和站点信息。
- 生产网站要求纯静态，控制后台故障不能影响线上访问。
- 多次项目中重复出现的数据清洗、URL 处理、主题开发、构建、发布和验收需要标准化。

因此，问题不能只用“抓取旧站并导出 HTML”解决。系统必须把内容资产、站点结构、视觉主题、页面组合和生产发布分离，才能同时获得复用性和设计自由度。

---

## 3. 产品目标与非目标

### 3.1 产品目标

1. 一个后台管理多个独立网站。
2. 一个 `super_admin` 管理全部功能，不建设复杂角色权限。
3. 同时支持迁移建站、改版建站、全新建站和复制建站。
4. WordPress 作为第一优先来源，通过适配器扩展其他来源。
5. 内容与主题解耦，同一份标准内容可被不同主题渲染。
6. 用站点蓝图复用网站结构，用组件和板块复用功能，用主题保留视觉差异。
7. 迁移模式下精确保留或明确处置旧 URL 和 SEO。
8. 新站模式下可生成规范 URL、SEO、Sitemap 和结构化数据。
9. 通过后台长期维护产品、新闻、页面、分类、菜单、媒体和网站配置。
10. 每次构建使用冻结输入，可复现、可审计、可回滚。
11. 生产站完全静态化，动态能力通过独立服务提供。
12. 第二个及后续网站主要投入在内容映射、设计配置和少量专属组件，而不是重写整个平台。

### 3.2 明确非目标

V1 不建设：

- 类似 Webflow 的自由画布设计器。
- 任意 CSS、JavaScript 在线编辑和执行。
- 多组织 SaaS、套餐、计费和租户自助注册。
- 多角色 RBAC、成员协作和复杂审批。
- 完整商城、支付、订单、库存和会员中心。
- 任意 WordPress 插件数据零人工自动迁移。
- 自动承诺搜索排名绝不波动。
- 未经人工确认自动把迁移结果或 AI 内容发布到生产环境。
- Kubernetes、复杂微服务和多区域主动容灾。

### 3.3 V1 成功标准

| 维度 | 验收目标 |
|---|---|
| 建站模式 | 四条业务路径均能完成，前三条必须有真实样板 |
| 多站点 | 至少 3 个站点数据、构建和发布相互隔离 |
| 蓝图 | 同一蓝图能初始化两个不同品牌的新站 |
| 主题 | 至少 2 套视觉差异明显的主题使用同一内容协议 |
| 迁移 | 至少 1 个真实 WordPress 站完成导入、差异处理和静态预览 |
| 新站 | 无旧站输入也能从蓝图、手工内容及 CSV/JSON 构建完整网站 |
| URL | 迁移站已知 URL 100% 有明确处置或批准豁免 |
| SEO | 迁移站具备旧站快照、目标值和构建结果的三方差异报告 |
| 内容运营 | 超管可无代码维护产品、新闻、页面、菜单、媒体和 SEO |
| 构建 | 同一冻结输入的业务产物 Hash 一致 |
| 发布 | 至少一种部署适配器完成真实发布和回滚演练 |
| 独立性 | 控制面停止运行后，已发布静态站仍可正常访问 |

---

## 4. 用户与权限模型

### 4.1 唯一角色

V1 只有一种平台角色：

```text
super_admin
```

该角色可以管理全部网站、数据源、内容、主题、蓝图、构建、发布和系统设置。

不实现：

- 站点管理员。
- 编辑、审核、发布等分级角色。
- 菜单权限、按钮权限和数据权限配置器。
- 用户组和组织层级。

### 4.2 账号与安全

即使只有一个角色，仍必须具备：

- 初始管理员一次性创建流程，禁止默认密码。
- 强密码和可选强制 MFA；生产公网后台必须启用 MFA。
- 恢复码、会话查看和会话撤销。
- 登录限流、失败锁定和安全审计。
- 高风险操作二次确认。
- 发布、回滚、删除、密钥变更的不可变操作日志。

单一角色只是减少权限复杂度，不代表取消安全控制。

---

## 5. 四条核心业务流程

### 5.1 原样迁移

```text
创建迁移站点
→ 登记旧站来源
→ 获取 WXR / REST / 数据库 / uploads / Sitemap
→ 建立源快照
→ 导入并标准化内容
→ 建立旧 URL 和 SEO 基线
→ 选择兼容主题或实现专属主题
→ 人工处理异常映射
→ 冻结并构建
→ 自动门禁
→ 预览确认
→ 最终差量同步
→ 发布和切站
```

目标是内容、URL 和 SEO 保真。视觉可接近旧站，但不要求把旧主题代码原样搬入系统。

### 5.2 老内容换新模板

```text
完成旧站导入
→ 选择目标站点蓝图和新主题
→ 把标准内容映射到新页面模板和板块
→ 生成兼容性报告
→ 补齐缺失字段和专属板块
→ 保留旧路径或建立一对一 Redirect
→ SEO 差异验收
→ 构建、预览和发布
```

“换模板”不是简单换 CSS。它包括页面类型匹配、板块组合、菜单重建、媒体适配和缺失字段补齐。

### 5.3 全新建站

```text
创建新站
→ 选择站点蓝图
→ 选择蓝图支持的主题/主题预设
→ 填写品牌、域名、语言和联系方式
→ 安装内容类型、默认页面、菜单和 SEO 规则
→ 导入 CSV/JSON 或手工新增内容
→ 调整页面板块
→ 构建、门禁、预览和发布
```

此流程不得依赖 WordPress ID、旧 URL、WXR 或旧站字段。

### 5.4 复制建站

支持三种复制范围：

| 模式 | 复制内容 | 复制结构/主题 | 复制环境和密钥 |
|---|---:|---:|---:|
| 仅结构 | 否 | 是 | 否 |
| 结构 + 示例内容 | 仅明确标记的示例数据 | 是 | 否 |
| 完整业务副本 | 可选 | 是 | 否 |

复制后必须重新设置站点标识、域名、品牌、环境、部署目标和密钥引用。任何 Secret、发布锁、历史 Release 和线上统计不得被复制。

---

## 6. 核心产品概念

### 6.1 概念关系

```text
Content Type / Content Entry
            ↓
      Block Instance
            ↓
       Page Instance
            ↓
       Page Template
            ↓
          Theme
            ↑
      Site Blueprint
```

### 6.2 站点蓝图 Site Blueprint

站点蓝图是“创建一个可运营网站所需的结构安装包”，不是视觉主题的别名。

一个蓝图至少声明：

- 蓝图 ID、版本和兼容协议版本。
- 适用站点类型，如企业站、产品目录站、新闻站。
- 必需和可选的站点配置字段。
- 需要安装的内容类型及其字段 Schema。
- 默认页面实例和页面模板绑定。
- 默认板块组合和插槽规则。
- 默认菜单和菜单项结构。
- 默认 URL 生成规则和 SEO 规则。
- 允许使用的主题和默认主题绑定。
- 可选的示例内容包。
- 可选的 CSV/JSON 映射配置。
- 可选的迁移映射配置。

V1 至少提供：

1. `corporate-basic`：企业展示、新闻、产品目录、联系页面。
2. `catalog-pro`：多分类产品、产品详情、参数、下载和询盘入口。

### 6.3 主题 Theme

主题负责最终 HTML 结构、CSS、响应式、动效和展示组件，不负责保存业务内容。

主题 Manifest 声明：

- 主题 ID、版本和渲染协议版本。
- 支持的蓝图、内容类型和模板。
- 模板入口和 Block Renderer。
- 必需站点配置和设计令牌 Schema。
- 可用的主题预设。
- 公共运行时和组件包兼容版本。
- 构建命令、依赖锁和产物约束。

主题之间不得直接引用彼此的内部组件。

### 6.4 页面模板 Page Template

页面模板定义页面的结构约束：

- 适用页面/内容类型。
- 可用插槽，如 `hero`、`main`、`sidebar`、`after_content`。
- 每个插槽允许的板块类型。
- 必需板块、最大数量和顺序约束。
- 页面级 SEO 和结构化数据策略。
- 对应主题的渲染入口。

### 6.5 页面实例 Page Instance

页面实例是某个站点中真实存在的页面组合，包含：

- 页面标题、Slug、Locale 和状态。
- 绑定的页面模板版本。
- 板块实例及顺序。
- 菜单归属和内部链接。
- URL 与 SEO 配置。
- 当前修订和已发布修订。

### 6.6 板块定义与板块实例

板块定义是可复用协议，板块实例是页面中的实际数据。

```ts
interface BlockInstance<T = Record<string, unknown>> {
  id: string
  siteId: string
  pageId: string
  blockType: string
  schemaVersion: number
  slotKey: string
  position: number
  variant?: string
  data: T
  settings?: {
    anchorId?: string
    themeMode?: 'default' | 'light' | 'dark'
    spacing?: 'none' | 'small' | 'medium' | 'large'
  }
  visibility: {
    enabled: boolean
    locales?: string[]
  }
}
```

V1 采用有限插槽和结构化配置，不允许自由坐标和任意嵌套。

### 6.7 内容类型与内容条目

首版标准内容类型：

- `basic_page`
- `product`
- `news_article`
- `category`
- `tag`
- `brand`
- `download`
- `faq`
- `menu`
- `redirect`

站点可以安装扩展字段，但扩展字段必须通过版本化 Schema 声明，不能把全部数据塞入无约束 JSON。

### 6.8 映射配置 Mapping Profile

映射配置把来源字段转换为统一内容字段：

```text
来源字段
→ 清洗与转换
→ 标准字段
→ 默认值/字典/单位处理
→ 校验
→ 冲突策略
→ 导入结果
```

它必须支持：

- 字段重命名和类型转换。
- HTML 清洗和短代码处置。
- 分类、枚举、单位和日期映射。
- 媒体 URL 到媒体实体的转换。
- 一个来源字段拆分为多个字段。
- 多个来源字段合并。
- 必填缺失报告。
- 预览前 N 条转换结果。
- 映射版本化和重跑。

---

## 7. 组件化与复用策略

### 7.1 四层复用模型

```text
第一层：数据契约、Schema、URL、SEO、媒体工具
第二层：无样式基础组件与可访问性交互
第三层：Headless 业务逻辑和内容查询
第四层：主题展示组件和品牌视觉
```

前三层公共复用，第四层由主题独立实现。

### 7.2 建议公共包

```text
packages/
  contracts/             # DTO、Schema、事件和状态机
  content-model/         # 内容类型与修订协议
  blueprint-sdk/         # 蓝图定义、安装和升级
  import-sdk/            # 来源适配器和字段映射
  block-contracts/       # Block Schema 与版本迁移
  theme-runtime/         # 渲染快照读取和主题协议
  ui-primitives/         # 无样式或低样式基础组件
  headless-components/   # 菜单、分页、筛选、表单逻辑
  seo-runtime/           # Meta、Canonical、JSON-LD、Sitemap
  media-runtime/         # 响应式媒体和资源解析
  route-compiler/        # 路由、Redirect 和部署规则编译
  validation-rules/      # 自动门禁规则
  observability/         # 日志、指标和 Trace 约定
```

### 7.3 复用边界

| 能力 | 公共复用 | 主题独立 |
|---|---:|---:|
| 内容 Schema、修订和导入 | 是 | 否 |
| URL、SEO、媒体解析 | 是 | 仅配置和展示差异 |
| 菜单、分页、筛选逻辑 | 是 | HTML 和视觉独立 |
| Product/News 查询 | 是 | 卡片和列表独立 |
| Header/Footer 数据协议 | 是 | 结构和视觉独立 |
| 页面模板和动画 | 否 | 是 |
| 品牌排版和颜色 | Token 可配置 | 是 |
| 专属业务组件 | 可提取逻辑 | 展示通常独立 |

### 7.4 首版板块目录

全局板块：

- Header
- Footer
- Notice Bar
- Global CTA
- Contact Info
- Cookie/Privacy Notice

页面板块：

- Hero
- Rich Text
- Image + Text
- Feature Grid
- Statistics
- Logo/Partner Wall
- Gallery
- Video
- Product List
- Product Category Grid
- News List
- FAQ
- Download List
- Contact Form
- CTA

系统板块：

- Breadcrumbs
- Product Main Info
- Product Parameters
- Product Gallery
- Article Body
- Taxonomy Archive
- Pagination
- SEO Head

Legacy HTML 仅作为迁移过渡板块，必须清洗、隔离、标记并制定结构化替换计划。

---

## 8. 总体架构

```mermaid
flowchart TB
  subgraph Sources[输入来源]
    WP[WordPress WXR / REST / SQL]
    WEB[HTML / Sitemap / 浏览器渲染]
    DB[其他 CMS / MySQL / API]
    FILE[CSV / JSON / XML / ZIP]
    MANUAL[后台手工录入]
  end

  subgraph Factory[SiteForge 控制面]
    ADMIN[Art Design Pro 超管后台]
    API[NestJS 模块化单体 API]
    JOB[任务调度与 Worker]
    RAW[不可变来源快照]
    MAP[适配器与映射引擎]
    CONTENT[统一内容与修订]
    BLUEPRINT[站点蓝图]
    PAGE[页面模板与板块]
    ROUTE[URL / SEO / Sitemap]
    MEDIA[媒体资产]
    THEME[主题与公共组件]
    BUILD[冻结快照与静态构建]
    GATE[自动门禁]
    RELEASE[Release / 部署 / 回滚]
  end

  subgraph Production[独立生产面]
    NGINX[Nginx 静态站]
    CDN[对象存储 + CDN]
    DYNAMIC[表单 / 搜索等独立 API]
  end

  Sources --> JOB --> RAW --> MAP --> CONTENT
  ADMIN --> API --> JOB
  BLUEPRINT --> PAGE
  CONTENT --> PAGE --> ROUTE
  MEDIA --> PAGE
  ROUTE --> BUILD
  THEME --> BUILD
  BUILD --> GATE --> RELEASE
  RELEASE --> NGINX
  RELEASE --> CDN
  NGINX -.按需调用.-> DYNAMIC
  CDN -.按需调用.-> DYNAMIC
```

### 8.1 控制面与生产面分离

- 控制面负责管理、导入、构建、验收和发布。
- 生产面只包含不可变静态文件、服务器规则和明确的动态 API。
- 生产页面不得在访问时查询 SiteForge 数据库。
- SiteForge、Redis 或 PostgreSQL 短时离线不得影响已发布网站。

### 8.2 模块化单体

V1 使用 NestJS 模块化单体 + 独立 Worker，不提前拆微服务：

```text
Auth
Sites / Environments
Blueprints
Content / Revisions
Pages / Blocks / Menus
Sources / Imports / Mappings
Media
Routes / SEO
Themes
Builds / Validation
Releases / Deployments
Forms
Audit / Operations
```

模块间通过明确 Service、Repository、事件和共享契约通信，禁止跨模块直接改表。

### 8.3 技术栈

| 层 | 选型 |
|---|---|
| Monorepo | pnpm Workspace |
| 管理后台 | Art Design Pro + Vue 3 + TypeScript + Element Plus |
| 状态与路由 | Pinia + Vue Router |
| API | NestJS 模块化单体 |
| ORM | Drizzle ORM |
| 数据库 | PostgreSQL 16 |
| 队列 | Redis + BullMQ；最小切片可先使用持久化数据库 Job Runner |
| 静态构建 | Astro |
| 抓取 | TypeScript HTML 解析；Playwright 仅作 JS/异常页面兜底 |
| Schema | JSON Schema/Zod，具体边界在 ADR 中锁定 |
| 对象存储 | S3 兼容存储；本地开发可使用文件适配器 |
| 测试 | Vitest + API 集成测试 + Playwright |
| 部署 | Docker Compose 控制面；Nginx/SSH 或 OSS/CDN 生产站 |
| 可观测性 | 结构化日志 + 指标 + 告警 |

Node、pnpm、PostgreSQL、构建镜像和第三方依赖必须锁定版本。

---

## 9. 建议仓库结构

```text
cms-one/
  apps/
    admin/                    # Vue 3 管理后台
    api/                      # NestJS API/CLI
    worker/                   # 导入、媒体、构建、验证、发布 Worker
    preview-server/           # 本地/受控预览
  packages/
    contracts/
    database/
    auth/
    content-model/
    blueprint-sdk/
    import-sdk/
    wordpress-adapter/
    file-import-adapter/
    block-contracts/
    theme-runtime/
    route-compiler/
    seo-runtime/
    media-runtime/
    validation-rules/
    deployment-sdk/
  themes/
    pilot-minimal/
    corporate-modern/
  blueprints/
    corporate-basic/
    catalog-pro/
  fixtures/
    sanitized-wxr/
    sample-csv/
    sample-json/
    route-cases/
  infra/
    compose/
    nginx/
    scripts/
  docs/
    architecture/
    adr/
    operations/
    migration/
  artifacts/                 # Git ignore
  storage/                   # Git ignore
```

主题、蓝图和适配器都必须通过 SDK 契约注册，禁止把站点专属判断散落在 API、构建器和公共组件中。

---

## 10. 核心领域模型

### 10.1 站点和环境

| 实体 | 责任 |
|---|---|
| `sites` | 站点身份、模式、默认语言、状态 |
| `site_config_revisions` | 品牌、联系信息、功能开关等不可变修订 |
| `site_environments` | preview/staging/production 的域名和发布目标 |
| `site_blueprint_bindings` | 站点绑定的蓝图及版本 |
| `theme_bindings` | 站点/环境绑定的主题、预设和 Token 版本 |
| `deployment_targets` | 部署适配器和 Secret 引用 |

`site_mode` 至少包含：

```text
migration_preserve
migration_redesign
new_build
clone
```

### 10.2 蓝图、模板和板块

| 实体 | 责任 |
|---|---|
| `site_blueprints` | 蓝图稳定身份 |
| `site_blueprint_versions` | 不可变蓝图 Manifest 和安装包版本 |
| `blueprint_installations` | 某站安装、升级、失败和回滚记录 |
| `page_template_definitions` | 页面模板和插槽约束 |
| `page_instances` | 站点真实页面 |
| `page_revisions` | 页面不可变修订 |
| `block_definitions` | 板块 Schema、UI Schema 和兼容版本 |
| `block_instances` | 页面中的板块实例 |
| `block_instance_revisions` | 板块不可变修订 |
| `menus` / `menu_items` | 导航结构和内部链接 |

### 10.3 内容与修订

| 实体 | 责任 |
|---|---|
| `content_types` | 内容类型 Schema 和版本 |
| `content_entries` | 稳定内容身份、站点、类型、Locale |
| `content_revisions` | 不可变内容版本和 Hash |
| `content_publication_pointers` | current/published 双指针 |
| `taxonomies` / `terms` | 分类法和分类项 |
| `content_term_relations` | 内容与分类关系 |
| `content_links` | 内部引用和删除影响分析 |

导入只更新 current revision，不得自动修改 published revision。只有显式发布动作才能改变 published pointer。

### 10.4 来源、快照和导入

| 实体 | 责任 |
|---|---|
| `source_connections` | 来源逻辑连接和 Secret 引用 |
| `source_snapshots` | 某次 WXR、文件、接口响应和媒体目录的不可变证据 |
| `source_records` | 来源稳定键与平台对象身份映射 |
| `mapping_profiles` | 字段映射和转换规则版本 |
| `import_jobs` | 一次导入任务 |
| `import_items` | 每条来源记录的 created/updated/skipped/conflict/failed |
| `import_conflicts` | 人工决定保留、覆盖、合并或忽略 |

来源稳定身份使用来源系统 ID 或受控复合键，不能使用 Permalink 作为内容主键。

### 10.5 媒体

| 实体 | 责任 |
|---|---|
| `media_assets` | 媒体稳定身份、Hash、MIME、安全状态 |
| `media_variants` | WebP/AVIF/缩略图等衍生版本 |
| `media_usages` | 正文、板块、特色图等引用位置 |
| `legacy_asset_routes` | 旧资源 URL 到新资源的映射 |

媒体删除前必须执行引用检查。默认软删除，不直接清除物理原件。

### 10.6 路由与 SEO

| 实体 | 责任 |
|---|---|
| `route_registry` | 精确路径、类型、目标、状态和来源证据 |
| `route_collisions` | 大小写、尾斜杠、静态文件映射等碰撞风险 |
| `redirect_rules` | 301/302 和目标 |
| `seo_revisions` | Title、Description、Canonical、Robots、OG、JSON-LD |
| `source_page_snapshots` | 旧站原始/渲染 SEO 证据 |
| `sitemap_entries` | Sitemap 纳入与排除理由 |

精确路由键和碰撞检测键必须分离，避免错误地把大小写或尾斜杠不同的历史 URL 合并。

### 10.7 构建、验收和发布

| 实体 | 责任 |
|---|---|
| `build_jobs` | 构建状态、输入、日志和结果 |
| `build_input_snapshots` | 冻结构建输入和总 Hash |
| `validation_runs` | 门禁规则、结果、豁免和报告 |
| `artifacts` | 构建产物、Manifest 和 Checksums |
| `releases` | 可发布的不可变版本 |
| `deployments` | 发布目标、步骤和结果 |
| `publish_locks` | 防止同站并发发布 |
| `rollback_events` | 回滚版本、原因和结果 |
| `audit_logs` | 关键操作审计 |

---

## 11. 来源适配与导入系统

### 11.1 适配器协议

每个来源适配器实现：

```ts
interface SourceAdapter {
  probe(input: SourceInput): Promise<CapabilityReport>
  snapshot(input: SourceInput): Promise<SourceSnapshotRef>
  discover(snapshot: SourceSnapshotRef): AsyncIterable<SourceRecord>
  normalize(record: SourceRecord, profile: MappingProfile): Promise<NormalizedRecord>
  diff?(previous: SourceSnapshotRef, current: SourceSnapshotRef): Promise<SourceDiff>
}
```

适配器只负责来源发现和标准化，不直接发布内容、不写生产路径、不调用主题。

### 11.2 首版适配器优先级

P0：

- WordPress WXR。
- 已解包 uploads 媒体目录。
- Sitemap/Sitemap Index。
- CSV。
- JSON。
- 后台手工录入。

P1：

- WordPress REST API。
- WordPress SQL 只读导出。
- HTML 抓取。
- ZIP 上传和安全解包。
- 通用 REST API。

P2：

- PHP/MySQL 自研 CMS。
- Drupal/Joomla 等专用适配器。
- Excel 和第三方业务系统连接。

### 11.3 WordPress 首版范围

必须支持：

- post、page、product CPT。
- 分类、标签、产品分类、产品标签及关系。
- Attachment、特色图片、正文图片和产品图库。
- Yoast 常见 Title、Description、Canonical 和主分类字段。
- 原 Permalink，包括 `.html`、`.php`、目录和非标准后缀。
- Sitemap 中额外的已知 URL。
- 试点明确使用的少量主题字段。

必须识别并报告但允许暂不转换：

- 未配置的 CPT。
- Elementor/WPBakery 等复杂布局数据。
- 未知短代码。
- 插件私有表数据。
- WooCommerce 订单、支付、库存和复杂变体。
- 评论、用户和敏感个人数据。

### 11.4 CSV/JSON 新站导入

新站导入至少支持：

- 选择目标内容类型。
- 自动识别列名/键名和数据类型。
- 交互式建立字段映射。
- 预览转换和验证错误。
- 设置唯一键和更新策略。
- 下载错误行报告。
- 重跑幂等。
- 将映射保存为版本化 Profile。

### 11.5 冲突策略

每次导入可选择默认策略，但冲突必须逐条留痕：

```text
create_only
update_if_unchanged
overwrite_current
merge_selected_fields
skip
manual_review
```

已经在后台人工修改的字段默认受保护，迁移差量不得静默覆盖。

---

## 12. URL、SEO 与迁移保真

### 12.1 URL 来源

迁移站的已知 URL 基线至少由以下集合组成：

```text
WXR 可推导 URL
∪ Attachment URL
∪ Sitemap/Sitemap Index
∪ HTML 抓取结果
∪ 服务器 Rewrite/Redirect 规则
∪ 访问日志、GSC、GA4（可获得时）
∪ 人工补充清单
```

报告必须明确列出已接入和未接入来源，禁止把“当前已知 URL”描述为“所有历史 URL”。

### 12.2 路径处置

每条迁移 URL 必须进入一种状态：

```text
preserve      原路径输出 200
redirect      明确跳转
gone          明确 410
exclude       批准排除并记录原因
unresolved    未处理；发布门禁前必须清零
```

新站 URL 则由蓝图和内容类型规则生成，不要求存在旧 URL 基线，但仍需执行冲突、Canonical、Sitemap 和内部链接检查。

### 12.3 SEO 三方对比

```text
source_raw → source_rendered → target_build
```

- `source_raw`：旧数据库、插件、WXR 或 API 中的 SEO 数据。
- `source_rendered`：旧网站最终 HTML 和响应头。
- `target_build`：新静态预览的真实 HTTP 结果。

对比至少包含：

- Title、Description。
- Canonical。
- Robots 和 X-Robots-Tag。
- H1 和标题结构。
- OG/Twitter Card。
- JSON-LD。
- hreflang。
- 状态码、Redirect 和链路。
- Sitemap 纳入情况。
- 内部链接和媒体可达性。

### 12.4 门禁严重级别

- P0：发布阻断，必须修复。
- P1：默认阻断，可由超管填写理由、影响和到期时间后豁免。
- P2：告警，不阻断但进入报告。
- P3：优化建议。

Canonical 指向错误域名、关键 URL 404、Redirect 环、noindex 误设、Sitemap 包含错误页面等均属于 P0。

---

## 13. 媒体与静态资源

### 13.1 处理流程

```text
登记来源
→ 下载或读取本地输入
→ 协议/MIME/大小/像素安全校验
→ Hash 去重
→ 保存原件
→ 生成受控衍生图
→ 建立使用关系
→ 建立旧路径映射
→ 构建输出
```

### 13.2 安全规则

- 拒绝 `file://`、内网地址、回环地址和受限协议。
- 处理 DNS 重绑定、跳转后目标和下载总预算。
- MIME 必须通过文件内容验证，不能只信扩展名。
- SVG 默认清洗或转安全格式，未经允许不得原样内联。
- ZIP 必须限制条目数、展开大小、目录穿越和符号链接。
- EXIF 和潜在敏感元数据按策略清理。

### 13.3 路径策略

- 迁移站优先保留重要旧媒体路径。
- 新站使用稳定、可缓存的资源路径。
- 构建产物不得引用控制面私有地址。
- 外链资源必须在发布前明确选择保留远程、转存或阻断。

---

## 14. 内容发布与版本模型

### 14.1 双指针模型

每个内容、页面和站点配置都保留：

```text
current_revision_id
published_revision_id
```

- 保存编辑只更新 current。
- 导入只创建或更新 current。
- 发布内容时显式更新 published。
- 静态构建默认只读取 published。
- 预览可选择读取 current，但必须标识为预览并设置 noindex。

### 14.2 内容状态

```text
draft
published
archived
```

V1 不实现复杂审批流。状态变更仍记录操作人、时间和原因。

### 14.3 删除规则

- 被页面、菜单、板块、SEO 或其他内容引用时禁止直接删除。
- 删除已发布内容前必须选择 Redirect、Gone 或替代目标。
- 默认软删除，物理清理通过独立受控任务执行。
- 删除不得导致历史 Release 无法回滚。

---

## 15. 静态构建体系

### 15.1 冻结构建输入

```text
BuildInput = PublishedContentSnapshot
           + PageAndBlockSnapshot
           + RouteAndSeoSnapshot
           + MediaManifest
           + BlueprintBinding
           + ThemeBuildSnapshot
           + SiteEnvironmentSnapshot
```

构建期间不得读取变化中的在线业务表、Seed 数据或远程内容。

### 15.2 Render Snapshot

主题只接收冻结文件，例如：

```text
site.json
blueprint.json
content.json
pages.json
blocks.json
menus.json
taxonomies.json
routes.json
seo.json
assets.json
render-manifest.json
```

主题不得：

- 查询 PostgreSQL。
- 调用控制面 API。
- 读取原始 Source Snapshot。
- 使用站点专属 Seed fallback。
- 在构建时访问网络。

### 15.3 Artifact 结构

```text
artifacts/jobs/<build-job-id>/
  input/
  dist/
  manifests/
    build-manifest.json
    route-manifest.json
    asset-manifest.json
    checksums.txt
  reports/
    validation-summary.json
    validation-report.html
    url-coverage.json
    seo-diff.json
  logs/
    build.log
```

### 15.4 可复现性

同一 Build Input 连续构建两次应满足：

- HTML、CSS、JS、媒体和 Manifest 的业务 Hash 一致。
- Job ID 和时间可以不同，但不得进入业务页面内容。
- 排序、时区、随机数和生成时间必须固定或显式注入。
- 输入为空、Hash 不符、未知 Block 或不兼容主题时立即失败。

### 15.5 增量构建

V1 先实现可靠全量构建。只有在依赖图、缓存失效和回滚模型稳定后，才引入选择性增量构建，不能为了速度牺牲正确性。

---

## 16. 自动验收门禁

### 16.1 所有站点共用门禁

- 构建输入 Schema 和 Hash 完整。
- 所有内部链接可达。
- 资源不存在 404。
- Title、Description、Canonical 和 H1 符合规则。
- Sitemap 与 Robots 一致。
- JSON-LD 可解析。
- HTML 结构和关键可访问性规则通过。
- 无控制面地址、临时域名和未批准远程依赖。
- 无未知 Block、缺失 Renderer 和未发布引用。
- 目标文件系统不存在大小写、保留名和路径长度冲突。

### 16.2 迁移站额外门禁

- URL 基线 `unresolved=0`。
- 所有保留 URL 在预览真实 HTTP 返回正确状态。
- Redirect 无环、无超长链、目标可达。
- P0 SEO 差异为 0。
- 关键页面内容和媒体数量达到验收阈值。
- 最终差量后无未审查覆盖冲突。

### 16.3 新站额外门禁

- 蓝图必需页面、菜单和站点配置齐全。
- 示例内容没有被误发布，除非明确转为正式内容。
- 新域名、Canonical、Sitemap 和结构化数据一致。
- 不存在占位 Logo、测试联系方式和默认文案。
- CSV/JSON 导入错误已清零或批准排除。

### 16.4 复制站额外门禁

- 未复制 Secret、部署目标、历史 Release 和统计标识。
- 域名、品牌、Canonical、表单收件地址和隐私信息已替换。
- 不存在来源站点 ID 或内部地址泄漏。

---

## 17. 预览、发布与回滚

### 17.1 Preview

- Preview 只读取该 Build 的 Dist 和 Route Manifest。
- Preview 必须自包含，不查询实时数据库。
- 预览入口需要访问控制并默认 `noindex`。
- 必须正确模拟 HTML、Asset、301、410 和 404。

### 17.2 Release 状态机

```text
draft
→ building
→ validating
→ ready
→ deploying
→ active
```

异常状态：

```text
failed
cancelled
superseded
rolled_back
```

### 17.3 发布流程

1. 获取站点环境发布锁。
2. 校验 Release、门禁和批准豁免。
3. 上传不可变版本目录。
4. 校验文件数量、大小和 Hash。
5. 对临时入口执行真实 HTTP 冒烟。
6. 原子切换当前版本指针。
7. 刷新 CDN。
8. 对生产域名执行关键路径检查。
9. 记录 Deployment 和 Audit。

### 17.4 回滚

- 回滚是把活动指针切回历史不可变 Release，不是重新构建旧代码。
- 回滚前检查历史产物仍然完整。
- 回滚后执行生产冒烟和 CDN 刷新。
- 至少保留最近 N 个 Release；N 由存储策略配置。
- 上线前必须完成一次生产等价环境回滚演练。

---

## 18. 管理后台设计

### 18.1 技术原则

管理后台采用 Art Design Pro 作为工程底座：

- Vue 3 + TypeScript 实现业务页面和组合式逻辑。
- Element Plus 提供表格、表单、上传、树和弹窗。
- Pinia 管理客户端状态。
- OpenAPI 或共享契约生成 API 类型。
- 移除或关闭多角色、注册、演示菜单等不需要的底座功能。

控制台主题与生产网站主题完全独立。

### 18.2 信息架构

| 一级菜单 | 核心页面 |
|---|---|
| 工作台 | 站点概览、失败任务、构建状态、线上告警 |
| 网站工厂 | 新建网站向导、复制网站、蓝图目录 |
| 网站 | 基本信息、域名、环境、主题、部署目标 |
| 数据源 | 来源连接、快照、能力探测、凭据引用 |
| 导入与映射 | 导入任务、字段映射、预览、冲突和错误 |
| 内容 | 页面、产品、新闻、分类、品牌、FAQ、下载 |
| 页面设计 | 页面模板、板块实例、排序、可见性和预览 |
| 菜单 | 菜单树、内部链接和多语言项 |
| 媒体 | 原件、衍生图、引用、旧路径和安全状态 |
| URL | 路径注册表、冲突、Redirect、Gone |
| SEO | 元信息、Sitemap、结构化数据、迁移差异 |
| 主题 | 主题版本、预设、Token、兼容性报告 |
| 构建与测试 | 构建快照、日志、产物和门禁报告 |
| 发布 | Release、部署、生产检查和回滚 |
| 系统 | 超管账号、会话、密钥、备份、审计和通知 |

### 18.3 新建网站向导

步骤：

1. 选择创建方式：迁移、迁移改版、全新、复制。
2. 填写站点名称、标识、语言和目标域名。
3. 选择蓝图。
4. 选择主题和主题预设。
5. 填写品牌、Logo、联系方式和基础 SEO。
6. 配置来源或选择手工/文件导入。
7. 预览即将创建的内容类型、页面和菜单。
8. 确认安装并进入站点工作台。

安装必须由后台 Job 执行，失败时可回滚，不留下半安装状态。

### 18.4 页面编辑器

V1 页面编辑器提供：

- 选择允许的页面模板。
- 新增、复制、排序、隐藏和删除板块。
- Schema 驱动字段表单。
- 媒体、内容和内部链接选择器。
- 桌面、平板、手机静态预览。
- 当前草稿与已发布版本对比。

不提供自由拖拽坐标、任意嵌套和在线写代码。

### 18.5 Schema 驱动表单

每个 Content Type、Block、Blueprint 和 Theme Config 提供：

- 数据 Schema。
- UI Schema。
- 默认值。
- 校验消息。
- 版本号和迁移函数。

前端和后端必须使用同一契约验证。生产构建遇到未知版本时必须失败，不能静默忽略。

---

## 19. API 与 CLI 范围

### 19.1 首版 API 模块

```text
/auth
/sites
/site-environments
/blueprints
/themes
/content-types
/contents
/pages
/blocks
/menus
/sources
/source-snapshots
/mapping-profiles
/imports
/media
/routes
/seo
/builds
/validations
/releases
/deployments
/audit-logs
```

所有站点级接口必须显式带 `site_id` 上下文，并通过 Repository 级隔离测试。

### 19.2 首版 CLI

CLI 用于早期纵向切片、自动化和故障恢复，不替代最终后台：

```text
site:create
site:clone
site:inspect
blueprint:list
blueprint:validate
blueprint:install
theme:list
theme:compatibility
source:snapshot
content:import-wxr
content:import-csv
content:import-json
content:add
content:publish
route:compile
build:create
build:validate
preview:start
release:create
release:deploy
release:rollback
```

破坏性或生产操作必须要求站点、环境和确认参数，不允许模糊默认目标。

---

## 20. 动态能力边界

纯静态网站仍可能需要表单、搜索和第三方功能。

### 20.1 首版处理

| 能力 | 方案 |
|---|---|
| 联系/询价表单 | 独立 Form API，静态页只提交请求 |
| 搜索 | 小站构建静态索引；大站接独立搜索服务 |
| 地图 | 受控第三方脚本或静态地图 |
| 视频 | 隐私增强嵌入或自托管 |
| 统计 | 每站独立配置 ID，构建时注入 |
| 多语言 | 模型预留 Locale；完整工作流进入 V1.1 |
| 登录/会员/支付 | V1 不做，必要时对接外部系统 |

### 20.2 Form API 最低要求

- Origin 和站点校验。
- CSRF/滥用防护、速率限制和蜜罐。
- 输入 Schema、长度和附件校验。
- 隐私同意和数据保留策略。
- WebHook/邮件重试及死信队列。
- 接收成功与转发成功分开记录。
- 后台查看状态，但敏感内容最小化保存。

---

## 21. 安全、备份与可观测性

### 21.1 安全基线

- Secret 只保存引用，不写入数据库明文字段、日志或构建产物。
- 采集器执行 SSRF 防护和受控出口。
- HTML 采用白名单清洗，原始内容只保存在受控 Source Snapshot。
- 文件上传执行 MIME、大小、恶意内容和路径安全检查。
- 构建默认断网、受限 CPU/内存/磁盘和超时。
- 管理后台启用 CSP、CSRF、防点击劫持和安全 Cookie。
- 依赖执行许可证、漏洞和锁文件检查。
- 跨站数据访问通过自动测试阻断。

### 21.2 备份对象

- PostgreSQL。
- 原始来源快照。
- 媒体原件。
- Blueprint、Theme 和构建镜像版本。
- Artifact 和 Release Manifest。
- Secret 管理系统配置的独立备份流程。

必须定期进行从空环境恢复演练，只完成“备份成功”不算闭环。

### 21.3 任务可靠性

所有长任务必须具备：

- 持久化状态。
- 心跳和 stale 检测。
- 幂等键。
- 重试策略。
- 取消能力。
- 超时和资源预算。
- 死信记录。
- 结构化进度和错误摘要。

### 21.4 关键指标

- 导入吞吐量、失败率和冲突数。
- 构建时长、排队时长和成功率。
- 门禁 P0/P1 数量。
- 部署成功率和回滚次数。
- 媒体缺失和死链数量。
- Form API 成功率和转发延迟。
- 存储使用量和备份恢复结果。

---

## 22. 测试策略

### 22.1 单元测试

- 内容 Schema 和修订逻辑。
- 蓝图安装/升级规划。
- 字段转换和映射函数。
- URL 规范化、精确键和碰撞键。
- Redirect 图和 Sitemap。
- SEO 合并优先级。
- 媒体类型、安全和路径映射。
- Block Schema 迁移。
- 构建快照 Canonical JSON 和 Hash。

### 22.2 契约测试

- Source Adapter 协议。
- Blueprint Manifest。
- Theme Manifest 和 Render Contract。
- Block Definition 和 Renderer。
- Deployment Adapter。
- API OpenAPI/共享类型。

### 22.3 集成测试

- 数据库约束、事务和站点隔离。
- 同一 Source Snapshot 重跑幂等。
- 导入不自动发布。
- 蓝图安装失败完整回滚。
- 当前/已发布双指针。
- Build Input 冻结后不受在线编辑影响。
- Job 进程中断后识别 stale 并安全恢复。
- Release 发布锁防止并发覆盖。

### 22.4 构建和端到端测试

- WXR → 内容 → 页面 → 静态站。
- CSV/JSON → 新站 → 静态站。
- 老内容 → 新主题 → 原路径输出。
- 后台新增产品/新闻 → 发布 → 重建。
- Theme/Blueprint 不兼容时阻断。
- 预览返回 200/301/410/404 正确。
- 发布、生产冒烟和回滚。

### 22.5 视觉与质量测试

- 两套主题的关键模板截图基线。
- 桌面、平板和手机视口。
- 关键组件可访问性。
- Core Web Vitals 和页面体积预算。
- 图片比例、溢出、字体和交互回归。

### 22.6 必备测试夹具

- 最小 WXR。
- 重复 ID、重复 Slug 和特殊 URL WXR。
- 含短代码和恶意 HTML 的 WXR。
- 缺失媒体和错误 MIME。
- CSV/JSON 正常、缺字段、重复唯一键和类型错误样本。
- Redirect 环、链和路径碰撞。
- 两个蓝图版本及升级样本。
- 两个主题及缺失 Renderer 的失败样本。

---

## 23. V1 产品范围

### 23.1 P0 必须交付

- 单一超级管理员登录、MFA、会话和审计。
- 多站点和 preview/staging/production 环境。
- `corporate-basic` 站点蓝图。
- 第一套正式主题和公共组件协议。
- WXR、Sitemap、已解包媒体、CSV、JSON 和手工内容输入。
- 统一内容、修订、页面、板块、菜单和媒体模型。
- URL 注册表、SEO 三方对比和门禁。
- 冻结构建输入、Astro 静态构建和自包含 Preview。
- Nginx/SSH 或 OSS/CDN 中至少一个正式部署适配器。
- Release、原子发布、生产检查和回滚。
- Vue 3 管理后台核心业务页面。
- 三类真实样板验收。

### 23.2 P1 建议随 V1 完成

- 第二套主题。
- `catalog-pro` 蓝图。
- WordPress REST 差量输入。
- HTML 抓取和 Playwright 补扫。
- 复制建站。
- Form API。
- 主题 Token 后台编辑。
- 视觉回归和性能预算。

### 23.3 V1.1

- 完整多语言和 hreflang 工作流。
- 定时发布和批量操作。
- WordPress SQL 深度适配。
- ZIP 安全解包。
- 图片 AVIF/WebP 衍生和智能裁切。
- 选择性增量构建。
- WebHook 与外部业务系统同步。
- 搜索服务接入。
- 更多蓝图、主题和适配器。

---

## 24. 项目实施策略

### 24.1 实施原则

1. 先证明贯穿全链路的最小网站工厂，不先堆完整后台页面。
2. 同时验证迁移站和全新站，防止数据模型只服务 WordPress。
3. 先建立契约和冻结输入，再开发复杂主题和发布自动化。
4. 先可靠全量构建，再优化增量构建。
5. 所有阶段必须有可运行产物和明确 Gate，不以“代码基本完成”作为完成标准。
6. 旧 `cms` 只按白名单复用，移植前先写契约测试。

### 24.2 第一纵向切片必须扩大为“双入口切片”

原 V2 只验证 WXR 迁移，容易把平台做成迁移工具。修正后的第一切片同时验证：

**路径 A：迁移入口**

```text
hesupipe WXR/Sitemap/媒体
→ Source Snapshot
→ 标准内容
→ URL/SEO
→ pilot-minimal
→ 静态构建
→ Gate
→ Preview
```

**路径 B：新站入口**

```text
site:create
→ corporate-basic 蓝图
→ corporate-modern 主题
→ CSV/JSON 产品和新闻
→ 手工新增页面
→ 静态构建
→ Gate
→ Preview
```

两条路径必须汇合到同一套标准内容、页面、路由、构建和门禁模型，不允许维护两套构建器。

### 24.3 切片阶段暂不实现完整后台

第一切片先用 CLI 和最小内部 API 证明模型正确，再开发 Art Design Pro 管理后台。否则容易在模型不稳定时投入大量表格和表单页面。

CLI 不是临时脚本，必须调用正式 Application Service，并被后续 HTTP Controller 和后台复用。

---

## 25. 分阶段实施计划

以下按 4–5 人核心团队估算约 24–28 周；单开发者 + AI 辅助通常需要约 36–48 周。真实周期必须在阶段 0 根据试点数据和团队能力重新校准。

### 阶段 0：范围冻结与资产基线（第 1–2 周）

任务：

- 确定一个 WordPress 迁移试点和一个全新站业务样板。
- 获取经授权的 WXR、媒体、Sitemap、服务器规则和字段样本。
- 固定旧 `cms` 代码 Commit 并运行现有测试。
- 建立可复用资产白名单和禁止复制清单。
- 锁定 ADR：ORM、Schema、对象存储、构建沙箱、部署目标。
- 建立 Git、CI、依赖和敏感数据规则。

交付物：

- 试点数据清单。
- URL/SEO 初始基线。
- 蓝图业务需求。
- ADR 集合。
- 风险登记和校准排期。

Gate M0：输入合法可用，两个切片入口范围明确，所有 P0 决策有负责人和截止时间。

### 阶段 1：工程底座与领域契约（第 3–5 周）

任务：

- 初始化 pnpm Monorepo、TypeScript Strict、Lint、Test 和 CI。
- 建立 PostgreSQL、Drizzle Migration 和数据库测试。
- 定义 Site、Revision、Source、Blueprint、Theme、Page、Block、Route、Build 契约。
- 建立数据库持久化 Job Runner、心跳和 stale 状态。
- 建立本地文件 Storage Adapter。
- 完成第一批契约测试和安全测试框架。

交付物：

- 可运行 CLI/API Application Context。
- 正式数据库迁移。
- 契约包。
- Job 和 Artifact 基础设施。

Gate M1：空库可一键迁移；核心约束落数据库；任务中断可识别；测试在 CI 稳定通过。

### 阶段 2：蓝图与全新建站最小链路（第 6–8 周）

任务：

- 实现 Blueprint Manifest、校验、安装和回滚。
- 实现 `corporate-basic`。
- 实现内容类型、页面、模板、板块和菜单安装。
- 实现 `site:create`、`blueprint:list/install`。
- 实现 CSV/JSON 导入、映射预览和幂等。
- 实现手工 `content:add/publish`。
- 建立新站默认 URL/SEO 规则。

交付物：

- 无旧站数据也能创建完整数据库站点。
- 样例 CSV/JSON 成功导入产品和新闻。
- 蓝图安装失败可完整回滚。

Gate M2：新站入口不包含任何 WordPress 假设；同一蓝图可安装到两个站点且数据隔离。

### 阶段 3：WordPress 迁移与映射链路（第 9–12 周）

任务：

- Source Connection/Snapshot 和 Hash。
- 流式 WXR Parser 和 WordPress Adapter。
- Sitemap、媒体目录和来源记录。
- HTML 清洗、短代码报告和字段映射。
- current/published 双指针和导入幂等。
- 导入报告、冲突和人工覆盖保护。
- URL 注册表和旧路径证据。

交付物：

- 真实试点可重复导入。
- 第二次导入同快照不产生重复修订。
- 导入后不会自动发布。
- 不支持对象有明确清单和原因。

Gate M3：试点范围内所有对象有 created/updated/skipped/conflict/failed 明确结果；URL `unresolved` 有可执行清理计划。

### 阶段 4：主题、板块和静态构建（第 13–16 周）

任务：

- Theme Manifest、Render Contract 和公共组件包。
- `pilot-minimal` 和 `corporate-modern` 两套主题或预设。
- Block Schema、Renderer 和版本迁移。
- 冻结 Render Snapshot。
- Astro 构建、Route/Asset/Build Manifest。
- 自包含 Preview Server。
- 相同输入可复现构建。

交付物：

- 迁移站和新站共用一个构建管线。
- 同一内容能被两套主题渲染。
- 主题缺少 Renderer 时明确阻断。

Gate M4：禁止数据库、Seed 和网络进入构建；两次构建业务 Hash 一致；两个样板均可 HTTP 预览。

### 阶段 5：管理后台核心闭环（第 17–20 周）

任务：

- 接入 Art Design Pro，清理多角色和演示功能。
- 超管登录、MFA、会话和审计。
- 新建网站向导。
- 站点、蓝图、主题和环境页面。
- 内容、页面、板块、菜单和媒体管理。
- 导入、映射、冲突和报告页面。
- URL、SEO、构建和预览页面。

交付物：

- 超管不依赖 CLI 完成日常建站和内容运营。
- Schema 驱动表单复用 Content/Block/Theme 配置。

Gate M5：超管通过 UI 完成“创建新站 → 导入产品 → 新增新闻 → 调整页面 → 构建预览”。

### 阶段 6：SEO 门禁、Release 和正式部署（第 21–24 周）

任务：

- SEO 三方差异和自动门禁。
- Redirect 图、Sitemap、死链和媒体检查。
- Release、发布锁、不可变版本和回滚。
- 实现一个正式 Deployment Adapter。
- 生产临时入口和 HTTP 冒烟。
- 备份、恢复、日志、指标和告警。

交付物：

- 可发布、可回滚的正式 Release。
- JSON/HTML 验收报告。
- 恢复和回滚演练记录。

Gate M6：全部 P0 清零；P1 均修复或正式豁免；发布与回滚演练通过。

### 阶段 7：三类样板验收和稳定期（第 25–28 周）

任务：

- 样板 A：WordPress 原路径迁移。
- 样板 B：老内容进入新主题。
- 样板 C：蓝图 + CSV/JSON + 手工内容的新站。
- 最终差量、切站和生产监控。
- 修复性能、可访问性、视觉和运维问题。
- 整理运行手册和后续蓝图/主题开发指南。

Gate M7：三类样板全部通过独立验收；至少一个真实生产发布；完成一次真实或生产等价回滚。

---

## 26. 三类样板的验收标准

### 26.1 样板 A：旧站原路径迁移

- WXR 范围内内容、分类和媒体全部有明确结果。
- 当前已知 URL 全部有处置，`unresolved=0`。
- 核心旧路径真实 HTTP 状态正确。
- P0 SEO 差异为 0。
- 导入不覆盖人工修改，不自动发布。
- 控制面关闭后静态站仍正常运行。

### 26.2 样板 B：老内容换新主题

- 不复制迁移适配器到主题。
- 标准内容直接进入新模板和板块。
- 主题兼容报告列出缺失字段和 Renderer。
- 旧路径保持或有批准的一对一跳转。
- 新视觉下内容、SEO 和内部链接完整。
- 可切回前一主题 Release。

### 26.3 样板 C：全新站

- 没有旧站、WXR 和历史 URL 也能创建。
- `corporate-basic` 自动建立内容类型、页面、菜单和 SEO 默认值。
- CSV/JSON 导入产品，后台手工新增新闻和页面。
- 示例数据不误入生产。
- 选择主题后可生成完整静态站并发布。

---

## 27. Definition of Done

一个功能只有同时满足以下条件才算完成：

- 产品验收条件清晰并通过。
- 数据库约束和迁移存在。
- API/CLI/UI 使用同一 Application Service。
- 正常、异常、权限和跨站隔离测试通过。
- 日志中无 Secret 和敏感原始数据。
- 长任务可取消、重试、超时和恢复。
- 有操作说明、错误说明和必要运行手册。
- 不依赖本地 Seed、隐式环境变量或开发者电脑状态。
- CI 中 lint、typecheck、unit、integration 和相关 e2e 通过。
- 关键变更有 ADR 或更新本文档。

站点达到可发布状态还必须满足：

- Build Input 已冻结并有 Hash。
- 全部门禁通过或有有效豁免。
- Preview 已人工确认。
- Release 和部署目标明确。
- 回滚目标存在且完整。
- 生产冒烟检查清单已准备。

---

## 28. 关键风险与控制

| 风险 | 后果 | 控制措施 |
|---|---|---|
| 只围绕 WXR 建模 | 新站功能被迫伪装成迁移 | 第一切片同时实现新站入口 |
| 把主题当蓝图 | 换主题导致内容结构混乱 | 蓝图、模板、主题独立版本化 |
| 任意 JSON 泛滥 | 后台、验证和升级失控 | Schema、版本和数据库关键约束 |
| 导入自动发布 | 未审查内容上线 | current/published 双指针 |
| Seed fallback | 发布演示数据 | 生产构建禁止 Seed，输入为空即失败 |
| 旧路径处理错误 | SEO 和外链损失 | URL 注册表、真实 HTTP 门禁 |
| 同一站并发发布 | 版本覆盖和混合产物 | 发布锁和不可变版本目录 |
| 主题重复业务逻辑 | 后续主题成本失控 | 四层复用和契约测试 |
| 页面编辑器过度自由 | 内容不可迁移、样式不可控 | 有限插槽和结构化板块 |
| 旧项目直接复制 | 把安全和一致性缺陷带入新系统 | 白名单移植、先测试后复用 |
| 媒体下载 SSRF/恶意文件 | 内网泄露或执行风险 | 出口限制、MIME 检测、配额和清洗 |
| 单超管账号丢失 | 平台无法操作 | MFA、恢复码、离线恢复流程和备份 |
| 工期被主题定制吞噬 | 平台能力无法闭环 | 每站专属需求进入扩展包并控制范围 |
| 追求增量构建过早 | 缓存错误发布旧内容 | V1 先可靠全量构建 |

---

## 29. 团队职责建议

| 职责 | 主要工作 |
|---|---|
| 产品/项目负责人 | 范围、试点、验收、变更控制 |
| 后端/平台工程 | 领域模型、API、Job、构建和发布 |
| 前端工程 | Art Design Pro 后台和 Schema 表单 |
| 主题工程 | Astro 主题、板块和公共展示组件 |
| 数据/迁移工程 | 来源盘点、适配器、映射和差异处理 |
| QA/运维 | 门禁、E2E、部署、监控和恢复演练 |
| 设计 | 主题规范、响应式和组件视觉 |

单开发者 + AI 模式下，上述职责仍然存在，只是由同一人分阶段承担。应严格控制并行工作，每个阶段先完成 Gate 再进入下一阶段。

---

## 30. 项目治理与变更控制

### 30.1 决策记录

以下变更必须写 ADR：

- 数据模型核心身份和修订语义。
- 蓝图、主题和 Block 协议。
- 构建输入和可复现策略。
- 路由、Redirect 和部署映射。
- 安全边界和 Secret 管理。
- ORM、队列、存储和部署适配器变更。

### 30.2 范围变更

新增需求按以下分类：

- P0：不做就不能安全上线。
- P1：明显影响首版业务闭环。
- P2：可进入 V1.1。
- P3：长期候选。

任何新增主题专属功能都要先判断：

1. 是否是公共数据或业务逻辑。
2. 是否应成为通用 Block。
3. 是否只属于主题展示。
4. 是否应作为站点扩展包，而不是进入核心平台。

### 30.3 文档同步

实现与本文发生差异时，不能只改代码。必须更新本文或 ADR，并在发布说明中写出兼容影响和迁移方案。

---

## 31. 立即执行的前两周计划

### 第 1–2 天：冻结事实基线

- 固定 `D:\project\cms` 可参考 Commit。
- 在干净环境运行现有 lint、typecheck、unit、e2e 和 build。
- 记录通过项、失败项和无法运行项。
- 确认 `D:\project\cms-one` 为新架构主仓库。

### 第 3–4 天：准备双入口样本

- 准备脱敏最小 WXR、Sitemap 和媒体样本。
- 准备新站 products.csv、news.json 和品牌配置。
- 定义两个样本预期页面、菜单、URL 和 SEO。

### 第 5–6 天：冻结核心契约

- Site、Source Snapshot、Content Entry/Revision。
- Blueprint、Page Template、Block Definition/Instance。
- Route、SEO、Build Input 和 Theme Manifest。
- 编写 ADR 和契约测试样例。

### 第 7–8 天：建立工程骨架

- 初始化 Workspace、CI 和 TypeScript Strict。
- 建立 PostgreSQL/Drizzle Migration。
- 建立 API Standalone Context、CLI 和持久化 Job。
- 建立 Artifact 和本地 Storage 目录约定。

### 第 9–10 天：做最小双入口证明

- `site:create` 安装最小蓝图。
- CSV 导入 2–3 个产品。
- WXR 导入 2–3 条内容。
- 两边都转换为同一内容模型。
- 生成最小 Render Snapshot。
- 用同一主题输出静态 HTML。

两周结束必须回答：

1. 新站流程是否完全不依赖 WordPress 字段。
2. 迁移内容和新内容是否真正进入同一模型。
3. 蓝图、主题和页面模板边界是否清晰。
4. 构建是否只读取冻结文件。
5. 现有 `cms` 资产哪些能低风险复用。

如果以上任一问题答案是否定，不进入完整后台开发。

---

## 32. 立项前必须确认的事项

- 第一迁移试点的真实数据授权和范围。
- 第一全新站的业务类型、内容字段和设计目标。
- 首个正式部署目标是 Nginx/SSH 还是 OSS/CDN。
- 是否要求首版公网开放管理后台；若是，MFA 和安全基线进入 P0。
- 表单、搜索、多语言和第三方统计的首版边界。
- 两套主题是完全独立设计还是一个主题的两个预设。
- 旧 URL 可允许的 Redirect 比例和 SEO 豁免审批方式。
- 迁移完成后的 WordPress 是否下线、保留只读或继续短期差量。
- 团队配置和可接受的首版周期。

这些事项影响排期，但不改变本文的核心架构方向。

---

## 33. 最终交付物

### 33.1 软件

- SiteForge 超级管理员后台。
- NestJS API、CLI 和 Worker。
- PostgreSQL Schema 和迁移。
- Blueprint SDK、Theme Runtime、Import SDK、Deployment SDK。
- WordPress WXR、CSV、JSON、Sitemap 和媒体输入能力。
- `corporate-basic` 蓝图。
- 至少两套可验证主题或一套主题加一套明显差异化主题。
- Astro 静态构建、Preview、Gate 和 Release。
- 至少一个生产部署适配器。
- Form API（若列为首版试点 P0）。

### 33.2 文档

- 架构和 ADR。
- Blueprint、Theme、Block 和 Adapter 开发规范。
- WordPress 迁移手册。
- 新站创建和内容运营手册。
- 发布、回滚、备份和恢复手册。
- 安全和 Secret 管理手册。
- 测试报告、URL/SEO 报告和试点验收报告。

### 33.3 样板

- 一个原路径 WordPress 静态迁移站。
- 一个老内容换新主题的改版站。
- 一个由蓝图和新数据生成的全新站。

---

## 34. 最终判断

按照本文实施后，SiteForge 将具备以下完整能力：

```text
它既能把旧网站搬过来，
也能把旧内容装进全新设计，
还能完全不依赖旧站，从蓝图和新数据创建新网站；
随后继续在同一个后台维护内容，
通过统一的静态构建、SEO 门禁、发布和回滚体系长期运营。
```

这才是目标中的“网站生产工厂”。

原纵向切片 V2 的迁移、路由、构建和门禁设计可以保留，但必须按本文补入站点蓝图、全新建站、CSV/JSON 映射、页面/板块实例和双入口验收。若仍只完成 WXR → 静态站，最终只能得到优秀的迁移工具，不能得到完整的网站工厂。