浅念
3c57c167f2
导入 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>
9.2 KiB
9.2 KiB
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 路由
- compose.yaml 双服务同标签构建冲突：
- 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
功能拆解：
POST /api/factory/sites/{site}/wizard/start{url}→ 调adapters.analyze()识别平台 → 返回推荐路径（WP REST / WXR 上传 / 爬虫 / 基线上传）- 向导状态机（pending → analyzed → importing → baseline → media → done），每步可重试、可跳过，状态落库
- WP REST 全量分页导入（现有 1000 条上限 → 10000，走 worker 队列异步 + 进度查询）
- 媒体自动发现：导入完成后自动生成 assets inventory（现有 API），向导里展示"待本地化图片清单"并提供构建时镜像开关
- sitemap.xml 自动拉取生成基线（当前基线只能手动上传文件；加一个"从 URL 拉取 sitemap"入口，受 ensure_public_url 约束）
- 爬虫容量 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
功能拆解：
- 通用 XML 数据导入（任意扁平/两层 XML → 行记录，走现有 mapping 管道）
- MySQL 只读连接器：连接配置（主机/库/账号）用 Fernet 加密存库；只允许
SELECT，白名单表，单表 ≤10000 行，超时与行数硬上限；预览表结构 → 选表选列 → 进 mapping 管道（复用 dry-run/commit） - PostgreSQL 连接器（同框架第二实现）
content_sense：对解析后的 columns+样本行打分（品牌/价格/续航→vehicle；作者/日期→post；案例地点→case），输出推荐 content_type 与推荐主题（automotive/industrial/corporate/minimal 关键词匹配），前端"智能推荐"面板一键采纳- 大批量：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 扩展
功能拆解：
- 6 个新区块（全部声明式、白名单校验，video 仅允许 https YouTube/Vimeo embed URL，map 用静态图片不引第三方 JS——延续"不执行用户代码"红线）
- 整站模板：
POST /api/factory/sites/{site}/export-template把整站设计打包 JSON；建站时可选整站模板初始化（区别于现有首页级 preset） - 模板兼容性检查（复用 theme compatibility 思路：区块类型是否被当前版本支持）
- （可选，需确认）草稿模式：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
功能拆解：
- 站点 locale 字段 + 语言变体关系组；克隆为翻译站（复制结构、内容置为待翻译占位，不机器翻译、不伪造）
- 构建时各语言站 sitemap 互相输出 hreflang；语言切换器区块（白名单）
- SFTP 发布目标：host/账号/路径，密码加密存储；"发布到此目标"= 上传当前 release 目录（原子：先传
.new再 rename），发布历史落库，失败回滚提示 - S3 兼容目标（endpoint/key/secret/bucket/prefix），同样走审批门禁后才可发布
- 发布动作复用现有 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 可并行（不同子系统）