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

160 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/凭据）永不入库
Reference in New Issue View Git Blame Copy Permalink