From ceb610602550c7a4c466dd001f497a9d50f56408 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Wed, 21 Oct 2026 14:31:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20V4=20=E5=9F=BA=E7=BA=BF=E9=87=8D?= =?UTF-8?q?=E8=AF=84=E4=BC=B0=E4=B8=8E=E8=B7=AF=E7=BA=BF=E5=AE=9A=E5=88=B6?= =?UTF-8?q?=20V1.0=E2=80=94=E2=80=94=E8=B7=AF=E7=BA=BFA=E7=A1=AE=E8=AE=A4?= =?UTF-8?q?=EF=BC=88Plan3=E2=86=92=E8=93=9D=E5=9B=BE=E2=86=92=E5=8F=8C?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=9E=84=E5=BB=BA=EF=BC=89=EF=BC=8C=E8=B5=84?= =?UTF-8?q?=E4=BA=A7=E4=BF=9D=E5=85=A8=E5=88=A4=E5=AE=9A=E4=B8=8E=E5=B7=AE?= =?UTF-8?q?=E8=B7=9D=E8=B4=A6=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- SiteForge_V4基线重评估与路线定制_V1.0.md | 68 + SiteForge_网站工厂完整项目计划方案_V4.0.md | 1913 ++++++++++++++++++++ 2 files changed, 1981 insertions(+) create mode 100644 SiteForge_V4基线重评估与路线定制_V1.0.md create mode 100644 SiteForge_网站工厂完整项目计划方案_V4.0.md diff --git a/SiteForge_V4基线重评估与路线定制_V1.0.md b/SiteForge_V4基线重评估与路线定制_V1.0.md new file mode 100644 index 0000000..d3c6404 --- /dev/null +++ b/SiteForge_V4基线重评估与路线定制_V1.0.md @@ -0,0 +1,68 @@ +# SiteForge V4 基线重评估与路线定制 V1.0 + +> 日期：2026-10-21 +> 输入：`SiteForge_网站工厂完整项目计划方案_V4.0.md`（新最高基线）× 当前进度（Plan 1/2 已收官、Plan 3 已批准待执行） +> 决策：用户已确认 **路线 A**（先执行 Plan 3，再做蓝图阶段）+ **新站样板先用通用定义**（corporate-basic） + +--- + +## 1. 结论 + +V4 把产品从"迁移平台"升级为"网站工厂"（四条路径）。**已完成的三轮计划没有工作被作废**：Plan 1 ≈ V4 阶段 1，Plan 2+3 ≈ V4 阶段 3（迁移路径主体）。V4 的实质增量是蓝图/页面板块/新建站/CSV/JSON 域，以及"双入口切片"的正确性要求——通过路线定制吸收，不需要回退任何实现。 + +定制后的计划序列： + +```text +Plan 3（执行中） = V4 阶段 3 收尾：导入管道落库 +Plan 4（新写） = V4 阶段 2：站点蓝图 + 全新建站最小链路（含页面/板块/菜单模型 + CSV/JSON 导入） +Plan 5（新写） = V4 阶段 4：双入口主题与静态构建（两路径汇合同一构建器） +Plan 6（新写） = V4 阶段 5：Art Design Pro 管理后台核心闭环 +Plan 7（新写） = V4 阶段 6：SEO 门禁 + Release + 部署适配器 + 回滚 +Plan 8（新写） = V4 阶段 7：三类样板验收（迁移原样/老内容新主题/蓝图新站） +``` + +## 2. 现状 → V4 映射（资产保全判定） + +| 资产 | V4 对应 | 处置 | +|---|---|---| +| 21 表 schema（sites/snapshots/entries/revisions/taxonomies/media/routes/build/audit） | §10 领域模型 | **直接保留**；V4 §10.3-10.7 的核心身份/双指针/快照语义与现有实现一致 | +| 四冻结契约（UniversalRow + 三 Manifest） | §11 适配器协议、§15.2 Render Snapshot | 保留；Render Snapshot 文件清单在 Plan 5 按 V4 §15.2 扩展（加 blueprint/pages/blocks/menus/seo） | +| WXR 适配器 + PHP 解析 + 清洗 + 报告 | §11.3 WordPress 首版范围 | 保留（V4 要求的 post/page/product/分类/attachment/Yoast/permalink 全覆盖） | +| source:register + 媒体侧车 + sf CLI | §19.2 首版 CLI 子集 | 保留 | +| globalSetup 测试基建 / ADR×16 / 门禁纪律 | §22 测试策略 | 保留扩展 | +| Plan 3（已批准） | §25 阶段 3 全部交付物 | **照原样执行** | + +## 3. 差距账本（按落地计划分组） + +### Plan 4（蓝图阶段）需要新增 +- **数据库**：`site_blueprints` / `site_blueprint_versions` / `blueprint_installations` / `site_blueprint_bindings`；`content_types`（安装化内容类型）；`page_template_definitions` / `page_instances` / `page_revisions` / `block_definitions` / `block_instances` / `block_instance_revisions`；`menus` / `menu_items` +- **能力**：Blueprint Manifest 契约 + 校验 + 安装/回滚（后台 Job 化）；`corporate-basic` 蓝图实体；`site:create` / `blueprint:list/install` CLI；CSV/JSON 导入 + 映射预览 + 幂等；`content:add`（手工）；新站 URL/SEO 默认规则（route_registry 的第二写入方） +- **Gate（=V4 M2）**：新站入口零 WordPress 假设；同一蓝图装两站数据隔离；安装失败完整回滚 + +### Plan 5（构建阶段）需要新增 +- `site_environments` / `theme_bindings` / `deployment_targets` 表；Theme Manifest 扩展（蓝图兼容/预设）；两套主题（pilot-minimal 迁移向 + corporate-modern 新站向）；Block Renderer + Schema 版本迁移；冻结构建输入扩展（V4 §15.1 七元组）；自包含 Preview Server +- **Gate（=V4 M4）**：两路径同一构建器；同输入双构建 Hash 一致；双样板可 HTTP 预览 + +### Plan 6/7/8 需要（后台/发布/验收） +- mapping_profiles / import_items / import_conflicts（冲突队列 + 人工覆盖保护——V4 §11.5；Plan 3 的报告级冲突可升级为表级） +- media_variants / legacy_asset_routes；route_collisions / redirect_rules / seo_revisions / source_page_snapshots / sitemap_entries +- Art Design Pro 后台（V4 §18 信息架构）；Release/发布锁/部署适配器/回滚；Form API（按试点需要） +- 复制建站（V4 路径 4，P1） + +## 4. 对既有基线文档的裁决（随 V4 §1.1 生效） + +- V4.0 = 产品/架构/实施/验收**最高基线** +- V2 切片设计 = 数据/路由/构建/门禁细节参考（冲突处以 V4 为准） +- V3.0 / 实施计划 V1.0 = 历史参考 +- Plan 1-3 文档 = 实施记录，继续有效 + +## 5. 时间线重估（诚实口径） + +V4 自估：4-5 人团队 24-28 周；单开发者+AI **36-48 周**。当前进度约折抵 V4 阶段 1 全部 + 阶段 3 的 2/3（约 8-10 周等价工作量）。剩余（Plan 3 收尾 + Plan 4-8）按 V4 口径约 **28-40 周**。里程碑驱动的节奏不变：每计划终审通过才进下一个。 + +## 6. 待用户后续输入（不阻塞 Plan 3/4 启动） + +1. 全新站样板的真实业务定制（现为通用 corporate-basic，品牌/字段/设计后补） +2. 首个正式部署目标（Nginx/SSH vs OSS/CDN）——Plan 7 前确定 +3. 后台是否公网开放（决定 MFA 强制度）——Plan 6 前确定 +4. Task 0.2 cms 数据备份（阶段 6/L3 前必须补——责任链持续携带） diff --git a/SiteForge_网站工厂完整项目计划方案_V4.0.md b/SiteForge_网站工厂完整项目计划方案_V4.0.md new file mode 100644 index 0000000..dac4521 --- /dev/null +++ b/SiteForge_网站工厂完整项目计划方案_V4.0.md @@ -0,0 +1,1913 @@ +# SiteForge 网站工厂完整项目计划与实施方案 + +> 版本：V4.0 +> 编制日期：2026-10-21 +> 文档状态：产品、架构、研发、测试和试点实施的统一基线 +> 管理后台：Art Design Pro + Vue 3 + TypeScript + Element Plus +> 核心定位：支持旧站迁移、旧内容换新模板、全新网站搭建的多站点静态网站生产工厂 + +--- + +## 0. 文档结论 + +SiteForge 不应只做“WordPress 静态迁移工具”，也不应做成另一个 WordPress。它应是一套由单一超级管理员使用的网站生产工厂： + +```text +旧站或新数据 + ↓ +采集 / 导入 / 手工录入 + ↓ +统一内容模型与字段映射 + ↓ +站点蓝图初始化网站结构 + ↓ +主题 + 页面模板 + 板块组合完成展示 + ↓ +冻结内容、路由、SEO、媒体和主题版本 + ↓ +静态构建 → 自动验收 → 预览 → 发布 → 回滚 +``` + +系统必须完整支持以下三条主业务路径： + +1. **原样迁移**：导入旧站，尽量保持原内容、URL、SEO 和页面行为，输出纯静态站。 +2. **迁移并改版**：导入旧内容，选择新蓝图或新主题重新组织展示，同时保留旧 URL，必要时生成受控跳转。 +3. **全新建站**：不依赖任何旧网站，选择蓝图和主题，通过手工录入、CSV、JSON 或 API 导入新内容并生成新站。 + +此外支持第四条辅助路径： + +4. **复制建站**：复制已有站点的结构、配置和可选内容，替换品牌、域名和数据后快速创建同类网站。 + +只有当以上四条路径共用同一套内容、蓝图、主题、构建和发布体系时，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 产品目标 + +1. 一个后台管理多个独立网站。 +2. 一个 `super_admin` 管理全部功能，不建设复杂角色权限。 +3. 同时支持迁移建站、改版建站、全新建站和复制建站。 +4. WordPress 作为第一优先来源，通过适配器扩展其他来源。 +5. 内容与主题解耦，同一份标准内容可被不同主题渲染。 +6. 用站点蓝图复用网站结构，用组件和板块复用功能，用主题保留视觉差异。 +7. 迁移模式下精确保留或明确处置旧 URL 和 SEO。 +8. 新站模式下可生成规范 URL、SEO、Sitemap 和结构化数据。 +9. 通过后台长期维护产品、新闻、页面、分类、菜单、媒体和网站配置。 +10. 每次构建使用冻结输入，可复现、可审计、可回滚。 +11. 生产站完全静态化，动态能力通过独立服务提供。 +12. 第二个及后续网站主要投入在内容映射、设计配置和少量专属组件，而不是重写整个平台。 + +### 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 只有一种平台角色： + +```text +super_admin +``` + +该角色可以管理全部网站、数据源、内容、主题、蓝图、构建、发布和系统设置。 + +不实现： + +- 站点管理员。 +- 编辑、审核、发布等分级角色。 +- 菜单权限、按钮权限和数据权限配置器。 +- 用户组和组织层级。 + +### 4.2 账号与安全 + +即使只有一个角色，仍必须具备： + +- 初始管理员一次性创建流程，禁止默认密码。 +- 强密码和可选强制 MFA；生产公网后台必须启用 MFA。 +- 恢复码、会话查看和会话撤销。 +- 登录限流、失败锁定和安全审计。 +- 高风险操作二次确认。 +- 发布、回滚、删除、密钥变更的不可变操作日志。 + +单一角色只是减少权限复杂度，不代表取消安全控制。 + +--- + +## 5. 四条核心业务流程 + +### 5.1 原样迁移 + +```text +创建迁移站点 +→ 登记旧站来源 +→ 获取 WXR / REST / 数据库 / uploads / Sitemap +→ 建立源快照 +→ 导入并标准化内容 +→ 建立旧 URL 和 SEO 基线 +→ 选择兼容主题或实现专属主题 +→ 人工处理异常映射 +→ 冻结并构建 +→ 自动门禁 +→ 预览确认 +→ 最终差量同步 +→ 发布和切站 +``` + +目标是内容、URL 和 SEO 保真。视觉可接近旧站，但不要求把旧主题代码原样搬入系统。 + +### 5.2 老内容换新模板 + +```text +完成旧站导入 +→ 选择目标站点蓝图和新主题 +→ 把标准内容映射到新页面模板和板块 +→ 生成兼容性报告 +→ 补齐缺失字段和专属板块 +→ 保留旧路径或建立一对一 Redirect +→ SEO 差异验收 +→ 构建、预览和发布 +``` + +“换模板”不是简单换 CSS。它包括页面类型匹配、板块组合、菜单重建、媒体适配和缺失字段补齐。 + +### 5.3 全新建站 + +```text +创建新站 +→ 选择站点蓝图 +→ 选择蓝图支持的主题/主题预设 +→ 填写品牌、域名、语言和联系方式 +→ 安装内容类型、默认页面、菜单和 SEO 规则 +→ 导入 CSV/JSON 或手工新增内容 +→ 调整页面板块 +→ 构建、门禁、预览和发布 +``` + +此流程不得依赖 WordPress ID、旧 URL、WXR 或旧站字段。 + +### 5.4 复制建站 + +支持三种复制范围： + +| 模式 | 复制内容 | 复制结构/主题 | 复制环境和密钥 | +|---|---:|---:|---:| +| 仅结构 | 否 | 是 | 否 | +| 结构 + 示例内容 | 仅明确标记的示例数据 | 是 | 否 | +| 完整业务副本 | 可选 | 是 | 否 | + +复制后必须重新设置站点标识、域名、品牌、环境、部署目标和密钥引用。任何 Secret、发布锁、历史 Release 和线上统计不得被复制。 + +--- + +## 6. 核心产品概念 + +### 6.1 概念关系 + +```text +Content Type / Content Entry + ↓ + Block Instance + ↓ + Page Instance + ↓ + Page Template + ↓ + Theme + ↑ + Site Blueprint +``` + +### 6.2 站点蓝图 Site Blueprint + +站点蓝图是“创建一个可运营网站所需的结构安装包”，不是视觉主题的别名。 + +一个蓝图至少声明： + +- 蓝图 ID、版本和兼容协议版本。 +- 适用站点类型，如企业站、产品目录站、新闻站。 +- 必需和可选的站点配置字段。 +- 需要安装的内容类型及其字段 Schema。 +- 默认页面实例和页面模板绑定。 +- 默认板块组合和插槽规则。 +- 默认菜单和菜单项结构。 +- 默认 URL 生成规则和 SEO 规则。 +- 允许使用的主题和默认主题绑定。 +- 可选的示例内容包。 +- 可选的 CSV/JSON 映射配置。 +- 可选的迁移映射配置。 + +V1 至少提供： + +1. `corporate-basic`：企业展示、新闻、产品目录、联系页面。 +2. `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 板块定义与板块实例 + +板块定义是可复用协议，板块实例是页面中的实际数据。 + +```ts +interface BlockInstance> { + 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 + +映射配置把来源字段转换为统一内容字段： + +```text +来源字段 +→ 清洗与转换 +→ 标准字段 +→ 默认值/字典/单位处理 +→ 校验 +→ 冲突策略 +→ 导入结果 +``` + +它必须支持： + +- 字段重命名和类型转换。 +- HTML 清洗和短代码处置。 +- 分类、枚举、单位和日期映射。 +- 媒体 URL 到媒体实体的转换。 +- 一个来源字段拆分为多个字段。 +- 多个来源字段合并。 +- 必填缺失报告。 +- 预览前 N 条转换结果。 +- 映射版本化和重跑。 + +--- + +## 7. 组件化与复用策略 + +### 7.1 四层复用模型 + +```text +第一层：数据契约、Schema、URL、SEO、媒体工具 +第二层：无样式基础组件与可访问性交互 +第三层：Headless 业务逻辑和内容查询 +第四层：主题展示组件和品牌视觉 +``` + +前三层公共复用，第四层由主题独立实现。 + +### 7.2 建议公共包 + +```text +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. 总体架构 + +```mermaid +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，不提前拆微服务： + +```text +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. 建议仓库结构 + +```text +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` 至少包含： + +```text +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 适配器协议 + +每个来源适配器实现： + +```ts +interface SourceAdapter { + probe(input: SourceInput): Promise + snapshot(input: SourceInput): Promise + discover(snapshot: SourceSnapshotRef): AsyncIterable + normalize(record: SourceRecord, profile: MappingProfile): Promise + diff?(previous: SourceSnapshotRef, current: SourceSnapshotRef): Promise +} +``` + +适配器只负责来源发现和标准化，不直接发布内容、不写生产路径、不调用主题。 + +### 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 冲突策略 + +每次导入可选择默认策略，但冲突必须逐条留痕： + +```text +create_only +update_if_unchanged +overwrite_current +merge_selected_fields +skip +manual_review +``` + +已经在后台人工修改的字段默认受保护，迁移差量不得静默覆盖。 + +--- + +## 12. URL、SEO 与迁移保真 + +### 12.1 URL 来源 + +迁移站的已知 URL 基线至少由以下集合组成： + +```text +WXR 可推导 URL +∪ Attachment URL +∪ Sitemap/Sitemap Index +∪ HTML 抓取结果 +∪ 服务器 Rewrite/Redirect 规则 +∪ 访问日志、GSC、GA4（可获得时） +∪ 人工补充清单 +``` + +报告必须明确列出已接入和未接入来源，禁止把“当前已知 URL”描述为“所有历史 URL”。 + +### 12.2 路径处置 + +每条迁移 URL 必须进入一种状态： + +```text +preserve 原路径输出 200 +redirect 明确跳转 +gone 明确 410 +exclude 批准排除并记录原因 +unresolved 未处理；发布门禁前必须清零 +``` + +新站 URL 则由蓝图和内容类型规则生成，不要求存在旧 URL 基线，但仍需执行冲突、Canonical、Sitemap 和内部链接检查。 + +### 12.3 SEO 三方对比 + +```text +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 处理流程 + +```text +登记来源 +→ 下载或读取本地输入 +→ 协议/MIME/大小/像素安全校验 +→ Hash 去重 +→ 保存原件 +→ 生成受控衍生图 +→ 建立使用关系 +→ 建立旧路径映射 +→ 构建输出 +``` + +### 13.2 安全规则 + +- 拒绝 `file://`、内网地址、回环地址和受限协议。 +- 处理 DNS 重绑定、跳转后目标和下载总预算。 +- MIME 必须通过文件内容验证，不能只信扩展名。 +- SVG 默认清洗或转安全格式，未经允许不得原样内联。 +- ZIP 必须限制条目数、展开大小、目录穿越和符号链接。 +- EXIF 和潜在敏感元数据按策略清理。 + +### 13.3 路径策略 + +- 迁移站优先保留重要旧媒体路径。 +- 新站使用稳定、可缓存的资源路径。 +- 构建产物不得引用控制面私有地址。 +- 外链资源必须在发布前明确选择保留远程、转存或阻断。 + +--- + +## 14. 内容发布与版本模型 + +### 14.1 双指针模型 + +每个内容、页面和站点配置都保留： + +```text +current_revision_id +published_revision_id +``` + +- 保存编辑只更新 current。 +- 导入只创建或更新 current。 +- 发布内容时显式更新 published。 +- 静态构建默认只读取 published。 +- 预览可选择读取 current，但必须标识为预览并设置 noindex。 + +### 14.2 内容状态 + +```text +draft +published +archived +``` + +V1 不实现复杂审批流。状态变更仍记录操作人、时间和原因。 + +### 14.3 删除规则 + +- 被页面、菜单、板块、SEO 或其他内容引用时禁止直接删除。 +- 删除已发布内容前必须选择 Redirect、Gone 或替代目标。 +- 默认软删除，物理清理通过独立受控任务执行。 +- 删除不得导致历史 Release 无法回滚。 + +--- + +## 15. 静态构建体系 + +### 15.1 冻结构建输入 + +```text +BuildInput = PublishedContentSnapshot + + PageAndBlockSnapshot + + RouteAndSeoSnapshot + + MediaManifest + + BlueprintBinding + + ThemeBuildSnapshot + + SiteEnvironmentSnapshot +``` + +构建期间不得读取变化中的在线业务表、Seed 数据或远程内容。 + +### 15.2 Render Snapshot + +主题只接收冻结文件，例如： + +```text +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 结构 + +```text +artifacts/jobs// + 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 状态机 + +```text +draft +→ building +→ validating +→ ready +→ deploying +→ active +``` + +异常状态： + +```text +failed +cancelled +superseded +rolled_back +``` + +### 17.3 发布流程 + +1. 获取站点环境发布锁。 +2. 校验 Release、门禁和批准豁免。 +3. 上传不可变版本目录。 +4. 校验文件数量、大小和 Hash。 +5. 对临时入口执行真实 HTTP 冒烟。 +6. 原子切换当前版本指针。 +7. 刷新 CDN。 +8. 对生产域名执行关键路径检查。 +9. 记录 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 新建网站向导 + +步骤： + +1. 选择创建方式：迁移、迁移改版、全新、复制。 +2. 填写站点名称、标识、语言和目标域名。 +3. 选择蓝图。 +4. 选择主题和主题预设。 +5. 填写品牌、Logo、联系方式和基础 SEO。 +6. 配置来源或选择手工/文件导入。 +7. 预览即将创建的内容类型、页面和菜单。 +8. 确认安装并进入站点工作台。 + +安装必须由后台 Job 执行，失败时可回滚，不留下半安装状态。 + +### 18.4 页面编辑器 + +V1 页面编辑器提供： + +- 选择允许的页面模板。 +- 新增、复制、排序、隐藏和删除板块。 +- Schema 驱动字段表单。 +- 媒体、内容和内部链接选择器。 +- 桌面、平板、手机静态预览。 +- 当前草稿与已发布版本对比。 + +不提供自由拖拽坐标、任意嵌套和在线写代码。 + +### 18.5 Schema 驱动表单 + +每个 Content Type、Block、Blueprint 和 Theme Config 提供： + +- 数据 Schema。 +- UI Schema。 +- 默认值。 +- 校验消息。 +- 版本号和迁移函数。 + +前端和后端必须使用同一契约验证。生产构建遇到未知版本时必须失败，不能静默忽略。 + +--- + +## 19. API 与 CLI 范围 + +### 19.1 首版 API 模块 + +```text +/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 用于早期纵向切片、自动化和故障恢复，不替代最终后台： + +```text +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 实施原则 + +1. 先证明贯穿全链路的最小网站工厂，不先堆完整后台页面。 +2. 同时验证迁移站和全新站，防止数据模型只服务 WordPress。 +3. 先建立契约和冻结输入，再开发复杂主题和发布自动化。 +4. 先可靠全量构建，再优化增量构建。 +5. 所有阶段必须有可运行产物和明确 Gate，不以“代码基本完成”作为完成标准。 +6. 旧 `cms` 只按白名单复用，移植前先写契约测试。 + +### 24.2 第一纵向切片必须扩大为“双入口切片” + +原 V2 只验证 WXR 迁移，容易把平台做成迁移工具。修正后的第一切片同时验证： + +**路径 A：迁移入口** + +```text +hesupipe WXR/Sitemap/媒体 +→ Source Snapshot +→ 标准内容 +→ URL/SEO +→ pilot-minimal +→ 静态构建 +→ Gate +→ Preview +``` + +**路径 B：新站入口** + +```text +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：长期候选。 + +任何新增主题专属功能都要先判断： + +1. 是否是公共数据或业务逻辑。 +2. 是否应成为通用 Block。 +3. 是否只属于主题展示。 +4. 是否应作为站点扩展包，而不是进入核心平台。 + +### 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。 + +两周结束必须回答： + +1. 新站流程是否完全不依赖 WordPress 字段。 +2. 迁移内容和新内容是否真正进入同一模型。 +3. 蓝图、主题和页面模板边界是否清晰。 +4. 构建是否只读取冻结文件。 +5. 现有 `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 将具备以下完整能力： + +```text +它既能把旧网站搬过来， +也能把旧内容装进全新设计， +还能完全不依赖旧站，从蓝图和新数据创建新网站； +随后继续在同一个后台维护内容， +通过统一的静态构建、SEO 门禁、发布和回滚体系长期运营。 +``` + +这才是目标中的“网站生产工厂”。 + +原纵向切片 V2 的迁移、路由、构建和门禁设计可以保留，但必须按本文补入站点蓝图、全新建站、CSV/JSON 映射、页面/板块实例和双入口验收。若仍只完成 WXR → 静态站，最终只能得到优秀的迁移工具，不能得到完整的网站工厂。 +