xinyouhe/cms-SiteForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f15ea85db4e5409a4c210f7154ed81b201f87667
cms-SiteForge/docs/SiteForge_V2_Architecture.md
T

906 lines
42 KiB
Markdown
Raw Normal View History

chore: baseline V8.10.0-dev.1 with v8_workflows type-mapping fix and trade-pro spec
2026-10-22 16:49:25 +08:00
# SiteForge 智能网站生产工厂
> **完整产品需求与技术架构方案（PRD + Architecture + Implementation Plan）**
> 版本：V2.0（对 V1.0“通用多站点迁移与静态建站平台”的定位升级）
> 日期：2026-10-21
> 状态：产品与研发规划版
> 适用：产品经理、设计师、前后端研发、测试、运维、Claude 等编程助手
---
## 0. 核心定义与产品定位
**SiteForge 不只是旧网站迁移工具，而是“网站工厂（Website Factory）”：以模板、数据、页面结构和站点配置为原材料，经过装配、构建、验证和发布，持续生产完全独立的网站。**
网站可以：
1. **旧站改造**：从 WordPress、其他 CMS、自研 PHP 或普通网站导入既有内容，选用全新主题，保留旧站 SEO 和 URL，重建设计不同的静态网站。
2. **模板建站**：没有旧站，选择行业模板，填入企业资料、Logo、产品、文章和媒体文件，直接形成新站。
3. **数据建站**：从 Excel/CSV/JSON/XML、API、数据库或图片资料批量导入新内容，自动建立内容类型和页面，匹配模板生成网站。
4. **自由建站**：从空白项目开始创建导航、页面、区块、数据集合、主题和页面规则；最终保存为可复用的新模板。
5. **混合建站**：上述方式可自由组合，例如“旧站文章 + 新 Excel 产品 + 新模板 + 自定义页面”。
统一原则：**内容和视觉彻底分离，迁移和新建使用同一个内容模型、页面装配器、静态构建器、质量检测及发布系统。**
### 0.1 产品成功标准
- 非迁移用户也能完整创建、编辑、构建并发布一个新网站。
- 旧站迁移不是复制旧视觉，而是按“内容映射 → 新主题 → 全新网站”装配。
- 同一份数据可以切换不同主题、重复构建；主题切换不得无故删除内容。
- 一份设计可以保存为模板；模板升级不能未经确认覆盖站点定制内容。
- 多网站独立运行、互不影响；输出静态文件后生产站不依赖中心平台在线。
- 迁移站保留需要保留的 URL、SEO、链接和媒体访问行为；全新站可自由制定 URL/SEO 策略。
- 导出物有真实 HTML/CSS/JS/媒体、必要的路由/重定向/服务器配置，而非只提供开发框架项目。
### 0.2 非目标与边界
- 不是承诺对任何公开 URL 一键获得不可见的后台、私有数据或完整业务代码。
- 不是将所有交互功能硬转为静态 HTML；账号、支付、订单、实时库存、复杂搜索等需要独立 API/服务。
- 不是初期一次性建成可对任意复杂页面精准拖拽设计的通用 Webflow 类编辑器。
- 不保证迁移后搜索排名零波动；系统负责风险降低、可追溯验证和监测。
---
## 1. 四大建站入口与混合生产工作流
| 模式 | 起始条件 | 用户主要步骤 | 输出 |
|---|---|---|---|
| A 旧站重建 | 有旧网站 | 识别旧站 → 导入内容/SEO/URL → 选主题 → 映射 → 预览 → 构建 → 发布 | 新设计的独立网站 |
| B 模板新建 | 无旧站 | 选行业模板 → 填公司信息 → 导入或新增内容 → 配置栏目 → 预览 → 发布 | 全新网站 |
| C 数据驱动 | 有 Excel/API/数据库 | 导入数据 → 字段映射 → 生成内容集合 → 选模板 → 自动建立列表/详情页 → 发布 | 数据驱动批量页面网站 |
| D 空白搭建 | 需要自主设计 | 创建站点 → 可视化组装页面 → 配置设计变量/数据 → 预览 → 发布 → 沉淀为模板 | 定制网站与可复用模板 |
### 1.1 “继续生产”能力
网站创建完后可继续：新增文章和产品、批量导入新数据、替换 Banner、维护多语言、增删栏目、修改 SEO、调整主题样式、升级组件、局部/全站重建、回滚到旧版本。**迁移任务完成不等于站点项目结束。**
### 1.2 三个关键产品动作
- **Create Site**：从空白、模板或克隆既有站点结构新建。
- **Import Content**：随时将旧站、文件、API 等数据导入现有站点，映射、去重、合并和校验。
- **Build & Publish**：将某一明确的数据版本 + 主题版本 + 站点配置打包成可追溯静态发布版本。
不能把“导入网站”与“创建网站”绑定成一对一：一个站点允许多个数据源，一个数据源也可按授权复用到多个站点。
---
## 2. 总体架构：三条输入管线、一个生产流水线
```mermaid
flowchart TB
subgraph Inputs[网站生产输入]
I1[旧站导入：WP/CMS/PHP/HTML]
I2[新内容导入：Excel/CSV/JSON/API/媒体]
I3[从零创建：内容编辑器/页面编辑器]
end
subgraph Core[SiteForge 网站工厂控制中心]
C1[通用内容中心 / 媒体中心]
C2[模板市场 / 主题设计系统]
C3[页面编辑器 / 页面装配规则]
C4[网站蓝图 Site Blueprint]
C5[URL / SEO / 多语言规则]
C6[任务引擎 / 版本 / 权限]
end
subgraph Pipeline[网站生产流水线]
P1[数据校验与字段映射]
P2[站点装配与路由解析]
P3[静态构建 HTML/CSS/JS]
P4[预览 / SEO / 功能 / 链接检查]
P5[发布 / ZIP 导出 / 回滚]
end
I1 --> P1
I2 --> P1
I3 --> C1
P1 --> C1
C1 --> C4
C2 --> C4
C3 --> C4
C5 --> C4
C6 --> C4
C4 --> P2 --> P3 --> P4 --> P5
P5 --> S[独立运行的网站 A / B / C ...]
```
### 2.1 控制面与生产面分离
控制面：SiteForge 后台、API、数据/媒体资产、模板、采集、构建任务、发布/审核。生产面：各网站独立的静态文件/CDN/Nginx 与可选独立业务 API。**线上网站运行不要求 SiteForge API 或数据库常驻可用。**
### 2.2 “网站”并不是“主题”
一个网站由以下因素组合：
```
Website Release =
Site Configuration
+ Site Blueprint (页面/栏目/菜单/区块/路由规则)
+ Theme & Component Version
+ Content Snapshot
+ Asset Snapshot
+ SEO & Redirect Rules
+ Environment & Build Settings
```
这是保证可重复构建、主题更换和版本回滚的核心公式。
---
## 3. 关键领域模型（必须从第一天设计好）
### 3.1 Site（站点）
唯一站点 ID、站点类型、语言/地区、域名、环境、数据源、主题引用、权限、发布策略。
### 3.2 Site Blueprint（网站蓝图）
蓝图描述**网站结构而不是内容本身**：
- 页面树：主页、关于我们、联系方式、服务、产品、新闻、品牌、活动等。
- 导航树：顶部主导航、Mega Menu、页脚、移动导航。
- 页面类型：普通静态页、内容集合列表、集合详情、分类聚合、专题页。
- 路由规则：固定页 slug、列表分页、产品 URL 格式、语言前缀。
- SEO 规则：title 模板、canonical、sitemap/noindex、结构化数据类型。
- 区块编排：Banner、产品网格、优势、表单、统计、FAQ、CTA 等。
- 设计变量：品牌色、字体、布局宽度、间距、圆角、响应式断点。
- 模板绑定：哪个页面类型使用哪套布局及组件。
- 功能扩展：搜索、询盘、表单、在线聊天、外部 API 等。
站点蓝图可以从模板初始化，也可以由编辑器独立创建；保存之后属于站点自身，主题升级不得悄悄覆盖人工更改。
### 3.3 Content Type（内容类型）与 Entry（内容条目）
内容中心不能硬编码只支持“文章”和“产品”，应支持动态类型：
- 默认类型：Page、Post、Product、Category、Brand、Service、Case、FAQ、Team、Download。
- 自定义内容类型：如汽车的 Vehicle、工业管材的 Pipe、房地产的 Property。
- 字段定义：短文本、富文本、数字、布尔、日期、枚举、关系、数组、媒体、SEO 字段、多语言字段、引用。
- 校验规则：是否必填、唯一性、格式、单位、可搜索/筛选、跨字段规则。
- 数据状态：draft / review / published / archived；版本和来源可追踪。
### 3.4 Theme（主题）/ Template（页面模板）/ Component（组件）
- **主题 Theme**：完整设计风格及组件集合、页面模板、响应式规则、设计 Token。
- **页面模板 Page Template**：例如首页、产品列表、产品详情、文章详情、专题落地页。
- **组件 Component**：Hero、图片网格、产品卡、参数表、图文交错、导航栏、页脚等。
- **主题实例 Theme Instance**：某站点在主题基础上的参数覆盖与自定义区块配置。
### 3.5 Route Registry（路由注册表）
一切最终发布 URL 的唯一事实源：`site_id + method + normalized_path + locale + route_behavior`；必须记录来源及冲突处理，不能仅由标题推断路径。
---
## 4. 模板工厂：不仅选模板，还要生产模板
### 4.1 模板分类
- 行业模板：汽车出口、工业品、制造业、外贸 B2B、企业介绍、服务类、资讯类。
- 页面模板：首页、列表、详情、关于、联系、新闻、案例、FAQ、落地专题等。
- 区块库：Hero、统计、产品参数、网格、时间线、客户评价、团队、展会等。
- 布局方案：顶部导航、侧边导航、全宽、多列、自适应等。
### 4.2 模板选择体验
每个主题展示 PC/移动端预览、适合行业、支持的内容类型、内置页面数量、菜单形态和可编辑范围。选择主题后运行 `compatibilityCheck`，提示当前内容是否满足主题必需字段，并提供字段映射或替代组件选项。
### 4.3 模板来源
1. 平台预置主题。
2. 开发人员以标准主题 SDK 编写并注册主题。
3. 在设计器中制作页面，保存为模板或区块。
4. 从现有网站**复制结构/设计配置**作为新项目起点，不自动复制私有数据。
### 4.4 防止主题与数据耦合
主题只能根据语义接口取数据，例如 `products.featured`、`company.name`、`posts.latest`。不能把某个具体产品、域名或 WordPress ID 硬编码进主题组件。
### 4.5 模板升级
主题使用不可变版本号。站点自行选择是否升级；升级前进行数据兼容性检测和区块差异预览；不支持自动合并的站点私有修改应手动解决。
---
## 5. 可视化建站编辑器（分级实现）
### 5.1 编辑器 V1：区块式编辑
支持：增删页面、排列标准区块、替换组件样式、设定图片/文案/数据引用、编辑导航与页脚、调整设计 Token、切换 PC/平板/手机预览、草稿/审核/发布。
### 5.2 编辑器 V2：结构化可视化编排
支持：嵌套容器、列布局、响应式属性、条件显示、组件插槽、集合绑定、重复列表、页面模板编辑和全站设计系统管理。
### 5.3 编辑器 V3（可选）：高级自由设计
高级拖拽、交互动效、定制脚本、组件市场等；需严格控制任意 HTML/JS 注入与主题兼容问题。
**不建议 V1 开发任意像素拖拽引擎。** 先用区块式编辑器建立高复用度和稳定构建体验；高级主题仍允许开发者编写独立代码。
### 5.4 主题自由度分级
- L1 配置型：换色、Logo、素材和文案即可上线。
- L2 区块型：调整首页和内页的组件排列及内容映射。
- L3 高级定制型：独立开发主题，完全自定义 HTML、样式、交互和布局。
这避免为了统一拖拽而让不同网站“长得一样”。
---
## 6. 内容工厂：手动、批量、API 与旧站多源输入
### 6.1 数据输入管道
| 输入渠道 | 典型数据 | 数据处理 |
|---|---|---|
| 后台手动新增 | 文章、产品、服务、页面 | 表单编辑和字段校验 |
| Excel / CSV | 车型、价格、参数、批量产品 | 预览字段、列映射、类型推断、增量更新 |
| JSON / XML | 第三方结构化数据 | schema 映射、字段转换、关系解析 |
| API / Webhook | ERP、CRM、内部商品系统 | 授权连接、定时/手动同步、冲突策略 |
| SQL / 备份 | 原数据库内容 | 隔离解析、适配映射、数据脱敏 |
| WordPress XML/API | 文章、产品、分类、meta | WordPress 插件与字段适配器 |
| 通用网站抓取 | 公开页面、SEO、图片、菜单 | 页面发现、JS 渲染、去噪和人工确认 |
| 媒体 ZIP / 对象存储 | 图片、PDF、视频 | 去重、批量命名和资源引用映射 |
### 6.2 通用导入工作台
选择数据源 → 预览 → 识别内容类型 → 字段映射 → 数据清洗 → 去重/冲突策略 → 导入模拟运行（dry-run） → 确认入库 → 验证关联与资源 → 保留导入快照。
支持“仅新增”“按唯一键更新”“新增+更新”“人工审核冲突”；**默认不得直接覆盖人工编辑过的字段**。保留来源字段值、最新导入值、人工覆盖值及优先级。
### 6.3 内容与页面的区别
- 录入 1000 个车型，不意味着手工建 1000 个页面。
- 车型都是 `Vehicle` 内容条目；系统采用一个 `vehicle-detail` 页面模板批量生成 1000 个对应 URL。
- 新增车型后自动生成新详情页并更新分类列表、筛选数据、站点地图与内部链接。
### 6.4 媒体中心
- 原图存储，派生多尺寸格式；保留 alt、文件名、来源 URL 和使用关系。
- 旧站媒体需维护原路径映射，必要时保留原 URL 的资源响应。
- 批量上传、图库、资源去重、视频外链、PDF 和下载附件。
- 资源删除时检查使用关系；不能造成已上线页面引用失效。
---
## 7. 网站装配引擎（全产品最核心的技术）
### 7.1 输入
`site_blueprint.json + theme@version + content_snapshot + asset_manifest + route_registry + SEO_policy`
### 7.2 核心过程
1. 验证主题与内容类型是否兼容。
2. 解析页面树与导航，构造页面上下文。
3. 读取数据绑定配置，生成列表和详情集合。
4. 根据 URL/语言规则生成页面路径，检测重复与冲突。
5. 按页面模板渲染静态 HTML，并生成 CSS/JS。
6. 生成 sitemap、robots、结构化数据和必要的重定向配置。
7. 执行页面链接、SEO、媒体、性能及功能验证。
8. 形成不可变构建产物、版本元数据和差异报告。
### 7.3 装配示例：汽车站
- 公司信息绑定 `company.*`。
- 首页精选车型绑定 `vehicles where featured=true`。
- 品牌列表绑定 `brands`，每个品牌生成 `/brands/{slug}/`。
- 车型详情绑定 `vehicles`，生成 `/models/{slug}/` 或从旧站注册表获取原有 URL。
- 新闻内容绑定 `posts`，自动生成新闻列表和详情。
- PC 和移动端页面由同一语义内容驱动，但主题可采用不同响应式布局。
### 7.4 蓝图 JSON 示例
```json
{
"siteKey": "export-auto-demo",
"mode": "migration-redesign",
"theme": {"id": "automotive-premium", "version": "1.4.0"},
"locale": "en",
"designTokens": {"primaryColor": "#1765B2", "contentWidth": "1280px"},
"pages": [
{"kind": "static", "path": "/", "template": "home"},
{"kind": "collection", "path": "/products/", "template": "product-list", "contentType": "vehicle"},
{"kind": "entry", "template": "product-detail", "contentType": "vehicle", "routeSource": "registry"}
],
"navigation": {"header": ["/", "/products/", "/about-us/", "/contact/"]},
"seoPolicy": "preserve-imported"
}
```
### 7.5 主题数据绑定示例
```json
{
"template": "home",
"slots": {
"hero": {"type": "Hero", "bindings": {"title": "site.homeHero.title", "image": "site.homeHero.image"}},
"featured": {"type": "VehicleGrid", "source": {"contentType": "vehicle", "filter": {"featured": true}, "limit": 8}},
"news": {"type": "LatestPosts", "source": {"contentType": "post", "limit": 3}}
}
}
```
规则应由受控 schema/查询 DSL 解释，**禁止把任意用户输入作为数据库查询或 JS/SQL 执行**。
---
## 8. 旧站迁移子系统（Website Factory 的一个入口）
### 8.1 兼容范围与优先顺序
P0：WordPress（REST API + WXR XML + SQL + `wp-content`）、HTML 静态站、普通 PHP 公开站。P1：Drupal、Joomla、自定义 CMS、Vue/React 渲染站。P2：电商、会员、复杂业务站专用适配器。
### 8.2 自动扫描
抓取 robots、sitemap、内部链接、菜单、页面、分页、媒体和 head SEO；识别 CMS、页面类型、动态表单、语言、状态码和 canonical；得到带来源、置信度和异常标记的扫描清单。
### 8.3 迁移独有工作流
`Old Site → Snapshot → Extract → Normalize → Map To Theme → Route/SEO Preserve → Preview/QA → Cutover`
1. 建立旧站不可变快照，记录内容、URL、响应状态、SEO、媒体。
2. 能取得权限时优先组合 API/备份/网页数据，不能取得权限时抓取公开内容并标记未知项。
3. 将旧站类型映射到统一类型，例如 WooCommerce product → Product / ACF car → Vehicle。
4. 让用户选择新的视觉主题，映射旧数据字段到新页面组件。
5. 保留旧 URL 注册表、历史 301、canonical 和 SEO 元数据；异常需明示审核。
6. 禁止新主题自动重写旧路由。新增加的内容可按新建路由规则生成。
7. 预览视觉不同的新站并以旧站数据基线自动验收。
8. 发布时注意 DNS、CDN、缓存、预览 noindex、必要 API 以及回滚。
9. 上线后追踪 404、搜索抓取和流量变化；上线前后还可进行增量同步直至冻结旧站写入。
### 8.4 关键事实
公开页面采集无法保证后台未展示字段完整；网站登录、支付、购物车及实时功能不能纯静态复制；要在扫描报告中明确“可自动”“需授权”“需开发扩展”“不迁移”四种处置结果。
---
## 9. 新站创建子系统（与迁移同等优先级）
### 9.1 模板新建流程
1. 输入网站名称、主语言、品牌信息、目标行业、域名（可延后绑定）。
2. 选择模板并预览 PC/移动端。
3. 从模板生成站点蓝图、页面树、导航和内容类型定义。
4. 进入引导式公司资料表：名称、Logo、联系方式、社媒、地址、企业简介。
5. 手工或批量添加产品、文章、品牌、图片；主题根据字段绑定渲染页面。
6. 修改页面区块、主色、字体和导航，设置联系表单目标。
7. 自动生成页面、站点地图与 SEO 默认值；检查内容完整性。
8. 预览、发布、绑定域名；未来继续从后台更新。
### 9.2 空白新建流程
1. 创建站点与内容类型。
2. 配置导航/页脚和布局框架。
3. 通过区块编辑器建立页面和模板。
4. 建立动态集合页及详情路由规则。
5. 绑定内容和媒体，预览并发布。
6. 经审核将该站的可复用结构导出为主题/站点模板。
### 9.3 导入内容建站流程
1. 上传 `vehicles.xlsx`，识别标题、品牌、图片、价格、参数等。
2. 创建或选择 `Vehicle` 内容类型，建立字段映射、唯一键和数据校验。
3. 选择适合的产品站主题；若字段不足，提示补齐，而不是凭空生成。
4. 由车型集合创建列表、详情、品牌聚合页，生成对应 URL。
5. 配置通用企业资料、SEO、导航，发布成完整新站。
### 9.4 主题替换机制
切换主题时预检查必需字段、页面类型、交互能力、导航结构及 URL 兼容性。允许在临时预览环境试装，保留旧主题和站点蓝图版本；确认后切换，不删除原内容和媒体。
---
## 10. URL 与 SEO：区分“迁移”和“新建”两种政策
### 10.1 迁移站（Preserve Mode）
- 以实际旧站最终有效访问行为为基线，保留用户可见有效 URL、状态码和所需重定向链。
- Title、Description、Canonical、Robots、Hreflang、JSON-LD、Open Graph、图片 alt、内链和 sitemap 做差异比对。
- 旧 URL 到新构建产物一对一登记，包含中文路径、大小写、尾部斜杠、`.html`、分页、文件、查询参数规则。
- 404 处理必须区分原本无效和新迁移导致；如果页面已批准下线，应设置合适的 301/410 行为。
- 允许设计变化，但不能因使用新模板悄悄改变原 SEO/URL。
### 10.2 新站（Generate Mode）
- 按站点定义 slug 策略和 URL 规则；允许人工指定覆盖。
- 使用 SEO 默认模板，例如 `{product.name} | {site.name}`，并提示检查重复标题/空描述。
- 自动生成 robots、sitemap、Open Graph、必要的 JSON-LD 和 canonical。
- 多语言模式需完整管理 locale URL、翻译关联和 hreflang。
- 预览域名必须鉴权并禁止搜索索引。
### 10.3 混合模式
来源于旧站的内容使用 Preserve URL，新增内容使用 Generate URL；注册表统一检查冲突。**不能简单设置一个整站 `preserve=true` 就忽略新内容路径生成。**
### 10.4 质量门禁
迁移站关键 URL 和 SEO 的未批准差异必须阻止发布；新站的门禁主要是 URL 冲突、重复规范地址、无效内链、关键必填字段缺失和资源失效。
---
## 11. 管理后台信息架构（建议菜单）
```
SiteForge
├── 工作台 Dashboard
│ ├── 网站数量 / 最近发布 / 失败任务 / 风险
│ └── 快速操作：新建网站 / 导入内容 / 创建模板
├── 网站工厂
│ ├── 所有网站
│ ├── 创建网站向导（空白 / 模板 / 旧站 / 数据）
│ ├── 网站蓝图 / 页面树 / 菜单 / 域名
│ └── 预览 / 历史版本 / 克隆结构
├── 内容中心
│ ├── 内容类型设计器
│ ├── 文章 / 产品 / 自定义集合
│ ├── 公司资料 / 全局数据
│ ├── 数据导入与同步
│ └── 媒体资源库
├── 设计中心
│ ├── 模板库 / 主题库
│ ├── 页面模板 / 区块库
│ ├── 页面编辑器
│ ├── 全站设计 Token
│ └── 自定义主题注册与版本
├── 迁移中心
│ ├── 网站技术扫描
│ ├── WordPress / CMS 导入
│ ├── 字段映射 / 旧站快照
│ ├── URL / SEO 基线
│ └── 迁移差异报告
├── 构建与发布
│ ├── 构建任务 / 预览
│ ├── 自动验收与报告
│ ├── 发布审批 / 目标服务器
│ ├── ZIP 导出 / 历史版本
│ └── 回滚 / CDN 缓存刷新
└── 系统设置
├── 用户 / 团队 / 角色
├── API 密钥 / 数据源凭证
├── 适配器 / 扩展服务
├── 审计日志 / 告警
└── 存储 / 域名 / 环境
```
### 11.1 新建网站首页建议
四个同级入口卡片：**旧站改造、使用模板新建、导入数据建站、空白建站**。不要把“迁移”置于唯一入口，也不要把“选择模板”藏在迁移流程中。
### 11.2 网站内部工作台
概览 → 内容 → 页面 → 设计 → SEO/路由 → 预览 → 发布 → 设置。便于独立运营每个网站，不要求管理员理解数据仓库和构建细节。
---
## 12. 推荐技术选型与研发边界
| 部分 | 推荐 | 备注 |
|---|---|---|
| 后台界面 | Vue 3 + TypeScript + Element Plus / Art Design Pro | 多站点、内容编辑、区块页面编辑器 |
| 核心 API | Python FastAPI + Pydantic + SQLAlchemy | 复用 Python 采集、数据处理和内部工程经验 |
| 异步任务 | Celery + Redis（或 Dramatiq） | 采集、媒体、导入、同步、质量任务 |
| 数据库 | PostgreSQL | JSONB 扩展字段、关系表和审计日志 |
| 采集服务 | Python httpx/Scrapy + Playwright | SSR/动态页面扫描与插件适配 |
| 模板及静态生成 | Astro + TypeScript/Node Worker | 主题组件、静态页面编译、增量/全量构建 |
| 资产存储 | S3 兼容对象存储/OSS + 本地缓存 | 原图、附件、站点版本和静态包 |
| 部署 | Nginx / 对象存储 + CDN / SSH 或 Git 工作流 | 独立站交付和可回滚 |
| 任务与日志 | PostgreSQL + Redis + 集中日志 | 可追踪的导入和发布作业 |
| 运行 | Docker Compose 首选 | 后期再按规模拆分服务 |
**为什么不强制全部使用一种语言**：数据采集/规范化适合 Python；静态主题的现代前端生态适合 TypeScript/Astro。通过版本化 JSON 契约连接两个 Worker，避免牺牲网站的设计自由度。若团队对 NestJS 更熟，也可替换 API 层，不影响领域模型和构建协议。
### 12.1 部署架构
- API、PostgreSQL、Redis、导入 Worker、构建 Worker、管理前端、对象存储等分别通过容器管理。
- 每个网站生成独立不可变 `release_id` 的产物并可单独导出、上传和回滚。
- 为不同域名、地区和站点提供独立构建与部署配置。
- 预览站点与生产站点隔离，预览授权、禁止索引。
---
## 13. 数据库详细方案
### 13.1 数据库分域
**组织与权限**：`organizations`、`users`、`memberships`、`roles`、`permissions`。
**网站与蓝图**：`sites`、`site_environments`、`site_blueprints`、`site_settings`、`page_nodes`、`navigation_menus`、`navigation_items`、`site_domains`。
**内容模型**：`content_types`、`field_definitions`、`content_entries`、`entry_versions`、`entry_relations`、`content_localizations`、`global_entries`。
**媒体**：`media_assets`、`media_variants`、`media_references`、`media_source_urls`。
**模板与组件**：`themes`、`theme_versions`、`page_templates`、`component_definitions`、`component_instances`、`design_tokens`、`site_theme_bindings`。
**数据输入与适配器**：`data_sources`、`adapter_definitions`、`import_jobs`、`import_items`、`field_mappings`、`sync_policies`、`source_snapshots`、`source_identity_map`。
**URL 与 SEO**：`routes`、`redirect_rules`、`seo_records`、`seo_snapshots`、`link_checks`、`route_diffs`。
**构建发布**：`build_jobs`、`build_artifacts`、`releases`、`deployments`、`quality_reports`、`audit_events`。
### 13.2 SQL 示意
```sql
CREATE TABLE sites (
id UUID PRIMARY KEY,
organization_id UUID NOT NULL,
name TEXT NOT NULL,
site_key TEXT NOT NULL,
creation_mode TEXT NOT NULL CHECK (creation_mode IN
('blank','template','migration','data_import','clone_structure')),
default_locale TEXT NOT NULL DEFAULT 'en',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (organization_id, site_key)
);
CREATE TABLE content_types (
id UUID PRIMARY KEY,
site_id UUID NOT NULL REFERENCES sites(id),
type_key TEXT NOT NULL,
schema_json JSONB NOT NULL,
UNIQUE (site_id, type_key)
);
CREATE TABLE content_entries (
id UUID PRIMARY KEY,
site_id UUID NOT NULL REFERENCES sites(id),
content_type_id UUID NOT NULL REFERENCES content_types(id),
source_identity TEXT,
slug TEXT,
locale TEXT NOT NULL DEFAULT 'en',
status TEXT NOT NULL DEFAULT 'draft',
data_json JSONB NOT NULL,
version INTEGER NOT NULL DEFAULT 1,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE site_blueprints (
id UUID PRIMARY KEY,
site_id UUID NOT NULL REFERENCES sites(id),
revision INTEGER NOT NULL,
blueprint_json JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (site_id, revision)
);
CREATE TABLE routes (
id UUID PRIMARY KEY,
site_id UUID NOT NULL REFERENCES sites(id),
locale TEXT NOT NULL,
path TEXT NOT NULL,
behavior TEXT NOT NULL, -- render | redirect | gone | proxy
target_entry_id UUID NULL REFERENCES content_entries(id),
target_url TEXT NULL,
source_kind TEXT NOT NULL, -- imported | generated | manual
UNIQUE (site_id, locale, path)
);
CREATE TABLE build_jobs (
id UUID PRIMARY KEY,
site_id UUID NOT NULL REFERENCES sites(id),
blueprint_revision INTEGER NOT NULL,
theme_version TEXT NOT NULL,
input_manifest JSONB NOT NULL,
status TEXT NOT NULL,
started_at TIMESTAMPTZ,
finished_at TIMESTAMPTZ
);
```
数据库 DDL 只是结构示意；正式实现应补全租户隔离策略、外键/索引、关系类型、软删、版本表、迁移脚本和审计字段。`source_identity_map` 不应在跨数据源之间简单依赖 slug 去重。
### 13.3 数据治理约束
- 以 `organization_id + site_id` 强制作用域隔离，查询接口必须实现授权校验。
- 导入前保存 raw source；标准化后保留原来源与变更来源。
- 使用内容版本快照支持回滚和差异查看。
- 记录手动字段覆盖，不允许重导入无声覆盖。
- 涉及多语言、复杂关系、复用媒体时，不用一张任意 JSONB 表取代所有关系模型。
---
## 14. 核心 API 契约（示意）
```text
POST /api/sites # 建立网站；body.creationMode
GET /api/sites # 站点清单
GET /api/sites/{siteId}
POST /api/sites/{siteId}/clone-structure
GET /api/themes # 主题库
GET /api/themes/{themeId}/versions
POST /api/sites/{siteId}/theme/preview # 试装主题/兼容性检查
POST /api/sites/{siteId}/theme/activate
GET /api/sites/{siteId}/blueprint
PUT /api/sites/{siteId}/blueprint # 乐观锁 revision
GET /api/sites/{siteId}/content-types
POST /api/sites/{siteId}/content-types
GET /api/sites/{siteId}/entries
POST /api/sites/{siteId}/entries
PATCH /api/sites/{siteId}/entries/{entryId}
POST /api/sites/{siteId}/imports # 文件/API/CMS/旧站导入
POST /api/imports/{jobId}/dry-run
POST /api/imports/{jobId}/commit
GET /api/imports/{jobId}/conflicts
GET /api/sites/{siteId}/routes
GET /api/sites/{siteId}/seo-audit
POST /api/sites/{siteId}/builds
GET /api/builds/{buildId}
POST /api/sites/{siteId}/releases/{releaseId}/publish
POST /api/sites/{siteId}/deployments/{deployId}/rollback
GET /api/sites/{siteId}/quality-reports
```
### 14.1 任务状态机
`created → queued → running → needs_review | failed | completed`；构建验收后再从 `completed` 经 `approved → published`，允许取消、重试、失败恢复，但每个状态转换须有审计记录。
### 14.2 构建契约
Node/Astro 构建 Worker 只接受经过签名/授权访问的不可变输入 manifest，输出静态包路径、构建报告、内容 hash、资源清单和验收结果；不要将数据库直接暴露给静态构建主题代码。
---
## 15. 质量验收体系（按建站模式执行）
### 15.1 通用验收
- 所有必需页面可访问、无冲突路由、没有意外 404/5xx。
- 内容、分类、关联、图片和附件链接完整；过滤 XSS 等不可信脚本。
- PC / 移动端核心页面无溢出、错位和严重布局问题。
- sitemap、robots、canonical 与发布目标域名一致。
- 站点预览不被搜索引擎收录，正式站按配置开放索引。
- 表单、询盘、导航、搜索等启用功能经过实际测试。
- 发布包可在隔离环境部署并独立访问；能回滚。
### 15.2 迁移专用验收
- 旧站已发现的有效 URL 都有一致访问或批准例外；关键路径的未批准变化阻断发布。
- SEO 标题、描述、canonical、robots、hreflang 等做旧/新对照。
- 产品/文章/页面数与旧站基线差异有解释；不可获取内容明确列出。
- 资源与重定向规则逐项校验；上线后持续关注抓取和错误。
### 15.3 新站专用验收
- 必填企业信息、Logo、联系路径和站点语言完整。
- 集合列表与详情页数量正确，新增内容可以重新生成网页。
- SEO 自动生成规则没有导致大量重复标题或无意义内容。
- 所选模板适用内容字段，缺失信息不能通过臆造补全。
### 15.4 验收报告分级
`BLOCKER`（必须解决）/ `WARNING`（可人工批准）/ `INFO`。不要把“页面加载成功”视作“内容迁移完整”。
---
## 16. 构建、部署、静态导出与持续更新
### 16.1 全量与局部构建
V1 可先全量构建保证正确性；V2 根据内容变化计算影响依赖：更新车型 → 对应详情、分类、品牌列表、首页精选和 sitemap 等重建。依赖图要可追踪，以免漏刷引用页。
### 16.2 交付格式
```
release-2026-10-21-a1b2/
├── public/
│ ├── index.html
│ ├── about-us/index.html
│ ├── products/index.html
│ ├── products/example/index.html
│ ├── assets/...
│ ├── sitemap.xml
│ └── robots.txt
├── server/
│ ├── nginx.conf.example
│ └── redirects.json
├── manifest.json
├── quality-report.json
└── deployment-notes.md
```
旧站存在 `.html`、尾斜杠与目录结构差异时，按照路由注册表选择适当静态目录或 Web 服务器规则；**输出文件路径本身不代表 HTTP 访问语义自动等同**，必须经过实际服务器验收。
### 16.3 部署策略
- 预览 / staging / production 三级环境，可选择简化为 preview + production。
- 产物不可变、版本化；原子切换部署；媒体缓存和 HTML 缓存采用不同策略。
- 支持 ZIP 下载、SSH/SFTP、Git CI、对象存储 + CDN；不同站点独立域名和缓存。
- 发布操作与回滚操作留存操作人、时间、版本和差异。
### 16.4 外部服务扩展
表单、询盘、搜索、评论、登录等由独立功能适配器负责；主题仅通过公开的组件/客户端 SDK 调用，避免各站重复实现且不把平台后台变成生产站依赖。
---
## 17. 安全、权限、成本与可维护性
- **采集 SSRF**：阻断内部 IP、云元数据地址、敏感主机及重定向跳转；抓取速率限制、URL 白名单、robots 与站点使用权限审查。
- **文件安全**：ZIP 解压路径穿越、恶意 HTML/JS/PHP、上传扩展名、MIME、体积限制与资源扫描。
- **数据隔离**：租户、站点、内容、媒体、API 凭证严格隔离，导出权限与发布权限分离。
- **主题安全**：主题依赖锁定、审核第三方组件、禁止把未审核用户表达式转换为运行代码。
- **SEO 安全**：导入外站数据时不能盲目继承失效域名 canonical/跳转目标；必须判别并显示冲突。
- **构建安全**：构建 Worker 沙箱、资源/CPU/时间限制、审计命令、脱离机密生产凭证。
- **版本安全**：导入快照、内容版本、主题版本、发布版本皆可追溯与恢复。
- **数据备份**：数据库备份、媒体/源快照、构建物及密钥轮换政策。
---
## 18. 开发路线图：从最小“网站工厂”开始
### 阶段 0 — 架构与样本验证（建议 2–3 周）
成果：Site Blueprint schema、内容类型/字段协议、主题 manifest、路由引擎规则、导入/构建 JSON 契约、站点项目 UI 原型；准备 3 个试点样本（WordPress 迁移、新站模板、新数据批量导入）。
### 阶段 1 — MVP 网站工厂（建议 6–10 周）
**必须同时具备“新建”和“迁移”两条路径。**
- 站点项目管理、主题目录（至少两套不同设计）、站点蓝图。
- 内容模型（页面/文章/产品/分类、可扩展字段）、媒体上传与基础编辑。
- 模板新建、CSV/Excel 导入、WordPress 核心内容导入。
- 页面装配/静态构建、基本 URL/SEO 模式、预览与 ZIP 导出。
- 自动验收、单站版本管理。
验收：同一系统能生产一个无旧站的新网站和一个 WP 迁移重建网站；两站视觉结构不同且可独立访问。
### 阶段 2 — 可规模化多站点运营（建议 6–10 周）
- 通用网站爬虫与插件适配器、字段映射工作台。
- 主题兼容性检测、区块式编辑器、页面/菜单可视化设置。
- 增量导入、媒体处理、版本化部署与一键回滚。
- URL/SEO 完整旧新站差异报告、批量质量门禁。
- 多站点、多权限、多环境和站点克隆结构。
验收：至少一个非 WordPress 站可迁移，模板与数据独立升级可运行。
### 阶段 3 — 完整模板工厂与自动化（按实际业务决定）
- 可视化页面模板编辑、组合式区块库。
- 自定义主题 SDK 和内部主题市场、模板版本升级迁移。
- API 数据同步、任务计划、依赖图增量构建。
- AI 内容分类、字段匹配和页面布局建议（人工审核）。
- 更多 CMS / ERP 适配器和复杂组件。
> 时间均为粗略研发规划区间，不是工期承诺；应基于团队人数、模板复杂度、实际旧站数据和试点验收调整。
---
## 19. 研发团队协作与目录建议
```text
siteforge/
├── apps/
│ ├── admin-web/ # Vue 管理后台
│ └── api/ # FastAPI 主服务
├── workers/
│ ├── imports/ # 导入与数据清洗
│ ├── crawler/ # 旧站抓取和 CMS 适配
│ ├── media/ # 媒体处理
│ ├── builder/ # Astro 构建服务
│ └── qa/ # URL/SEO/功能验收
├── packages/
│ ├── blueprint-schema/ # 站点蓝图协议
│ ├── content-schema/ # 内容与字段协议
│ ├── adapter-sdk/ # 数据源接入接口
│ ├── theme-sdk/ # 主题数据绑定/组件接口
│ ├── route-engine/ # 路由规则与映射
│ └── build-contract/ # 输入/输出 manifest
├── themes/
│ ├── corporate-clean/
│ ├── automotive-premium/
│ └── industrial-b2b/
├── migrations/ # 数据库演进
├── docs/ # PRD、ADR、API、模板规范
├── tests/ # 完整端到端样本
└── infra/ # Docker、Nginx、CDN、CI
```
### 19.1 设计/数据/研发协作界面
- 设计师交付主题原型与组件规范。
- 研发把组件封装成可配置主题，声明需要哪些数据字段。
- 内容人员录入内容和映射字段，不需修改代码。
- 项目负责人检查预览并发布。
- 可选开发人员继续以 SDK 开发特殊功能，保持独立品牌差异。
### 19.2 文档最小集合
PRD、站点蓝图 JSON Schema、Theme Manifest、组件数据绑定规范、适配器 SDK、数据模型 ERD、API OpenAPI、任务状态机、部署/回滚手册、验收测试用例。
---
## 20. 首批试点与详细验收用例
### 试点 A：旧 WordPress 汽车网站 → 新汽车主题
提供 WordPress XML + SQL/媒体（若可用）+ 网站 URL；输出文章/车型/品牌/分类和 SEO；选择全新汽车主题；旧站现存核心 URL 不改变；首页/品牌/车型详情样式与旧站不同；确认可离线发布。
### 试点 B：新建工业品网站（无任何旧站）
选择工业主题 → 添加公司 Logo/简介/联系方式 → 批量上传管材 Excel 和图片 → 自动生成产品分类与详情 → 配置联系页面 → 预览 → 以纯静态文件发布。
### 试点 C：已有网站 + 新数据混合
在 A 项目后续导入新一批产品 CSV：仅新增/更新相应产品，不覆盖旧文章与人工编辑；新增页面按新规则生成路由；原迁移 URL 不改变；系统更新受影响页面与 sitemap。
### 试点 D：空白页面 → 保存为模板 → 复用到第二个网站
从空白建立官网页面树和首页组件结构，绑定内容字段，保存为可复用模板；新项目使用该模板和另一套公司资料生成不同网站，不复制试点的私有内容。
**上述四个试点是网站工厂成功与否的核心验收，不允许用“只完成 WP 迁移”代替。**
---
## 21. 风险与关键决策
| 风险/问题 | 对策 |
|---|---|
| 模板不适配导入数据 | 主题声明字段和页面能力，预检查并引导补齐字段 |
| “一键搬家”遗漏旧数据 | 多源交叉提取、数据覆盖率报告、人工审核和异常列表 |
| 新主题导致旧 URL 改变 | URL 注册表独立于主题、迁移模式发布门禁 |
| 模板升级覆盖独立设计 | 主题版本锁定、兼容检测、差异预览、独立站点覆盖层 |
| 内容修改无法及时更新静态站 | 事件触发构建、预览与人工或自动发布策略 |
| 大站生成耗时过长 | 静态构建分批、缓存、增量依赖、构建 Worker 并发 |
| 复杂业务功能无法静态化 | 独立服务/API 适配器、功能清单和迁移边界确认 |
| AI 生成错误产品参数或公司事实 | 不凭空补全、标记来源和置信度、人工审阅 |
| 运营长期绑定平台无法退出 | 保证完整静态包、资源与服务器规则可导出 |
### 21.1 推荐冻结的架构决策
1. Website Factory 为总产品；Migration Center 仅是子模块。
2. 模板和内容分离；Site Blueprint 负责装配。
3. 四种同级建站入口；导入在网站创建后随时可用。
4. “旧站 SEO 保真”与“新站 SEO 生成”是两种独立策略。
5. 线上输出优先真正静态文件；额外动态能力作为可选扩展。
6. 站点、内容、媒体、主题、蓝图、构建物独立版本化。
7. 第一阶段不追求任意像素自由拖拽，保留独立主题开发能力。
---
## 22. 可立即拆解的第一轮开发任务
### Sprint A：基础项目与协议
- 建立仓库、开发环境、CI、PostgreSQL、Redis、身份与网站项目模型。
- 完成 Site Blueprint / Theme Manifest / Content Type Schema 草案及验证器。
- 创建模板库 UI、四入口建站首页和站点工作台初版。
### Sprint B：内容 + 模板 + 构建闭环
- 手动创建产品、文章、基本页面和媒体。
- 实现两种设计风格不同的主题，完成数据绑定和列表/详情页生成。
- 输入规范 manifest，Astro 全量构建、预览站点和 ZIP 导出。
### Sprint C：数据导入 + WordPress 迁移
- CSV/Excel 字段映射、dry-run、幂等更新、异常行报告。
- WordPress WXR/API 导入和图片资源迁移。
- 旧站 URL/SEO 基线及 Preserve Mode。
### Sprint D：上线级质量闭环
- URL/SEO/媒体/内链验收、构建版本、发布审批和回滚。
- 四项端到端试点验收；填写已知限制和改进清单。
---
## 23. 最终交付物清单
- SiteForge 管理后台（含四种建站入口）。
- 通用内容中心、动态内容类型、媒体库、导入工作台。
- 模板/主题/组件中心、站点蓝图、区块式页面配置。
- WordPress 适配器、通用爬虫、Excel/CSV/JSON 导入能力。
- 静态装配与构建引擎，包含 ZIP 导出与独立服务器部署。
- 旧站路由与 SEO 比对、新站 SEO 自动生成、自动验收和质量报告。
- 多网站环境/发布/回滚/权限/审计能力。
- 至少三套不同业务风格的参考主题与必要主题 SDK 文档。
- 四个试点通过报告、自动化测试、开发部署手册和数据恢复演练。
---
## 24. 一句话总结
**SiteForge 是“有内容就能造网站、没有内容也能从零造网站、有旧网站就能搬内容换设计、造完还能持续管理和再次生成”的通用网站工厂。**
旧站迁移、内容管理、主题市场、页面设计、SEO、静态构建与发布，都是围绕“生产网站”这一核心能力服务的工序，而不是独立产品的拼接。
Reference in New Issue Copy Permalink