Files

T

浅念 ceb6106025 docs: V4 基线重评估与路线定制 V1.0——路线A确认（Plan3→蓝图→双入口构建），资产保全判定与差距账本

Co-Authored-By: Claude Code <noreply@anthropic.com>

2026-10-21 14:31:07 +08:00

57 KiB

Raw Permalink Blame History

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

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

0. 文档结论

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

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

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

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

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

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

只有当以上四条路径共用同一套内容、蓝图、主题、构建和发布体系时，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 产品目标

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

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 只有一种平台角色：

super_admin

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

不实现：

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

4.2 账号与安全

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

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

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

5. 四条核心业务流程

5.1 原样迁移

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

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

5.2 老内容换新模板

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

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

5.3 全新建站

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

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

5.4 复制建站

支持三种复制范围：

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

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

6. 核心产品概念

6.1 概念关系

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

6.2 站点蓝图 Site Blueprint

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

一个蓝图至少声明：

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

V1 至少提供：

corporate-basic：企业展示、新闻、产品目录、联系页面。
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 板块定义与板块实例

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

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

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

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

它必须支持：

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

7. 组件化与复用策略

7.1 四层复用模型

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

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

7.2 建议公共包

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. 总体架构

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，不提前拆微服务：

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. 建议仓库结构

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 至少包含：

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 适配器协议

每个来源适配器实现：

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 冲突策略

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

create_only
update_if_unchanged
overwrite_current
merge_selected_fields
skip
manual_review

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

12. URL、SEO 与迁移保真

12.1 URL 来源

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

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

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

12.2 路径处置

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

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

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

12.3 SEO 三方对比

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 处理流程

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

13.2 安全规则

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

13.3 路径策略

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

14. 内容发布与版本模型

14.1 双指针模型

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

current_revision_id
published_revision_id

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

14.2 内容状态

draft
published
archived

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

14.3 删除规则

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

15. 静态构建体系

15.1 冻结构建输入

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

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

15.2 Render Snapshot

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

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 结构

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 状态机

draft
→ building
→ validating
→ ready
→ deploying
→ active

异常状态：

failed
cancelled
superseded
rolled_back

17.3 发布流程

获取站点环境发布锁。
校验 Release、门禁和批准豁免。
上传不可变版本目录。
校验文件数量、大小和 Hash。
对临时入口执行真实 HTTP 冒烟。
原子切换当前版本指针。
刷新 CDN。
对生产域名执行关键路径检查。
记录 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 新建网站向导

步骤：

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

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

18.4 页面编辑器

V1 页面编辑器提供：

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

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

18.5 Schema 驱动表单

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

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

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

19. API 与 CLI 范围

19.1 首版 API 模块

/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 用于早期纵向切片、自动化和故障恢复，不替代最终后台：

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 实施原则

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

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

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

路径 A：迁移入口

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

路径 B：新站入口

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：长期候选。

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

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

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。

两周结束必须回答：

新站流程是否完全不依赖 WordPress 字段。
迁移内容和新内容是否真正进入同一模型。
蓝图、主题和页面模板边界是否清晰。
构建是否只读取冻结文件。
现有 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 将具备以下完整能力：

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

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

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

57 KiB Raw Permalink Blame History Unescape Escape

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

0. 文档结论

1. 文档权威关系

1.1 当前权威文档

1.2 代码库关系

2. 建设背景与问题定义

3. 产品目标与非目标

3.1 产品目标

3.2 明确非目标

3.3 V1 成功标准

4. 用户与权限模型

4.1 唯一角色

4.2 账号与安全

5. 四条核心业务流程

5.1 原样迁移

5.2 老内容换新模板

5.3 全新建站

5.4 复制建站

6. 核心产品概念

6.1 概念关系

6.2 站点蓝图 Site Blueprint

6.3 主题 Theme

6.4 页面模板 Page Template

6.5 页面实例 Page Instance

6.6 板块定义与板块实例

6.7 内容类型与内容条目

6.8 映射配置 Mapping Profile

7. 组件化与复用策略

7.1 四层复用模型

7.2 建议公共包

7.3 复用边界

7.4 首版板块目录

8. 总体架构

8.1 控制面与生产面分离

8.2 模块化单体

8.3 技术栈

9. 建议仓库结构

10. 核心领域模型

10.1 站点和环境

10.2 蓝图、模板和板块

10.3 内容与修订

10.4 来源、快照和导入

10.5 媒体

10.6 路由与 SEO

10.7 构建、验收和发布

11. 来源适配与导入系统

11.1 适配器协议

11.2 首版适配器优先级

11.3 WordPress 首版范围

11.4 CSV/JSON 新站导入

11.5 冲突策略

12. URL、SEO 与迁移保真

12.1 URL 来源

12.2 路径处置

12.3 SEO 三方对比

12.4 门禁严重级别

13. 媒体与静态资源

13.1 处理流程

13.2 安全规则

13.3 路径策略

14. 内容发布与版本模型

14.1 双指针模型

14.2 内容状态

14.3 删除规则

15. 静态构建体系

15.1 冻结构建输入

15.2 Render Snapshot

15.3 Artifact 结构

15.4 可复现性

15.5 增量构建

16. 自动验收门禁

16.1 所有站点共用门禁

16.2 迁移站额外门禁

16.3 新站额外门禁

16.4 复制站额外门禁

17. 预览、发布与回滚

17.1 Preview

17.2 Release 状态机

17.3 发布流程

57 KiB

Raw Permalink Blame History