xinyouhe/cms-SiteForge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: import SiteForge Factory V5 source (baseline)

Browse Source 
导入 SiteForge Factory V5 基线源码：
- FastAPI + SQLite + Docker Compose（Web + Worker）架构
- 四套商业主题 × 14 页面模板（1.1.0，含历史版本快照）
- 四种建站模式骨架 + 迁移审计 + 发布门禁
- 52 项 pytest 测试
- 补全计划主文档 docs/superpowers/plans/

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
2026-10-22 10:42:19 +08:00
commit 3c57c167f2
264 changed files with 11682 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CHANGELOG_v0.3.md
+17
View File
@@ -0,0 +1,17 @@
# SiteForge v0.3 变更
## 从 v0.2 到 v0.3
- 新增 `app/blueprints.py`：受限的页面区块协议、区块输入校验、字段占位符、动态内容数据源和网页 HTML 渲染。
- 四套主题新增 `manifest.json` 与 9 种 `page-presets.json`，支持独立行业主题的页面预设。
- 增加 11 类实际渲染的页面区块及共享响应式 `blocks.css`。
- 新增完整屏可视化编辑器 `/editor/{site_id}/{entry_id}`：区块拖拽排序、属性面板、预览、保存、构建。
- 新增站点内容类型字段模型管理及数据结构存储、导航编辑和静态绑定参数表。
- 新增 `/apply-theme` 批量一键套版，以及 `/scaffold` 默认栏目初始化。
- 旧的 WordPress / CSV / XLSX / JSON / 静态导出和登录机制保留，已有旧站内容不自动覆盖。
- 新增 Art Design Pro Vue3 / Element Plus 独立对接示例（非官方完整前端代码）。
- 编写新增端到端 API 单测，旧用例继续回归。
## 风险与后续重点
开发版暂未实现基于官方 Art Design Pro 工程的实际构建、复杂页面组件多级布局、全站实时预览、复杂插件迁移、分布式任务队列、企业角色权限、公共云多目标部署。Docker 尚须在用户的运行环境验证镜像构建及持久卷。
docs/COMMERCIAL_THEME_V5.md
+57
View File
@@ -0,0 +1,57 @@
# SiteForge V5 商业主题交付说明
> V5 是在 V4 原有后台、内容模型、编辑器与构建流程上迭代的**行业网站主题交付候选版**。完成页面功能及技术回归，不代表现已取得各类网站的商用法律、运营或视觉验收。
## 本轮实际开发
- 四个独立主题 Automotive、Industrial、Corporate、Minimal，继续保留各自 14 类页面模板。
- 页面视觉重新整理：商业版字体排版、节奏、卡片、详情与参数布局、按钮交互、移动端适配；四套不同视觉方向。
- 主题自带本地 SVG 视觉示意素材，可离线浏览；上传企业正式图片或 Logo 后，会优先展示真实素材。内置插画不是实际产品图片，请正式交付前替换。
- 全站 Logo 优先使用网站实际配置。导航多级菜单、品牌与分类目录、产品画廊、筛选、对比页面结构等保持数据驱动。
- 移动端导航与筛选空状态、键盘焦点、减少动态效果偏好等交互改进。
- 站点 OG 标题/摘要与主题色，继承站点已有 Title/SEO/Canonical/Robots，不自行修改迁移来源 URL。
- 建立商业交付报告 `commercial-readiness.json`，提示演示内容、占位图、Logo、询盘渠道及隐私说明等待人工验证事项。报告也在 `siteforge-report.json` 包含摘要。这与静态质量检测分开，**不会虚构已合规或已上线**。
- 新增主题 `1.1.0`。保留 V4 主题 `1.0.0` 的完整模板快照供已锁定旧主题的站点使用；更旧的 `0.3.0` 仍保留。
- 修正后台主题预览的商业 CSS 与本地 SVG 资源加载，使其与构建所用主题文件一致。
## 四套主题的业务定位
| 主题 | 风格与重点 | 常见栏目 |
| --- | --- | --- |
| Automotive | 深蓝与暖金、大幅车辆展示、车型与品牌分区 | 首页/车型/品牌/参数/新闻/案例/联系 |
| Industrial | 浅蓝与工程网格、产品分级、规格表 | 首页/分类/产品/规格/案例/技术文章/联系 |
| Corporate | 现代紫白体系、业务能力与项目展示 | 首页/服务/关于/案例/新闻/联系 |
| Minimal | 中性色编辑式布局、作品陈列 | 首页/作品/服务/简介/联系 |
## 快速使用
1. Docker Desktop 启动后，在项目目录初始化 `.env`，然后运行 `docker compose up -d --build`。
2. `http://localhost:8787/` 登录。`/theme-gallery` 查看主题，`/factory-studio` 创建网站。
3. 在网站项目中初始化完整栏目，添加企业资料、Logo、正式邮箱、产品与文章。
4. 选择主题版本 `1.1.0`、预览、生成静态站并在 ZIP 中查看 `commercial-readiness.json` 与 `siteforge-report.json`。
5. 完成真实设备、内容、图片版权、SEO、表单、法律页面与性能检查后再上线。
## 商业交付前人工验收清单
- [ ] 企业 Logo、品牌颜色、产品主图、图库和版权授权材料均已填入；不再使用演示素材。
- [ ] 首页、关于、产品、品牌、新闻、案例、联系与 404 页面逐页核对；不允许空栏或虚构数据。
- [ ] PC 1440px/1024px、手机 390px/360px 等设备检查，尤其是中文/英文长标题和多级菜单。
- [ ] 真实询盘接收渠道已配置并实际发送验证；如连接第三方表单，需要其隐私和防垃圾邮件机制。
- [ ] Title、Description、Canonical、Robots、Sitemap 和历史 URL 与旧站基线一致（仅迁移项目）。
- [ ] 图片与 PDF、内部链接、搜索、筛选、参数/画廊和键盘操作实际验证。
- [ ] 业务文案和业绩指标经过企业审核，隐私政策/法律页按目标市场要求配置。
- [ ] 部署环境的 HTTPS、缓存、日志、备份、回滚、安全与压力测试已通过。
## 当前不在本轮保证范围
不保证任意 WordPress/Elementor/ACF/WooCommerce 无损迁移；不提供任意代码主题安全安装、内置邮件服务器、完整 Art Design Pro 官方仓库整合、PostgreSQL/Redis、多云一键发布，也未完成正式生产环境合规或多浏览器全面测试。构建通过只是技术成功，`commercially_certified` 固定为 `false`。
## 测试方法
```bash
python -m pytest -q
PYTHONPATH=. SITEFORGE_DEMO_OUT=/tmp/siteforge-demo python scripts/make_theme_demo.py
python scripts/make_offline_preview.py /tmp/siteforge-demo /tmp/siteforge-preview.html
```
静态演示使用虚构内容，包含各主题的本地 `visual/hero.svg`；不依赖第三方图片服务。
docs/IMPLEMENTATION_V4.md
+22
View File
@@ -0,0 +1,22 @@
# V4 功能验收矩阵
| 用户期望 | 本次已实现 | 继续开发/验收 |
|---|---|---|
| 四套完整行业主题 | 原 V3 的四套主题共 56 组独立模板；V4 追加多级导航、产品图库 Lightbox、可配置 HTTPS 表单和主题兼容性检查 | 专业素材、真实表单接收服务、复杂车型筛选逻辑与视觉优化 |
| 可视化组件设计 | 支持编辑器响应式多列布局、列内区块、全页自由布局/追加模式、完整主题预览、可复用组件库 | 自由网格画布、高级排版控制、多人实时协作 |
| 内容智能装配 | Excel/CSV/JSON 解析预览、字段别名、车型/能源/续航/图库/参数绑定、关系报告与品牌空页面装配 | 多值关系、多语言和复杂字段映射、AI 语义匹配需人工确认 |
| WordPress 迁移 | WXR/REST 等原有路径 + V4 特殊字段转换、SEO 清单、静态构建差异和人工复核机制 | SQL 全库深度适配、复杂插件无损解析及真实站验收 |
| 发布前审计 | WXR/sitemap/CSV/JSON 基线；实际 HTML 路由、title、description、canonical、robots、H1 和质量检查；差异 CSV；单条人工接受理由 | 真实 HTTP 状态 / CDN 规则与线上 Google Search Console 指标监控 |
## 源数据验证标准
- 未抓取/导出的路径不能自动假设不存在。
- HTTP 200 的源路径必须有对应 HTML，缺少会阻断发布。
- SEO 源数据缺失时只报告已知差异，不虚构旧站 metadata。
- 所有警告必须审核接受或修复后重新构建；结构阻断项不允许直接接受例外。
- 复杂 Elementor、ACF、WooCommerce 数据保留原始字段，部分安全转换并列出人工核查项。
- 构建产物中不得出现未识别的本地资源/内链错误；外部资源应按实际站点审核是否本地化。
## 运行安全界限
本项目不提供 Docker 容器启动成功的保证。不要将默认测试端口直接暴露公网；请配置 HTTPS、限流、备份、生产安全审计。管理中心与客户静态网站独立部署。
docs/PRODUCTION_ROADMAP.md
+17
View File
@@ -0,0 +1,17 @@
# SiteForge 企业正式生产化清单
本项目实现了单机 Docker Web 形式的网站生产核心功能。要达到大型企业多团队多环境长期运行标准，还应完成如下工程工作（不属于本次已验证能力）：
1. **数据库和队列**：从当前 SQLite WAL 单实例升级到 PostgreSQL（Alembic 迁移、多租户行级访问控制、连接池）和 Redis/RabbitMQ + Worker；构建任务幂等、重试退避、死信队列、任务超时和容量控制。
2. **账号与认证**：接入 OIDC / SSO、MFA、账号生命周期、细粒度角色审批、管理员紧急停用和会话撤销。当前 Cookie 签名在有效期内仍需账户禁用验证。
3. **审计不可抵赖**：当前审计日志与主库共存，应写入追加型独立日志、配置审计保留策略和异地日志汇聚。
4. **主题市场与沙箱**：严格的主题 Manifest 版本约束、组件兼容性、预览沙箱、第三方主题供应链签名、模板回滚和主题资产扫描。
5. **高级可视化编辑**：页面级断点独立控制、样式变量冲突检测、组件属性 Schema、草稿分支、多人冲突锁、预览审批，避免用户自定义不受控的 HTML/JS。
6. **大型 CMS 迁移**：WordPress 数据库/ACF/Elementor/WooCommerce 扩展适配器、Drupal、Joomla、Shopify/Headless CMS 权限 API、分页重试和导入幂等；开放页面爬虫不可替代私有源数据。
7. **静态 QA**：旧站抓取 URL 完整性（包含状态码/Canonical/Hreflang/HTTP 缓存/结构化数据）、手机/桌面视觉差异、在线域名上线后的真实 301/404 响应检查，Search Console 监测。
8. **安全**：运行时镜像与 Python 包漏洞扫描、供应链锁文件、SSRF DNS pinning / 网络 egress ACL、文件解析沙箱、病毒扫描、限流共享 Redis、CSP/安全响应头、DNS/CDN 变更审批。
9. **发布管道**：Nginx/Caddy/对象存储/CDN 多提供商部署器、同步版本清单、预部署审核、流量切换、回滚、不同环境变量密钥管理。
10. **运维 SLO**：Prometheus/OpenTelemetry、集中日志、异常报警、备份异地与还原演练、容量规划、真实 Docker/Kubernetes 压测及 RPO/RTO 目标。
11. **Art Design Pro 官方集成**：取得有权使用的 Art Design Pro 版本源码，按对应版本路由/权限系统接入并在 Node 构建环境完整测试、验证其许可证要求。
建议实施顺序：正式试点环境 → 真实 WP 站迁移基线验收 → PostgreSQL/队列 → Art 前端正式整合 → 安全审计 → 大型网站灰度发布。
docs/RELEASE_STATUS_V2.md
+29
View File
@@ -0,0 +1,29 @@
# SiteForge V2 六大优先级 · 开发交付与验收状态
最后核对：2026-10-21。本文件用“已实现/基础实现/未实现/未验证”分别记录，不把开发代码视为已通过生产验收。
| 用户要求 | 当前交付的可用能力 | 尚需继续的功能 | 状态 |
|---|---|---|---|
| ① 完整主题 | 四套独立设计、9 类页面预设、导航/响应式页脚、静态搜索和筛选、上传声明式主题 ZIP、版本管理、预览、站点固定版本 | 更完善的商业设计资产、更多独立布局组件、高级导航交互、行业专题详情定制 | 基础实现，视觉未商业验收 |
| ② 可视化编辑 | 区块拖拽排序/增删/复制、图片上传、预览双击文字编辑、PC/平板/手机布局差异、设计 Token、构建实时生效 | 任意布局嵌套/多层栅格、任意元素拖放、实时协同、完整撤销/重做、复杂动画 | 结构化区块编辑已实现 |
| ③ 内容智能装配 | 产品/车型/品牌映射、字段别名识别、规则保存、CSV/JSON 映射预演、冲突报告、实际导入、内容关联列表和详情 | 多层关联复杂自动识别、AI 语义识别、全量 Excel/数据库字段映射后台工作流和数据质量分析 | 规则式自动装配已实现 |
| ④ 完整旧站迁移 | WP WXR/REST、公开爬取、CSV/XLSX/JSON、ACF/Woo 部分字段、原 URL 基线、SEO 差异/404/资源质量检查、发布门禁 | Elementor 深度重构、完整 Woo 业务数据、非 WP 专有 CMS/数据库深度迁移、真实网站逐页验收 | 基础迁移，**不保证无损** |
| ⑤ 正式 Art Design Pro | Vue3 业务页面与官方工程离线接入脚本；完整可用原生 Web 控制台 | 官方完整工程及依赖集成、前端生产构建、路由与登录权限同构、官方 UI E2E | **尚未正式完成** |
| ⑥ 企业级发布运维 | 登录 RBAC、操作审计、异步 Worker、双人审批、本地发布、版本回滚、Docker Compose 数据卷 | PostgreSQL/Redis、多实例高可用、远程发布/HTTPS/CDN、监控告警、压测/渗透/容灾演练 | 基础交付，**未完成生产化** |
## 本次可以跑通的闭环
- 从空白新建站点 → 初始化标准栏目 → 添加/导入内容 → 选择主题 → 设计区块 → 构建 → 预览 → 导出静态站。
- 旧站内容按字段导入 → URL 和 SEO 基线 → 更换主题 → 检查是否丢页 → 审批 → 本地发布。
- 一个账号仅能管理授权网站；不同账号申请与审批。新增版本后原内容保持可追溯。
## 生产发布前的强制验收
- [ ] 真实 Docker 环境完成 Compose 构建与 Web/Worker 启停验证。
- [ ] Art Design Pro 官方代码整合并通过 `pnpm build`、浏览器验收（若坚持用它作为唯一后台）。
- [ ] 数据卷、数据库升级方案、异地备份和恢复演练。
- [ ] 真实旧站全量 URL/SEO/资源清单与新站差异报告无未处理阻断项。
- [ ] 登录/权限/CSRF/SSRF/上传文件安全检查和渗透测试。
- [ ] CDN/HTTPS/多域名发布、回滚、容量和性能验收。
**结论：这是可继续扩展的 V2 开发集成版本，不等于六项要求全部生产级完成。**
docs/SiteForge_V2_Architecture.md
+905
View File
@@ -0,0 +1,905 @@
# 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、静态构建与发布，都是围绕“生产网站”这一核心能力服务的工序，而不是独立产品的拼接。
docs/superpowers/plans/2026-10-22-siteforge-completion-master-plan.md
+133
View File
@@ -0,0 +1,133 @@
# SiteForge 网站工厂补全 — 主计划（Master Plan）
> **For agentic workers:** 本文档是路线图级主计划。每个 Phase 会各自展开为独立的任务级实施计划（TDD、bite-sized steps），按 superpowers:writing-plans 流程单独编写和评审后再执行。
**Goal:** 把现有 SiteForge V5（四种建站模式骨架已完成 ~70%）补全为需求定义的"智能网站生产工厂"：四种模式名实相符、可组合、可随时修改、可一键交付。
**Architecture:** 全部在现有 FastAPI + SQLite + 声明式主题/区块架构上增量演进，不推倒重来。每个 Phase 独立交付可测试的软件，完成后系统始终可用。
**Tech Stack:** Python 3.12 / FastAPI / SQLite（Phase 5 前不换）/ Jinja2 / 原生 JS / Docker Compose
---
## 前提与决策点（实施前需用户确认）
| # | 决策 | 推荐 | 影响 |
|---|---|---|---|
| D1 | 多语言方案 | **站点级复制 + hreflang 互链**（一个语言一个 site，跨站关联），不改 entries 表结构 | 单站多语言混存需重构 route 唯一约束和全部主题模板，代价高且当前无此需求证据 |
| D2 | 数据库连接器首发 | **MySQL 只读**（WordPress 老站生态主流） | 决定 Phase 2 连接器实现顺序 |
| D3 | PostgreSQL 迁移时机 | **推迟到 Phase 5**（试点验证后再做） | 提前做会拖慢所有功能迭代 |
| D4 | Phase 顺序 | 1→2→3→4→5 | Phase 1 最快见效（纯编排已有 API） |
## 工程前提（阻塞项，最先做）
- [ ] **P0-1: `git init`** —— 当前项目不是 git 仓库，任何实施前必须先有版本控制（.gitignore 已存在，需补 `storage/`、`.env`、`*.png` 截图）
- [ ] **P0-2: 修复实测发现的 3 个缺陷**：
- compose.yaml 双服务同标签构建冲突：`docker compose up -d --build` 失败（已验证规避法：先 `docker compose build siteforge`）。修法：worker 服务加 `build: false` 或 image 复用策略
- worker 容器 unhealthy：worker 服务加 `healthcheck: disable: true`（继承镜像 HEALTHCHECK 探测 8787 所致）
- favicon.ico 404：补一个内置 favicon 路由
- [ ] **P0-3: CI 自检脚本**（`scripts/ci.sh`：pytest + compileall + node --check，与 README 自检命令一致）
---
## Phase 1 — 模式 A 补全：迁移向导（"输入旧站地址"一站式）
**解决缺口：** 模式 A 现在要手动 5 步；需求是输入地址后系统自动编排。无表结构变更，纯编排层，最快见效。
**Files:**
- Create: `app/migration_wizard.py`（向导状态机 + 编排逻辑）
- Create: `app/static/wizard.js`（前端步骤面板，挂在 factory-v2）
- Modify: `app/factory_api.py`（挂载向导路由）
- Modify: `app/db.py`（wizard_state 表）
- Test: `tests/test_migration_wizard.py`
**功能拆解：**
1. `POST /api/factory/sites/{site}/wizard/start` `{url}` → 调 `adapters.analyze()` 识别平台 → 返回推荐路径（WP REST / WXR 上传 / 爬虫 / 基线上传）
2. 向导状态机（pending → analyzed → importing → baseline → media → done），每步可重试、可跳过，状态落库
3. WP REST 全量分页导入（现有 1000 条上限 → 10000，走 worker 队列异步 + 进度查询）
4. 媒体自动发现：导入完成后自动生成 assets inventory（现有 API），向导里展示"待本地化图片清单"并提供构建时镜像开关
5. sitemap.xml 自动拉取生成基线（当前基线只能手动上传文件；加一个"从 URL 拉取 sitemap"入口，受 ensure_public_url 约束）
6. 爬虫容量 60 → 200 页，带 robots.txt 检查
**验收标准：** 输入一个真实 WordPress 站地址，向导引导完成 内容导入→基线→媒体清单→构建→审计报告 全流程，中途退出可恢复状态。
---
## Phase 2 — 模式 C 补全：数据源连接器 + 自动匹配
**解决缺口：** XML 不支持、数据库/API 连接完全没有、"自动识别类型/自动匹配模板"没有。
**Files:**
- Modify: `app/table_loader.py`（+XML 行解析）
- Create: `app/connectors.py`（MySQL/PG 只读连接器框架 + 凭据加密存储）
- Create: `app/content_sense.py`（列名/值特征打分 → 内容类型 + 行业主题推荐）
- Modify: `app/importers.py`、`app/factory_api.py`（连接器端点、批量导入走 worker）
- Modify: `app/worker.py`（新 job kind: `import`）
- Test: `tests/test_connectors.py`、`tests/test_content_sense.py`
**功能拆解：**
1. 通用 XML 数据导入（任意扁平/两层 XML → 行记录，走现有 mapping 管道）
2. MySQL 只读连接器：连接配置（主机/库/账号）用 Fernet 加密存库；只允许 `SELECT`，白名单表，单表 ≤10000 行，超时与行数硬上限；预览表结构 → 选表选列 → 进 mapping 管道（复用 dry-run/commit）
3. PostgreSQL 连接器（同框架第二实现）
4. `content_sense`：对解析后的 columns+样本行打分（品牌/价格/续航→vehicle；作者/日期→post；案例地点→case），输出推荐 content_type 与推荐主题（automotive/industrial/corporate/minimal 关键词匹配），前端"智能推荐"面板一键采纳
5. 大批量：mapping commit 改为分批（500/批）入 worker 队列，前端进度条；上限 1000 → 50000
**验收标准：** 上传一份 5000 行车型 Excel → 系统推荐 vehicle 类型 + automotive 主题 → 异步导入完成 → 构建出含分类/品牌聚合页的完整站点。连一个测试 MySQL 库选表导入同样走通。
---
## Phase 3 — 模式 D 补全：编辑器区块扩充 + 整站模板
**解决缺口：** 区块仅 12 种；"保存为新模板"只有首页级。
**Files:**
- Modify: `app/blueprints.py`（新区块类型：carousel / video(白名单 embed) / tabs / pricing / map-static / form-link）
- Modify: `app/static/editor.js` + `app/static/blocks.css`（新区块编辑与渲染）
- Create: `app/site_templates.py`（整站模板存取：多页面 blocks + 导航 + 设置 + 主题 + 设计令牌）
- Modify: `app/db.py`（site_templates 表）、`app/factory_api.py`（导出/应用端点）
- Test: `tests/test_site_templates.py`、tests/test_factory.py 扩展
**功能拆解：**
1. 6 个新区块（全部声明式、白名单校验，video 仅允许 https YouTube/Vimeo embed URL，map 用静态图片不引第三方 JS——延续"不执行用户代码"红线）
2. 整站模板：`POST /api/factory/sites/{site}/export-template` 把整站设计打包 JSON；建站时可选整站模板初始化（区别于现有首页级 preset）
3. 模板兼容性检查（复用 theme compatibility 思路：区块类型是否被当前版本支持）
4. （可选，需确认）草稿模式：entry status=draft 不进构建 —— 改动面大，默认不做
**验收标准：** 从零设计一个完整站点（多页+导航+设计令牌）→ 一键存为整站模板 → 新建站点套用该模板 → 构建结果与原站视觉一致。新 taxonomy 区块在编辑器和构建产物中渲染正确。
---
## Phase 4 — 横向刚需：多语言 + 发布连接器
**解决缺口：** 出口外贸场景的多语言（D1 方案）；重新发布的"一键上线"。
**Files:**
- Create: `app/multilang.py`（站点语言属性 + hreflang 互链 + 一键克隆翻译站）
- Create: `app/publish_targets.py`（SFTP 与 S3 兼容目标：凭据加密、连通性测试、发布/回滚记录）
- Modify: `app/db.py`（sites.locale、site_relations、publish_targets、publish_history 表）
- Modify: `app/builder.py`（sitemap 输出 hreflang alternates）
- Modify: `app/static/factory-v2.js`（语言管理面板、发布目标面板）
- Test: `tests/test_multilang.py`、`tests/test_publish_targets.py`
**功能拆解：**
1. 站点 locale 字段 + 语言变体关系组；克隆为翻译站（复制结构、内容置为待翻译占位，不机器翻译、不伪造）
2. 构建时各语言站 sitemap 互相输出 hreflang；语言切换器区块（白名单）
3. SFTP 发布目标：host/账号/路径，密码加密存储；"发布到此目标"= 上传当前 release 目录（原子：先传 `.new` 再 rename），发布历史落库，失败回滚提示
4. S3 兼容目标（endpoint/key/secret/bucket/prefix），同样走审批门禁后才可发布
5. 发布动作复用现有 release_requests 审批流（未审批的构建禁止推送到外部目标）
**验收标准：** 一个中文站克隆出英文变体站，两站 sitemap 含正确 hreflang；任一构建版本经审批后一键 SFTP 推送到测试服务器并可访问。
---
## Phase 5 — 生产化加固（引用 docs/PRODUCTION_ROADMAP.md，单独立项）
PostgreSQL/Redis、SSO/MFA、审计外置、E2E 视觉回归、供应链与渗透测试、监控 SLO。**不在本主计划展开**，功能补全（Phase 1-4）验证业务闭环后再启动，避免过早优化。
---
## 执行方式
- 每个 Phase 开始前：按 superpowers:writing-plans 写任务级详细计划（含 TDD 步骤与完整代码）→ 评审 → 按 subagent-driven 或 inline 方式执行
- 每个 Phase 结束：`scripts/ci.sh` 全绿 + Docker 实测启动 + 浏览器验收（复用本次会话已验证的冒烟流程）
- 顺序建议：P0（0.5 天）→ Phase 1（最快见效）→ Phase 2 → Phase 3 → Phase 4；Phase 2/3 可并行（不同子系统）