134 lines
9.2 KiB
Markdown
134 lines
9.2 KiB
Markdown
|
# 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 可并行（不同子系统）
|