docs: carry over COMPLETION_PLAN.md (v2.0) from remote main

Co-Authored-By: Claude Code <noreply@anthropic.com>

docs/COMPLETION_PLAN.md

@@ -0,0 +1,347 @@
+# SiteForge 网站工厂 — 完整实现与生产落地计划
+
+> 版本：v2.0（2026-10-22）
+>
+> 状态：评审后优化版
+>
+> 目标读者：项目负责人、产品负责人、实施工程师、测试与运维人员
+>
+> 配套文档：[PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md)、[执行级计划目录](superpowers/plans/)
+
+---
+
+## 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/WXR/REST/Sitemap/受控爬取 | 保留 URL、SEO 与真实内容的新版静态站 |
+| B. 模板建站 | 行业主题、企业资料、产品内容 | 可编辑、可复用、可发布的新站 |
+| C. 数据装配 | Excel/CSV/JSON/XML/API/只读数据库 | 经映射、校验、去重后批量生成的内容与页面 |
+| D. 自由设计 | 声明式区块、设计令牌、页面模板 | 安全可控且可复用的整站模板 |
+
+### 2.2 本轮非目标
+
+- 不做任意 HTML/JavaScript 上传和执行。
+- 不在未确认授权的情况下抓取、复制或发布第三方内容。
+- 不承诺像素级自由定位或完整替代专业设计工具。
+- 不自动生成或机器翻译业务事实；系统只提供结构、占位和校验。
+- 单机试点阶段不承诺多实例高可用；达到多实例门槛后再切 PostgreSQL 与独立队列。
+
+---
+
+## 3. 已确认基线
+
+### 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 | 任务 | 验收标准 |
+|---|---|---|
+| 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 桌面与移动端完成登录、后台、构建历史、预览导航冒烟。
+- 记录镜像摘要、数据库备份点和回滚命令。
+
+---
+
+## 7. P1：平台底座（3–5 人日）
+
+业务功能开始扩张前先统一以下能力，避免每个模块重复实现且行为不一致。
+
+| ID | 能力 | 关键要求 |
+|---|---|---|
+| 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 在任务执行中被终止后能够恢复或明确失败，不产生重复内容或半成品构建。
+
+---
+
+## 8. P2：模式 A — WordPress 迁移闭环（5–8 人日）
+
+### 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 连接器
+
+| 连接器 | 首发范围 | 安全要求 |
+|---|---|---|
+| XML | 扁平与两层记录结构 | 安全解析、明确根/记录节点、预览错误定位 |
+| HTTP API | GET + 分页 + JSON 路径映射 | HTTPS 优先、域名白名单、超时、响应上限、重试、令牌脱敏 |
+| MySQL | 单库、白名单表/视图、选列读取 | 必须使用数据库侧只读账号；TLS；参数化查询；禁止用户提交原始 SQL |
+| PostgreSQL | P3 后半或 P7 | 复用连接器协议，不与应用主库迁移混为一谈 |
+
+“应用代码检查 SELECT”不能替代数据库权限。凭据加密还必须包含主密钥存储、轮换、吊销和备份恢复策略。
+
+### 9.3 验收
+
+- 5,000 行车型数据完成推荐、映射、异步导入、品牌/分类聚合和构建。
+- 中途取消或失败后可重试，不重复写入；整个导入批次可回滚。
+- XML、API、MySQL 均有本地容器化夹具；测试不依赖真实生产数据库。
+
+---
+
+## 10. P4：模式 D — 编辑器与整站模板（5–8 人日）
+
+| ID | 任务 | 验收重点 |
+|---|---|---|
+| 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 视口；焦点、标签、对比度和减少动画设置 |
+
+退出条件：从多页站点保存模板，在空站应用并构建；视觉结构一致，内容数据不被错误复制，模板失败可完整回滚。
+
+---
+
+## 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. 关键决策与负责人
+
+| 决策 | 推荐方案 | 最晚决定时间 |
+|---|---|---|
+| 首个业务闭环 | WordPress 迁移 → 审计 → 发布 | P2 开工前 |
+| 数据库连接器首发 | MySQL；PostgreSQL 作为第二实现 | P3 开工前 |
+| API 认证首发 | Bearer token + 自定义请求头白名单，不支持用户脚本 | P3 开工前 |
+| 发布首发 | 若客户环境明确则优先 SFTP，否则 S3 兼容 | P5 开工前 |
+| 多语言 URL | 根据正式域名/CDN 架构决定，不在代码中硬编码 | P6 开工前 |
+| 单机容量门槛 | 用压测确定；超过门槛触发 P7 | P7 立项前 |
+
+每项决策必须记录负责人、日期、备选方案和影响，不再只保留“待确认”文字。
+
+---
+
+## 17. 推荐的下一迭代
+
+下一迭代只执行 P0，不并行开发新连接器：
+
+1. 轮换测试期间使用过的管理员密码和会话密钥。
+2. 从当前源码重建容器，确认运行版本从 v4.0.0 升至 v5.0.0。
+3. 修复预览链接 404，并增加自动化与浏览器回归。
+4. 修复 Worker 健康检查，补 favicon。
+5. 完成备份恢复、桌面/移动端冒烟，并记录可回滚版本。
+6. P0 验收通过后，再为 P1 写执行级 TDD 计划。
+
+只有 P0 全部退出条件满足，才能把当前系统标记为“v5 基线可用”。