cms-website/SiteForge_完整项目计划方案_V3.0.md

# SiteForge 多站点静态迁移与内容发布平台

> 完整项目计划方案 V3.0  
> 编制日期：2026-10-20  
> 文档状态：立项、研发与试点执行基线  
> 适用范围：WordPress 为主，兼容 HTML、PHP/MySQL、自研 CMS、API 与标准数据文件  
> 设计原则：单一超级管理员、组件化复用、每站独立设计、纯静态生产、URL/SEO 优先、可审计发布与回滚

---

## 0. 执行摘要

SiteForge 是一套面向多网站运营的迁移与发布控制平台。它负责扫描旧站、导入内容、保留 URL 和 SEO、重新设计主题、生成静态网站，并在后续持续管理产品、新闻、页面和媒体。

平台不是另一个 WordPress，也不是通用拖拽建站器。它的核心价值是把多次网站迁移中重复发生的工作标准化：

```text
旧站盘点
→ 全量导入
→ 数据标准化
→ URL/SEO 冻结
→ 独立主题实现
→ 差量同步
→ 静态构建
→ 自动验收
→ 发布确认
→ 原子切换
→ 监测与回滚
```

生产网站输出独立的 HTML、CSS、JavaScript 和媒体文件，不实时依赖 SiteForge 数据库。表单、搜索等必须动态运行的能力通过独立 API 或服务提供。

V1 采用以下核心技术方向：

- Art Design Pro 管理后台底座（Vue 3 + TypeScript + Element Plus）。
- NestJS 模块化单体 API。
- PostgreSQL 数据库。
- Redis + BullMQ 任务队列。
- TypeScript 抓取与 Playwright 渲染兜底。
- Astro 静态构建。
- S3 兼容对象存储。
- Docker Compose 部署控制面。
- Nginx/SSH 和对象存储/CDN 两类发布适配器。

V1 只设置一种系统角色 `super_admin`，默认由一个超级管理员账号管理全部功能，不建设 RBAC、成员和复杂审批系统。高风险操作通过二次确认、MFA、不可变日志和可回滚发布降低风险。

---

## 1. 建设背景与目标

### 1.1 当前问题

- 多个网站主要使用 WordPress，也存在其他 CMS、PHP、自研系统或纯 HTML 网站。
- 每次迁移都需要重新处理内容、URL、SEO、图片、服务器规则和发布流程。
- 网站之间设计差异大，无法直接使用同一套页面模板。
- 旧站积累了历史路径、外链和搜索流量，不能随意改变 URL。
- 新站希望保持纯静态，同时仍需要持续新增产品、新闻和页面。
- 现有迁移通常依赖人工脚本，缺少可重复、可审计和可回滚的标准流程。

### 1.2 建设目标

1. 一个后台集中管理多个网站。
2. 优先深度支持 WordPress，通过适配器兼容其他来源。
3. 精确保留旧 URL、状态码、跳转和 SEO 行为。
4. 每个站点可使用完全独立的主题和页面设计。
5. 使用组件化、板块化机制提高开发复用率。
6. 后台可以长期维护产品、新闻、页面、菜单和媒体。
7. 生产站以纯静态方式部署，控制面故障不影响线上访问。
8. 每次构建、验收、发布和回滚都有完整记录。
9. 完成两个差异化试点后，新站主要投入集中在来源映射、异常处理和主题设计。

### 1.3 成功标准

| 维度 | V1 成功标准 |
|---|---|
| URL | 基线 URL 100% 有明确处置结果或批准例外 |
| SEO | 关键 SEO 属性有来源快照、目标值和差异报告 |
| 内容 | 核心页面、产品、文章、分类、媒体通过业务抽检 |
| 设计 | 至少两套视觉差异明显的独立主题运行在同一平台 |
| 发布 | 构建可追溯、发布原子化、回滚经过实际演练 |
| 稳定性 | SiteForge 短时离线不影响已经发布的生产站点 |
| 运营 | 超级管理员可无代码新增产品、新闻和普通页面 |
| 复用 | 第二个站点复用迁移、URL、SEO、构建和发布链路 |

### 1.4 不做承诺

- 仅凭公开 URL 自动发现后台未公开内容和私有字段。
- 任意复杂页面构建器内容零人工转换成理想的新设计。
- 电商交易、支付、订单和会员系统完全静态化。
- 网站迁移后搜索排名绝对不波动。
- V1 支持所有 CMS、任意主题切换和通用低代码设计。

---

## 2. 产品范围与版本边界

### 2.1 V1 必须交付

| 能力 | 是否阻塞试点 | 验收方式 |
|---|---:|---|
| 多站点与环境管理 | 是 | 至少两个站点隔离运行 |
| 单一超级管理员 | 是 | 登录、MFA、恢复、会话撤销可用 |
| WordPress REST/WXR/SQL/uploads 导入 | 是 | 真实试点数据导入通过 |
| Sitemap/HTML/Playwright 扫描 | 是 | 输出可审计 URL 与页面清单 |
| 原始快照与差量同步 | 是 | 重跑不重复，切站前完成最终增量 |
| 统一内容与内容修订 | 是 | 产品、新闻、页面可编辑和回滚 |
| URL 注册表与路由编译 | 是 | 目标部署环境真实 HTTP 验证 |
| SEO 快照与差异报告 | 是 | P0/P1 门禁有效 |
| 媒体迁移与旧路径保持 | 是 | 关键媒体无未处理 404 |
| 主题/模板/板块协议 | 是 | 两个差异化主题使用同一协议 |
| 组件化公共包 | 是 | 两个主题复用数据、SEO、媒体和交互逻辑 |
| Astro 全量静态构建 | 是 | 产物可独立部署 |
| 预览、验收、发布、回滚 | 是 | 完成一次上线及回滚演练 |
| Nginx/SSH 发布 | 是 | 试点目标发布通过 |
| S3/OSS + CDN 发布 | 二选一 | 如作为试点目标则验收 |
| 表单基础服务 | 按站点 | 提交、重试、隐私和反垃圾通过 |
| 备份、监控和操作日志 | 是 | 完成恢复演练与告警测试 |

### 2.2 V1.1 建议能力

- 多语言内容和 hreflang 完整工作流。
- 定时发布和批量发布。
- 简单站内搜索或独立搜索服务接入。
- 图片 WebP/AVIF 衍生和更精细的媒体优化。
- PHP/MySQL、Drupal、Joomla 等第二批深度适配器。
- 页面依赖图驱动的选择性重建。
- WebHook 和外部业务系统联动。

### 2.3 暂不建设

- 自由画布式低代码编辑器。
- 无限层级嵌套板块。
- 复杂商城、订单、支付和会员中心。
- 多角色、成员、细粒度 RBAC 和站内审批流。
- 跨组织 SaaS 计费和主题市场。
- 自动发布未经人工确认的 AI 生成或迁移结果。
- Kubernetes、多区域主动容灾和复杂微服务拆分。

---

## 3. 总体架构

```mermaid
flowchart TB
  subgraph Sources[旧站与数据来源]
    WP[WordPress]
    WEB[HTML / JS 网站]
    DB[PHP / MySQL / 自研 CMS]
    FILE[WXR / CSV / JSON / XML / ZIP]
    LOG[访问日志 / GSC / GA4]
  end

  subgraph Control[SiteForge 控制面]
    ADMIN[超级管理员后台]
    API[模块化 API]
    JOB[任务调度与 Worker]
    RAW[原始快照]
    CDM[统一内容库]
    ROUTE[URL / SEO 引擎]
    THEME[主题 / 板块 / 组件]
    BUILD[隔离静态构建]
    QA[自动验收门禁]
    RELEASE[Release 与部署]
  end

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

  Sources --> JOB
  ADMIN --> API
  API --> JOB
  JOB --> RAW
  RAW --> CDM
  CDM --> ROUTE
  ROUTE --> THEME
  THEME --> BUILD
  BUILD --> QA
  QA --> RELEASE
  RELEASE --> NGINX
  RELEASE --> CDN
  NGINX -.按需调用.-> DYNAMIC
  CDN -.按需调用.-> DYNAMIC
```

### 3.1 控制面与生产面

控制面包含后台、API、数据库、队列、采集、内容、构建和发布。生产面只包含不可变静态文件、部署规则和明确的动态服务。

生产网页不得在请求时读取 SiteForge 数据库，也不得依赖 WordPress/PHP 运行时。

### 3.2 模块化单体

V1 使用模块化单体 API 与独立 Worker，不拆分大量微服务：

```text
API：认证、站点、内容、URL、SEO、主题、任务、发布
Worker：扫描、导入、媒体、构建、验证、部署
共享契约：Schema、DTO、事件、状态机
```

### 3.3 四个发布输入

```text
Release = ContentSnapshot
        + RouteSeoSnapshot
        + ThemeBuildSnapshot
        + SiteEnvironmentSnapshot
```

发布后的 release 必须能准确回答：用了哪些内容、路由、SEO、媒体、主题代码、依赖、环境配置和构建镜像。

---

## 4. 超级管理员与操作流程

### 4.1 唯一系统角色

V1 只定义 `super_admin` 一种角色，管理：

- 全部网站和环境。
- 数据源、扫描、导入和字段映射。
- 产品、新闻、页面、分类、菜单和媒体。
- URL、SEO、Sitemap 和跳转。
- 主题、模板、板块和组件版本。
- 预览、构建、发布、回滚和备份。
- 系统配置、密钥引用和操作日志。

默认只启用一个日常超级管理员账号，不建设团队成员和权限分配。系统需提供：

- 强密码策略。
- MFA。
- 一次性恢复码。
- 登录失败限流。
- 会话列表和远程撤销。
- 登录异常提醒。
- 高风险操作重新输入密码/MFA。
- 操作日志记录账号、会话、IP、时间、对象和结果。

### 4.2 简化内容状态

不建设复杂审批流：

```text
draft → ready_to_publish → publishing → published → archived
```

外部内容、SEO或设计人员的确认结果可以作为备注和附件保存，由超级管理员执行最终发布确认。

### 4.3 高风险操作

以下操作必须二次确认：

- 生产发布。
- 生产回滚。
- 删除发布中的内容或 URL。
- 清空导入批次。
- 删除媒体原件。
- 更换生产域名或部署目标。
- 修改密钥、备份和安全配置。

---

## 5. 端到端迁移与切站流程

### 5.1 完整流程

```mermaid
flowchart TD
  A[创建站点与授权确认] --> B[连接数据源]
  B --> C[URL/SEO/功能全量盘点]
  C --> D[第一次全量导入]
  D --> E[标准化与字段映射]
  E --> F[主题和板块实现]
  F --> G[预览与多轮修复]
  G --> H[迁移期间差量同步]
  H --> I[上线前内容冻结]
  I --> J[最终差量导入与全站重扫]
  J --> K[锁定发布快照]
  K --> L[静态构建与自动验收]
  L -->|失败| E
  L -->|通过| M[超级管理员发布确认]
  M --> N[原子发布与缓存刷新]
  N --> O[上线监测与保护期]
  O -->|严重异常| P[回滚]
  O -->|稳定| Q[关闭旧站写入并归档]
```

### 5.2 差量同步

差量判断综合使用：

- 来源稳定 ID。
- WordPress `modified_gmt` 等更新时间。
- 内容和元数据 checksum。
- 媒体哈希。
- 页面最终 HTML/SEO checksum。
- 删除、隐藏和状态变化标记。

每次同步输出：新增、更新、删除、无变化、冲突和失败。人工修改过的目标内容不得被来源更新静默覆盖，必须进入冲突队列。

### 5.3 切站时间线建议

```text
T-7天：完整彩排，验证发布和回滚
T-3天：缩短 DNS TTL，确认旧站备份
T-1天：执行倒数第二次差量同步
T-2小时：冻结旧站内容写入
T-90分钟：最终差量导入和 URL/SEO 重扫
T-45分钟：锁定快照、构建、门禁检查
T-15分钟：发布确认和临时入口冒烟
T时刻：切换生产并刷新缓存
T+2小时：高频关键 URL、表单和日志监测
T+7天/约定期：确认稳定后归档旧环境
```

实际时间按网站规模调整。

### 5.4 回滚触发条件

- 关键 URL 大量 404/500。
- Canonical/Robots 全站错误。
- 核心页面内容或媒体系统性缺失。
- 表单等关键业务无法使用。
- 发布规则与静态文件版本不一致。
- 性能或可用性达到站点约定的严重阈值。

---

## 6. URL 全集与扫描系统

### 6.1 URL 发现来源

不能只依赖 Sitemap 和站内爬虫。基线合并以下来源：

1. Sitemap 和 Sitemap Index。
2. 首页、导航、分类、分页和全部站内链接。
3. WordPress数据库中的公开内容、附件和历史 permalink。
4. REST API/WXR/其他结构化导出。
5. Nginx/Apache/CDN访问日志中的落地 URL。
6. Search Console 页面数据。
7. GA4/其他分析工具的历史着陆页。
8. 现有 Nginx、Apache、CDN 重定向规则。
9. 业务提供的广告、邮件、二维码和重要外链。
10. 已知媒体、PDF和站点验证文件。

### 6.2 URL 基线状态

每条 URL 标记：

```text
discovered
verified_active
verified_redirect
verified_not_found
requires_auth
unknown
excluded_with_reason
```

报告必须区分“确认遗漏”和“无法证明是否存在”。所谓 100% URL 处置率，是指已确认的 URL 基线全部有明确处理，而不是声称发现了互联网上所有历史地址。

### 6.3 扫描策略

- 明确允许的域名、子域名、协议和端口。
- HTTP 抓取优先，JS 页面进入 Playwright 队列。
- 每站设置并发、速率、深度、最大页面数和文件大小。
- 保留原始 URL，同时生成规范化辅助键。
- 不粗暴合并大小写、尾斜杠、查询参数和编码形式。
- 任务支持断点续跑、重试、取消和恢复。
- 保存响应头、状态码、跳转链、原始 HTML、渲染 DOM 和 checksum。

### 6.4 URL 注册表

```text
host
original_path
normalized_lookup_key
query_policy
source_status
target_status
route_kind
target_content_id
target_file
redirect_location
indexable
priority
source_snapshot_id
verification_status
```

`route_kind`：`html`、`redirect`、`asset`、`gone`、`dynamic`。

### 6.5 路径兼容

必须区分：

- `/about`、`/about/`、`/about.html`
- `/Article/`、`/article/`
- Unicode 原文与不同百分号编码
- `/news/page/2/`、标签和归档页
- `?p=123`、`?page_id=123`
- `.php` 历史入口
- 媒体、PDF、字体和验证文件

系统内部路径采用 UTF-8，并定义唯一的编码/解码规则。发布前检查 Windows 与 Linux 文件系统的大小写、保留名称和 Unicode 规范化冲突。

---

## 7. 部署能力矩阵与路由编译

### 7.1 部署适配器契约

每种部署目标声明能力：

```ts
interface DeploymentCapabilities {
  exactStatusCodes: boolean;
  redirects: boolean;
  queryRouting: boolean;
  caseSensitivePaths: boolean;
  customHeaders: boolean;
  custom404: boolean;
  gone410: boolean;
  atomicSwitch: boolean;
  rollback: boolean;
  cachePurge: boolean;
  edgeLogic: boolean;
}
```

### 7.2 路由编译

统一 `route-manifest` 根据目标平台编译成：

- Nginx location/rewrite/map 规则。
- Apache规则（后续按需）。
- 对象存储静态文件结构。
- CDN Redirect/Rewrite/Edge 规则。
- 自定义错误页和响应头配置。

若部署目标无法实现某个关键 URL 的状态码或查询路由，预检必须阻止发布，并给出替代建议。

### 7.3 基础输出方式

- `/about-us/` → `about-us/index.html`
- `/news/a.html` → `news/a.html`
- `.php` 页面 → 服务器规则映射到静态文件
- 查询参数语义路由 → Edge规则或独立服务
- 历史媒体路径 → 原样文件或精确映射

### 7.4 部署能力验收

不能只检查文件是否存在，必须在与生产一致的 Web Server/CDN 预览环境中逐 URL 发起 HTTP 请求，验证状态码、Location、Content-Type、缓存头和页面内容。

---

## 8. 来源适配器与数据导入

### 8.1 可信度顺序

```text
数据库/平台 API > 标准导出文件 > 页面 HTML/渲染 DOM
```

HTML 同时用于验证最终对外页面，因此即使拥有数据库也应抓取旧站 HTML Head 和正文摘要进行交叉核对。

### 8.2 适配器接口

```ts
export interface SourceAdapter {
  readonly id: string;
  detect(ctx: ScanContext): Promise<DetectionResult>;
  probe(ctx: ImportContext): Promise<CapabilityReport>;
  discover(ctx: ImportContext): AsyncIterable<SourceResourceRef>;
  extract(ref: SourceResourceRef, ctx: ImportContext): Promise<SourceRecord>;
  normalize(record: SourceRecord, ctx: MappingContext): Promise<NormalizedRecord[]>;
  collectAssets?(ctx: ImportContext): AsyncIterable<SourceAsset>;
  extractSiteSettings?(ctx: ImportContext): Promise<SourceSiteSettings>;
  diff?(from: SnapshotRef, to: SnapshotRef): Promise<SourceDiff>;
  verify?(ctx: ImportContext): Promise<AdapterVerification>;
}
```

统一错误码：

```text
AUTH_REQUIRED
RATE_LIMITED
PRIVATE_CONTENT
UNSUPPORTED_FIELD
UNSUPPORTED_DYNAMIC_FEATURE
MISSING_ASSET
PARSE_FAILURE
SOURCE_CHANGED
SECURITY_REJECTED
```

### 8.3 WordPress 首版范围

- `wp_posts`、`wp_postmeta`。
- 分类、标签及关联。
- 页面、文章、公开 CPT。
- 菜单、附件、特色图片。
- WXR 内容和 postmeta。
- REST API 公开内容。
- `wp-content/uploads`。
- Yoast SEO、Rank Math 常见字段，并与最终 HTML Head 比对。
- Gutenberg 基础块。
- ACF 原始字段保留和人工映射。
- WooCommerce 商品基础信息、属性、变体和图库按试点评估。

专项适配：Elementor、WPBakery、多语言插件、自定义表、复杂短代码、主题私有字段。

### 8.4 导入幂等与冲突

源记录唯一键：

```text
site_id + source_connection_id + source_type + source_id + locale
```

使用 checksum 区分新增、变化和未变化。人工编辑过的字段保存 `override` 标记；再次导入时保留来源新值和人工值，产生冲突，不自动覆盖。

### 8.5 原始快照

保存：

- 原始文件或响应位置。
- 来源连接与适配器版本。
- 提取时间和时区。
- 源 ID、URL 和状态。
- checksum。
- 导入批次。
- 清洗、映射和异常日志。

---

## 9. 统一数据模型

### 9.1 模型原则

- PostgreSQL 保存关系和业务状态。
- JSONB 保存扩展字段，但核心关系使用独立表。
- 对象存储保存原始快照、媒体、报告和 release。
- 所有业务实体包含 `site_id`。
- 发布内容采用不可变 revision。
- 跨实体引用可追踪，删除有影响分析。

### 9.2 核心实体

| 领域 | 实体 |
|---|---|
| 管理员 | admin_user、admin_session、recovery_code |
| 站点 | site、domain、environment、site_setting |
| 来源 | source_connection、import_job、source_snapshot、source_record |
| 内容 | content_entry、content_revision、page_block |
| 引用 | content_reference、global_fragment_usage |
| 分类 | taxonomy、term、content_term |
| 媒体 | media_asset、media_variant、media_usage |
| 导航 | menu、menu_item |
| 路由 | route_registry、redirect_rule、route_snapshot |
| SEO | seo_record、seo_snapshot、seo_change_note |
| 主题 | theme、theme_version、template_binding、block_schema |
| 构建 | build_job、build_input_snapshot、build_artifact |
| 验收 | validation_run、validation_issue、exception_note |
| 发布 | release、deployment_target、deployment、rollback_event |
| 运维 | job_lease、dead_letter_job、audit_log、credential_reference |

### 9.3 核心内容类型

- `page`
- `post`
- `product`
- `product_category`
- `brand`
- `taxonomy_term`
- `menu`
- `global_fragment`
- `media_asset`

### 9.4 内容引用关系

板块引用的产品、文章、媒体和路由写入 `content_reference`：

```text
site_id
source_revision_id
source_block_id
reference_type
target_content_id
target_media_id
target_route_id
```

用途：

- 删除前影响分析。
- 防止悬空引用。
- 计算需要重建的页面。
- 媒体垃圾回收。
- 生成相关推荐和反向引用报告。

### 9.5 删除与下线

已发布内容不能直接物理删除。操作步骤：

1. 显示引用页面和媒体影响。
2. 选择保留页面、301/308、410或取消发布。
3. 验证站内链接和 Sitemap。
4. 创建新的内容和路由快照。
5. 构建并发布。
6. 达到保留期限后再清理无引用媒体。

### 9.6 并发编辑

所有草稿更新包含 revision/version。后台使用 ETag 或版本号进行乐观锁；即使只有一个账号，也要防止多标签页或重复请求覆盖较新的修改。

---

## 10. 内容、主题、板块与组件化

### 10.1 基本关系

```text
内容数据 → 板块实例 → 页面模板 → 主题渲染 → 静态页面
```

- 内容保存业务数据。
- 板块保存结构化展示数据。
- 模板约束页面区域和允许的板块。
- 主题决定最终 HTML、CSS、动画和响应式效果。

### 10.2 板块类型

全局板块：Header、Footer、顶部通知、全局 CTA、联系方式。

页面板块：Hero、富文本、图文、图库、Feature、数据指标、产品列表、文章列表、参数表、下载、FAQ、CTA。

模板系统板块：面包屑、产品主信息、产品参数、文章正文、列表分页、SEO Head。

站点专属板块：360 展示、工厂流程、经销商地图等。

Legacy HTML：只用于未完成结构化的历史页面，必须清洗、隔离并标记。

### 10.3 板块实例

```ts
interface BlockInstance<T = Record<string, unknown>> {
  id: string;
  type: 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[] };
}
```

`slotKey` 支持 `main`、`sidebar`、`before_content`、`after_content` 等有限区域，不提供自由坐标布局。

### 10.4 Schema 驱动后台

每个板块提供：

- JSON Schema：字段、类型、长度、必填和枚举。
- UI Schema：后台控件、标签、媒体选择和内部链接选择。
- Schema Version：板块升级和数据迁移。

前端表单和后端保存均执行校验。生产构建遇到未知或不兼容板块时必须失败。

### 10.5 四层组件复用

```text
第一层：数据契约与工具
第二层：无样式基础组件
第三层：Headless 业务逻辑
第四层：主题展示组件
```

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

公共包：

```text
content-contracts
block-contracts
theme-runtime
ui-primitives
headless-components
content-resolvers
media-components
seo-components
form-runtime
design-tokens
```

复用边界：

| 能力 | 公共复用 | 主题独立 |
|---|---:|---:|
| 数据类型、Schema、迁移 | 是 | 否 |
| URL、SEO和媒体解析 | 是 | 可配置 |
| 菜单树、分页、表单状态 | 是 | 展示独立 |
| 产品和文章查询 | 是 | 卡片独立 |
| Hero内容协议 | 是 | 渲染独立 |
| Header/Footer | 逻辑可复用 | 结构与视觉独立 |
| 页面模板、动画、品牌样式 | 否 | 是 |

主题之间禁止直接引用对方内部组件。两个主题重复出现的非视觉逻辑提取到公共包，纯视觉实现留在主题。

### 10.6 主题清单

主题 manifest 声明：

- 主题 ID、版本和构建引擎。
- 兼容的 runtime 和公共包版本。
- 模板及入口文件。
- 每个模板允许、必需和最大数量的板块。
- 板块 renderer、schema 和 variant。
- 站点配置 schema。
- 可编辑区域。

### 10.7 主题版本

- 公共包遵循语义化版本。
- 破坏性变更提供迁移函数或兼容层。
- Release 锁定主题、公共包和构建镜像版本。
- 两套示范主题自动执行契约和截图回归。
- 主题切换前生成兼容报告，缺少 renderer 时禁止生产构建。

详细实现可参考 `SiteForge_主题与板块设计方案_V1.0.md`，V3 中与该文档冲突时以本方案为准。

---

## 11. SEO 迁移

### 11.1 三套数据

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

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

最终对外行为以 `source_rendered` 作为重要基线，插件字段用于补充来源和解释差异。

### 11.2 对比字段

- Title、Description。
- Canonical。
- Robots Meta与响应头。
- H1/H2和正文摘要。
- Hreflang。
- Open Graph和Twitter Card。
- JSON-LD。
- Sitemap收录。
- 图片alt。
- 内部链接。
- 发布和更新时间。
- 面包屑。

### 11.3 严重级别

| 级别 | 示例 | 处理 |
|---|---|---|
| P0 | 关键 URL 缺失、全站 noindex、Canonical 错域、重定向循环 | 阻止发布 |
| P1 | 核心正文缺失、关键 Title 未批准改变、大量资源 404 | 修复或记录例外后确认 |
| P2 | 次要 OG、ALT、非核心结构化数据差异 | 可带记录发布 |
| P3 | 性能、语义和图片优化建议 | 进入优化清单 |

原站存在 SEO 错误时，迁移和优化分开记录；只有超级管理员明确确认后才在迁移中修复。

---

## 12. 媒体与静态资源

### 12.1 媒体数据

- 来源 URL和旧路径。
- MIME、扩展名、尺寸和大小。
- SHA-256。
- 原件位置和衍生资源。
- alt、caption和语言。
- 引用内容和板块。
- 迁移、验证和安全状态。

### 12.2 处理策略

- 保存原始二进制，不只保存远程地址。
- 已索引或被外链引用的旧路径优先保持。
- WebP/AVIF和缩略图作为衍生资源。
- 处理 `src`、`srcset`、懒加载、CSS URL、PDF、SVG、字体和视频封面。
- 不通过全局字符串替换修改 HTML 引用。
- 清理无引用媒体前执行引用和 URL 影响分析。

### 12.3 安全

- 限制类型、大小、文件数量和解压总量。
- 防 ZIP/TAR目录穿越和压缩炸弹。
- SVG/HTML净化。
- 禁止可执行文件进入公开产物。
- 对上传附件执行恶意文件和敏感信息扫描。

---

## 13. 构建系统

### 13.1 构建输入快照

构建开始时创建不可变 `build_input_snapshot`：

```text
site_id
environment_id
content_snapshot_id
route_snapshot_id
seo_snapshot_id
asset_manifest_id
theme_version_id
site_config_version
dependency_lock_hash
source_commit
runtime_version
container_image_digest
locale
timezone
build_timestamp
```

构建过程中发生的新编辑不进入本次 build。

### 13.2 可复现构建

- 使用锁定依赖和固定运行时。
- 构建镜像按 digest 固定。
- 外部资源必须下载并固定哈希，或明确列入允许的远程依赖。
- 时间、时区、随机数和排序规则固定。
- 输出 manifest 和 checksums。
- 历史 release 回滚直接恢复产物，不重新构建。

### 13.3 隔离执行

构建和第三方适配器运行在隔离容器/沙箱中：

- 只读代码和输入快照。
- 独立可写临时目录。
- CPU、内存、磁盘和执行时长限制。
- 默认禁止任意网络访问，按任务白名单开放。
- 不挂载控制面密钥和主数据库凭据。
- 构建完成后销毁临时环境。

### 13.4 构建并发

- 同站点同环境只允许一个发布构建持有租约。
- 普通预览构建可以排队或按限额并行。
- 每个 Job 有唯一幂等键。
- 旧构建完成时如果输入版本已经落后，不得自动发布。
- 取消只在定义好的安全点生效。
- Worker 通过心跳续租，失联后任务可安全恢复。

### 13.5 构建产物

```text
releases/<release_id>/
  dist/
  build-input.json
  build-manifest.json
  route-manifest.json
  asset-manifest.json
  validation-summary.json
  migration-report.html
  checksums.txt
```

### 13.6 全量与增量

V1 使用按站全量构建。全局板块、主题或路由变化均全量构建。V1.1 根据 `content_reference` 建立依赖图，再实现选择性重建。

---

## 14. 发布、原子切换与回滚

### 14.1 发布状态机

```text
created
→ snapshot_locked
→ building
→ validating
→ ready_to_publish
→ publishing
→ verifying
→ published
```

异常状态：`failed`、`cancelled`、`rolled_back`、`partially_deployed`。

### 14.2 发布锁

生产发布获取 `environment_publish_lock`。切换时使用当前 `active_release_id` 做比较并交换：只有当前线上版本与启动发布时一致，才能切换到新 release，避免旧任务覆盖新版本。

### 14.3 发布步骤

1. 锁定构建输入。
2. 在隔离环境生成 release。
3. 执行本地校验。
4. 上传不可变版本目录。
5. 校验文件数量、大小和哈希。
6. 使用临时入口执行真实 HTTP 验收。
7. 获取发布锁并再次检查当前版本。
8. 原子切换静态目录和路由规则。
9. 刷新必要 CDN 缓存。
10. 立即执行生产冒烟。
11. 标记 `published` 或执行补偿/回滚。

### 14.4 对象存储注意事项

对象存储根目录直接同步不一定原子。优先使用版本前缀加入口指针/部署版本切换；HTML和路由规则作为同一部署事务处理。静态指纹资源长期缓存，HTML、Sitemap和非指纹文件按变更策略刷新。

### 14.5 回滚

回滚切换到上一个已验证 release，包括：

- 静态文件。
- 路由规则。
- 响应头配置。
- 必要的动态服务配置版本。
- CDN缓存策略。

首个试点正式上线前必须完成一次生产等价环境回滚演练。

---

## 15. 动态能力

### 15.1 处置原则

每个旧站动态功能必须选择：

```text
保留原服务 / 新 API 承接 / 第三方替换 / 静态降级 / 正式下线
```

没有结论的动态功能不能视为迁移完成。

### 15.2 功能方案

| 功能 | 推荐实现 |
|---|---|
| 联系/询价 | 独立 Form API + 邮件/CRM |
| 小站搜索 | 构建时生成客户端索引 |
| 大站搜索 | 独立搜索服务 |
| 分析统计 | 站点配置化接入 |
| 下载统计 | CDN/边缘日志或下载 API |
| 多语言 | V1.1 locale内容 + hreflang + 路由规则 |
| 定时发布 | V1.1调度构建与部署 |
| 会员/订单/支付 | 独立业务系统 |
| 复杂筛选 | 客户端索引或搜索 API |

### 15.3 Form API 要求

- 站点和来源域名白名单。
- CSRF/Origin检查。
- 验证码、IP/指纹限流和反垃圾。
- 请求幂等键，防止重复询盘。
- 字段 schema 和长度限制。
- 隐私同意及政策版本记录。
- 敏感字段加密和日志脱敏。
- 数据保留、导出和删除策略。
- 邮件/CRM WebHook重试与死信队列。
- 附件类型、大小和恶意文件检查。
- 提交已接收、转发成功和转发失败分开记录。

---

## 16. 管理后台

### 16.1 前端技术选型

管理后台确定采用 **Art Design Pro** 作为工程底座，其底层技术为 **Vue 3 + TypeScript + Element Plus**。三者不是二选一关系：

- Art Design Pro：后台布局、菜单、标签页、登录页面、基础工程规范和通用页面框架。
- Vue 3 + TypeScript：业务页面、状态管理、组合式逻辑和类型约束。
- Element Plus：表单、表格、弹窗、分页、上传、树形控件等基础 UI。

V1 只有超级管理员，不启用 Art Design Pro 中复杂的角色、按钮和动态权限配置。路由和菜单由系统模块固定声明，登录后拥有全部功能。

后台建议沿用底座已有的 Vue Router、Pinia、请求封装、国际化和构建工具；具体依赖版本在项目初始化时锁定。业务 API 类型由共享契约或 OpenAPI 生成，避免前后端各自维护重复接口类型。

管理后台主题只影响 SiteForge 控制台，不得与生产网站的 Astro 主题系统混用。

### 16.2 信息架构

| 菜单 | 主要能力 |
|---|---|
| 工作台 | 站点状态、迁移进度、失败任务、线上告警 |
| 网站 | 域名、环境、语言、主题、部署目标 |
| 数据源 | 连接、凭据引用、导出文件、能力探测 |
| 扫描与导入 | URL 来源、任务、差量、冲突和失败 |
| 数据映射 | 源字段、标准字段、转换、未识别字段 |
| 内容 | 页面、产品、新闻、分类、品牌、菜单 |
| 页面板块 | 模板、板块、顺序、区域、预览 |
| 媒体 | 原件、衍生、引用、旧路径和安全状态 |
| URL | 路径、状态、跳转、冲突、部署兼容 |
| SEO | 元信息、Sitemap、结构化数据、差异 |
| 主题 | 主题版本、模板、组件兼容、预览 |
| 构建 | 输入快照、任务、日志、产物 |
| 测试 | URL、SEO、内容、资源、视觉报告 |
| 发布 | Release、发布确认、部署、回滚 |
| 系统 | 超管账号、会话、密钥、备份、日志、通知 |

页面编辑器仅提供板块新增、复制、排序、隐藏、删除、字段编辑、媒体/内容引用和静态预览，不提供自由画布和任意 CSS/JavaScript。

---

## 17. 任务队列与可观测性

### 17.1 队列类型

- Probe
- Crawl
- Import
- Normalize
- Asset
- Build
- Validate
- Deploy
- Cache Purge
- Form Delivery

### 17.2 任务规则

- Job ID和幂等键。
- 最大重试次数。
- 指数退避和随机抖动。
- 可重试错误与永久错误分类。
- Worker心跳和租约。
- 超时和失联任务回收。
- 死信队列与人工重放。
- 每站点并发、抓取速率和资源配额。
- 取消和恢复检查点。
- 外部副作用记录，避免重复发送或重复部署。

### 17.3 关键指标

- 队列长度、等待时间和失败率。
- 扫描页面数、成功率和每分钟请求。
- 导入新增/更新/冲突/失败数量。
- 构建时长、页面数、产物大小。
- 验收问题分布。
- 发布成功率和回滚次数。
- 生产 4xx/5xx、关键 URL 可用性。
- 表单接收与转发成功率。
- 存储、数据库和备份状态。

### 17.4 告警

- 关键任务连续失败。
- 队列长时间无消费者。
- 构建或发布超时。
- 关键 URL不可访问。
- 生产出现全站 noindex/Canonical错误。
- 表单转发积压。
- 备份失败或恢复验证失败。
- 存储容量接近阈值。

---

## 18. 自动验收与发布门禁

### 18.1 测试矩阵

| 维度 | 自动检查 | 通过条件 |
|---|---|---|
| URL来源 | 多来源合并与去重 | 未处理 URL 为0或有明确例外 |
| HTTP行为 | 状态、跳转、Header、Content-Type | 与路由注册表一致 |
| SEO | Title、Canonical、Robots、Hreflang、JSON-LD | P0为0，P1修复或记录例外 |
| 内容 | 标题、正文摘要、产品核心字段 | 满足站点验收清单 |
| 引用 | 内容、媒体、路由反向关系 | 无悬空关键引用 |
| 媒体 | 文件、MIME、哈希、尺寸 | 无未处理关键缺失 |
| 内链 | href/src/srcset/CSS URL | 无未处理内部死链 |
| 主题契约 | 模板、板块、schema、renderer | 全部兼容 |
| 视觉 | 典型页面桌面/移动截图 | 新设计基线审核通过 |
| 可访问性 | 语义、键盘、焦点、对比度 | 达到项目基线 |
| 动态功能 | 表单、搜索和外部服务冒烟 | 每项成功用例通过 |
| 性能 | Lighthouse/Web Vitals | 达到各站约定目标 |
| 安全 | 敏感文件、依赖、CSP、恶意内容 | 无高危问题 |
| 部署 | 目标能力和路由预检 | 无关键不兼容 |
| 回滚 | 完整 release 恢复 | 演练通过 |

### 18.2 强制阻止发布

- 最终差量同步未完成。
- 关键 URL 未映射或意外 404/500。
- 重定向循环或关键查询路由无法实现。
- 生产页面存在错误 noindex、Canonical或预览域名。
- 大量核心内容、媒体或引用缺失。
- 主题缺少板块渲染器或 schema 不兼容。
- 部署目标不支持关键路由行为。
- 构建输入快照不完整或版本已过期。
- 当前环境存在其他发布任务。
- Release 无法回滚。
- 未通过超级管理员发布确认。

### 18.3 报告

```text
inventory.csv
route-diff.csv
seo-diff.csv
content-diff.csv
reference-diff.csv
assets-diff.csv
broken-links.csv
deployment-capability.json
issues.json
screenshots/
summary.html
```

---

## 19. 安全设计

### 19.1 认证与会话

- 超级管理员强密码和MFA。
- 密码使用成熟算法加盐哈希。
- 短期会话、HttpOnly/Secure/SameSite Cookie。
- CSRF防护。
- 登录限流和异常提醒。
- 恢复码离线保存。
- 高风险操作重新验证。

### 19.2 凭据

- 数据源和部署凭据进入密钥管理。
- 数据库只保存引用，不保存可见明文。
- 优先只读凭据。
- 日志自动脱敏。
- 密钥支持轮换和撤销。

### 19.3 SSRF与采集

- 域名、协议和端口白名单。
- DNS解析后检查IP。
- 每次重定向重新校验。
- 拒绝内网、回环、链路本地和云元数据地址。
- 受限网络出口和请求速率。

### 19.4 供应链与构建

- 锁定依赖和运行时。
- 依赖漏洞和许可证扫描。
- 生成软件物料清单。
- 主题/适配器来源和版本可追溯。
- 构建沙箱默认无控制面密钥。
- 发布产物执行敏感信息扫描。

### 19.5 Web安全

- CSP及必要安全响应头。
- Legacy HTML和SVG净化。
- 外部脚本、iframe和域名白名单。
- 预览站访问控制和禁止索引。
- 表单输入校验、限流和隐私保护。

---

## 20. 备份、恢复与数据保留

### 20.1 备份对象

- PostgreSQL。
- 对象存储中的原始快照和媒体。
- 构建 release 和报告。
- 路由与部署规则。
- 加密密钥配置和恢复材料。
- 系统配置及审计日志。

### 20.2 建议目标

首版建议基线，可按实际业务调整：

- PostgreSQL RPO：24小时以内；关键迁移/发布窗口前额外备份。
- 控制面 RTO：8小时以内。
- 已发布静态站 RTO：1小时以内，通过现有 release 恢复。
- 至少保留最近30天数据库备份。
- 生产 release 至少保留最近10个和所有人工标记版本。
- 原始迁移快照保留至站点迁移验收完成后的约定期限。

### 20.3 一致性与演练

数据库备份记录对应的对象存储清单和密钥版本。恢复时按同一备份点恢复数据库、对象和配置。首个试点上线前完成一次恢复演练，此后至少每季度验证一次。

### 20.4 数据删除

制定原始 SQL、个人数据、表单数据、日志和媒体的保留期限。清理任务先生成预览清单，超级管理员确认后执行，并保留删除审计。

---

## 21. 非功能要求

### 21.1 性能

- 管理后台常用查询应分页。
- 大型导入和构建全部异步执行。
- 静态页面按站点设定性能目标。
- 图片包含尺寸并生成适配资源。
- 客户端 JavaScript 按需加载。

### 21.2 可访问性

建议以 WCAG 2.1 AA 为基础目标：语义结构、键盘操作、焦点状态、颜色对比、表单标签、替代文本和减少动画偏好。

### 21.3 浏览器

项目启动时确定支持矩阵，默认支持主流浏览器最近两个稳定版本及当前主流移动浏览器。特殊旧浏览器按站点单独评估。

### 21.4 配额

每站配置：

- 最大 URL 数。
- 最大抓取深度和并发。
- 最大媒体和单文件大小。
- 最大构建时长和产物大小。
- 预览版本和 release 保留数量。

超出配额时停止任务并给出明确原因，不自动无限消耗资源。

---

## 22. 技术栈与仓库结构

### 22.1 技术栈

| 层级 | 技术 |
|---|---|
| 后台 | Art Design Pro（Vue 3 + TypeScript + Element Plus） |
| API | NestJS + TypeScript |
| 数据库 | PostgreSQL |
| ORM | 预研阶段在 Prisma与团队既有方案中确定，并记录ADR |
| 队列 | Redis + BullMQ |
| 抓取 | Crawlee/Undici + Cheerio |
| JS渲染 | Playwright |
| 静态构建 | Astro + TypeScript |
| Schema | JSON Schema + Ajv |
| 媒体 | Sharp |
| 对象存储 | S3兼容存储/MinIO |
| 运行 | Docker Compose |
| 测试 | 单元、契约、集成、Playwright E2E、HTTP验收 |

### 22.2 仓库

```text
siteforge/
  apps/
    admin/
    api/
    worker/
    builder/
    form-api/
  packages/
    contracts/
    content-contracts/
    block-contracts/
    adapter-sdk/
    adapter-wordpress/
    adapter-generic-web/
    route-engine/
    seo-engine/
    asset-engine/
    validation-engine/
    deployment-engine/
    theme-runtime/
    ui-primitives/
    headless-components/
    content-resolvers/
    media-components/
    seo-components/
    form-runtime/
    design-tokens/
  themes/
    pilot-wordpress/
    pilot-secondary/
  infra/
    docker/
    nginx/
    database/
    monitoring/
  docs/
    adr/
    api/
    runbooks/
    migrations/
  tests/
    fixtures/
    contract/
    integration/
    e2e/
```

### 22.3 ADR 决策记录

以下决策必须形成 ADR：

- ORM选择。
- 对象存储与生产部署目标。
- URL 编码和文件映射规则。
- 主题/公共包版本策略。
- 富文本与 HTML 净化方案。
- 构建沙箱实现。
- Form API 数据保留和邮件/CRM策略。

---

## 23. API 范围

```text
POST   /api/v1/auth/login
POST   /api/v1/auth/mfa/verify
POST   /api/v1/auth/logout
GET    /api/v1/auth/sessions
DELETE /api/v1/auth/sessions/:id

POST   /api/v1/sites
GET    /api/v1/sites/:siteId
POST   /api/v1/sites/:siteId/connections
POST   /api/v1/sites/:siteId/scans
POST   /api/v1/sites/:siteId/imports
POST   /api/v1/sites/:siteId/imports/:id/diff

GET    /api/v1/sites/:siteId/content
PATCH  /api/v1/sites/:siteId/content/:contentId
GET    /api/v1/sites/:siteId/content/:contentId/references

GET    /api/v1/sites/:siteId/routes
POST   /api/v1/sites/:siteId/routes/validate
GET    /api/v1/sites/:siteId/seo/diff

GET    /api/v1/themes
GET    /api/v1/themes/:themeId/manifest
PUT    /api/v1/sites/:siteId/theme

POST   /api/v1/sites/:siteId/builds
GET    /api/v1/sites/:siteId/builds/:buildId
POST   /api/v1/sites/:siteId/validations

POST   /api/v1/sites/:siteId/releases/:releaseId/publish
POST   /api/v1/sites/:siteId/deployments/:deploymentId/rollback
GET    /api/v1/sites/:siteId/reports/:type
```

所有站点 API 在服务端验证登录状态、`site_id`、对象归属、版本号和并发条件。

---

## 24. 测试策略

### 24.1 单元测试

- URL规范化辅助键。
- 重定向循环检测。
- SEO差异分类。
- Schema验证和板块迁移。
- 内容引用和删除影响。
- checksum和差量判断。
- 部署能力匹配。

### 24.2 契约测试

- 每个来源适配器使用相同 fixture 契约。
- 每个部署适配器满足 capability 接口。
- 每个主题 manifest、模板、板块和 renderer 完整。
- API DTO与事件版本兼容。

### 24.3 集成测试

- WordPress导入到内容修订。
- 内容到Astro静态输出。
- Route Manifest到Nginx/CDN规则。
- 构建、校验、发布和回滚。
- Form API到邮件/CRM和死信重放。

### 24.4 测试夹具

至少覆盖：

- WordPress默认固定链接。
- `.html`和`.php`路径。
- 中文/Unicode路径。
- 大小写冲突。
- 尾斜杠混用。
- 查询参数入口。
- 多级分类和分页。
- Yoast/Rank Math。
- ACF/Gutenberg。
- 重定向链和媒体重定向。
- JS渲染页面。
- 不支持板块和板块版本升级。

### 24.5 视觉测试

新旧站只比较内容和关键结构，不做像素一致要求。新主题建立自己的视觉基线，后续主题升级与该基线做截图回归。

---

## 25. 项目阶段与排期

以下按约5人核心团队估算：1名项目/产品负责人、2名前后端工程师、1名迁移/数据工程师、1名测试/运维，设计师阶段性参与。

### 阶段0：真实数据盘点与技术预研（第1–2周）

任务：

- 选择WordPress试点和第二来源试点。
- 获取数据库、WXR、uploads、日志、Sitemap和服务器规则。
- 建立URL/SEO/功能初始基线。
- 验证重点插件、页面构建器和路径类型。
- 确定ORM、存储、部署和构建沙箱ADR。

交付：试点评估报告、来源能力报告、风险清单、字段样本、最终V1范围与校准排期。

### 阶段1：平台骨架与安全基础（第3–5周）

任务：

- Monorepo、环境、CI。
- 超管登录、MFA、会话和日志。
- PostgreSQL、Redis、对象存储。
- 站点、环境、快照、任务和密钥引用。
- Worker租约、重试和死信框架。

交付：可登录、创建站点、运行并观察后台任务。

### 阶段2：扫描、导入与URL/SEO基线（第6–9周）

任务：

- Sitemap/HTML/Playwright扫描。
- WordPress REST/WXR/SQL/uploads导入。
- 多来源URL合并。
- 原始快照、差量同步和冲突处理。
- 内容、媒体、URL和SEO核心模型。

交付：首站真实数据可重复导入，生成URL/SEO/内容清单。

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

任务：

- Block Schema、模板和主题manifest。
- 公共组件包。
- 后台板块编辑。
- 首套试点主题。
- 隔离可复现构建。
- 内容引用和删除影响分析。

交付：首站能从后台内容生成完整静态预览。

### 阶段4：第二主题、第二来源与动态功能（第14–16周）

任务：

- 第二套明显不同的主题。
- 通用网页/第二来源适配。
- 公共组件复用验证。
- 表单或试点必需动态服务。
- 目标部署适配器和能力预检。

交付：两个站点、两种来源、两套主题在同一平台运行。

### 阶段5：门禁、发布与生产化（第17–20周）

任务：

- URL/SEO/内容/媒体/视觉验收。
- 发布锁、原子切换和CDN策略。
- 回滚、监控、告警和备份恢复。
- 最终差量同步和切站Runbook。
- 上线彩排、正式切换和保护期。

交付：至少一个试点正式上线，两个试点均完成完整迁移与回滚闭环。

### 25.1 计划区间

建议按20–24周预留项目周期，目标20周，额外4周用于复杂插件、历史路径、内容清理和试点反馈。若团队少于4人，应减少第二来源范围或顺延工期。

---

## 26. 团队职责

这里是项目职责，不是系统角色：

| 职能 | 责任 |
|---|---|
| 项目/产品 | 范围、优先级、试点协调和业务结论 |
| 架构/后端 | 数据、API、任务、构建、发布和安全 |
| 前端/主题 | 管理后台、组件包、主题和响应式页面 |
| 迁移/数据 | 扫描、适配器、字段映射、URL/SEO基线 |
| 测试/运维 | 自动验收、部署、监控、备份和回滚 |
| 设计 | 品牌规范、模板设计和视觉验收 |
| SEO/内容业务 | 提供线下确认，由超管记录结论 |

系统内所有操作仍由超级管理员完成。

---

## 27. 试点资料清单

### 27.1 WordPress试点

- 域名、授权和主机信息。
- WXR、SQL、网站目录和uploads。
- 插件/主题列表及版本。
- SEO插件、ACF/CPT和页面构建器信息。
- Sitemap和服务器重写规则。
- 访问日志、GSC、GA4落地页。
- 重要页面和高流量页面。
- 表单、搜索、多语言、会员、交易和第三方脚本。
- DNS、CDN、证书和生产发布权限。

### 27.2 第二试点

- 非WordPress或只能从HTML/API/数据库迁移。
- 页面结构与第一站明显不同。
- 可验证独立主题和通用适配器。
- 能提供足够数据和业务确认人。

### 27.3 设计资料

- Logo、字体、颜色和品牌规范。
- 桌面/移动设计稿。
- 页面类型和组件清单。
- 内容优先级和典型页面。
- 目标浏览器和性能要求。

---

## 28. 风险管理

| 风险 | 影响 | 应对 |
|---|---|---|
| 数据来源不完整 | 页面或字段遗漏 | 多来源URL全集、明确未知范围 |
| 迁移期间旧站继续更新 | 切站时丢内容 | 差量同步、冻结窗口、最终重扫 |
| 页面构建器复杂 | 无法自动结构化 | 原始数据保留、映射、Legacy兜底 |
| URL规则混合 | 404或错误跳转 | 注册表、部署能力预检、真实HTTP测试 |
| 部署目标能力不足 | 无法保持状态码和查询规则 | 路由编译器、Edge或更换目标 |
| 构建并发 | 旧版本覆盖新版本 | 输入快照、租约、CAS发布锁 |
| 主题过度通用 | 所有网站设计雷同 | 复用数据与逻辑，视觉独立 |
| 公共组件耦合 | 升级影响全部主题 | 语义版本、契约测试、截图回归 |
| 动态功能遗漏 | 表单/搜索失效 | 功能处置表和上线冒烟 |
| 构建代码不可信 | 泄密或破坏环境 | 隔离容器、限额、默认断网 |
| 超管账号丢失 | 无法管理系统 | MFA恢复码、离线备份、恢复Runbook |
| 备份不可恢复 | 故障时数据永久丢失 | RPO/RTO、关联清单、季度演练 |
| 范围扩张 | V1延期 | 版本矩阵和变更评审 |
| SEO波动 | 搜索流量下降 | 基线、门禁、监测和快速回滚 |

---

## 29. 最终交付物

### 29.1 软件

- SiteForge管理后台。
- API、数据库迁移和Worker。
- 超管认证、MFA、会话和操作日志。
- WordPress与通用网页适配器。
- URL、SEO、内容、媒体和引用引擎。
- 主题SDK、组件公共包和两套主题。
- Astro隔离构建系统。
- 路由编译和部署适配器。
- 验收报告、发布锁、回滚和监控。
- Form API或试点动态能力。
- Docker、Nginx、备份和运维配置。

### 29.2 文档

- 产品功能与后台说明。
- 系统架构和ADR。
- 数据库字典和ER图。
- API、队列和状态机协议。
- 适配器SDK。
- 主题、板块和组件开发规范。
- URL/SEO迁移规范。
- 安全和数据保留规范。
- 部署、监控、备份和恢复手册。
- 切站与回滚Runbook。
- 自动测试和验收模板。
- 两个试点迁移报告。

### 29.3 最终验收流程

两个试点能够完成：

```text
多来源盘点
→ 全量导入
→ 标准化与映射
→ 独立主题
→ 差量同步
→ URL/SEO冻结
→ 静态构建
→ 自动门禁
→ 目标环境预检
→ 发布确认
→ 原子发布
→ 生产验证
→ 回滚演练
```

所有未支持内容和功能必须进入异常清单，不能静默遗漏。

---

## 30. 立项前需要确认

1. 首个WordPress试点站。
2. 第二个不同来源试点站。
3. 两个站点的页面数、媒体量、语言和动态功能。
4. 是否能提供SQL、uploads、访问日志、GSC和服务器规则。
5. 生产主要部署到Nginx还是对象存储/CDN。
6. 表单提交到邮箱、CRM还是两者。
7. V1是否只做单语言和手动发布。
8. 目标RPO、RTO和旧站保留期。
9. 品牌设计稿和页面类型是否已经确定。
10. 超级管理员账号和恢复材料由谁保管。

---

## 31. 立即执行计划

1. 收集两个试点资料并建立只读备份。
2. 从Sitemap、数据库、日志、GSC和业务清单合并URL初始全集。
3. 建立10–20个真实页面的最小纵向PoC。
4. 验证：导入 → 标准化 → URL/SEO → 主题渲染 → 静态发布。
5. 确定ORM、部署目标、构建沙箱和Form API ADR。
6. 冻结V1范围矩阵和验收清单。
7. 再进入20周左右的正式开发与试点实施。

---

## 32. 最终结论

本方案将SiteForge定位为“多站点迁移与静态发布控制平台”。系统统一的是数据、URL、SEO、组件协议、构建和发布，不强制统一每个网站的设计。

项目成功的关键不只是采集页面，而是：

- 从多来源建立可信URL全集。
- 迁移期间持续差量同步，切站时不丢数据。
- 使用可追溯的内容和路由快照。
- 用公共数据/逻辑组件提高复用，同时保留主题视觉独立。
- 在目标部署环境验证真实HTTP行为。
- 通过构建锁、发布锁和不可变release避免版本错乱。
- 通过门禁、监控、备份和回滚控制上线风险。

按本方案完成两个差异化试点后，后续网站可以复用迁移、内容、URL、SEO、构建、测试和发布能力，把新增站点的主要工作收敛到数据映射、异常处理和独立主题设计。

---

## 附录A：发布前检查表

| 检查项 | 结果 | 备注 |
|---|---|---|
| 旧站写入已冻结 |  |  |
| 最终差量同步完成 |  |  |
| URL多来源基线完成 |  |  |
| 关键URL状态与跳转通过 |  |  |
| SEO P0/P1处理完成 |  |  |
| 内容和媒体抽检通过 |  |  |
| 主题/板块契约通过 |  |  |
| 表单/搜索等动态功能通过 |  |  |
| 部署能力预检通过 |  |  |
| 构建输入快照锁定 |  |  |
| 生产冒烟脚本准备 |  |  |
| 回滚版本和脚本确认 |  |  |
| 数据库/对象存储备份完成 |  |  |
| 超级管理员完成发布确认 |  |  |

## 附录B：核心状态机

内容：

```text
draft → ready_to_publish → published → archived
```

迁移记录：

```text
raw → normalized → needs_review → verified
```

构建发布：

```text
created → snapshot_locked → building → validating
→ ready_to_publish → publishing → verifying → published
```

任务异常：

```text
failed / cancelled / dead_lettered / partially_deployed / rolled_back
```

## 附录C：官方实现参考

- WordPress REST API：<https://developer.wordpress.org/rest-api/reference/>
- WordPress WXR：<https://wordpress.org/documentation/article/tools-export-screen/>
- WP-CLI export：<https://developer.wordpress.org/cli/commands/export/>
- Astro路由：<https://docs.astro.build/en/reference/routing-reference/>
- Google不变URL的站点迁移：<https://developers.google.com/search/docs/crawling-indexing/site-move-no-url-changes>
- Google URL变更迁移：<https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes>
- OWASP SSRF防护：<https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html>

> 框架版本、插件兼容性、部署供应商能力、项目周期和RPO/RTO，应在阶段0完成真实试点盘点后最终确认。

> 对应的详细Sprint、任务分解、依赖、验收门槛和上线时间线，见 `SiteForge_项目实施计划_V1.0.md`。