Files

T

浅念 25dcdf0a4d docs: 路线 V1.1——迁移优先快线为主（用户拍板最快见效），蓝图后移至迁移 MVP 后

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

2026-10-21 15:04:51 +08:00

25 KiB

Raw Blame History

SiteForge 迁移优先、快速见效实施计划

版本：V1.0
编制日期：2026-10-21
上位方案：SiteForge_网站工厂完整项目计划方案_V4.0.md
实施主线：先完成一个真实 WordPress 网站的静态迁移预览，再补齐生产能力，最后扩展为完整网站工厂
管理后台：Art Design Pro + Vue 3 + TypeScript + Element Plus

1. 实施结论

当前最合适的顺序不是先开发完整后台、全部蓝图和所有数据来源，而是先做一条可以真正跑通、可以在浏览器看到效果的迁移链路：

真实 WordPress 数据
→ 导入页面、产品、新闻和媒体
→ 转换为统一内容模型
→ 使用第一套主题渲染
→ 生成纯静态网站
→ 本地浏览器预览

第一阶段只聚焦：

一个真实 WordPress 试点站。
一种主要语言。
WXR + 已解包媒体目录 + Sitemap。
页面、产品、新闻三个核心内容类型。
一套可继续演进的主题。
本地静态构建和 HTTP 预览。

目标节奏：

时间	可见成果
第 3 天	可以查看导入后的内容和数量报告
第 5 天	可以在浏览器看到首页、列表页、详情页雏形
第 10 天	可以看到第一版较完整的迁移静态网站
第 4 周	URL、SEO、媒体和内容完整性达到迁移验收水平
第 6 周	可以通过简化后台修改内容并重新构建
第 8 周	具备正式预览、发布和回滚能力
第 9 周以后	逐步补充蓝图、全新建站、第二主题和其他来源

以上按“单开发者 + AI 辅助、能够获取完整试点资料”估算。多人团队可以并行压缩时间，但验收顺序不变。

2. 为什么先做迁移主线

先做真实迁移有五个直接好处：

最快产生可在浏览器查看的页面，便于确认设计方向。
能尽早暴露真实数据、旧 URL、图片和 SEO 的复杂情况。
可以验证内容模型是否足够通用，而不是停留在文档设计。
第一套主题、公共组件和构建链路可以直接成为后续新站的基础。
项目每周都有可演示成果，不需要等完整后台全部完成。

但迁移优先不等于写一次性脚本。以下五个基础从第一天就必须保留：

Source Snapshot：保存不可变输入证据。
统一内容模型：主题不能直接读取 WordPress 字段。
current/published 修订边界：导入不能自动发布。
Theme Manifest/Render Snapshot：主题只读取冻结数据。
Route Registry：旧路径不能散落在页面代码中。

这些基础可以先实现最小版，但不能省略，否则后面扩展新站时会整体重写。

3. 第一阶段范围冻结

3.1 第一阶段必须做

WordPress WXR 文件登记和 Hash。
已解包 uploads 媒体目录登记。
Sitemap 导入。
post、page、product 导入。
分类、标签、产品分类关系。
特色图片、正文图片、产品图库。
Title、Description、Canonical 基础 SEO。
原 Permalink 和媒体旧路径。
首页、普通页面、产品列表、产品详情、新闻列表、新闻详情。
Astro 静态构建。
本地 HTTP Preview。
最小 URL、SEO、死链和媒体检查。

3.2 第一阶段明确暂缓

完整 Art Design Pro 后台。
MFA、公网账号系统和复杂安全运维。
WordPress REST、SQL 直连和在线差量同步。
HTML 全站爬虫和 Playwright 扫描。
第二主题和主题在线切换。
全新建站向导和完整 Blueprint 管理后台。
CSV/JSON 通用导入界面。
Redis/BullMQ 集群。
OSS/CDN、多部署目标和自动 DNS 切换。
多语言完整工作流。
表单、搜索、会员和电商交易。
自由拖拽页面设计器。

3.3 重要说明

第一版浏览器效果是“可演示预览”，不是可以立即替换线上旧站的生产版本。只有完成 URL、SEO、媒体、发布和回滚门禁后，才允许切站。

4. 最短可见效果路线

flowchart LR
  A[WXR + 媒体 + Sitemap] --> B[最小导入器]
  B --> C[统一内容模型]
  C --> D[Render Snapshot]
  D --> E[第一套 Astro 主题]
  E --> F[静态文件]
  F --> G[本地 HTTP Preview]
  G --> H[逐步补充 URL/SEO/媒体门禁]

为了尽快看到效果，第一周不等待完整后台：

用 CLI 启动导入和构建。
用数据库和 JSON 报告查看导入结果。
主题只实现试点网站需要的核心页面。
Preview Server 直接读取本次构建产物。
后台在核心模型稳定后接入同一批 Application Service。

这样做不会浪费工作，因为 CLI、API 和后台都调用同一业务服务。

5. 第 0 步：准备真实试点资料（第 1–2 天）

5.1 输入资料

必须准备：

WordPress WXR 导出。
wp-content/uploads 的已解包目录或完整媒体副本。
Sitemap/Sitemap Index。
当前线上域名和目标预览域名。
首页、产品列表、产品详情、新闻列表、新闻详情的参考截图。
Logo、字体、颜色和品牌资料。
已知 Nginx/Apache Rewrite 和 Redirect 规则。

建议补充：

WordPress 数据库只读导出。
当前主题和自定义字段说明。
Yoast/Rank Math 等 SEO 插件信息。
页面构建器和短代码清单。
Google Search Console、访问日志和历史高流量 URL。

5.2 当天动作

对 WXR、Sitemap 和媒体目录生成 Hash。
统计文章、页面、产品、分类和媒体数量。
抽取 5–10 个代表性页面作为首批验证样本。
列出特殊 URL：.html、.php、多级目录、大小写、中文路径。
列出复杂内容：短代码、表格、图库、视频、下载和页面构建器。
把真实输入放在 Git Ignore 的受控目录中。

5.3 交付物

pilot-input-inventory.md：输入和数量清单。
pilot-known-issues.md：已知异常和复杂内容。
pilot-pages.md：首批展示页面清单。
脱敏最小测试夹具。

5.4 完成条件

输入可读取且来源明确。
知道第一版浏览器需要展示哪些页面。
真实数据和凭据不会进入 Git。
不再使用“等数据以后再调整模型”的方式推进。

6. 第 1 步：建立最小工程骨架（第 2–3 天）

6.1 只建立当前需要的目录

apps/
  api/                    # NestJS Application Context + CLI
  preview-server/         # 静态预览
packages/
  database/
  contracts/
  content-model/
  wordpress-adapter/
  route-compiler/
  theme-runtime/
themes/
  pilot-minimal/
fixtures/
artifacts/
storage/

管理后台、Worker、Blueprint SDK 等目录等进入对应阶段再建立，不先生成大量空模块。

6.2 最小技术基础

pnpm Workspace。
TypeScript Strict。
NestJS Standalone Application Context。
PostgreSQL 16。
Drizzle ORM 和正式 Migration。
Vitest。
Astro 第一主题。
结构化日志。

6.3 最小数据表

第一批只建立：

sites
source_connections
source_snapshots
import_jobs
import_items
source_records
content_entries
content_revisions
content_publication_pointers
taxonomies
terms
content_term_relations
media_assets
media_usages
route_registry
seo_revisions
build_jobs
build_input_snapshots

可以先不建立完整 Release、Deployment、Blueprint UI 等表，但核心主键、站点隔离、Revision 和 Snapshot 语义必须正确。

6.4 第一批命令

site:create
source:register
source:snapshot
content:import-wxr
content:publish
build:create
preview:start

6.5 完成条件

空数据库可以一键执行 Migration。
CLI 能创建试点站点。
Job 有数据库状态，不只存在内存。
所有表都有明确 site_id 或平台级边界。
CI 能执行 lint、typecheck 和最小单元测试。

7. 第 2 步：最小 WXR 导入（第 3–5 天）

7.1 第一批字段

先支持浏览器出效果所需字段：

类型	最小字段
Page	title、slug、content、excerpt、status、date、permalink
Post	title、slug、content、excerpt、date、author display、category、tag
Product	title、slug、content、excerpt、featured image、gallery、category、基础参数
Media	source URL、relative path、title、alt、caption、MIME
SEO	title、description、canonical、robots

7.2 实现要求

使用流式 XML 解析，不把完整 WXR 载入内存。
限制文件大小、XML 深度、字段长度和处理时间。
WordPress ID 作为来源身份，Permalink 只作为 URL 证据。
HTML 经白名单清洗后进入 Content Revision。
原始内容保存在 Source Snapshot，不直接丢弃。
同一 Snapshot 重跑不产生重复内容和重复 Revision。
导入只更新 current，不更新 published。

7.3 快速展示策略

第一轮只选 10–30 条代表性数据：

1 个首页来源页面。
2–3 个普通页面。
5–10 个产品。
5–10 篇新闻。
相关分类和媒体。

先验证模型和主题，再放开全量导入。禁止为了“看起来全量完成”直接把未知字段原样塞入主题。

7.4 导入报告

至少输出：

created
updated
skipped
conflict
failed
unsupported

每项都包含来源 ID、目标 ID、原因和错误摘要。

7.5 第一个可见成果

第 3–5 天结束时应能查看：

导入了多少页面、产品、新闻、分类和媒体。
哪些记录失败以及失败原因。
数据库中标准化后的内容。
一份 JSON/HTML 导入摘要。

8. 第 3 步：第一套主题和静态预览（第 4–10 天）

这一阶段与最小导入并行衔接，是“最快看到效果”的核心。

8.1 先实现六种页面

按以下顺序开发：

BaseLayout、Header、Footer。
首页。
普通页面。
产品列表。
产品详情。
新闻列表和新闻详情。
404 页面。

8.2 第一批公共组件

SeoHead
SiteHeader
SiteFooter
Breadcrumbs
RichText
ResponsiveMedia
ProductCard/ProductGrid
NewsCard/NewsList
TaxonomyList
Pagination
NotFoundPage

8.3 最小 Theme Manifest

interface ThemeManifest {
  key: string
  version: string
  renderContractVersion: string
  supportedContentTypes: string[]
  requiredSiteConfig: string[]
  templates: Array<{
    key: string
    appliesTo: string
  }>
}

8.4 Render Snapshot

第一版至少生成：

site.json
content.json
taxonomies.json
routes.json
assets.json
render-manifest.json

Astro 主题只能读取这些冻结文件，不能查询 PostgreSQL，不能调用 API，也不能使用站点专属 Seed 数据。

8.5 页面视觉优先级

为了快速接近真实效果，优先处理：

页面整体宽度、字体、颜色和间距。
Header、首页 Hero、产品卡片和 Footer。
产品详情主图、标题、参数和 CTA。
新闻正文排版和图片。
移动端基础响应式。

动画、复杂筛选、精细微交互和全部页面像素级还原后置。

8.6 第 5 天演示标准

首页可打开。
至少一个列表页和一个详情页可打开。
页面使用真实导入内容，不使用硬编码产品和新闻。
图片可以显示，允许暂时使用原地址或最小本地复制。
页面之间可以通过链接跳转。

8.7 第 10 天演示标准

六种核心页面全部可打开。
核心内容来自正式 WXR 导入链路。
主要图片已本地化。
页面包含基础 Title、Description 和 Canonical。
Preview 能返回 200 和 404。
生成第一版 Sitemap。
桌面和手机宽度下没有明显布局破坏。

9. 第 4 步：从演示站升级为完整迁移预览（第 3–4 周）

看到效果后，立即补迁移正确性，不能继续只打磨页面外观。

9.1 全量导入

放开全部范围内的 post、page、product。
导入全部分类关系。
识别 Attachment、特色图、图库和正文图片。
统计未知 CPT、短代码和页面构建器数据。
大数据量下使用流式处理和批次事务。

9.2 媒体完整化

按文件内容计算 Hash 并去重。
校验 MIME、大小和像素。
记录缺失、损坏和远程资源。
建立媒体使用关系。
保留重要旧媒体 URL 或生成明确映射。
生成媒体缺失报告。

9.3 URL Registry

合并：

WXR Permalink
∪ Attachment URL
∪ Sitemap
∪ 人工补充 URL

每条 URL 必须进入：

preserve
redirect
gone
exclude
unresolved

9.4 SEO 基线

对首批关键页面保存：

旧站渲染后的 Title、Description、Canonical、Robots。
H1 和结构化数据。
新构建结果。
差异级别和处理状态。

9.5 最小自动门禁

关键 URL 200。
Redirect 无环。
内部链接无 404。
页面资源无 404。
Title、Description、Canonical 存在。
Sitemap 只包含允许索引的 HTML 页面。
无旧域名误用、临时域名和控制面地址。
未处理关键媒体为 0。

9.6 第 4 周里程碑 M1

称为“完整迁移预览”，必须满足：

范围内内容全部有明确导入结果。
当前已知 URL 都已登记。
核心页面内容和图片完整。
P0 SEO 问题为 0。
静态预览可以进行业务人员审查。
尚未完成的内容有清晰报告，不能隐藏异常。

10. 第 5 步：最小管理后台（第 5–6 周）

数据模型和预览稳定后再接入 Art Design Pro。

10.1 后台第一批页面

只开发日常迁移和内容修改真正需要的页面：

菜单	首版功能
登录	超管登录、退出、会话
网站	试点站点信息和构建状态
导入任务	运行状态、数量、错误和重跑
内容	页面、产品、新闻列表和编辑
分类	分类树和关系
媒体	浏览、替换、Alt 和使用位置
URL	路径、状态、Redirect 和异常
SEO	页面 SEO 编辑和差异
构建	创建构建、日志、报告和预览入口

暂时不开发：

完整网站工厂向导。
蓝图市场。
第二主题管理。
自由页面编辑器。
复杂 Token 在线设计器。
多角色和权限配置。

10.2 内容编辑要求

页面、产品和新闻可以新增、编辑、发布和归档。
保存只创建 current Revision。
“发布内容”显式更新 published pointer。
能查看当前稿和已发布版本差异。
导入重跑不能静默覆盖人工编辑。
删除前显示 URL、菜单、媒体和内部链接影响。

10.3 后台接入原则

后台、CLI 和后续 API 共用 Application Service。
API DTO 从共享契约或 OpenAPI 生成类型。
表单尽量由内容 Schema 驱动。
不为快速开发绕开 Service 直接改数据库。

10.4 第 6 周里程碑 M2

超管能够：

登录后台。
查看导入结果。
修改一个产品和一篇新闻。
新增一篇新闻。
发布这些内容。
重新构建。
打开新预览查看变化。

11. 第 6 步：生产级构建、发布和回滚（第 7–8 周）

11.1 冻结构建输入

正式 Build Input 包含：

PublishedContentSnapshot
RouteAndSeoSnapshot
MediaManifest
ThemeBuildSnapshot
SiteEnvironmentSnapshot

11.2 构建要求

只读取 Input 目录。
默认断网。
禁止 Seed fallback。
输入 Schema 或 Hash 错误立即失败。
输出 Build、Route、Asset Manifest 和 Checksums。
同一输入连续构建业务文件 Hash 一致。

11.3 正式 Preview

自包含，不查询数据库。
支持 HTML、静态资源、301、410、404。
受访问控制保护。
默认 noindex。
使用与生产相同的路由处理规则。

11.4 第一部署适配器

优先只选择实际试点需要的一种：

Nginx/SSH；或
S3/OSS + CDN。

不要同时开发两种部署适配器。

11.5 发布流程

创建 Release
→ 运行全部 Gate
→ 上传不可变版本
→ 临时入口 HTTP 冒烟
→ 获取发布锁
→ 原子切换
→ 生产域名检查
→ 记录发布结果

11.6 回滚

保留历史不可变 Release。
回滚只切换版本指针，不重新构建。
回滚后执行 HTTP 冒烟。
正式切站前必须演练一次。

11.7 第 8 周里程碑 M3

可以从后台或受控 CLI 创建 Release。
自动门禁失败时无法发布。
能发布到试点环境。
能回滚到上一个版本。
控制面停止后静态网站仍可访问。

12. 第 7 步：迁移站正式验收（第 8–10 周）

12.1 内容验收

页面、产品、新闻和分类数量对账。
重点页面逐页检查。
富文本、表格、图库、下载和视频抽检。
未支持对象全部有处置方案。

12.2 URL 验收

当前已知 URL unresolved=0。
关键 URL 全量真实 HTTP 检查。
普通 URL 按风险分层抽检或全量检查。
Redirect 无环、无错误跨域和无过长链。
404、410 和排除页面符合批准清单。

12.3 SEO 验收

P0 差异为 0。
P1 已修复或有书面豁免。
Canonical、Robots、Sitemap、JSON-LD 正确。
不把 Preview、临时域名和测试页面纳入索引。

12.4 发布前准备

最终差量窗口。
内容冻结时间。
DNS/CDN 缓存计划。
旧站备份和只读保留策略。
生产监控和回滚触发条件。
上线后 7 天观察安排。

12.5 迁移 MVP 完成定义

完成该阶段后，可以认为“迁移网站板块”达到 V1：

一个真实 WordPress 站已完整迁移。
超管能继续维护内容。
静态站可构建、验收、发布和回滚。
URL 和 SEO 有证据闭环。
后续迁移站可以复用同一条主链路。

13. 迁移 MVP 后的补充顺序

迁移网站板块稳定后，按以下顺序扩展为完整网站工厂。

13.1 第一优先：把已有迁移能力产品化

新建迁移站向导。
WordPress 来源能力探测。
映射配置保存和复用。
冲突处理后台。
HTML 抓取和 Playwright 补扫。
REST/SQL 差量同步。
迁移模板和检查表。

13.2 第二优先：站点蓝图和全新建站

Blueprint Manifest 和安装事务。
corporate-basic 蓝图。
默认内容类型、页面、菜单和 SEO。
CSV/JSON 通用导入。
后台手工创建新站。
示例内容生命周期。

验收：无任何旧站输入也能生成完整网站。

13.3 第三优先：老内容换新主题

完整 Page Template 和 Block Instance。
Schema 驱动板块编辑器。
第二套视觉差异明显的主题。
主题兼容性报告。
缺失 Renderer 和缺失字段门禁。
老内容到新模板的映射配置。

验收：同一份内容能进入新主题，且旧 URL 和 SEO 不丢失。

13.4 第四优先：复制建站和批量生产

仅结构复制。
结构 + 示例内容复制。
可选完整内容复制。
品牌和域名替换检查。
Secret、Release 和部署目标禁止复制。

13.5 第五优先：平台增强

第二部署适配器。
多语言和 hreflang。
Form API。
搜索服务。
图片衍生和优化。
选择性增量构建。
更多 CMS 适配器。
更多蓝图和主题。

14. 逐周计划总表

周次	主目标	浏览器可见成果	阶段 Gate
第 1 周	真实数据最小导入 + 第一主题	首页、列表、详情雏形	真实内容进入页面
第 2 周	核心页面、媒体和最小 SEO	第一版完整静态预览	六种页面可浏览
第 3 周	全量导入、媒体和 URL Registry	大部分旧站内容可查看	内容对账可审计
第 4 周	SEO 差异和自动门禁	完整迁移预览	M1
第 5 周	Art Design Pro 后台骨架	内容列表和编辑	后台读写正式 API
第 6 周	发布内容、重新构建	后台修改可反映到预览	M2
第 7 周	Release 和部署适配器	试点环境发布	门禁阻断有效
第 8 周	回滚、备份和生产检查	可发布、可回滚版本	M3
第 9–10 周	正式迁移验收和切站	第一真实迁移站	迁移 MVP
后续	蓝图、新站、第二主题	网站工厂能力逐步上线	按独立里程碑验收

15. 每日开发执行方式

为了始终以可见效果为主线，每个工作日按以下顺序进行：

先选择一个可以端到端完成的小场景。
写清楚输入、输出和验收页面。
先补关键契约测试或失败测试。
实现最小数据链路。
立即生成静态页面并在 Preview 中检查。
记录异常数据，不用硬编码掩盖。
提交前执行 lint、typecheck、unit 和相关集成测试。
更新迁移数量和风险看板。

每周五必须提供：

一个可以点击查看的新效果。
本周内容/URL/媒体覆盖率。
当前失败和未支持清单。
下周将关闭的 3–5 个最重要问题。

16. 任务优先级规则

当外观、完整性和平台功能发生冲突时，使用以下顺序：

数据不能丢失、错绑或跨站泄漏。
URL 和 SEO 不能发生不可逆损失。
构建必须来自真实冻结数据。
核心页面必须能正常展示和使用。
超管可以维护上线后的内容。
发布和回滚必须可靠。
才处理次要动画、精细视觉和通用化增强。

为了展示效果，可以先减少支持的页面数量，不能伪造完成状态或绕过数据模型。

17. 快速见效过程中禁止的做法

把试点内容硬编码进 Astro 页面。
让主题直接读取 WXR 或 WordPress 私有字段。
用 Permalink 作为内容唯一主键。
导入完成后自动发布全部内容。
构建数据缺失时静默使用 Seed。
先复制旧 CMS 全部代码再慢慢整理。
为了页面能打开忽略 URL 冲突。
只检查生成文件，不通过 HTTP 验证状态码和跳转。
在核心模型未稳定前开发完整后台所有菜单。
把“预览效果不错”当成“可以正式切站”。

18. 需要从旧 `D:\project\cms` 参考的内容

可以优先参考或改造：

WXR 字段识别和映射经验。
WordPress REST/WXR 测试夹具。
媒体下载、去重和旧路径处理经验。
Astro 页面和组件的视觉实现参考。
SEO 基础输出和 Gate 规则。
URL 对照报告逻辑。
管理后台工程壳。
Docker Compose 和 CI 配置。

不能直接继承为正式实现：

默认认证和默认 Secret。
迁移即发布的流程。
Seed fallback 构建。
非原子发布和不完整回滚。
无约束的 settings JSONB 路由。
站点隔离不足的 Service/Repository。
整页硬编码并绑定单站数据的 Astro 页面。

复用顺序必须是：

先理解行为
→ 建立测试夹具和契约
→ 抽取安全的规则或局部实现
→ 接入新模型
→ 运行回归测试

19. 第一批具体开发任务清单

P0-A：当天必须准备

确认试点站和目标页面。
获取 WXR、媒体和 Sitemap。
建立输入 Hash 和清单。
确认真实数据不进入 Git。

P0-B：工程骨架

初始化 pnpm Workspace。
建立 PostgreSQL 和 Drizzle Migration。
建立 Site、Source、Content、Route 和 Build 最小模型。
建立 CLI Application Context。
建立持久化 Job 状态。

P0-C：迁移导入

流式解析 WXR。
导入 page/post/product。
导入 taxonomy/term/relation。
导入 Attachment 元数据。
清洗 HTML。
建立 Source Record 幂等映射。
输出导入报告。

P0-D：静态效果

建立 Render Snapshot。
建立 pilot-minimal Theme Manifest。
实现 Layout/Header/Footer。
实现首页。
实现普通页。
实现产品列表/详情。
实现新闻列表/详情。
实现 Preview Server。

P0-E：迁移正确性

全量媒体本地化。
建立 Route Registry。
生成 Sitemap。
建立 SEO 差异。
检查死链、资源和 Redirect。
生成 HTML/JSON 验收报告。

P1：后台和发布

Art Design Pro 后台初始化。
单一超管登录。
内容、媒体、URL、SEO 页面。
构建和预览页面。
Release 和发布锁。
第一 Deployment Adapter。
回滚和生产冒烟。

20. 最终执行判断

本计划采用以下渐进路线：

第一周：真实数据生成真实页面
第二周：形成可以完整浏览的静态预览
第四周：形成可审查的完整迁移预览
第六周：后台可以维护内容并重建
第八周：可以安全发布和回滚
第十周：完成第一真实迁移站
之后：在已验证底座上增加新站、蓝图、第二主题和更多来源

这条路线能最快让项目产生可见价值，同时不会把系统做成只能使用一次的迁移脚本。

第一阶段的唯一主线是：

用真实旧站数据，尽快生成一个可以浏览、可以对比、可以逐步接近上线标准的纯静态网站。

当第一条迁移链路稳定后，站点蓝图、全新建站和复制建站都应复用已经验证的内容、主题、构建、SEO 和发布能力，而不是另起一套系统。

25 KiB Raw Blame History Unescape Escape