# SiteForge 网站工厂 — 完整实现补全计划

> 版本：v1.0（2026-10-22）
> 目标读者：项目负责人 / 实施工程师
> 配套文档：[PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md)（生产化清单）、[superpowers/plans/](superpowers/plans/)（执行级任务计划）

---

## 1. 项目目标

**一句话：** 做一台"网站生产工厂"——原材料（旧站/模板/数据/自由设计）从任意入口进，流水线另一头产出可直接上线的纯静态网站，且四种方式可组合、成品可随时修改重发布。

**四种建站模式（需求定义）：**

| 模式 | 输入 | 输出 |
|---|---|---|
| A. 旧站迁移 | 旧网站地址（WordPress 等） | 原内容 + 全新视觉，SEO/URL 不丢 |
| B. 模板建站 | 行业模板 + 公司资料/Logo/产品 | 完整新站 |
| C. 数据装配 | Excel/CSV/JSON/XML/数据库/API | 自动识别类型、匹配模板、批量生成 |
| D. 自由设计 | 可视化编辑器从零排版 | 个性站点，可存为新模板 |

---

## 2. 现状基线（2026-10-22 实测确认）

已在本机 Docker 环境完整验证：镜像构建、双容器启动、登录/CSRF、建站、自动栏目、同步+异步构建（10 页静态站 0 错误）、管理台/工厂 UI、静态站预览全部通过。

| 模块 | 完成度 | 结论 |
|---|---|---|
| 模式 A 旧站迁移 | ~70% | WordPress 路径可用（WXR/REST/爬虫/媒体ZIP/基线审计/发布门禁），但需手动 5 步，仅支持 WP |
| 模式 B 模板建站 | ~90% | 基本完成；缺表单收件（外部化设计）、多语言 |
| 模式 C 数据装配 | ~60% | Excel/CSV/JSON+字段映射强；缺 XML、数据库/API 连接器、类型/模板自动匹配 |
| 模式 D 自由设计 | ~65% | 编辑器安全可控（12 区块/14 模板/列布局）；缺常见商业区块、整站级模板保存 |
| 组合与随时修改 | ~90% | 架构支持已验证；缺一键上线（发布连接器） |
| 工程基础 | — | **已补齐：git 仓库已建立**（origin: xinyouhe/cms-SiteForge） |

---

## 3. 总体策略

1. **增量演进，不推倒重来**：现有 FastAPI + SQLite + 声明式主题架构质量良好，全部新功能在其上叠加。
2. **每个 Phase 独立交付**：完成后系统始终可运行、可演示，CI 全绿才算结束。
3. **顺序**：P0（工程前提）→ Phase 1 → 2 → 3 → 4 → 5；Phase 2/3 相互独立可并行。
4. **红线不破**：不执行用户上传的代码（主题/区块保持声明式白名单）；不伪造业务数据；发布保持审批门禁。

---

## 4. P0：工程前提（0.5–1 天）

| 任务 | 内容 | 验收 |
|---|---|---|
| P0-1 ✅ | git 仓库 + 远程 origin + .gitignore（已完成并推送基线提交） | `git log` 可见基线 |
| P0-2 | 修复 3 个实测缺陷：① compose.yaml 两服务同标签构建冲突（`up -d --build` 失败）② worker 容器假 unhealthy（继承镜像 HEALTHCHECK）③ favicon 404 | `docker compose up -d --build` 一条命令成功；两容器均 healthy；浏览器无 404 |
| P0-3 | `scripts/ci.sh`：pytest + compileall + node --check 一键自检 | 本机跑通全绿，纳入每次提交前检查 |

---

## 5. Phase 1：模式 A 补全 — 迁移向导（3–5 天）

**目标：** "输入旧站地址"从手动 5 步变一站式引导流程。纯编排层，无表结构大改，最快见效。

**任务分解：**

| # | 任务 | 涉及文件 |
|---|---|---|
| 1.1 | 向导状态机（start→analyzed→importing→baseline→media→done，可重试/跳过/恢复） | 新 `app/migration_wizard.py`、`app/db.py`（wizard_state 表） |
| 1.2 | `wizard/start {url}`：调 `adapters.analyze()` 识别平台，返回推荐路径 | `app/factory_api.py` |
| 1.3 | WP REST 全量分页导入（上限 1000→10000，走 worker 异步 + 进度查询） | `app/adapters.py`、`app/worker.py`（job kind: wp-import） |
| 1.4 | sitemap.xml 从 URL 拉取生成基线（现只能手动上传文件） | `app/migration_audit.py` |
| 1.5 | 媒体自动清单：导入后自动生成 assets inventory + 待本地化列表 + 构建镜像开关 | 复用 `/assets/inventory` |
| 1.6 | 爬虫容量 60→200 页 + robots.txt 检查 | `app/importers.py` |
| 1.7 | 前端向导面板（分步 UI，挂在 factory-studio） | 新 `app/static/wizard.js`、`factory-v2.html` |

**验收标准：** 输入一个真实 WordPress 站地址，向导引导完成 导入→基线→媒体清单→构建→审计报告 全流程；中途关闭页面重进可恢复状态。测试 `tests/test_migration_wizard.py` 全绿。

---

## 6. Phase 2：模式 C 补全 — 数据源连接器 + 自动匹配（5–8 天）

**目标：** 补上"XML / 数据库 / API"三种进料口和"自动识别类型、自动匹配模板"。

| # | 任务 | 涉及文件 |
|---|---|---|
| 2.1 | 通用 XML 数据导入（扁平/两层 XML → 行记录，进现有 mapping 管道） | `app/table_loader.py` |
| 2.2 | **MySQL 只读连接器**：凭据 Fernet 加密存库；仅 SELECT；白名单表；单表 ≤10000 行；预览表结构→选表选列→mapping dry-run/commit | 新 `app/connectors.py` |
| 2.3 | PostgreSQL 连接器（同框架第二实现） | `app/connectors.py` |
| 2.4 | 内容类型 + 行业主题智能推荐（列名/样本值规则打分：品牌+续航→vehicle→automotive 主题），前端"智能推荐"一键采纳 | 新 `app/content_sense.py` |
| 2.5 | 大批量异步导入：mapping commit 分批（500/批）入 worker 队列，进度条；总量上限 1000→50000 | `app/factory_api.py`、`app/worker.py` |

**验收标准：** ① 5000 行车型 Excel → 推荐 vehicle+automotive → 异步导入 → 构建出含分类/品牌聚合页的站；② 测试 MySQL 库选表导入走通；③ 通用 XML 文件导入走通。测试 `tests/test_connectors.py`、`tests/test_content_sense.py` 全绿。

---

## 7. Phase 3：模式 D 补全 — 编辑器扩充 + 整站模板（4–6 天）

**目标：** 提升设计自由度与复用能力。

| # | 任务 | 涉及文件 |
|---|---|---|
| 3.1 | 新增 6 区块：轮播 carousel、视频 video（仅白名单 https YouTube/Vimeo embed）、选项卡 tabs、价格表 pricing、静态地图 map、表单链接 form-link —— 全部声明式、白名单校验 | `app/blueprints.py`、`app/static/blocks.css`、`editor.js` |
| 3.2 | 整站模板：导出 = 多页面 blocks + 导航 + 设置 + 主题 + 设计令牌 打包 JSON；建站时可选整站模板初始化 | 新 `app/site_templates.py`、`app/db.py`（site_templates 表） |
| 3.3 | 模板兼容性检查（区块类型是否被目标主题版本支持） | `app/site_templates.py` |
| 3.4 | （可选，默认不做）草稿模式 entry status=draft —— 改动面大，需单独确认 | — |

**验收标准：** 从零设计完整站点（多页+导航+令牌）→ 存为整站模板 → 新站套用 → 构建视觉与原站一致；6 个新区块在编辑器与构建产物中渲染正确并有测试覆盖。

---

## 8. Phase 4：横向刚需 — 多语言 + 发布连接器（5–8 天）

**目标：** 出口外贸场景的语言能力 + "重新发布一键上线"。

| # | 任务 | 涉及文件 |
|---|---|---|
| 4.1 | 站点 locale + 语言变体关系组；一键克隆翻译站（复制结构，内容置为待翻译占位，**不机器翻译不伪造**） | 新 `app/multilang.py`、`app/db.py`（sites.locale、site_relations） |
| 4.2 | 各语言站 sitemap 互输 hreflang alternates；语言切换器区块（白名单） | `app/builder.py`、`app/blueprints.py` |
| 4.3 | **SFTP 发布目标**：凭据加密、连通性测试、原子上传（.new→rename）、发布历史、失败提示 | 新 `app/publish_targets.py` |
| 4.4 | S3 兼容发布目标（endpoint/key/secret/bucket/prefix） | `app/publish_targets.py` |
| 4.5 | 外部发布强制走现有 release_requests 审批门禁 | `app/factory_api.py` |

**验收标准：** 中文站克隆英文变体站，两站 sitemap hreflang 正确；任一构建版本经审批后一键 SFTP 推送到测试服务器可访问。测试全绿。

---

## 9. Phase 5：生产化加固（另行立项，引用 PRODUCTION_ROADMAP.md）

PostgreSQL/Redis、SSO/MFA、审计外置、E2E 视觉回归、供应链与渗透测试、监控 SLO。**功能闭环（Phase 1–4）验证后再启动**，避免过早优化。

---

## 10. 里程碑与时间估算

| 里程碑 | 内容 | 估算（人日） | 交付物 |
|---|---|---|---|
| M0 | P0 完成 | 0.5–1 | 一条命令启动 + CI |
| M1 | Phase 1 完成 | 3–5 | 一站式迁移演示（真实 WP 站） |
| M2 | Phase 2 完成 | 5–8 | Excel/数据库/XML → 全自动建站演示 |
| M3 | Phase 3 完成 | 4–6 | 整站模板库 + 富区块编辑器 |
| M4 | Phase 4 完成 | 5–8 | 中英双语站 + 一键 SFTP 上线 |
| M5 | Phase 5 | 另估 | 生产级部署 |

合计功能补全（M0–M4）约 **17–28 人日**。

---

## 11. 待确认决策点（阻塞相应 Phase 开工）

| # | 决策 | 推荐 |
|---|---|---|
| D1 | 多语言方案（阻塞 Phase 4） | 站点级复制 + hreflang 互链，不改 entries 表 |
| D2 | 数据库连接器首发（阻塞 Phase 2） | MySQL 只读 |
| D3 | PostgreSQL 时机 | 推迟到 Phase 5 |
| D4 | Phase 顺序 | 1→2→3→4（2/3 可并行） |

## 12. 工作流程约定

- 每个 Phase 开工前：展开为任务级 TDD 详细计划（写入 `docs/superpowers/plans/`）并评审
- 每个 Phase 收尾：CI 全绿 + Docker 实测启动 + 浏览器验收（复用已验证的冒烟流程）
- 提交规范：小步提交，`feat:/fix:/chore:` 前缀；敏感信息（.env/凭据）永不入库