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 的正式版本。