cms-website/SiteForge_现有CMS项目复用评估_V1.0.md

# SiteForge 现有 CMS 项目复用评估 V1.0

> 评估对象：`D:\project\cms`  
> 目标项目：`D:\project\cms-one`（SiteForge）  
> 评估日期：2026-10-20  
> 依据：现有源码、数据库 Schema、测试、构建脚本、基础设施配置，以及 SiteForge V3.0 方案与实施计划。

---

## 1. 结论

`D:\project\cms` 不是简单样例，而是一个已经具备管理后台、控制 API、WordPress 迁移、内容模型、Astro 静态站运行时和基础测试的早期平台原型。

它与 SiteForge 的目标高度同源，适合作为**代码底座和经验来源**，不建议把 SiteForge 完全从零重写。但它当前仍然是“单站 MVP 向平台化演进”的状态，部分文档设计明显领先于实际代码，因此不能整体原样搬入。

推荐原则：

1. SiteForge V3.0 方案继续作为当前项目的唯一产品与架构基线。
2. 选择性继承 `cms` 中已经验证的代码，不继承其过时的权限、发布、路由和数据边界。
3. 优先复用迁移解析、内容版本、管理后台壳、Astro 组件、测试夹具等高价值资产。
4. 对认证、发布、路由注册、主题架构、媒体安全和表单服务进行结构性重构。
5. 不复制缓存、依赖目录、构建产物、真实客户数据和历史存储文件。

---

## 2. 当前项目可以直接参考或复用的部分

### 2.1 Monorepo 工程骨架

来源：

- `D:\project\cms\package.json`
- `D:\project\cms\pnpm-workspace.yaml`
- `D:\project\cms\turbo.json`
- `D:\project\cms\.github\workflows`

可复用内容：

- pnpm Workspace + Turborepo 的项目组织方式。
- 管理后台、控制 API、构建 Worker、站点运行时和公共包的目录边界。
- TypeScript、Vitest、CI 的基础配置。
- 统一执行 `typecheck`、`test`、`build` 的任务编排。

需要调整：

- CI 安装应使用冻结锁文件，而不是 `--no-frozen-lockfile`。
- 增加数据库迁移校验、OpenAPI 契约校验、静态站质量门禁、安全扫描和产物校验。
- 不复制 `node_modules`、`.turbo`、`.data`、本地日志和构建输出。

复用等级：**高，可以直接作为工程骨架参考。**

### 2.2 Art Design Pro 管理后台基础

来源：`D:\project\cms\apps\admin-web`

已有能力：

- Vue 3 + TypeScript + Element Plus。
- Art Design Pro 布局、菜单、路由、Pinia、Axios 和通用组件。
- 站点列表、站点管理、内容管理、媒体、导航、设置、线索和迁移页面。
- WordPress 迁移的步骤式界面。

建议保留：

- 登录后主布局、导航、标签页、请求封装、异常处理和基础表格表单组件。
- 站点切换、站点列表、迁移向导和媒体选择器的交互结构。
- Element Plus 设计体系以及 Art Design Pro 已有的工程规范。

必须精简：

- 删除注册、找回密码、动态权限演示和多角色菜单逻辑。
- 用户角色只保留一个全局 `super_admin`，不设计复杂 RBAC。
- 清理仪表盘、电商演示、Mock 页面和无关组件。
- 将体积过大的站点管理页面拆成独立领域页面和复用组件。
- 内容表单由硬编码逐步改为 Schema 驱动。
- 复用前确认 Art Design Pro 及第三方资源的许可证适用范围。

复用等级：**高，建议直接继承后台壳和通用能力，业务页面按新方案重构。**

### 2.3 NestJS + Fastify + Drizzle 后端基础

来源：`D:\project\cms\services\control-api`

已有模块：

- 认证。
- 站点管理。
- 内容类型、内容条目和内容版本。
- 媒体管理。
- WordPress 迁移。
- 线索管理。
- 构建触发。

可复用内容：

- NestJS 模块化结构和 Fastify 适配。
- Drizzle + PostgreSQL 的访问方式。
- Zod 输入校验思路。
- 显式 `site_id` 上下文和站点隔离测试。
- 内容版本不可变、草稿与发布版本分离的基础设计。
- 站点模板初始化和默认导航生成逻辑。

需要重构：

- 用户表当前为站点级并带历史角色字段，应改为平台级单超管模型。
- 自制 HMAC Token 缺少成熟的过期、刷新、撤销和 MFA 机制，应替换。
- 审计日志、发布记录、构建任务和路由记录需要成为正式数据表，而不是内存或 JSON 附属数据。
- API 应补齐 OpenAPI、统一错误码、幂等键、操作审计和敏感操作二次确认。

复用等级：**高，适合作为后端起点，但认证和发布领域不可原样沿用。**

### 2.4 WordPress REST/WXR 迁移能力

来源：

- `D:\project\cms\services\control-api\src\migration`
- `D:\project\cms\apps\admin-web\src\views\sites\migrate-tab.vue`
- `D:\project\cms\tests`

已有能力：

- WordPress REST API 拉取。
- WXR 文件解析。
- 文章、产品等内容转换为中间结构。
- 媒体下载、去重和关联。
- 类型映射、迁移预览、批次导入和结果报告。
- 基于旧地址生成部分重定向。
- 幂等迁移和相关端到端测试。

这是旧项目中最值得保留的资产之一。现有文档还记录了多个真实网站迁移规模，说明相关代码不是纯概念设计。

必须调整：

- 迁移后不能自动发布，必须进入“导入批次 → 校验 → 人工审核 → 预览 → 发布”的流程。
- 旧 URL 不能只保存在 `siteSettings` JSON 中，应写入正式的 `route_registry`。
- 页面、分类、标签、自定义文章类型、附件和 SEO 元数据需要统一映射策略。
- 不能把无法映射的旧页面一律跳转首页，应进入冲突清单并人工处理。
- 语言不能硬编码为 `en/es`，应使用站点 Locale 配置。
- 增加断点续传、失败重试、限流、增量迁移、差异报告和可回滚批次。
- 从 HTML 提取内容时增加 XSS 清理和资源地址标准化。

复用等级：**很高，保留解析器、UniversalRow 思路、媒体抓取和测试夹具，重做迁移编排。**

### 2.5 内容模型、版本与导入幂等

来源：

- `D:\project\cms\services\control-api\src\content`
- `D:\project\cms\services\control-api\src\db`
- `D:\project\cms\docs\contracts\导入模板V1.md`

可复用内容：

- 内容类型定义与内容条目分离。
- 多语言内容记录。
- 不可变版本记录。
- 通过 `externalRef`、Slug 等键进行幂等合并。
- 导入预校验、错误报告、状态机和 CSV 安全方面的设计经验。

建议作为 SiteForge 内容中台的起点，但需要补充：

- 内容发布状态机。
- 计划发布和撤回。
- 关联内容完整性。
- Slug/URL 冲突检测。
- 导入批次与每条记录的来源追踪。
- 批次级回滚。
- 删除保护和引用检查。

复用等级：**高。**

### 2.6 Astro 静态站运行时和页面质量门禁

来源：`D:\project\cms\runtimes\astro-site-runtime`

已有能力：

- Astro 5 静态站构建。
- 首页、产品、分类、新闻、项目、关于、联系、支持和 Sitemap 页面。
- Header、Footer、Hero、分页、表单、卡片网格、CTA 等组件。
- 基础主题 Token。
- Title、Description、Canonical、H1、内部链接、图片和 Sitemap 检查。
- 重定向文件生成。
- 版本化构建产物和基础回滚脚本。

可直接复用：

- Astro 的构建基础。
- 现有语义组件和样式 Token 的代码经验。
- 门禁脚本和重定向生成器作为第一版基础。
- SEO 页面输出和 Sitemap 生成思路。

必须重构：

- 页面不能继续依赖硬编码站点配置和默认内容。
- 编译器必须读取冻结的发布快照，而不是构建过程中读取变化中的在线数据。
- 主题应拆成主题包、主题清单、Token、布局、区块注册表和站点配置。
- 区块应由统一 Block Renderer 渲染，不能每个网站复制页面文件。
- 构建产物切换要使用真正的原子发布机制，而不是删除后复制。
- 门禁检查应使用 HTML 解析器而不是仅靠正则，并增加重复元数据、结构化数据、hreflang、孤链、重定向环、状态码和性能预算。

复用等级：**中高，适合作为静态运行时原型，不应直接作为最终主题架构。**

### 2.7 主题 Token 和组件契约文档

来源：

- `D:\project\cms\docs\contracts\ThemeToken契约V1.md`
- `D:\project\cms\docs\contracts\组件契约V1.md`

值得吸收的内容：

- 使用语义 Token，而不是在组件中直接写颜色和尺寸。
- 主题变体、版本号和升级迁移规则。
- 组件输入、插槽、SEO、可访问性和懒加载约束。
- Hero、CardGrid、FeatureGrid、CTA 等组件的标准化思路。
- WCAG 2.2 AA 作为可访问性目标。

与 SiteForge 的结合方式：

- 把“组件契约”升级为正式的 Block Manifest。
- 每个组件声明字段 Schema、默认值、允许的布局、SEO 行为、资源依赖和兼容版本。
- 区分基础 UI 组件、内容区块、页面模板和站点主题四个层级。
- 主题只能组合和覆盖，不得复制修改公共组件源码。

复用等级：**高，适合作为当前主题与组件规范的补充输入。**

### 2.8 PostgreSQL、Redis、MinIO 基础设施

来源：`D:\project\cms\infrastructure`

建议沿用：

- PostgreSQL：业务数据库。
- Redis：队列、分布式锁、缓存和限流。
- MinIO：本地开发的 S3 兼容对象存储。

需要修改：

- 生产环境使用受控对象存储或独立部署的兼容服务。
- 镜像必须固定版本，不能长期使用 `latest`。
- 开发密码不得用于生产。
- 增加备份、恢复演练、生命周期、跨环境配置和 Secret 管理。

复用等级：**高。**

---

## 3. 可以参考，但必须重构后使用的部分

### 3.1 认证与权限

旧项目保留了多角色和站点级用户的历史痕迹，而 SiteForge 已明确只需要一个超级管理员。

新设计应为：

- 平台只有一个 `super_admin` 权限模型。
- 可允许配置一个或少量超级管理员账号，但权限完全一致，不建立角色矩阵。
- 使用成熟密码哈希、短期访问凭证、刷新/撤销机制、MFA、登录限流和安全日志。
- 所有高风险操作记录操作者、站点、对象、前后差异、IP、User-Agent 和时间。

旧认证代码只能参考接口结构，不能作为生产安全方案直接使用。

### 3.2 构建、发布与回滚

旧项目当前主要问题：

- 构建记录保存在进程内存中。
- API 进程直接启动构建命令。
- 构建锁仅在单进程内有效。
- Build Worker 目录基本还是占位。
- 发布替换并非严格原子操作。
- 回滚没有完整持久化的 Release 记录。

SiteForge 应改为：

1. API 创建持久化 Build Job。
2. Redis/BullMQ Worker 异步消费。
3. 同站点使用分布式发布锁。
4. 构建读取不可变 Site Snapshot。
5. 产物写入版本目录或对象存储。
6. 门禁通过后原子切换当前 Release 指针。
7. 每次发布记录输入快照、代码版本、主题版本、产物校验和和日志。
8. 回滚只切换到已验证 Release，不重新现场构建。

可继承的是构建命令、Astro 产物组织和基础门禁；发布编排需要重做。

### 3.3 路由与 SEO

旧项目能生成重定向文件，但路由仍是附属设置，不足以支撑“原路径不变”的核心要求。

SiteForge 必须建立独立的 `route_registry`：

- 每条公开 URL 都有唯一注册记录。
- 保存站点、Locale、路径、资源类型、资源 ID、状态、Canonical 和历史来源。
- 写入内容时先预占或校验路由。
- 迁移前导入完整旧站 URL 清单。
- 构建时从注册表生成页面和重定向。
- 发布门禁对旧 URL 覆盖率、404、重定向环和多跳重定向进行检查。

旧项目的 Redirect 生成脚本可以保留，但数据源应切换到路由注册表。

### 3.4 媒体系统

旧媒体模块已有 Sharp 缩略图和来源 URL 去重，可以保留处理经验，但存在以下缺口：

- 主要依赖本地磁盘。
- SVG 缺少严格清理。
- 删除时缺少完整引用检查。
- 未形成原文件、变体、Hash、使用关系和删除状态的完整模型。

SiteForge 应实现：

- S3 兼容对象存储。
- 文件 Hash 去重和 MIME 魔数校验。
- SVG 清理或默认禁用上传。
- 图片尺寸、格式、焦点、Alt 和变体管理。
- `media_usage` 引用关系。
- 软删除、延迟物理删除和可恢复窗口。
- WebP/AVIF 等派生资源异步生成。

### 3.5 表单与线索

旧 Lead 模块只适合作为简单 CRUD 示例，尚不等于可对公网开放的 Form API。

SiteForge 应补充：

- 表单定义和字段 Schema。
- 来源页面、UTM、Referrer、站点和 Locale。
- 服务端校验、蜜罐、验证码、频率限制和重复提交保护。
- 隐私同意记录和可配置保留期限。
- 通知重试、Webhook 签名和失败队列。
- CSV 导出安全处理。
- 所有更新必须同时按 `site_id` 和记录 ID 定位。

### 3.6 站点主题与页面编辑

旧运行时已有 Token 和组件，但页面结构仍偏硬编码。SiteForge 应建立四层结构：

1. **基础组件层**：Button、Container、Image、RichText 等。
2. **业务区块层**：Hero、ProductGrid、NewsList、FAQ、CTA、ContactForm 等。
3. **页面模板层**：首页、产品列表、产品详情、新闻列表、文章详情和普通页面。
4. **主题层**：Token、字体、间距、装饰样式、默认区块组合和可用模板清单。

主题包至少包含：

- `theme.manifest.ts`
- `tokens.ts`
- `blocks/`
- `layouts/`
- `templates/`
- `styles/`
- `migrations/`

后台编辑的是结构化区块配置，前台由 Block Renderer 统一渲染。这样才能同时做到不同网站效果不同、组件可复用、数据可迁移和主题可升级。

---

## 4. 当前阶段不建议复用或应暂缓的部分

### 4.1 数据分析和客户身份体系

旧文档中包含事件网关、ClickHouse、Tracking Plan、客户画像和增长分析等设计。这些能力会显著增加系统复杂度，但不是 SiteForge 第一阶段完成网站迁移、发布和维护的必要条件。

建议：

- V1 只保留基础访问统计接入位和必要操作日志。
- Event Gateway、ClickHouse、统一客户身份和高级分析延后到独立阶段。

### 4.2 复杂 RBAC、多租户商业化和计费

当前需求已经明确只需超级管理员，因此暂不建设：

- 角色与权限矩阵。
- 团队邀请和成员管理。
- 租户套餐、用量计费和支付。
- 审批流。

数据库可保留未来扩展空间，但不应为了可能的需求增加当前实现负担。

### 4.3 旧项目的真实数据与运行目录

不得直接复制：

- `.data`
- `storage`
- `node_modules`
- `.turbo`
- `.playwright-mcp`
- 构建产物和运行日志
- 客户网站内容、媒体、线索和导入文件
- `.env`、Token、密码及其他 Secret

确需使用真实迁移样本时，应先获得授权并完成脱敏，再转换为最小测试夹具。

### 4.4 历史文档的权威地位

旧项目文档中有大量值得借鉴的设计，但部分功能只存在于文档，代码尚未实现；也有部分规则与 SiteForge 当前单超管、统一路由和冻结快照发布模型冲突。

因此：

- SiteForge V3.0 方案是当前项目的权威基线。
- 旧项目文档仅作为输入和参考。
- 任何旧设计进入实现前，都要映射到 SiteForge 的领域模型和验收标准。

---

## 5. 复用优先级矩阵

| 能力 | 现状 | 复用建议 | 优先级 |
|---|---|---|---|
| pnpm/Turborepo 工程骨架 | 已成型 | 直接参考/继承 | P0 |
| Art Design Pro 后台壳 | 已成型 | 保留壳，清理演示与多角色 | P0 |
| NestJS/Fastify/Drizzle | 已成型 | 作为 API 基础 | P0 |
| 站点上下文与隔离测试 | 已有实现 | 保留并扩大覆盖 | P0 |
| WordPress REST/WXR 解析 | 已有实现和测试 | 重点继承，重做迁移流程 | P0 |
| 内容类型和版本 | 基本可用 | 扩展状态机与发布模型 | P0 |
| Astro 静态运行时 | 原型可用 | 保留构建基础，重构主题架构 | P0 |
| 主题 Token/组件契约 | 文档较完整 | 纳入新主题规范 | P0 |
| Redirect 生成 | 已有脚本 | 改用 route_registry 数据源 | P0 |
| SEO Gate | 基础版本 | 保留并增强 | P0 |
| PostgreSQL/Redis/MinIO | 已配置 | 直接沿用技术选型 | P0 |
| 导入幂等和报告 | 有基础 | 扩展为批次、回滚、差异报告 | P1 |
| 媒体缩略图处理 | 有基础 | 保留 Sharp，重构存储与安全 | P1 |
| 站点模板初始化 | 有基础 | 改造成站点蓝图/主题初始化 | P1 |
| Lead CRUD | 简单实现 | 仅参考，重做公网 Form API | P1 |
| BuildService | 原型 | 不直接复用，改为队列 Worker | P1 |
| Event Gateway | 占位/早期 | 暂缓 | P3 |
| ClickHouse/增长分析 | 超出当前范围 | 暂缓 | P3 |
| 多角色 RBAC | 与需求冲突 | 不采用 | 不做 |

---

## 6. 推荐落地方式

### 方案 A：以旧项目代码为技术底座进行净化和重构（推荐）

做法：

- 保留旧项目 Git 历史或创建一条新的 SiteForge 开发分支/仓库。
- 删除缓存、数据、演示页面和超出范围的模块。
- 以 SiteForge V3.0 的数据模型、模块边界和实施计划逐步替换旧实现。
- 每完成一个领域，就补齐迁移脚本、测试和验收门禁。

优点：

- 最大化利用已经写好的管理后台、迁移解析器、API 和 Astro 代码。
- 保留真实问题的修复经验和测试用例。
- 比从空目录重建更快进入可运行状态。

风险：

- 必须主动偿还旧原型留下的结构债务。
- 不能为了短期速度保留内存发布、JSON 路由、自制 Token 等关键缺陷。

### 方案 B：保持 `cms-one` 为全新仓库，选择性移植源码

适用于希望彻底清理历史包袱的情况。

建议只移植：

- 后台通用壳和基础组件。
- WordPress/WXR 解析器与测试夹具。
- 内容版本、幂等导入的核心逻辑。
- Astro 通用组件、主题 Token 和门禁脚本。
- PostgreSQL/Redis/MinIO 开发环境配置。

不要整目录复制。每次移植都应有对应的模块边界、测试和依赖清单。

综合成本与风险，推荐采用**方案 A 的代码继承方式 + 方案 B 的选择性净化原则**：把旧项目当成可运行底座，但按 SiteForge 方案逐域重构，而不是延续旧项目产品定义。

---

## 7. 第一批实际迁移任务

### 第 1 批：建立干净基线

1. 确认源码许可证和第三方资产许可证。
2. 导出仅包含受版本控制源码的干净代码副本。
3. 排除数据、媒体、日志、缓存、依赖和 Secret。
4. 删除后台演示页面、多角色路由和无关分析模块。
5. 固化 Node、pnpm、PostgreSQL、Redis 和 MinIO 版本。
6. 跑通 lint、typecheck、unit、e2e 和静态站构建基线。

### 第 2 批：修正核心架构

1. 实现平台级单超级管理员认证。
2. 建立 `route_registry`、`import_batches`、`build_jobs`、`releases`、`publish_locks` 等核心表。
3. 将构建改为持久化队列 Worker。
4. 将静态站编译输入改为冻结 Site Snapshot。
5. 建立对象存储媒体模型和引用关系。

### 第 3 批：迁移与主题平台化

1. 把现有 WordPress REST/WXR 代码接入导入批次。
2. 建立全量 URL 清单、映射、冲突和覆盖率报告。
3. 将现有 Astro 组件整理为基础组件和业务区块。
4. 实现 Theme Manifest、Block Manifest 和 Block Renderer。
5. 完成第一个真实站点的迁移、预览、门禁和原子发布。

### 第 4 批：运营能力

1. Schema 驱动内容表单。
2. 产品、新闻、普通页面和导航维护。
3. 安全的公网 Form API 和线索后台。
4. 发布历史、差异查看、一键回滚和审计日志。
5. 备份恢复、监控告警和灾难恢复演练。

---

## 8. 需要优先修复的已发现风险

1. **发布记录在内存中**：服务重启会丢失构建历史和锁状态。
2. **API 进程直接构建**：资源隔离、并发、重试和故障恢复不足。
3. **迁移即发布**：不满足人工审核、预览和可回滚要求。
4. **路由保存在 JSON 设置中**：无法可靠保证所有旧路径不变。
5. **自制 Token 能力不足**：缺少完整过期、撤销、MFA 和会话管理。
6. **本地媒体存储和直接删除**：生产可靠性和引用安全不足。
7. **SVG 缺少清理**：存在持久化 XSS 风险。
8. **Lead 更新条件不完整**：部分操作需同时限定 `site_id`。
9. **页面和 Locale 存在硬编码**：无法稳定支持不同站点和语言组合。
10. **文档数据库模型多于实际 Schema**：必须以迁移文件和运行代码确认真实能力。
11. **正则式 HTML Gate 有边界缺陷**：需要 DOM 解析和浏览器级补充验证。
12. **所谓原子发布仍有删除后复制窗口**：生产切换需要重新设计。

---

## 9. 最终建议

当前 SiteForge 项目应把 `D:\project\cms` 定位为：

- **实现底座**：复用工程骨架、后台壳、API 基础、迁移解析和 Astro 运行时。
- **经验库**：复用真实迁移中沉淀的测试、映射和质量门禁经验。
- **非权威需求来源**：产品范围、权限、发布和主题架构以 SiteForge V3.0 为准。

预计最能节省工期的五项资产是：

1. WordPress REST/WXR 迁移解析和测试。
2. Art Design Pro 管理后台基础。
3. NestJS/Fastify/Drizzle 内容 API 基础。
4. Astro 静态站组件与 SEO Gate。
5. 内容版本、幂等导入和站点隔离测试。

预计最不能直接继承的五项是：

1. 当前认证与多角色模型。
2. 内存式构建和发布流程。
3. JSON 化重定向与非正式路由管理。
4. 本地媒体删除和安全策略。
5. 迁移完成后直接发布的工作流。

按这个边界执行，可以保留旧项目的大部分有效研发投入，同时避免把原型阶段的关键技术债带入 SiteForge 的正式版本。