From 70b74b2e9349cb1687a5ef8759b155f6cff318f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=B5=85=E5=BF=B5?= Date: Thu, 22 Oct 2026 11:03:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=AE=A1=E5=88=92=20v2.0=20=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E2=80=94=E2=80=94compose=20=E5=86=B2=E7=AA=81?= =?UTF-8?q?=E6=A0=87=E8=AE=B0=E5=B7=B2=E5=A4=8D=E7=8E=B0=E3=80=81=E6=8E=A7?= =?UTF-8?q?=E5=88=B6=E5=8F=B0=E6=8E=AA=E8=BE=9E=E3=80=81P1-2=20=E7=B2=BE?= =?UTF-8?q?=E7=AE=80=E5=AE=9E=E7=8E=B0=E3=80=81=E5=8D=95=E4=BA=BA=E6=8E=92?= =?UTF-8?q?=E6=9C=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Code --- docs/COMPLETION_PLAN.md | 412 +++++++++++++++++++++++++++++----------- 1 file changed, 300 insertions(+), 112 deletions(-) diff --git a/docs/COMPLETION_PLAN.md b/docs/COMPLETION_PLAN.md index 4d2e13a..4ea22c2 100644 --- a/docs/COMPLETION_PLAN.md +++ b/docs/COMPLETION_PLAN.md @@ -1,159 +1,347 @@ -# SiteForge 网站工厂 — 完整实现补全计划 +# SiteForge 网站工厂 — 完整实现与生产落地计划 -> 版本：v1.0（2026-10-22） -> 目标读者：项目负责人 / 实施工程师 -> 配套文档：[PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md)（生产化清单）、[superpowers/plans/](superpowers/plans/)（执行级任务计划） +> 版本：v2.0（2026-10-22） +> +> 状态：评审后优化版 +> +> 目标读者：项目负责人、产品负责人、实施工程师、测试与运维人员 +> +> 配套文档：[PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md)、[执行级计划目录](superpowers/plans/) --- -## 1. 项目目标 +## 1. 评审结论 -**一句话：** 做一台"网站生产工厂"——原材料（旧站/模板/数据/自由设计）从任意入口进，流水线另一头产出可直接上线的纯静态网站，且四种方式可组合、成品可随时修改重发布。 +原 v1.0 计划的产品方向和四类建站模式定义是合理的，但还不能直接作为完整的交付计划使用，主要问题如下： -**四种建站模式（需求定义）：** +1. **基线混杂**：源码已经是 v5.0.0，但 2026-10-22 实际运行在 `127.0.0.1:8787` 的实例仍报告 v4.0.0；“源码已完成”不等于“部署已生效”。 +2. **遗漏实测缺陷**：静态页面能够生成，但预览页中的 `/products/`、`/about/` 等根路径链接会离开 `/preview/{site}/{build}/`，最终返回 404。 +3. **P0 证据补齐**：同镜像标签导致 Compose 构建冲突已于 2026-10-22 实测复现（`docker compose up -d --build` 报 `image "siteforge/web:5.0": already exists`；已验证规避法：先 `docker compose build siteforge` 再 `up -d`），可直接定性修复。Worker 继承 Web 健康检查、favicon 无路由、缺 Linux CI 脚本问题均已确认。 +4. **功能先于平台能力**：迁移、数据库/API 连接器和发布都依赖统一任务模型、幂等、进度、取消、审计、密钥管理和安全出网策略，原计划没有先补这些前置能力。 +5. **安全边界不完整**：只写“Fernet 加密”和“仅 SELECT”不足以保护数据库连接器；爬虫、Sitemap、远程媒体、SFTP/S3 还需要 SSRF、DNS 重绑定、重定向、证书/主机密钥和路径穿越防护。 +6. **验收不可重复**：仅以“一个真实 WordPress 网站”验收会受外网、站点改版和授权影响；必须同时维护确定性的本地测试夹具。 +7. **范围有遗漏**：Phase 2 的目标提到 API 连接器，任务表中却没有 API 连接器；XML 也缺少 XXE、压缩炸弹和文件大小限制。 +8. **发布闭环不足**：缺少预部署校验、不可变版本、原子切换、回滚、上线后探测及缓存策略。 +9. **多语言模型过简**：只克隆站点不足以稳定维护页面级 hreflang 对应关系，需要明确站点语言组和内容翻译组。 +10. **估算偏乐观**：17–28 人日没有包含安全设计、失败恢复、E2E、视觉回归、兼容性、文档和试点修复缓冲。 -| 模式 | 输入 | 输出 | +本 v2.0 计划将顺序调整为：**先稳定当前版本 → 建立平台底座 → 完成业务闭环 → 再扩大连接器和生产规模**。 + +--- + +## 2. 产品目标与交付边界 + +### 2.1 产品目标 + +把旧站、模板、结构化数据和可视化设计统一接入一条可追踪的生产流水线，输出可审计、可预览、可回滚、可独立部署的静态网站。 + +| 模式 | 输入 | 核心输出 | |---|---|---| -| A. 旧站迁移 | 旧网站地址（WordPress 等） | 原内容 + 全新视觉，SEO/URL 不丢 | -| B. 模板建站 | 行业模板 + 公司资料/Logo/产品 | 完整新站 | -| C. 数据装配 | Excel/CSV/JSON/XML/数据库/API | 自动识别类型、匹配模板、批量生成 | -| D. 自由设计 | 可视化编辑器从零排版 | 个性站点，可存为新模板 | +| A. 旧站迁移 | WordPress/WXR/REST/Sitemap/受控爬取 | 保留 URL、SEO 与真实内容的新版静态站 | +| B. 模板建站 | 行业主题、企业资料、产品内容 | 可编辑、可复用、可发布的新站 | +| C. 数据装配 | Excel/CSV/JSON/XML/API/只读数据库 | 经映射、校验、去重后批量生成的内容与页面 | +| D. 自由设计 | 声明式区块、设计令牌、页面模板 | 安全可控且可复用的整站模板 | + +### 2.2 本轮非目标 + +- 不做任意 HTML/JavaScript 上传和执行。 +- 不在未确认授权的情况下抓取、复制或发布第三方内容。 +- 不承诺像素级自由定位或完整替代专业设计工具。 +- 不自动生成或机器翻译业务事实；系统只提供结构、占位和校验。 +- 单机试点阶段不承诺多实例高可用；达到多实例门槛后再切 PostgreSQL 与独立队列。 --- -## 2. 现状基线（2026-10-22 实测确认） +## 3. 已确认基线 -已在本机 Docker 环境完整验证：镜像构建、双容器启动、登录/CSRF、建站、自动栏目、同步+异步构建（10 页静态站 0 错误）、管理台/工厂 UI、静态站预览全部通过。 +### 3.1 源码基线 -| 模块 | 完成度 | 结论 | +- FastAPI + SQLite WAL + 原生 JavaScript + Jinja2 + Docker Compose。 +- 源码版本常量为 v5.0.0。 +- 依赖已固定版本；已有 `scripts/check.ps1`。 +- 自动化回归已完成 54 项测试；Python 编译、JavaScript 语法和 Compose 配置检查通过。 +- 已实现登录/CSRF、站点与内容管理、主题切换、页面区块、文件导入、构建、ZIP 下载、预览、发布审批、审计和异步构建基础能力。 + +### 3.2 运行实例基线 + +- 登录、管理台、内容搜索、模板页、构建历史和质量报告可用。 +- 已有测试站点含 9 条内容和 2 个构建版本；最新版本生成 10 个 HTML 页面。 +- 主要预览页面直接访问成功，浏览器控制台仅 favicon 404 一项告警。 +- 最新构建只有“未配置正式域名，因此未生成绝对 canonical”告警。 +- **运行实例仍为 v4.0.0，尚未加载当前 v5.0.0 源码。** +- **预览导航中的根路径链接会跳出预览前缀并返回 404。** + +### 3.3 基线管理规则 + +此后文档中的“已完成”必须同时满足： + +1. 代码已合入并有测试； +2. Docker 镜像已从目标提交构建； +3. `/api/health` 返回预期版本和提交标识； +4. 浏览器冒烟测试通过； +5. 回滚步骤已验证。 + +--- + +## 4. 全局完成定义（Definition of Done） + +每个里程碑必须同时通过以下门禁： + +| 类别 | 强制验收 | +|---|---| +| 功能 | 正常流程、空数据、重复提交、失败重试、中断恢复均有测试 | +| 安全 | 权限校验、CSRF、输入上限、路径安全、敏感字段脱敏、出网策略通过评审 | +| 数据 | 数据库变更可前滚；破坏性变更有备份和恢复演练 | +| 任务 | 幂等、进度、超时、重试、取消或明确说明不可取消 | +| 前端 | Chrome 桌面与 390px/360px 移动端冒烟；关键页面无控制台错误 | +| 静态站 | 内链、资源、canonical、sitemap、robots、404、搜索索引检查通过 | +| 部署 | Compose 构建/启动、健康检查、版本校验、升级和回滚通过 | +| 文档 | 配置项、限制、运维步骤和已知问题同步更新 | + +所有测试必须使用本地固定夹具；真实外部网站和测试服务器仅作为补充验收，不能替代确定性测试。 + +--- + +## 5. 路线图总览 + +| 阶段 | 目标 | 依赖 | 估算人日 | +|---|---|---|---:| +| P0 | 当前版本稳定、部署与源码对齐 | 无 | 2–3 | +| P1 | 平台底座：迁移、任务、出网、密钥与可观测性 | P0 | 3–5 | +| P2 | 模式 A：WordPress 迁移闭环 | P1 | 5–8 | +| P3 | 模式 C：XML/API/数据库数据装配 | P1 | 7–11 | +| P4 | 模式 D：编辑器与整站模板 | P1 | 5–8 | +| P5 | 发布连接器与可回滚上线 | P0、P1 | 5–8 | +| P6 | 多语言内容关系与 hreflang | P2/P4 稳定后 | 5–8 | +| P7 | 多实例生产化与企业能力 | 业务试点通过 | 15–30 | + +P0–P6 总量约 **32–51 人日**。两名工程师在 P1 完成后并行推进 P2/P3/P4，预计日历时间约 4–7 周；若单人串行执行约 7–10 周。该估算不含大规模历史数据清洗和第三方系统协调。 + +--- + +## 6. P0：稳定当前版本（2–3 人日） + +### 6.1 任务 + +| ID | 任务 | 验收标准 | |---|---|---| -| 模式 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） | +| P0-1 | 从当前提交重建 Web/Worker 镜像；镜像加入版本与 Git SHA 标签 | `/api/health` 返回 v5.0.0 和目标提交；管理台标识一致 | +| P0-2 | 修复预览根路径链接：只在预览响应中安全改写站内 `href/src/action/poster`，不修改构建 ZIP | 点击首页、产品、关于、联系、搜索均保持在 `/preview/{site}/{build}/` 下；增加回归测试 | +| P0-3 | Worker 健康检查独立化 | Worker 不再继承访问 8787 的 Web HEALTHCHECK；采用进程/心跳检查或明确禁用并由任务监控替代 | +| P0-4 | 增加 favicon 路由或资源 | 登录页、管理台和预览无 favicon 404 | +| P0-5 | 修复 Compose 同标签构建冲突 | 已复现（见 §1）；修复后 `docker compose up -d --build` 一条命令直接成功，不再需要先单独 build 的规避步骤 | +| P0-6 | 补齐跨平台 CI | 保留 `scripts/check.ps1`，新增等价 `scripts/check.sh`；运行 pytest、compileall、全部 JS 语法、Compose 配置和镜像构建 | +| P0-7 | 密钥卫生 | 轮换已在测试沟通中暴露的管理员密码与会话密钥；确认 `.env` 未被 Git 跟踪；日志和测试输出不得打印凭据 | +| P0-8 | 备份恢复冒烟 | 备份数据卷/SQLite/归档，在空目录恢复并能登录、预览、下载旧构建 | + +### 6.2 退出条件 + +- 一条命令完成构建和启动，Web 健康、Worker 可观测。 +- 当前 54 项测试保持通过，并增加预览导航、版本和 Worker 健康相关测试。 +- Chrome 桌面与移动端完成登录、后台、构建历史、预览导航冒烟。 +- 记录镜像摘要、数据库备份点和回滚命令。 --- -## 3. 总体策略 +## 7. P1：平台底座（3–5 人日） -1. **增量演进，不推倒重来**：现有 FastAPI + SQLite + 声明式主题架构质量良好，全部新功能在其上叠加。 -2. **每个 Phase 独立交付**：完成后系统始终可运行、可演示，CI 全绿才算结束。 -3. **顺序**：P0（工程前提）→ Phase 1 → 2 → 3 → 4 → 5；Phase 2/3 相互独立可并行。 -4. **红线不破**：不执行用户上传的代码（主题/区块保持声明式白名单）；不伪造业务数据；发布保持审批门禁。 +业务功能开始扩张前先统一以下能力，避免每个模块重复实现且行为不一致。 ---- - -## 4. P0：工程前提（0.5–1 天） - -| 任务 | 内容 | 验收 | +| ID | 能力 | 关键要求 | |---|---|---| -| 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 一键自检 | 本机跑通全绿，纳入每次提交前检查 | +| P1-1 | 数据库迁移注册表 | 使用显式 schema 版本和顺序迁移；启动迁移可重复；失败不留下半完成状态 | +| P1-2 | 通用任务模型 | 完整字段设计为 `kind/state/progress/attempts/next_retry/lease/heartbeat/result/error/idempotency_key`；单机 SQLite 阶段先精简实现 `state/attempts/heartbeat/idempotency_key` 四个核心字段，其余留位，P7 扩规模时补全，避免过度设计 | +| P1-3 | 任务控制 | 查询进度、取消待执行任务、运行超时、同站点并发上限、全局容量上限 | +| P1-4 | 安全出网客户端 | 仅 http/https；禁止私网、环回、链路本地和云元数据地址；每次重定向重新校验；连接/读取/总时限和响应大小上限 | +| P1-5 | 密钥管理接口 | 应用只引用 secret ID；开发环境可用加密文件，生产对接 Docker/Kubernetes Secret 或专用密钥服务；支持轮换与删除 | +| P1-6 | 可观测性 | 结构化日志、request/job/build ID、任务耗时、失败分类、敏感字段脱敏、健康与就绪探针 | +| P1-7 | 配额与限流 | 上传大小、解压总量、条目数、并发任务、站点数和构建保留数均可配置 | + +退出条件：用故障注入验证 Worker 在任务执行中被终止后能够恢复或明确失败，不产生重复内容或半成品构建。 --- -## 5. Phase 1：模式 A 补全 — 迁移向导（3–5 天） +## 8. P2：模式 A — WordPress 迁移闭环（5–8 人日） -**目标：** "输入旧站地址"从手动 5 步变一站式引导流程。纯编排层，无表结构大改，最快见效。 +### 8.1 实施内容 -**任务分解：** +1. 建立版本化迁移会话：`created → analyzing → importing → auditing → media → building → review → completed/failed/cancelled`。 +2. 每一步保存输入、输出摘要、错误和重试次数；重复提交使用幂等键，支持关闭页面后恢复。 +3. 平台识别只给出证据和推荐，不依赖单一响应头或 HTML 特征。 +4. WP REST 全量分页导入进入通用任务队列；使用游标/页码检查点，可从断点续跑。 +5. WXR、REST 与爬虫使用稳定的源记录 ID 做去重；定义 `skip/update/fork` 冲突策略。 +6. Sitemap URL 拉取复用安全出网客户端；支持 sitemap index、gzip 和数量/大小上限。 +7. 受控爬虫遵守范围、深度、数量和速率限制；robots.txt 是合规提示，不是安全边界。 +8. 导入后自动生成 URL 基线、媒体清单、未本地化资源和需要人工检查的组件列表。 +9. 向导 UI 显示每一步的状态、进度、失败原因、重试/跳过条件和审计结果。 +10. 构建前门禁：缺失旧 URL、错误 canonical、断链和未处理重定向按严重级别阻断或告警。 -| # | 任务 | 涉及文件 | +### 8.2 验收 + +- 本地 WordPress REST/WXR/Sitemap 夹具完成全流程，网络中断后可续跑。 +- 重复启动同一迁移不会产生重复内容。 +- 私网地址、云元数据地址、超大响应和重定向到私网均被拒绝。 +- 经授权的真实 WordPress 站完成一次补充演示，并保存匿名化验收报告。 + +--- + +## 9. P3：模式 C — 数据装配与连接器（7–11 人日） + +### 9.1 安全导入管道 + +所有来源统一进入：`采样 → 字段识别 → 映射预览 → 校验 → 暂存 → 分批提交 → 构建`。 + +- XML 使用 `defusedxml`，禁用外部实体和 DTD；限制文件大小、节点深度、节点数与文本长度。 +- ZIP/压缩输入限制文件数、单文件大小、总解压大小和压缩比，防止压缩炸弹与路径穿越。 +- 记录源行号、源主键和导入批次；支持批次回滚，而不是只记录成功数量。 +- 内容类型和主题推荐使用可解释规则，显示命中的字段与分数；用户确认后才提交。 +- 大批量按 500 条以内分批，默认总量上限 50,000；限制应可配置并经过压测后调整。 + +### 9.2 连接器 + +| 连接器 | 首发范围 | 安全要求 | |---|---|---| -| 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` | +| XML | 扁平与两层记录结构 | 安全解析、明确根/记录节点、预览错误定位 | +| HTTP API | GET + 分页 + JSON 路径映射 | HTTPS 优先、域名白名单、超时、响应上限、重试、令牌脱敏 | +| MySQL | 单库、白名单表/视图、选列读取 | 必须使用数据库侧只读账号；TLS；参数化查询；禁止用户提交原始 SQL | +| PostgreSQL | P3 后半或 P7 | 复用连接器协议，不与应用主库迁移混为一谈 | -**验收标准：** 输入一个真实 WordPress 站地址，向导引导完成 导入→基线→媒体清单→构建→审计报告 全流程；中途关闭页面重进可恢复状态。测试 `tests/test_migration_wizard.py` 全绿。 +“应用代码检查 SELECT”不能替代数据库权限。凭据加密还必须包含主密钥存储、轮换、吊销和备份恢复策略。 + +### 9.3 验收 + +- 5,000 行车型数据完成推荐、映射、异步导入、品牌/分类聚合和构建。 +- 中途取消或失败后可重试，不重复写入；整个导入批次可回滚。 +- XML、API、MySQL 均有本地容器化夹具；测试不依赖真实生产数据库。 --- -## 6. Phase 2：模式 C 补全 — 数据源连接器 + 自动匹配（5–8 天） +## 10. P4：模式 D — 编辑器与整站模板（5–8 人日） -**目标：** 补上"XML / 数据库 / API"三种进料口和"自动识别类型、自动匹配模板"。 - -| # | 任务 | 涉及文件 | +| ID | 任务 | 验收重点 | |---|---|---| -| 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` | +| P4-1 | 区块属性 Schema 注册表 | 前后端共享类型、默认值、限制和主题支持矩阵 | +| P4-2 | 新增 carousel、video、tabs、pricing、map、form-link | 无任意脚本；视频/地图域名白名单；键盘和屏幕阅读器可用 | +| P4-3 | 整站模板包 | 包含版本、主题约束、页面 blocks、导航、设计令牌和所需内容模型；JSON Schema 校验 | +| P4-4 | 兼容性预检 | 应用前展示缺失区块、字段、主题版本和降级方案；失败不修改原站 | +| P4-5 | 草稿与发布状态 | 编辑不直接影响已发布构建；预览、审批、发布对象边界清晰 | +| P4-6 | 响应式与无障碍 | 1440/1024/390/360 视口；焦点、标签、对比度和减少动画设置 | -**验收标准：** ① 5000 行车型 Excel → 推荐 vehicle+automotive → 异步导入 → 构建出含分类/品牌聚合页的站；② 测试 MySQL 库选表导入走通；③ 通用 XML 文件导入走通。测试 `tests/test_connectors.py`、`tests/test_content_sense.py` 全绿。 +退出条件：从多页站点保存模板，在空站应用并构建；视觉结构一致，内容数据不被错误复制，模板失败可完整回滚。 --- -## 7. Phase 3：模式 D 补全 — 编辑器扩充 + 整站模板（4–6 天） +## 11. P5：发布连接器与回滚（5–8 人日） -**目标：** 提升设计自由度与复用能力。 +发布优先于多语言，因为只有形成“构建—审批—上线—验证—回滚”闭环，系统才真正可交付。 -| # | 任务 | 涉及文件 | +1. 发布目标只保存 secret 引用，不在 API、日志和审计详情中返回凭据。 +2. SFTP 强制校验主机密钥，限制目标根目录，禁止 `..`、符号链接逃逸和任意命令执行。 +3. SFTP 上传到不可变版本目录，校验文件清单后原子切换 `current`；保留上一版本用于一键回滚。 +4. S3 使用不可变版本前缀和 manifest；设置正确 Content-Type、Cache-Control、压缩元数据，最后切换发布指针。 +5. 所有外部发布强制关联已批准的 release request；构建内容变化后旧审批失效。 +6. 上线后执行主页、关键 URL、404、静态资源、canonical、sitemap 和重定向探测。 +7. 失败发布不影响当前线上版本；发布历史记录目标、构建、执行人、结果和回滚关系。 + +验收：在本地 SFTP/S3 兼容测试容器中完成发布、故障注入、重试和回滚；任意一步失败时线上指针保持原版本。 + +--- + +## 12. P6：多语言（5–8 人日） + +### 12.1 推荐模型 + +- `site_groups`：关联同一品牌的语言站。 +- `site_locales`：定义 locale、默认语言、域名/路径策略。 +- `translation_groups`：把不同语言站中语义相同的页面或内容条目关联起来。 +- 不自动翻译事实内容；克隆时创建“待翻译”状态，并禁止其进入正式发布。 + +### 12.2 必须先决策 + +1. 语言 URL 使用独立域名、子域名还是 `/en/` 路径。 +2. slug 是否本地化，以及变更后的重定向策略。 +3. 缺少翻译时隐藏、回退默认语言还是返回 404。 +4. `x-default` 指向哪个页面。 + +### 12.3 验收 + +- 中英文站的每个已关联页面生成对称 hreflang；不存在的翻译不输出错误链接。 +- sitemap、canonical、语言切换器和搜索索引相互一致。 +- “待翻译”内容不会意外发布。 + +--- + +## 13. P7：生产化与企业能力（15–30 人日，单独立项） + +触发条件：完成真实试点，或出现多实例、并发构建、企业身份接入、SLO/合规要求。 + +- PostgreSQL + 正式迁移工具；Redis/RabbitMQ 队列；多 Worker 租约和死信队列。 +- OIDC/SSO、MFA、会话撤销、最小权限角色与紧急停用。 +- 不可篡改审计、集中日志、指标、追踪、告警和运行手册。 +- 镜像/依赖扫描、SBOM、签名、主题供应链验证、恶意文件检测。 +- 跨环境密钥管理、数据库与对象存储备份、RPO/RTO 和恢复演练。 +- 性能与容量测试、灰度发布、CDN 刷新、Search Console/真实流量监测。 + +具体条目以 [PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md) 为基础，但开工前必须补充负责人、SLO、预算和目标部署架构。 + +--- + +## 14. 测试矩阵 + +| 层级 | 覆盖范围 | +|---|---| +| 单元测试 | URL/路径、映射规则、类型推荐、HTML 改写、迁移状态机、权限决策 | +| API 集成 | 认证/CSRF/RBAC、幂等、任务重试、导入回滚、发布审批失效 | +| 组件集成 | SQLite/数据库夹具、Worker 崩溃恢复、SFTP/S3、本地 WordPress/API 服务 | +| 静态 QA | 断链、资源、canonical/hreflang、sitemap、robots、404、搜索索引 | +| 浏览器 E2E | 登录、建站、导入、编辑、构建、预览导航、审批、发布、回滚 | +| 视觉回归 | 四主题首页/列表/详情/联系页，桌面和移动端基线截图 | +| 安全测试 | SSRF、重定向绕过、路径穿越、ZIP/XML 炸弹、越权、凭据泄漏、恶意主题包 | +| 恢复测试 | 数据库/归档恢复、Worker 中断、失败发布、旧版本回滚 | + +最低门槛：新增代码有针对性测试；主分支不得降低现有覆盖；关键路径 E2E 必须在发布前执行。 + +--- + +## 15. 指标与验收目标 + +| 指标 | MVP 目标 | +|---|---| +| 构建成功率 | 本地固定夹具 ≥ 99% | +| 任务可恢复性 | Worker 异常终止后无重复内容、无半成品发布 | +| 预览内链 | 关键页面 0 个 404 | +| 迁移 URL 保留 | 基线中应保留的 200 URL 100% 有页面或批准的重定向 | +| 静态质量 | 0 error；warning 必须被确认或登记豁免 | +| 发布回滚 | 测试环境 5 分钟内恢复上一版本 | +| 凭据暴露 | API、日志、导出、Git 历史中为 0 | +| 可访问性 | 关键流程键盘可操作；自动检查无高严重度问题 | + +--- + +## 16. 关键决策与负责人 + +| 决策 | 推荐方案 | 最晚决定时间 | |---|---|---| -| 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 —— 改动面大，需单独确认 | — | +| 首个业务闭环 | WordPress 迁移 → 审计 → 发布 | P2 开工前 | +| 数据库连接器首发 | MySQL；PostgreSQL 作为第二实现 | P3 开工前 | +| API 认证首发 | Bearer token + 自定义请求头白名单，不支持用户脚本 | P3 开工前 | +| 发布首发 | 若客户环境明确则优先 SFTP，否则 S3 兼容 | P5 开工前 | +| 多语言 URL | 根据正式域名/CDN 架构决定，不在代码中硬编码 | P6 开工前 | +| 单机容量门槛 | 用压测确定；超过门槛触发 P7 | P7 立项前 | -**验收标准：** 从零设计完整站点（多页+导航+令牌）→ 存为整站模板 → 新站套用 → 构建视觉与原站一致；6 个新区块在编辑器与构建产物中渲染正确并有测试覆盖。 +每项决策必须记录负责人、日期、备选方案和影响，不再只保留“待确认”文字。 --- -## 8. Phase 4：横向刚需 — 多语言 + 发布连接器（5–8 天） +## 17. 推荐的下一迭代 -**目标：** 出口外贸场景的语言能力 + "重新发布一键上线"。 +下一迭代只执行 P0，不并行开发新连接器： -| # | 任务 | 涉及文件 | -|---|---|---| -| 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` | +1. 轮换测试期间使用过的管理员密码和会话密钥。 +2. 从当前源码重建容器，确认运行版本从 v4.0.0 升至 v5.0.0。 +3. 修复预览链接 404，并增加自动化与浏览器回归。 +4. 修复 Worker 健康检查，补 favicon。 +5. 完成备份恢复、桌面/移动端冒烟，并记录可回滚版本。 +6. P0 验收通过后，再为 P1 写执行级 TDD 计划。 -**验收标准：** 中文站克隆英文变体站，两站 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/凭据）永不入库 +只有 P0 全部退出条件满足，才能把当前系统标记为“v5 基线可用”。