cms-website/SITEFORGE_V7_2_IMPLEMENTATION_PLAN.md

# SiteForge Factory V7.2 项目差距审计与下一步实施计划

> 审计对象：`C:\Users\30997\Downloads\SiteForge_Factory_V5_Web_Docker\SiteForge_Factory_V7_2`  
> 审计日期：2026-10-22  
> 目标：把当前“可控试点版”推进为需求文档所描述的可迁移、可搭建、可发布、可运维的网站工厂。

## 1. 执行结论

当前项目已经形成可运行的产品骨架，具备：站点管理、内容模型、区块编辑器、主题安装与版本固定、静态构建、构建队列、基础质量检查、备份接口、团队角色、审计记录、PostgreSQL/Redis 部署骨架和 HTTPS/HMAC 远程发布代理。

但它还不能被定义为“完整需求已实现”或“生产就绪”。更准确的定位是：

- 单机/小团队、受控数据量下可演示和试点；
- 主要快乐路径已有自动化测试；
- 真实迁移、批量数据、跨平台恢复、多语言、企业身份、生产可观测性仍不完整；
- PostgreSQL、远程发布和备份链路目前属于“有骨架，尚未完成生产证明”。

建议不要继续堆叠零散页面或按钮，而是先关闭平台正确性，再按“迁移闭环 → 数据工厂 → 编辑/模板 → 发布/多语言 → 生产治理”推进。

## 2. 本次验证事实

### 2.1 自动化与静态验证

- Python 测试共发现 86 项。
- Windows 默认编码环境：80 通过、6 失败。
- `PYTHONUTF8=1` 环境：85 通过、1 失败。
- 5 项失败来自测试使用 `Path.read_text()` 却未显式指定 UTF-8，属于跨平台测试可靠性问题。
- 剩余 1 项是真实缺陷：SQLite 在线备份后临时数据库文件句柄在 Windows 未及时释放，`TemporaryDirectory` 清理时报 `WinError 32`。
- 39 个 Python 文件通过 AST 解析。
- 7 个 JavaScript 文件通过语法检查。
- 默认、Enterprise、Release Agent 三套 Compose 配置解析通过。

### 2.2 尚未完成的环境验证

以下项目不能用“Compose 配置能解析”替代，仍需在真实 Docker Engine/目标服务器验证：

- 镜像完整构建及冷启动；
- Web/Worker 心跳、异常重启和任务续租；
- PostgreSQL + Redis 全量测试；
- 浏览器端端到端、响应式、可访问性和视觉回归；
- 备份恢复演练；
- Release Agent 的 TLS、真实传输、切换、回滚和发布后探测。

## 3. 需求覆盖矩阵

| 能力域 | 当前状态 | 主要缺口 | 结论 |
|---|---|---|---|
| 站点/内容基础 | 已有 | 站点环境、默认语言、发布策略、蓝图不是一等模型 | 部分完成 |
| 迁移工厂 | 有 WXR、WordPress REST、CSV/JSON/XLSX、有限抓取 | 无持久化迁移会话、断点续传、媒体盘点、冲突队列、回滚和真实大型样本证明 | 试点级 |
| 数据工厂 | 有映射、dry-run、提交 | 无通用 XML、认证 API、只读 MySQL、分批暂存、可逆导入、人工覆盖保护、5 万行证明 | 明显缺失 |
| 内容模型 | 基础字段可用 | 缺 enum/relation/array/media、唯一性、索引、跨字段校验、完整工作流 | 部分完成 |
| 页面编辑器 | 12 类区块、嵌套布局、响应式属性、撤销/重做、复用组件 | 缺审批/锁定/冲突合并、更多业务区块、视觉回归、完整无障碍保证 | 部分完成 |
| 主题/模板 | 主题包、版本固定、兼容检查、预览 | “模板”仍主要是主题+首页预设，不是可复用多页面站点蓝图；升级差异/回滚验证不足 | 部分完成 |
| 构建系统 | 静态构建、版本目录、质量报告 | 构建读取实时数据库而非冻结快照；无内容哈希、依赖图、增量构建和产物保留策略 | 高风险缺口 |
| 作业系统 | 幂等、租约、取消、重试、容量限制 | 仅正式支持 build；无统一进度、死信、诊断日志；未覆盖迁移/导入/媒体/发布 | 部分完成 |
| 发布系统 | 本地发布、HMAC Release Agent、版本切换/回滚 | 缺完整 TLS 部署证明、重放防护、发布后外部探测、CDN 清理、SFTP/S3/Git 等目标 | 试点级 |
| 多语言 | 文档有设计 | 无 locale、翻译组、canonical/hreflang、多语言 sitemap 全链路实现 | 未实现 |
| PostgreSQL/Redis | 有兼容桥和 Compose | DDL 迁移不完整；全局 advisory lock 串行化；无连接池/按站点锁；Redis 仅唤醒 | 非生产级 |
| 安全/权限 | 登录、CSRF、Origin 检查、角色、审计 | 缺 CSP/Permissions-Policy/TrustedHost；代理信任过宽；无 OIDC/MFA/会话撤销/密钥生命周期 | 部分完成 |
| 备份恢复 | SQLite 在线备份和部分目录打包 | Windows 句柄缺陷；遗漏主题包/发布数据等；无统一清单、校验和、外部副本与定期恢复证明 | 阻断生产 |
| 可观测性 | Request ID、基础日志、健康接口 | 无 metrics/tracing/告警/SLO/作业看板 | 未完成 |
| 供应链/CI | Python/JS/Compose/PG 基础 CI | 锁文件无哈希；无依赖审计、镜像扫描、SBOM、签名；CI 允许 commit=`unknown` | 不完整 |
| 商业验收 | 有 readiness/report 概念 | 架构要求的四类真实试点没有签字验收证据 | 未闭环 |

## 4. 当前必须先修的缺陷

### P0：发布阻断

1. **修复 Windows SQLite 备份句柄泄漏**  
   显式关闭在线备份使用的源/目标连接，再退出临时目录；增加 Windows 与 Linux 的备份→恢复→内容/媒体校验测试。

2. **统一 UTF-8 测试和文件协议**  
   所有文本读写显式 `encoding="utf-8"`；CI 增加 Windows runner，避免用 `PYTHONUTF8=1` 掩盖代码问题。

3. **让版本证据真实可信**  
   CI 构建必须注入真实 Git SHA；健康检查拒绝 `unknown`；镜像 OCI revision、API commit、部署清单三者必须一致。

4. **建立一次真实容器验收**  
   默认 SQLite 和 Enterprise PostgreSQL 两种拓扑都执行冷启动、建站、导入、编辑、构建、预览、发布、备份恢复。

5. **补安全基线**  
   增加 CSP、Permissions-Policy、TrustedHost；把受信代理网段做成显式配置，避免无条件 `forwarded-allow-ips=*`；核对 Cookie、上传、登录限速和错误回显。

6. **同步文档与事实**  
   README 当前测试数量与实际 86 项不一致；V6 运维文档的版本返回示例也需要更新。所有“已完成”声明都必须绑定自动化或验收报告。

### P1：平台正确性

1. 把所有历史 `CREATE TABLE IF NOT EXISTS` 收敛到有序、校验和固定、可回滚/可恢复的 schema migration；SQLite 和 PostgreSQL 使用同一版本账本。
2. PostgreSQL 从 SQL 翻译桥升级为明确支持的持久层：连接池、事务语义、唯一约束错误、按站点 advisory lock、并发测试。
3. 作业模型推广到 `build/import/crawl/media/publish/migration`，增加进度、阶段、结构化日志、死信、重放和保留清理。
4. 每个构建先生成不可变输入快照：`site_blueprint + theme@version + content_snapshot + asset_manifest + route_registry + seo_policy`；Worker 只读取快照。
5. 为构建输入、产物和报告记录 SHA-256，保证相同输入可复现，并能证明审批后内容没有漂移。
6. 扩大备份范围到数据库、media、theme_packages、构建/发布元数据、配置引用；生成 manifest 和校验和；备份自动复制到独立存储。
7. 为 secrets 增加版本、轮换、撤销和使用审计；环境变量/文件引用保留为开发模式，生产对接 Secret Manager/Vault 类接口。

## 5. 分阶段实施路线图

### M0 — V7.2.1 稳定基线（3–5 人日）

交付：

- 关闭上述 P0 缺陷；
- Windows/Linux、Python 3.12/3.13 全绿；
- 两套 Compose 最小端到端 smoke；
- 一份可重复执行的备份恢复报告；
- CI 中真实 SHA、镜像摘要和版本清单可追踪。

退出门槛：86/86 测试通过；不依赖环境编码；备份恢复后数据库记录、媒体哈希和构建记录一致；health commit 不为 `unknown`。

### M1 — 平台内核完成（7–12 人日）

交付：

- 全量 schema migration；
- 不可变构建快照及内容哈希；
- 通用作业状态机与结构化任务日志；
- 产物/日志/失败任务保留策略；
- PostgreSQL 并发和事务测试；
- metrics、基础告警和运维面板。

退出门槛：排队后修改内容不会改变已提交构建；Worker 崩溃后任务可续租或明确进入死信；两个站点并发构建不会被单一全局锁无谓串行。

### M2 — 迁移工厂闭环（8–12 人日）

交付：

- `migration_sessions` 持久化状态机；
- 探测→抓取→解析→路由/模板识别→媒体盘点→映射→预览→提交→对比报告；
- WordPress REST/WXR、Sitemap、受控 crawl 统一为可恢复任务；
- 冲突/警告队列、人工确认、断点续传；
- 旧 URL→新 URL、SEO 字段、媒体、页面数量对账。

退出门槛：用一份获得授权的真实 WordPress 网站完成两次可重复迁移；中途杀死 Worker 后可续传；报告能解释所有缺失、冲突和重定向。

### M3 — 数据工厂闭环（10–15 人日）

交付：

- CSV/JSON/XLSX/XML、认证 HTTP API、只读 MySQL 连接器；
- 数据源 profile 与加密 secret reference；
- 分页/游标、限速、超时、重试、断点续传；
- staging rows、字段映射、验证、去重、错误下载；
- import batch、原始来源标识、人工覆盖优先级、可逆提交。

退出门槛：5,000 行交互验收和 50,000 行压力验收；故障注入后无半提交；回滚只撤销本批变更，不覆盖后续人工编辑。

### M4 — 编辑器、内容模型与站点模板（10–15 人日）

交付：

- locale/environment/publish policy/site blueprint 成为一等模型；
- 内容字段增加 enum、relation、array、media、唯一性、搜索/筛选和跨字段校验；
- draft→review→published→archived 工作流和审批审计；
- carousel/video/tabs/pricing/form-link/map/timeline/testimonials/team 等高频区块；
- 多页面站点模板，实例化时不复制私有业务内容；
- 主题升级差异预览、兼容检查和一键回滚。

退出门槛：从模板新建站点后能独立升级内容；键盘操作、焦点、语义、对比度和三档响应式视觉回归通过；多人编辑冲突不会静默覆盖。

### M5 — 发布与多语言（12–20 人日）

交付：

- 先加固现有 Release Agent：TLS、nonce/replay cache、最小权限、审计、外部健康探测、失败自动回滚；
- 再按业务优先级增加 SFTP、S3/CDN 或 Git CI 目标，不同时铺开所有连接器；
- `site_locales`、translation groups、locale route registry；
- canonical、双向 hreflang、多语言 sitemap 和语言切换；
- 灰度/预发布、缓存失效、发布后链接抽检。

退出门槛：一次失败发布可自动回到上个健康版本；重复签名请求不能重放；双语言站点不存在孤立翻译或错误 hreflang。

### M6 — 生产与企业治理（15–30 人日）

交付：

- OIDC/SSO、可选 MFA、会话撤销、权限回归测试；
- 审计日志外送/不可变保留；
- Prometheus/OpenTelemetry 或等价指标与追踪、SLO 和告警手册；
- 依赖审计、镜像扫描、SBOM、镜像签名和许可证清单；
- 容量、峰值、混沌、灾备演练；
- RPO/RTO 与保留策略经业务签字。

退出门槛：达到约定 SLO；恢复演练达到 RPO/RTO；高危漏洞为零或有经批准的限时豁免；值班人员仅凭 Runbook 能完成恢复。

## 6. 推荐的下一迭代（两周）

两周内只做一条平台纵切，不开启大规模 UI 扩展：

### 第 1 周

1. 修复备份句柄和 5 个 UTF-8 测试。
2. CI 增加 Windows，校正测试计数，注入并校验真实 SHA。
3. 增加安全响应头、TrustedHost 和可信代理配置。
4. 建立 SQLite/PG 两套 Docker smoke 脚本。
5. 定义 build snapshot、job event、artifact manifest 三个数据契约。

### 第 2 周

1. 实现不可变 build snapshot，改 Worker 只消费 snapshot id。
2. 给作业增加 progress/stage/events/dead-letter。
3. 迁移第一批遗留表到 schema registry，并验证空库升级和旧库升级。
4. 完成备份 manifest、SHA-256 校验和独立恢复命令。
5. 在 CI 执行一次“建站→构建→备份→清空测试部署→恢复→重新构建”的闭环。

迭代结束演示必须证明：提交构建后再修改页面，原任务仍生成提交时版本；Worker 被终止后任务不会丢；备份能在空白环境恢复；所有测试跨平台通过。

## 7. 架构优化原则

1. **数据库是业务事实源，队列不是。** Redis 只做通知；任务状态、幂等键和租约落数据库。
2. **构建输入必须不可变。** 审批、构建、发布都引用 snapshot/hash，不读取“现在的站点”。
3. **外部输入先暂存再提交。** 爬取、API、数据库和文件导入必须进入 staging，校验/映射/人工确认后再原子提交。
4. **路由是一等数据。** 使用 route registry 管理 locale、来源、行为和冲突，不从标题临时推断最终 URL。
5. **人工编辑优先级显式化。** 每个字段记录 source、source key、同步时间和 manual override，增量同步不得静默覆盖。
6. **大任务统一进入作业系统。** 请求线程只创建任务；迁移、抓取、媒体处理、构建、发布都可恢复、可观测、可取消。
7. **每个“完成”都有证据。** 单元测试证明代码分支，E2E 证明用户流程，恢复演练证明可恢复，试点签字证明商业可用。

## 8. 四个最终业务验收场景

项目不能仅以“测试全绿”宣告完整，还需完成架构文档要求的四类试点：

1. **A：WordPress 汽车网站迁移** — 页面、文章、产品、媒体、SEO 和重定向全量对账。
2. **B：工业企业新站搭建** — 从模板到内容录入、响应式编辑、构建、预发布和正式发布。
3. **C：增量数据更新** — 再次同步时更新源数据，但保留人工修改并提供冲突报告。
4. **D：模板复用** — 从已验收站点提炼多页面模板，新建站点不携带客户私有内容。

每个试点必须保存：输入清单、映射版本、构建 snapshot/hash、质量报告、发布记录、回滚记录、遗留问题和业务负责人签字。

## 9. 预计投入与排期建议

- M0–M1：10–17 人日，先串行完成，建立稳定地基。
- M2–M5：40–62 人日，可由两条工作流并行，但共享 schema/job/snapshot 契约。
- M6：15–30 人日，需结合真实部署和企业要求。
- 总计：65–109 人日；若由 2 名熟悉 Python/FastAPI、前端和 Docker 的工程师执行，合理日历周期约 9–14 周，另加真实试点反馈时间。

估算不包含大规模视觉设计、客户数据清洗、第三方服务采购和等保/渗透测试认证。若首个商业目标只需要 WordPress 迁移 + 静态发布，应把 SFTP/S3、多语言、SSO 分阶段开启，避免范围同时膨胀。

## 10. “完整项目”定义（Definition of Done）

只有同时满足以下条件，才能将版本标记为完整：

- 需求覆盖矩阵无未解释的缺口，所有延期项有明确版本和责任人；
- Windows/Linux 支持矩阵全绿，真实浏览器 E2E 和可访问性门禁通过；
- SQLite 和 PostgreSQL 的升级、备份、恢复、并发和故障测试通过；
- 迁移/导入/构建/发布均可中断恢复、审计和回滚；
- 构建产物可由不可变输入重现，发布可追踪到 commit、snapshot、theme 和 artifact hash；
- 四个业务试点完成并签字；
- 安全、供应链、监控、告警、Runbook、RPO/RTO 均有证据；
- 文档内容与当前代码、版本、测试数量和部署方式一致。