upgrade: adopt V8.21.3 (V8.13→8.21.3: P5 SFTP/S3, P6 multilingual, editor overhaul, enterprise hardening)

Overlay ~150 upstream items onto our V8.12 base, preserving trade-pro theme, registry tests, and design docs. Re-applied our patch set (discovery/env_for/blocks.css/type-mapping/theme_color/frontend entries, test_theme_pro_v3 mods) — all anchors survived upstream evolution. New platform enhancement (fixes upgrade-introduced regression): multilingual.site_locale now honors settings_json.locale, plus PUT /api/i18n/sites/{id}/locale — standalone English sites get <html lang='en'> under the V8.15 locale-rewrite pipeline. compose: adopt V8.21.3 (image 8.21.3-dev.1, /api/ready probes, MySQL/S3 env) with project name pinned to siteforge-v8-10 (data volumes). Tests: 356 passed / 11 failed — all 11 confirmed pre-existing in pristine V8.21.3 on this host (10 upstream Windows env + our build test now green after locale fix). Patch registry updated in plan doc. Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-23 12:31:03 +08:00
parent 257c89e159
commit 601451f22b
218 changed files with 10441 additions and 628 deletions
@@ -0,0 +1,298 @@
+# SiteForge Enterprise V8.12.0-dev.1 — 工作台流程与任务状态增强
+
+> **开发集成版，尚未通过 P0–P4 全部生产验收门禁。** 完整工程在 V8.11 基线上升级；P5/多语言和 Art Design Pro 官方工程等未在本轮解决。
+
+
+## V8.11：管理后台重新设计（本轮重点）
+
+默认 `http://localhost:8787/` 现使用 **简洁工作台**，保留原有业务 API 和数据结构，不迁移数据库。
+
+- **工作台**：网站数量、操作引导、最近网站；不要求初学者理解 Worker/SEO/主题 Schema。
+- **我的网站**：一个地方选择所有网站；创建新站的表单只保留必要字段。
+- **网站概览**：四步流程（建立网站、准备内容、完善设计、构建预览），动态提示下一步。
+- **内容与页面**：页面、产品、新闻统一管理，可快捷修改文字或进入可视化设计器。
+- **外观与设计**：行业主题选择与实际页面编辑；草稿/发布隔离仍由原编辑器负责。
+- **导入与迁移**：默认进入带预演、复核与批次回滚的导入工作台；小文件直写保留为高级操作且必须确认。
+- **构建与交付**：使用既有异步 Worker，预览、静态 ZIP、质量报告集中呈现；正式审批和远程发布保留在企业交付中心。
+- **网站设置**：站点名称、域名、公司标语、Logo、类型等从设计功能中独立出来。
+- **高级工具**：折叠保留原有生产控制台、任务与审批、主题预览以及历史后台 `/classic`，确保不丢功能。
+
+新增页面在 `app/templates/workspace.html`，样式和功能逻辑在 `app/static/workspace.css`、`app/static/workspace.js`。
+专业页面已经使用 V8.11 的统一导航与分组交互；Art Design Pro 官方完整工程仍未正式编译整合。
+
+**运行前后检查**：登录、创建站点、内容编辑、主题切换、文件导入、异步构建、预览/ZIP、手机宽度侧边栏。
+
+**注意**：新 UI 不改变业务 API 或权限模型；`/classic` 留作过渡。真实浏览器/生产 Docker 的全面实机回归仍应在目标服务器执行。
+
+---
+
+## V8.9 已有能力（原样保留）
+
+
+
+1. **P0 离线恢复安全**：恢复前校验 ZIP 路径、内容范围和数据库完整性；同文件系统暂存目录重命名切换，保留原数据目录以便回退，失败不先覆盖旧数据库。使用 `python scripts/restore_backup.py backup.zip --data /path --confirmed-offline`（务必先停 Web/Worker），完整备份生成用 `python -m app.backup`。
+2. **P2 WordPress 响应式图片**：解析 `srcset`、`data-src`、`data-srcset`、`picture/source` 和视频 poster 的外部资源引用；受限本地化后保留宽度/倍数提示及懒加载 URL，无法处理的外链进入迁移复核，绝不静默删除 CDN 引用。外部 CSS 背景图、任意复杂插件布局仍未全面迁移。
+3. **P3 5000 条真实构建**：独立 SQLite 夹具 10×500 记录实际导入 5,000 条并生成超 5,000 个静态 HTML；构建器预计算品牌/分类索引，交付检查和质量审计改为流式处理，避免随内容数平方增长；正式 SEO 警告仍需清理。
+4. **P4 维持现有设计器与模板**：保留跨设备列设置、页面草稿、全站设计草稿、Owner 整站套版与事务回滚；针对优化过的构建器/质量检查加入回归测试。
+
+**验收报告与限制：** [P0–P4 V8.9 评估](docs/P0_P4_V8_9_VERIFICATION.md) | [原验收矩阵](docs/P0_P4_ACCEPTANCE_MATRIX.md)
+
+## 启动与测试（Windows PowerShell / Docker Desktop）
+
+```powershell
+# 在解压后的项目根目录执行，首次生成 .env
+# 不能直接覆写旧项目数据；务必使用新测试卷
+docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py
+docker compose up -d --build
+docker compose ps
+```
+
+- 简洁管理后台（默认推荐）：`http://localhost:8787/`
+- 旧版专业操作页：`http://localhost:8787/classic`
+- 高级数据与迁移工具：`http://localhost:8787/production-v8`
+- 主题中心：`http://localhost:8787/theme-gallery`
+- `/api/health` 应返回平台版本 `8.10.0-dev.1` 和构建提交标识。
+- 本地测试：`bash scripts/check.sh` 或 Windows PowerShell `scripts/check.ps1`。
+- 独立 5000 条验收：`python scripts/pilot_5000.py --report pilot.json`（默认只验证 5,000 条导入）。有足够资源的测试机上加 `--build` 同时检查整站构建；仍需分开核查 SEO 警告。。
+
+## 迁移及回滚注意
+
+离线恢复在目标目录旁保留 `*.pre-restore-*` 原数据目录；恢复完成后先验证旧构建、媒体、权限和管理员登录，再确认是否可以清理原目录。请先把备份 ZIP 拷贝到 Docker 卷之外。此恢复脚本适用于 SQLite 单机数据；**不是 PostgreSQL 恢复工具**。恢复前 Web 与 Worker 必须全部停止。
+
+## 开发验收边界
+
+此版本未在当前环境执行 Docker Engine、GitHub Actions 云端 CI、真实授权 WordPress 全站迁移、MySQL TLS 实机、生产密钥轮换以及桌面/移动浏览器完整视觉验收。P0–P4 尚不能全部标为生产交付完成。跨域 CDN、CSS 背景资源、付费/私有 WordPress 数据及复杂 WooCommerce/Elementor 页仍需定制适配与人工复核。
+
+---
+
+## 历史功能说明（原 V8.8/之前版本，仅供追溯）
+
+# SiteForge Enterprise V8.8.0-dev.1 — P0–P4 集成增强版
+
+> **交付状态：开发集成版，尚未通过 P0–P4 全部门禁，不应作为正式商业验收报告。**
+
+本版延续 V8.7 的完整源码，聚焦 P4（响应式独立列布局、图片素材库、整站模板两步审核与多页原子操作），同时修复深层页面 CTA/媒体根路径问题、版本与 Compose 遗留问题。旧站迁移、数据装配、安全 HTTP、Worker、四套主题继续保留。
+
+- **P4 设备布局**：页面中的多列区块可设置平板/手机独立列数、排序、跨度和显示隐藏；所有自定义 CSS 经过严格参数校验，并按页面作用域生成。
+- **P4 模板套版**：生产控制台先预检、再暂存，最后 Owner 发布；冲突拒绝、失败回滚，同步保证数据与 SEO 不被模板业务内容覆盖。旧版直接应用 API 需显式设置开发兼容开关。
+- **P4 媒体素材**：编辑器新增本站图片库选择，支持图片组件、画廊和轮播；深层页面正确使用根路径。
+- **验证状态与全部遗留**：[P0–P4 验收矩阵](docs/P0_P4_ACCEPTANCE_MATRIX.md)。
+- **运行**：与 V8.7 一样，首先在独立测试目录执行 `python scripts/init_config.py`（或 Docker 运行该脚本），再 `docker compose up -d --build`。不得覆盖运行中的旧版数据卷。
+
+---
+
+## V8.7 历史项目说明（保留升级依据）
+
+# SiteForge Enterprise V8.7.0-dev.1 — 全站设计草稿与响应式管理
+
+> **交付状态：开发试点版。** 本轮基于 V8.6 延续原 Web + Docker 工程，不是单独演示网站。
+
+## V8.7 本轮实际实现
+
+- **全站设计草稿**：`GET/PUT/DELETE /api/sites/{site}/site-design` 管理独立草稿；`POST /site-design/publish` 才更新用于正式构建的全站配置。对 `revision` 和底层设置指纹做并发冲突检查，发布记录保存在 `site_design_publications`。
+- **统一页眉/页脚/导航**：支持安全的三级导航、搜索显示、顶部公告、联系 CTA、页脚标题/介绍/邮箱、页脚菜单显示选项；四套专业主题的最终 HTML 均消费同一份配置。导航只允许站内路径，严禁任意脚本、外部链接注入。
+- **响应式控制**：平板与手机的区块间距、手机内容左右内边距、移动端公告和页脚导航显隐；已写入最终静态 `assets/custom.css` 和可视化编辑器预览 CSS。它是可交付的响应式参数编辑，**并非**完整独立设备画布。
+- **设计令牌统一入草稿**：字体、标题缩放、版心宽度、圆角等改为全站草稿保存/发布；未经发布不会更改新构建。编辑器内可在“设计规范”和“全站页眉与页脚”面板操作。
+- **关闭旧版直写绕过**：`/blueprint` 直写、旧导航直写、旧设计令牌直写及 `PATCH entry.meta` 的布局直写，在生产环境默认返回 HTTP 409。旧脚本若必须临时过渡，可显式设 `SITEFORGE_ALLOW_LEGACY_DIRECT_DESIGN_WRITE=1`；**正式生产不应启用此选项**。原后台导航表单与企业设计令牌页已改写全站草稿。
+- **测试**：在现有 168 项回归基础上新增 13 项专项测试，验证四主题、草稿构建隔离、发布、设计令牌、安全输入、跨站隔离、并发拒绝、旧接口安全门禁。
+
+### 使用方法
+
+1. 解压后先在**独立测试环境**启动 Docker（以下为 PowerShell）：
+
+   ```powershell
+   docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py
+   docker compose up -d --build
+   ```
+
+2. 登录 `http://localhost:8787/`，进入任意站点页面的 `/editor/{site_id}/{entry_id}` 设计器。
+3. 点击 **全站页眉与页脚**，调整导航/页眉/页脚/手机与平板设置，点击 **预览草稿**，随后 **保存全站草稿**。
+4. 由网站 Owner 点击 **发布全站设计**，然后触发 Worker 网站构建。现有已发布静态版本不会因保存或发布设计而被原位篡改。
+5. CI 中可执行 `pytest`、Python 编译检查、`node --check`；Docker、真实浏览器和服务器发布需要独立实机验收。
+
+### API 及兼容性
+
+| 方法与路径 | 行为 |
+|---|---|
+| `GET /api/sites/{site}/site-design` | 返回已发布配置或草稿、版本、冲突状态 |
+| `PUT /api/sites/{site}/site-design` | 携带 `config` 与 `expected_revision` 保存草稿 |
+| `POST /api/sites/{site}/site-design/publish` | Owner 审核发布，要求版本号 |
+| `DELETE /api/sites/{site}/site-design` | 删除未发布草稿 |
+| `GET /api/sites/{site}/site-design/publications` | 查询最近的发布审计记录 |
+| `POST /api/sites/{site}/pages/{entry}/editor-preview` | 请求体的 `site_design` 可预览未发布的整站草稿 |
+
+### 明确未完成
+
+- 目前并非 Figma 式自由定位编辑；完整 PC/平板/手机**独立布局**、全站模板可视化拖拽、实时跨设备视觉验收仍待开发。
+- 旧版批量套版及部分内容创建接口仍可能更新布局，需在后续将所有设计变更统一纳入发布工作流；本次仅限制上述直接绕过入口。
+- Art Design Pro 官方工程、复杂 CMS 无损迁移、PostgreSQL/Redis 多实例、SFTP/S3 正式发布仍未完成完整实机验收。
+- 当前环境无 Docker Engine，**不能宣称** `docker compose up` 已实机通过；亦未完成 GitHub 云端 CI 和真机 Chrome 视觉回归。
+
+---
+
+## 上一版 V8.6 的开发记录（保留供升级追踪）
+
+# SiteForge Enterprise V8.6.0-dev.1
+
+> **状态：开发试点版，P4 设计器与整站模板增强。** 同一主线延续 V8.5 的认证 API、只读 MySQL、V8.4 XML/API、WordPress 迁移、四套主题、构建 Worker 和发布审批。尚未完成正式商业/生产验收。
+
+## 这一轮新增（P4）
+
+- **六种声明式组件**：`carousel` 图片滚动展示、`video` YouTube/Vimeo 白名单视频、`tabs` 可访问详情分组、`pricing` 服务方案、`map` 可信地图外链、`form_link` 询盘入口。都使用可信渲染器输出，不允许用户提交 JavaScript。
+- **独立设计草稿**：V8.6 可视化编辑器的“保存草稿”只写入 `studio_drafts`，不会修改正式 entries 或被静态构建读取；“发布设计”才会原子写入正式页面，随后需重新构建静态网站。
+- **并发保护**：每次草稿更新携带 `expected_revision`；正式页面被其他人改动后，拒绝发布，防止静默覆盖。放弃草稿会恢复正式版设计。操作支持站点权限隔离与审计。
+- **整站模板兼容性**：模板带主题版本声明；新增 `/whole-site-templates/preflight` 无副作用检查，验证主题是否存在、指定版本是否可用、已安装组件、已有路径，后台预检后再应用。
+- **前端操作入口**：原 `/editor/{site_id}/{entry_id}` 页面新增保存草稿、发布设计、放弃草稿；整站模板控制台在应用前执行独立兼容性检查。原 `/blueprint` 直写接口保留兼容旧系统，尚未完全禁用。
+
+### Docker 运行
+
+Windows PowerShell（在解压后的项目根目录）：
+
+```powershell
+docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py
+docker compose up -d --build
+docker compose ps
+```
+
+页面：管理台 `http://localhost:8787/`；生产控制台 `/production-v8`；主题 `/theme-gallery`；设计器从网站页面进入 `/editor/{site_id}/{entry_id}`；API 版本 `/api/health`。
+
+首次升级必须使用**独立测试环境和数据副本**，备份 `.env`、数据库、媒体及归档。草稿表通过幂等方式初始化，未在原有生产数据库上完成实际迁移演练。
+
+### P4 接口
+
+| HTTP 接口 | 用途 |
+|---|---|
+| `GET /api/editor/blocks` | 读取组件注册表与属性契约 |
+| `GET /api/sites/{site}/pages/{entry}/studio-draft` | 获取当前草稿或正式布局 |
+| `GET /api/sites/{site}/pages/{entry}/studio-draft/preset?page_template=home` | 获取主题预设，不修改正式页 |
+| `PUT /api/sites/{site}/pages/{entry}/studio-draft` | 保存草稿，要求 `expected_revision` |
+| `POST /api/sites/{site}/pages/{entry}/studio-draft/publish` | 发布设计，需要 owner 角色和 `expected_revision` |
+| `DELETE /api/sites/{site}/pages/{entry}/studio-draft` | 放弃草稿 |
+| `POST /api/factory/sites/{site}/whole-site-templates/preflight` | 整站模板无副作用兼容检查 |
+
+开发环境已经完成 **168 项本地 pytest**、全部 JavaScript 语法与版本检查，另有“草稿构建不包含未发布内容 → 发布后重新构建包含内容”的实测回归。
+
+**未验收**：Docker Engine 实机、GitHub 云端 CI、浏览器 PC/手机端手工交互、真实客户内容视觉检查、Art Design Pro 官方工程编译、复杂 WordPress 无损迁移、PostgreSQL/Redis 多实例能力、SFTP/S3 正式发布。
+
+详细信息见 [V8.6 验收与剩余需求](docs/V8_6_RELEASE_STATUS.md)。
+
+---
+
+## 历史版本功能参考（以下内容为 V8.5 及更早阶段的开发记录，不是 V8.6 最新状态）
+
+---
+
+## V8.4 历史能力（继续保留）
+
+
+> 当前阶段：统一网站生产工厂，**P3 数据连接器第一轮（安全 XML、公开 JSON API + Worker）**。本版本是开发试点版，并非所有网站工厂需求均已实现。
+
+## V8.4 本轮新增
+
+- **安全 XML 导入**：`/production-v8` 可以上传 XML，选择记录节点、内容类型和字段映射，支持扁平或两级结构；使用 `defusedxml` 禁用 DTD 与外部实体，并限制最大 8 MB、1000 条记录及节点/深度上限。
+- **公开 HTTPS JSON API**：设置 `url`、JSON 列表路径（例如 `data.items`）、字段映射和分页；创建后提交 Worker 后台采集，使用既有租约/取消/重试/超时机制。每页形成独立暂存批次，可以审批提交或回滚。所有采集均不自动上线。
+- **进度和误差边界**：最多 50 页 × 每页 100 条，合计 5000 条；发生中断从已保存页码继续，复用已有同页批次避免重试重复写入；达到最大页数而上页满额会显示 `limit_reached`，不能视为采集完整。
+- **统一后台**：新增 XML 文件上传、API 创建、采集任务、取消和进度查询操作区域，并保留 WordPress 迁移、主题和编辑器。
+- **版本与 CI**：统一应用版本标记、Compose 名称、脚本和 CI 版本断言为 `8.5.0-dev.1`；**144 项本地自动化测试通过**。
+
+[详细功能、接口、安全限制与剩余需求](docs/V8_4_RELEASE_STATUS.md)
+
+**边界**：目前 API **只支持无需认证的公开 JSON**，不支持带密钥 API；MySQL 只读连接器、完整 Art Design Pro 编译和生产级外部发布也尚未完成。没有运行 Docker 实机或云端 CI，因此不得将该版本称为企业正式上线完成版。
+
+---
+
+## 既有 V8.3 迁移与建站功能（本轮保留）
+
+
+> SiteForge Enterprise 统一开发主线：**WordPress 可恢复迁移 + Sitemap 完整性审计 + 有界媒体本地化 + Worker 后台采集**。
+>
+> 版本状态：开发试点候选版，不可直接对外宣称完整 WordPress 无损迁移或企业生产部署已验收。V8.1 网站、主题、编辑器、导入批次和静态构建功能均在此版本继续维护。
+
+## 快速启动（Docker Desktop / Linux Docker）
+
+项目根目录第一次初始化：
+
+```bash
+# PowerShell 将 `$(pwd)` 改为 `${PWD}`
+docker run --rm -v "$(pwd):/project" -w /project python:3.12-slim python scripts/init_config.py
+docker compose up -d --build
+docker compose ps
+```
+
+- 登录：`http://localhost:8787/`
+- **V8.4 生产控制台**：`http://localhost:8787/production-v8`
+- 主题管理：`http://localhost:8787/theme-gallery`
+- 页面编辑：`http://localhost:8787/factory-studio`
+- 任务中心：`http://localhost:8787/operations`
+- 构建版本：`http://localhost:8787/api/health`；当前应显示 `8.5.0-dev.1`。
+
+**升级注意：** 不要直接覆盖 V8.1 正在运行的存储卷。先备份 `.env`、数据库、媒体和生成文件，在独立 Compose 项目中完成验收，然后安排升级与回滚。新版本表结构采用幂等的 `CREATE TABLE IF NOT EXISTS`，但并未进行真实旧数据库原地升级演练。
+
+## V8.3 新增：WordPress 关系数据与归档 URL 保真
+
+- 为每次 WordPress 迁移会话采集公开 REST 分类、标签和媒体库**元数据**，分别保存页码和已采集数量。关闭页面后可以继续下一页。
+- 原始 WordPress ID、分类/标签/特色图片的关联 ID 写入批次记录和关系索引；导入确认前，在已同步名称的情况下补充分类/标签字段；绝不凭空创建不存在的分类内容。
+- 分类/标签来源归档 URL 纳入旧站 SEO 基线。无对应的新页面或批准重定向时，需要通过差异检查处理。
+- 对缺失的标签/分类、未知特色图片、ACF 和页面构建器内容保留人工审核事项。公开 ACF 只保留有界快照，不承诺原样转换。
+- 控制台按钮：选择“分类 / 标签 / 媒体库”→ “同步目录下一页”→ “目录进度”，完成后再核对媒体和 Sitemap，最后确认导入。
+
+详细的操作与验收边界见 [V8.3 开发验收报告](docs/V8_3_RELEASE_STATUS.md)。
+
+## V8.3 迁移流程与增强
+
+1. 创建迁移会话：指定授权 WordPress 来源和最多采集条数。
+2. **提交 Worker 后台采集**：一次提交到统一数据库任务队列，Worker 子进程逐页采集 WordPress REST `pages/posts`，保持每页检查点。浏览器关闭后可以继续执行。
+3. 在任务中心监控扫描的排队、执行、取消、重试、超时等状态。扫描任务不会自动提交暂存内容、不会直接上线。
+4. **发现 Sitemap**：单独读取 WordPress `wp-sitemap.xml`；支持 `sitemapindex` 嵌套与有界 gzip XML，记录未从 REST 采集到的 URL。若使用 Yoast 或 RankMath 自定义 Sitemap，可以通过 API 指定同源 URL。
+5. **媒体本地化**：在最终导入前，手动分批读取（每次最多 40 个）暂存文章中的图片，限制大小、格式、原站域名，自动重写正文及特色图片路径。其他 CDN 域名默认拒绝自动下载，并形成待复核项。
+6. 检查扫描结果、Sitemap 缺页和图片缺失，明确点击“确认并导入”。将旧 URL / SEO 清单加入审计；存在未处理差异的迁移站继续受发布审批门禁限制。
+7. 选择主题后使用原有 Worker 构建网站，查看 QA 和 ZIP。
+
+**重要边界**：Sitemap 只用于发现遗漏，并不自动解析任意 Sitemap 页面内容；完整的 `srcset`、CSS 背景图片、跨域 CDN、附件、视频、登录后数据及复杂 Elementor/ACF/WooCommerce 迁移仍需要额外适配和人工复核。未运行 Sitemap 完整性审计时，系统不能保证完整发现旧站 URL。WP 媒体本地化是用户主动触发的、同步分批执行的步骤，不会在后台无界下载资源。
+
+## V8.3 主要接口
+
+所有接口需要原有 Session + CSRF + 网站权限；`POST` 不允许匿名调用。
+
+| 接口 | 说明 |
+|---|---|
+| `POST /api/migrations/sites/{site}/wordpress/sessions` | 创建迁移会话 |
+| `POST /api/migrations/sites/{site}/wordpress/sessions/{session}/scan` | 将 REST 扫描加入 Worker 队列；可传 `idempotency_key` |
+| `GET /api/migrations/sites/{site}/wordpress/sessions/{session}` | 查询检查点、页数和警告 |
+| `POST /api/migrations/sites/{site}/wordpress/sessions/{session}/sitemap` | 安全发现同源 Sitemap，JSON 可传 `url` |
+| `GET /api/migrations/sites/{site}/wordpress/sessions/{session}/sitemap` | 已发现 URL 数、缺失计数、前 100 项示例 |
+| `POST /api/migrations/sites/{site}/wordpress/sessions/{session}/media/localize` | 分批媒体本地化，JSON `limit` 1–40 |
+| `POST /api/migrations/sites/{site}/wordpress/sessions/{session}/finalize` | 明确确认提交，建立 URL/SEO 基线与复核项 |
+| `POST /api/migrations/sites/{site}/wordpress/sessions/{session}/cancel` | 取消会话；正在运行的任务另在任务中心申请取消 |
+
+后台扫描任务使用 `build_jobs.kind='wordpress_scan'`，与原网站构建共享 Worker/容量限制/租约/退避。可使用 `/operations` 监控或使用既有企业任务 API。**扫描完成不代表迁移交付完成**。
+
+## 测试与已知限制
+
+```bash
+bash scripts/check.sh
+python scripts/verify_release.py
+```
+
+截至本次代码交付，130 项自动化测试在当前开发环境全部通过，包含 V8.2 的 120 项和本轮的 10 项专项测试。测试覆盖嵌套 Sitemap、压缩炸弹、XXE、缺页审计、媒体格式与同源限制、子进程任务派发、幂等、容量门禁、API 鉴权等。
+
+本环境没有 Docker Engine；没有实际执行 Docker 实机启动、GitHub 云端 CI、官方 Art Design Pro 编译、真实 WordPress 全量迁移、浏览器全流程或远端正式发布。是否能交付企业生产仍需上述验收。
+
+接下来的 P2 收尾任务：自动尝试多种 Sitemap 路径、WordPress 媒体库/分类标签迁移、REST 采集的统计/重试监控、媒体 CDN 授权白名单和批量迁移压测。之后再推进 P3 XML/API/只读数据库连接器、P4 整站编辑器、P5 安全发布、多语言与 PostgreSQL/Redis 生产化。
+
+更多细节：[V8.3 验收与剩余功能](docs/V8_3_RELEASE_STATUS.md)。
+
+## V8.11：统一专业管理体验
+
+本版在 V8.10 基础上统一五个专业工具页面的导航、当前网站选择、业务提示、表单焦点和操作按钮。编辑器将“草稿/预览/正式发布”分组，平板和手机提供结构/预览/属性面板切换；任务中心按迁移、构建、审批发布分为三个阶段。所有原业务 API 与 Docker 服务保持不变。
+
+- 默认工作台：`http://localhost:8787/`
+- 主题预览：`/theme-gallery`
+- 页面编辑器：从工作台的“外观与设计”进入
+- 高级建站：`/factory-studio`
+- 数据迁移：`/production-v8`
+- 任务与交付：`/operations`
+
+详细功能对照与人工验收清单见 [`docs/V8_11_UNIFIED_ADMIN.md`](docs/V8_11_UNIFIED_ADMIN.md)。
+
+运行测试：`python -m pytest -q --disable-warnings`。本版在当前环境通过 218 项测试。Docker 实机与浏览器跨设备回归仍需部署后完成。
@@ -0,0 +1,12 @@
+# P6 快速操作
+
+登录 `http://localhost:8787/` → 我的站点 → 建立中文与英文两个独立 HTTPS 站。
+
+1. 进入“多语言管理”，创建语言组与两个语言站成员。
+2. 在中文站与英文站分别录入已翻译页面，各自设置 `status=published`。
+3. 建立翻译内容组（例如 `product:example`），将两个实际页面 ID 分别关联为 `approved`。
+4. 重新构建两个站点，并查看生成 HTML 与 Sitemap；无对应翻译的页面不会显示语言互链。
+5. 待翻译文案先存为 `draft`，可以关联为 `pending`，待审核确认以后改为 `published` 并设为 `approved`。
+6. 使用“构建与交付”审批发布。上线前仍需在真实域名上逐一核对 canonical、链接、翻译质量和 SEO。
+
+数据库升级为加法建表，不会自动复制或修改原网站内容。升级前请先备份现有卷。
@@ -0,0 +1,43 @@
+# SiteForge V8.13 — P5 发布闭环的交付与验收清单
+
+版本：`8.13.0-dev.1`。此报告区分 **源代码实现/本地自动化测试** 与 **Docker/外部生产实机验收**。
+
+## 本轮实现与已有能力
+
+| 验收点 | 当前状态 | 证据 / 限制 |
+|---|---|---|
+| 构建完成且 ZIP 可用 | 已实现与单元测试 | `release_api.approved` + `_archive_for` |
+| 静态质量、SEO 迁移审核、独立审批 | 已有代码 + 本轮 API 专项测试 | 未审批返回 409，迁移站差异会阻断 |
+| Web 不执行远程大文件上传 | 已实现 | API 提交 `remote_deploy` / `remote_rollback` 任务，返回 HTTP 202 |
+| 任务超时、幂等、容量、取消 | 已有 Worker + 本轮补充测试 | 单机 SQLite 租约；不是多区域事务 |
+| 远程 ZIP 不可变暂存 | 已实现与签名 Agent 模拟测试 | 按存档 SHA256 前 20 位命名，不更改 current |
+| 远程文件 SHA256、清单核验 | 已实现与模拟测试 | 篡改文件后拒绝激活 |
+| 单次版本切换 | 已实现与模拟测试 | `current` 指针文件通过 `os.replace` 原子替换 |
+| 激活后二次校验与首页探针 | 已实现与模拟测试 | 比对 Agent 公开首页的 SHA256；不等于真实域名探测 |
+| 异步历史版本回滚 | 已实现与模拟测试 | 仅回滚数据库记录中该站点该目标的版本；验真后切换 |
+| 目标密钥不进入前端 | 已实现的环境引用方案 | 推荐挂载到 `/run/secrets`，待生产轮换验收 |
+| SFTP / S3 原生连接器 | **未实现** | HTTPS 发布 Agent 为当前唯一可运行的远程目标类型 |
+| 真实 Docker、外网 TLS、CDN、域名 | **待实机验收** | 当前环境无 Docker Engine；没有公网发布测试服务器 |
+| 发布取消在切换瞬间的跨服务一致性 | **未完全解决** | 需增加远程状态 reconciliation / 运维确认 |
+| PostgreSQL/Redis 多 Worker | **待生产验收** | 独立 Compose 已配置但未完成真实高可用测试 |
+
+## 确定性专项测试
+
+- 不经过激活就上传两个版本时，当前线上指针保持不变。
+- 篡改 staging 文件后，Agent 拒绝激活且旧站保持可访问。
+- 伪造签名、非法 ZIP 路径、保留文件名、同名冲突会被拒绝。
+- 已批准构建通过异步 API 提交，在队列中去重；未批准构建禁止提交。
+- 运行签名 Agent 的完整暂存、校验、激活、再次验证、回滚逻辑（本地 TestClient 模拟）。
+- 任务数量达到上限时拒绝新任务；取消排队任务不影响已发布内容。
+
+## 正式上线前需要的人工/环境门禁
+
+1. Docker 一条命令在全新宿主机成功启动 Web 与 Worker，并验证 `/api/health` 精确报告版本/提交。
+2. 将 Agent 部署于真实 HTTPS 测试域名，独立密钥及 TLS 证书有效；仅开放预期入口。
+3. 在授权测试网站完成两轮发布，故障注入覆盖上传中断、校验失败、切换成功后 Web 超时、Worker 取消。
+4. 核对站点正式域名的首页、产品详情、404、canonical、sitemap、robots、媒体与链接。
+5. 验证真实站点切换/回滚并确认时间、缓存失效、老 URL 保留。
+6. 审计密钥轮换、管理员/审核人权限、备份/恢复和日志中的敏感数据。
+7. 完成 SFTP/S3 等其它发布方式后，逐个通过等价事务性/故障恢复门禁。
+
+**结论**：V8.13 的 HTTPS Agent 远程发布形成了本地可测试的发布闭环；尚不符合全部 P5 生产验收条件。
@@ -0,0 +1,32 @@
+# SiteForge Enterprise V8.14 — P5 原生发布验收记录
+
+版本：`8.14.0-dev.1`。本版在 V8.13 上添加 SFTP / S3 原生发布适配器、只读 S3 发布指针网关、统一发布目标状态与回滚入口。
+
+## 本轮已实现且有确定性测试覆盖
+
+| 能力 | 实际实现 | 测试边界 |
+|---|---|---|
+| 默认 HTTPS 签名 Agent 向后兼容 | 原发布 API、队列、签名与审批不变 | 继承 V8.13 专项回归 |
+| SFTP 主机密钥校验 | Paramiko RejectPolicy + 必须预置 known_hosts 和 SSH 私钥文件 | 配置与仿真 SFTP 文件系统测试，**未真实握手** |
+| SFTP 不可变目录与原子激活 | 分版本目录、SHA256 manifest、原子符号链接切换与回滚 | 本地仿真、注入损坏/探针失败；OpenSSH 实机待验收 |
+| S3 分版本对象上传 | 不变对象键、SHA256 内容校验、条件写入 current.json | FakeS3 条件语义测试，真实 AWS API 待验收 |
+| S3 网站读取服务 | 只读 gateway 根据版本指针解析站点资源，不直接曝光存储凭据 | ASGI TestClient + FakeS3 测试 |
+| 远端失败恢复 | 上传/校验失败保持旧版本；探针失败尝试恢复前一版本 | 本地故障注入测试 |
+| 审批、Worker、部署记录 | 原 API 选择后端、异步执行、记录发布与回滚 | 自动化测试 |
+| 后台展示 | 新增发布类型/目标配置状态、已发布版本回滚按钮 | JS 语法与组件级回归，真实浏览器待验证 |
+| 依赖与 Docker | 添加 boto3/Paramiko 完整依赖与 Compose 使用示例 | 配置审查；无 Docker Engine 实机验证 |
+
+## 不应宣称已完成的事项
+
+- SFTP 真实 SSH/TLS、主机指纹、私钥权限与 OpenSSH 原子扩展实测；环境中无法安装 Paramiko 验证真实服务器操作。
+- AWS/S3 真实凭据、桶 IAM、S3-compatible 条件写入能力及 CDN/域名部署。
+- Docker 单机真实启动、Linux CI 云端执行、浏览器桌面/移动端流程、各生产环境实际回滚演练。
+- 发布切换瞬间 Worker 崩溃的跨系统状态对账、长时间任务协调、完整运维监控、缓存刷新和 DNS 自动化。
+
+## 后续门禁
+
+1. 实际 Docker Compose clean room 部署+版本核查；两个账户完成一次分权审批。
+2. SFTP 容器夹具：上传、异常断网、错误 host key、目录符号链接攻击、原子切换和回滚。
+3. MinIO/S3 实机夹具：不可变对象校验、并发指针更新、被篡改对象、只读网关、旧版本回滚。
+4. 正式测试域名：主页、产品详情、404、canonical、sitemap、robots、媒体、缓存状态、安全响应头。
+5. 中断/重试后远端实际 current 与数据库发布历史 reconciliation；完成后才能标记 P5 生产通过。
@@ -0,0 +1,34 @@
+# SiteForge Enterprise V8.15 — P6 多语言建设与验收
+
+## 本轮完成的能力
+
+| 验收点 | 状态 | 证据 |
+|---|---|---|
+| 多语言站点组和默认语言 | 本地通过 | `language_groups` / `language_sites` / API |
+| 同一内容关联不同语言页面 | 本地通过 | `translation_units` / `translation_members` |
+| 已审核、已发布页面生成双向 hreflang | 本地通过 | 中英两站实际构建 + 自动化测试 |
+| sitemap 含 XHTML hreflang | 本地通过 | 两站 sitemap.xml 验证 |
+| 不存在的翻译不生成伪造链接 | 本地通过 | 缺失、草稿、noindex 测试 |
+| 待翻译内容不能意外发布 | 本地通过 | 仅 draft 可 pending，误设 published 时拒绝静态构建 |
+| x-default 指向默认语言 | 本地通过 | 明确默认语且存在审批页面才输出 |
+| 前台语言切换导航 | 代码完成 | 动态注入，并需真实浏览器视觉验收 |
+| 后台多语言菜单及表单 | 代码完成 | 集成 JS / API，真实浏览器端操作仍待验收 |
+| 原 243 项测试兼容 | 本地通过 | 本地 pytest 248 passed（含 5 项 P6 专项） |
+| 真实 Docker、Chrome、正式域名 | 待验收 | 当前环境无完整 Docker/远程域名实机测试 |
+
+## 主要限制
+
+1. **域名模式**：目前一个语言站一个独立 HTTPS 域名或子域名；同域子路径需进一步设计反向代理、站点构建根路径和 sitemap。
+2. **翻译质量**：不自动翻译事实，`approved` 表示人工确认的状态标记，不包含另一人独立翻译审批的完整审计流程。
+3. **动态语言链接**：已发布数据可生成对应 URL；必须额外核对真正上线服务器是否已有该版本，不等于远程可访问性证明。
+4. **各主题国际化**：四套主题中部分组件和预设仍为中文。正式外语商业交付需按语言提供真实导航、字段标题和空状态文案。
+5. **企业生产**：Art Design Pro 官方完整工程、PostgreSQL/Redis 多实例、真实 SFTP/S3 等依旧需要实机验收。
+
+## 手工部署验收步骤
+
+1. 在新 Docker 项目卷启动 V8.15；核对 `/api/health` 返回 `8.15.0-dev.1` 与期望提交 SHA。
+2. 创建两个真实的 HTTPS 语言域名站，填写翻译过的公司主页和产品页。
+3. 建立一组真实对应关系；分别构建和下载静态站，验证 URL、html lang、canonical、sitemap、hreflang 的对称性。
+4. 随机挑选缺翻译、草稿和 noindex 的页面，确认其不会产生无效的互链；将 pending 内容错误设为 published，确认构建被拒绝。
+5. Chrome/手机端点击前台语言切换，验证页面存在、焦点可达、移动布局无溢出。
+6. 正式发布前审批，两站完成远程发布后从公网检查首页和内页的 hreflang 相互指向，不将示例 `.example.org` 域名当作有效服务。
@@ -0,0 +1,40 @@
+# SiteForge Enterprise V8.16 — 企业部署基础验收记录
+
+版本：`8.16.0-dev.1`；阶段：**开发集成（非生产认证）**。
+
+## 本轮新增与测试门禁
+
+| 验收项 | 验证路径 | 当前结果 |
+| --- | --- | --- |
+| PostgreSQL 查询行数字/字段访问 | `tests/test_production_v816.py` | 本地模拟测试通过 |
+| PostgreSQL SQL 占位符、注释及 DDL 分句 | 同上 | 本地单元测试通过 |
+| PostgreSQL 初始化及 schema ledger | `scripts/verify_pg_bootstrap.py` | 脚本已扩展；需要 PostgreSQL 实例实测 |
+| PostgreSQL Worker `FOR UPDATE SKIP LOCKED`、事务与任务恢复 | CI `postgres-smoke` | 自动检查代码已接入；本机没有 PG 服务，未实际通过 |
+| Worker 按实例隔离心跳 | `tests/test_production_v816.py` | 本地通过 |
+| `/api/ready` 探针成功/失败及脱敏 | `tests/test_production_v816.py` | 本地通过 |
+| 全平台自动化回归 | `scripts/check.sh` | 按模块三组通过：95+82+78 = **255 项** |
+| HTTP + Worker 实际建站链路 | `python scripts/http_end_to_end.py` | **本地通过**：建站、保存、队列、静态 ZIP、预览 |
+| Chromium 桌面/移动端真实交互 | `scripts/browser_smoke.py` | **环境阻断**：`ERR_BLOCKED_BY_ADMINISTRATOR`，未通过 |
+| Docker Engine Web + Worker | `docker compose up -d --build` | 本机无 Docker Engine，未运行 |
+| Redis 通知故障降级 | 历史单元测试 | 通过；真实 Redis 容器未运行 |
+| Art Design Pro 官方构建 | 用户提供官方完整源码后执行 pnpm/构建 | **未完成**；交付包含安装脚本/适配页面，不含官方完整项目 |
+| 公网 SFTP/S3/HTTPS 上线和回滚 | 独立预生产环境 | **未完成** |
+
+说明：单进程连续执行所有 pytest 在约 84% 时超时；上述 255 项是三个独立 pytest 进程（95/82/78）分别完成并通过，不等同于单进程全量成功。新增真实 HTTP 集成构建了 10 个 HTML 页面，仍有缺少正式域名、未填充栏目内容的质量警告；只证明代码路径畅通。
+
+## 生产环境验收操作建议（必须在预生产进行）
+
+1. 对 V8.15 的 SQLite 数据卷和所有媒体、归档、发布目录做完整备份，先演练恢复；保留生产回退窗口。
+2. 在独立 PG 16+ 测试数据库执行 `scripts/verify_pg_bootstrap.py`。验证 Web、Worker 启动与并发 claim；**不把原 SQLite 文件当作 PostgreSQL 数据迁移**。SQLite → PG 的正式数据迁移、外键校验、内容数量和媒体对账还未实现为可一键生产执行的迁移器。
+3. `docker compose -f compose.enterprise.yaml config`、`up -d --build`，分别核对 Web `/api/ready`、Worker 本地健康以及 PostgreSQL/Redis 服务健康。
+4. 将两个 Worker 实例分别配置唯一的 `SITEFORGE_WORKER_INSTANCE`，断开其中一个，确认另一个健康状态不会使坏实例误报正常；断电中断后要检查租约回收与远程发布状态对账。
+5. 用完整真实数据做创建网站、WordPress 迁移、5000 条产品导入、构建、主题预览和多语言 SEO 检验。在 Chromium 1440/1024/390/360 视口进行后台与前台访问性/响应式验证。
+6. 在预生产的实际 SFTP/S3/HTTPS Agent 发布，逐步演练上传失败、激活失败、CDN 缓存、健康检查失败及人工回滚；审批人与执行人分离。
+7. 获取合法的 Art Design Pro 官方工程后执行 `scripts/install_into_art_design_pro.py`，完成实际路由/会话/CSRF 联调及 `pnpm build`。目前属于可选桥接，不要把它计为完成。
+
+## 风险边界
+
+- PostgreSQL 兼容桥目前在 PG + Psycopg 真机上仍需完整持续验证，不能因为 SQLite 测试通过就宣称 PG 生产稳定。
+- Redis 当前主要用于任务唤醒，任务权威状态仍在数据库；并非完整的分布式消息可靠性交付。
+- SFTP/S3 原生发布已支持本地仿真，但公网环境、强制 TLS、服务端权限和切换时缓存行为仍需验收。
+- 新版未添加 SSO、MFA 或企业级集中监控系统，也未完成 Art Design Pro 官方源码集成。
@@ -0,0 +1,92 @@
+# SiteForge V8.17 — 生产交付门禁执行手册
+
+> 状态：独立增量验收工具；不包含 V8.16 原项目源码、Art Design Pro 官方完整工程或真实测试环境。本文的项目结构以所获 V8.16 README 为依据。生产演练与授权审批必须由真实环境执行并存档。
+
+## 一、目标与范围
+
+- V8.16 具备 HTTP `/api/health`、`/api/ready`，PG 兼容层、Worker 实例标识与 HTTP/PG 浏览器测试脚本。
+- V8.17 增量提供不侵入应用数据的统一检查入口，报告 JSON + Markdown + 离线可视化 HTML。
+- **不替代** `scripts/check.sh`、`scripts/http_end_to_end.py`、`scripts/browser_smoke.py`、`scripts/verify_pg_bootstrap.py`；这些是应用级端到端验证。
+- **不会执行** Docker up/down/build、数据库迁移、写入、发布/回滚、备份/恢复、人工审批。
+
+## 二、集成路径
+
+1. 解压原 V8.16 完整工程到**隔离测试目录**，不要覆盖正式数据卷。
+2. 将本补充包 `scripts/siteforge_v817_audit.py` 和 `tests/test_siteforge_v817_audit.py` 分别复制到原项目同名目录中；不会替换已有模块。
+3. 按需复制 `docs/V8_17_ACCEPTANCE_RUNBOOK.md` 和 `examples/`。
+4. 运行 `python -m unittest discover -s tests -p 'test_siteforge_v817_audit.py' -v`，再执行以下命令。
+
+## 三、执行命令
+
+最小安全检查（无网络、无需 Docker）：
+
+```bash
+python scripts/siteforge_v817_audit.py --repo . --output reports/siteforge-v817
+```
+
+隔离 Docker 企业 Compose 已启动后：
+
+```bash
+python scripts/siteforge_v817_audit.py \
+  --repo . --docker --url http://127.0.0.1:8787 \
+  --output reports/enterprise-staging
+```
+
+使用已有隔离数据库配置；**PG 仅执行 SELECT 1（事务只读），Redis 仅执行 PING**：
+
+```bash
+# 以下环境变量需由运维通过私密渠道事先配置，切勿提交 .env 或 DSN 到仓库。
+python scripts/siteforge_v817_audit.py \
+  --postgres --redis --output reports/datastores
+```
+
+静态构建产物 URL 校验（old_urls.txt 需人工从旧站导出，不自动抓取）：
+
+```bash
+python scripts/siteforge_v817_audit.py \
+  --build-dir /path/to/generated/site \
+  --url-baseline old_urls.txt \
+  --output reports/static-seo
+```
+
+验收报告：`reports/*.html` 离线打开、`reports/*.json` 可机器读取、`reports/*.md` 可归档。返回码 2 代表存在 FAIL；WARN/SKIP 仅表示需要进一步处理，不视为生产通过。
+
+## 四、关键门禁和接受标准
+
+| 门禁 | 自动审计可做 | 仍需人工与真实环境执行 |
+|---|---|---|
+| 代码与 Compose | 文件完整性、Python AST、Compose 配置、容器状态 | 应用全测试集、供应链审计、CI 与镜像签名 |
+| Web 与 Worker | HTTP readiness、容器运行/health、Worker 服务发现 | 真实异步任务、租约竞争、断网恢复、容量压测 |
+| PostgreSQL | 真正连通后的 `SELECT 1` | **隔离测试库**运行原项目 PG bootstrap、迁移校验、恢复演练 |
+| Redis | PING | 队列可靠性、幂等、故障切换、持久化和告警演练 |
+| URL / SEO | html lang、canonical 规则、内部链接、旧路径覆盖、sitemap | 迁移映射审定、301/404、robots、实际源站比对、GSC 验收 |
+| 多语言 | hreflang 格式与语言标签 | 关联双方对称、翻译审核、独立域名 HTTPS |
+| 发布与回滚 | 读取人工证据表 | 真实 staging 激活、不可变版本、校验 SHA、回滚演练、审批隔离 |
+| Art Design Pro | 检查当前 `workspace` 静态入口 | **获得官方工程并构建**，完成组件/路由/权限/API 接入和验收 |
+
+## 五、证据记录规范
+
+以 `examples/evidence.template.json` 为模板记录 10 个阶段。每阶段保留 `status`、`operator`、`date`、`evidence`，例如证据可以是带日期的运行日志路径或测试报告 URL。工具只验证字段存在，**不核验证据内容真实性**。`pending` 永远不等同 `passed`。
+
+**回滚演练**：先备份隔离测试环境，生成构建 A，部署到 staging，生成 B，再回滚至 A；比对前后首页和关键 URL 的 SHA/状态码，确认旧版恢复。测试的真实日志由人工归档。不得自动在生产环境执行此脚本包的任何写入动作。
+
+**SSRF 风险**：HTTP 模式默认仅 localhost。远端只允许在操作者明确指定 `--allow-remote` 且获得目标授权时检查；URL 不得包含用户名、密码、查询或 fragment。代理/CDN 的响应和 TLS 配置需人工复核。
+
+## 六、管理后台 UX 接入约定（下一层）
+
+- 导航继续沿用“工作台 / 我的网站 / 内容页面 / 外观设计 / 导入迁移 / 构建交付 / 网站设置”；技术工具统一收纳高级工具。
+- 验收中心可在**构建交付 > 验收报告**展示 JSON：优先级为 FAIL、WARN、SKIP、PASS，附修复建议，保留站点上下文。
+- 不在编辑页弹出多层确认；破坏性/正式发布才要求明确确认或审批。
+- 未获得 Art Design Pro 官方完整源码前，该交付**不能称为官方集成**；正式集成需基于实际 Vue 项目文件、授权版本、组件结构和构建配置开展。
+
+## 七、Known limitations
+
+- 文件可用性为当前 V8.16 README 描述，不保证用户本地工程文件路径完全相同，缺项会被标注 WARN。
+- 报告 **不是渗透测试、上线证明、真实发布演练或真实数据备份报告**。
+- 单站静态链接检查不能证明跨语言站的双向 hreflang；多语言配对需单独验证。
+- 对于在 CDN 或独立路径进行的预览，构建本地链接存在不代表预览 rewrite 逻辑完全正确，需要另行浏览器检查。
+- 使用 JSON 证据表并不代表完成任何业务审批或合规认证。
+
+## 八、隔离 CI
+
+提供 `.github/workflows/siteforge-v817-acceptance.yml` 作为**人工触发**的独立验收工作流：一组运行只读源码检查/测试，一组在临时 PostgreSQL 16 和 Redis 7 容器中执行最小存活检查，并上传脱敏报告。该 CI **不能替代**在实际 SiteForge 企业 Compose 下的完整业务链路和故障注入。
@@ -0,0 +1,17 @@
+# V8.17 Integration Release Notes
+
+## 基线
+- V8.16.0-dev.1 完整源码，提供 30 个 pytest 测试模块；V8.16 既有报告记录 255 例通过，但官方脚本曾偶发卡住。
+- V8.17 以真实源码整合，而非仅以 Markdown 方案代替实现。
+
+## 变更范围
+- 新增 `scripts/regression_v817.py` 并统一 `.sh/.ps1` 回归入口；逐批超时、隔离诊断、可机器读取报告、失败保留证据。
+- V8.17 audit、WordPress URL baseline 工具及单元测试集成。
+- 修复 Chromium desktop/mobile 登录上下文共享，CI 增加真实浏览器检查。
+- 主项目版本、Compose 镜像版本、相关断言同步更新。
+
+## 未完成
+- 当前工作容器不具备 Docker Engine、隔离 PostgreSQL/Redis 服务器和正常可访问 localhost 的 Chromium policy；这些并不作为通过项。
+- 不自动覆盖生产卷或执行现有部署迁移。
+- 不包含 Art Design Pro 官方可编译完整工程，不声称完成前后端集成。
+- 完整历史版本说明保留在 README 后半部分。
@@ -0,0 +1,31 @@
+# SiteForge Enterprise V8.17.0-dev.1 — 源码集成回归结论
+
+**结论：V8.17 完整源码已整合并通过隔离本地集成回归。生产上线验收尚未完成。**
+
+## 已实际执行
+
+- 完整项目现有 + 新增自动化测试：**288 项/轮，连续 2 轮均通过**（总计 576 次通过，0 失败、0 超时）。详细见 `reports/v817-regression.json` / `*.html` 与 8 份 verbose 日志。
+- V8.17 新增 33 项专项测试包含异常超时检测、报告落地与旧 URL 路径一致性检查。
+- HTTP 真实端到端：`/api/ready` → 登录/CSRF → 新建站点、页面 → Worker 异步构建 → ZIP 下载 → HTML 预览，通过。
+- `scripts/verify_release.py`、全体应用 Python 编译、前端 JS 语法检查：通过。
+- V8.17 只读仓库审计：**12 PASS / 0 FAIL / 0 WARN / 2 SKIP**（未提供实际 `.env` 和正式发布证据）。
+- GitHub Actions 两套 CI YAML 结构能正常解析，但**没有在 GitHub Actions 运行**。
+
+## 仍然未通过 / 尚未执行
+
+- Chromium 当前环境：使用 `/usr/bin/chromium` 仍遇到 `net::ERR_BLOCKED_BY_ADMINISTRATOR`，属于执行环境策略限制；新增独立浏览器 CI，需在允许访问 localhost 的 Runner 中验收。
+- 当前容器没有 Docker Engine；PostgreSQL/Redis、多 Worker、远程 SFTP/S3/Agent 发布与真实回滚，均未执行真实集成验收。
+- Art Design Pro 官方完整源代码未提供；没有进行官方前端编译集成。
+- V8.16 曾完成的 5,000 车型导入/构建压力测试，本轮未重复执行，不把历史结果标记为新版本重测结果。
+
+## 修改范围
+
+- `scripts/regression_v817.py`、`.sh/.ps1`：可终止的批量回归和逐模块异常隔离，报告 JSON/Markdown/HTML + 日志。
+- `scripts/siteforge_v817_audit.py`、`scripts/export_wordpress_url_baseline.py`：无写入生产副作用的验收与 URL 路径检查。
+- `scripts/browser_smoke.py`：登录上下文复用、Playwright Chromium 自动查找、用户可覆写可执行文件路径。
+- `.github/workflows/`：连续两轮 Python 测试、真实 Chromium CI 以及独立 PostgreSQL/Redis 只读检查。
+- `app/version.py`、Compose 镜像、相关测试断言、README、文档：版本升级与项目交付文档。
+
+## 推荐下一验收步骤
+
+将此 ZIP 在隔离环境部署，先跑 `bash scripts/check.sh` 与 `python scripts/http_end_to_end.py`，随后用已配置安全凭据的独立测试 PG/Redis + Docker 验收，确认浏览器和部署链路；最后复核真实 WordPress URL 及正式发布、回滚和备份恢复。
@@ -0,0 +1,65 @@
+# SiteForge Enterprise V8.18 — 企业底座实现与验收说明
+
+> 2026-10-23 · 版本 `8.18.0-dev.1` · **开发集成版（不是生产上线批准）**
+
+## 本轮已实施代码
+
+1. **PostgreSQL 灾备误操作保护**：当 `SITEFORGE_DATABASE_URL` 指向 PostgreSQL，原 SQLite `python -m app.backup` 立即拒绝执行，不会错误创建一份空 SQLite 备份。
+2. **PostgreSQL 专属离线灾备**：`app.pg_disaster_recovery` + `scripts/pg_disaster_recovery.py` 使用客户端 `pg_dump` custom 格式、`pg_restore --list`、媒体/构建文件清单和 SHA-256 校验，最后原子更名 ZIP；离线校验无需数据库。恢复仅允许**空 PostgreSQL 数据库 + 不存在的数据目录**，使用单事务 `pg_restore`，不覆盖线上站点。机密信息不会放在子进程命令行参数中。
+3. **SQLite→PostgreSQL 内容迁移**：`app.sqlite_pg_transfer` + `scripts/migrate_sqlite_to_postgres.py`：SQLite 在线备份 API 制作快照（前提仍要求业务停写），按外键顺序处理当前 51 张表，检查列覆盖和目标表为空（迁移登记表例外、必须 checksum 匹配），单 PostgreSQL 事务写入，逐表行数与 SHA-256 对账。目标库必须在停机维护期间运行全套初始化。
+4. **发布状态不确定时防重复执行**：`remote_deploy`/`remote_rollback` 在 Worker 租约过期、网络失败、超时或运行中取消后标记失败并要求管理员核对远端指针，禁止自动重试外部副作用。普通构建仍保留原有重试能力。
+5. **CI 验收扩充**：新增隔离 PostgreSQL 数据迁移端到端验证脚本；本地测试使用模拟 PG 协议和工具进程，并且严格区分模拟与真实 PG 证据。
+
+## 一、禁止直接更新生产卷
+
+新建独立测试环境，备份 V8.17 的数据库和共享存储。切换 SQLite→PG 是**运维迁移**而非自动覆盖 `.env`：不能仅把 SQLite 环境变量指向 PostgreSQL 后直接运行现有容器。系统代码、数据库、媒体目录和 `published` 卷是不同组件，必须统一维护窗口。
+
+## 二、PostgreSQL 备份（维护窗口）
+
+以下命令在有 `pg_dump`、`pg_restore`、`psql` 的管理主机执行；客户端版本应不低于数据库服务器主版本（示例 PG 16）。须先停 Web 和所有 Worker，阻止数据库写入与媒体上传。
+
+```bash
+export SITEFORGE_DATABASE_URL='postgresql://backup_user:***@db-host:5432/siteforge?sslmode=verify-full&sslrootcert=/secure/ca.pem'
+python scripts/pg_disaster_recovery.py backup --data /path/to/siteforge-data --output /external/backup-20261023.zip --confirmed-offline
+python scripts/pg_disaster_recovery.py verify /external/backup-20261023.zip
+```
+
+不要把真实密码写到共享日志或 shell 历史；上例为占位符。建议使用安全的环境注入或管理员端凭据文件。`manifest.json` 的 SHA-256 证明读取后的完整性，**不证明备份来自可信发布者，也不代表进行了加密**。备份需转移到其他设备，配置保留策略和访问限制；`published` 独立卷还需要独立备份。
+
+恢复必须**事先创建空 PostgreSQL 目标库**和**不存在的共享数据目录**，并使用新测试实例恢复验证：
+
+```bash
+python scripts/pg_disaster_recovery.py restore-new /external/backup-20261023.zip --data /path/to/new-storage --confirmed-offline
+```
+
+不会自动切换服务或覆盖目标数据库。恢复后需再跑 `/api/ready`、内容/媒体、构建和发布链路的 E2E。数据库恢复和文件重命名跨系统不属于一个原子事务，失败时目标必须保持隔离，直到人工对账完成。
+
+## 三、SQLite 数据升级到 PostgreSQL（数据库部分）
+
+1. **停站**：关闭 Web、所有 Worker、文件上传与计划任务，确保 SQLite 和媒体不再变动。
+2. **双重备份**：运行既有 SQLite 备份与源文件目录副本；将外部备份单独存储。
+3. **全新 PostgreSQL 库**：使用独立新库运行完整 SiteForge schema 初始化；允许 ledger 的既定行，其他业务表必须为空。
+4. **迁移数据**：
+
+```bash
+export SITEFORGE_DATABASE_URL='postgresql://migration_user:***@db-host:5432/siteforge_stage?sslmode=require'
+python scripts/migrate_sqlite_to_postgres.py --source /path/to/old/siteforge.sqlite3 --confirmed-offline --report /external/migration-evidence.json
+```
+
+5. **同步外部文件**：`/data/media`、`legacy`、`builds`、`archives` 与 `published` 卷独立同步/校验（迁移工具**不会**代替 rsync/对象存储迁移）；不要把两个新旧服务同时指向可写目录。
+6. **验证**：逐表行数/哈希、媒体 URL、静态质量报告和线上正式域名一致性；如有失败保持旧站继续服务。
+7. **切换**：预生产全部通过后再人工批准业务切换，保留源库与可回滚路径。
+
+工具对旧 SQLite 数据库进行**只读备份快照**；向新 PostgreSQL 写入是显式 `--confirmed-offline` 才能执行的操作。导入使用单事务；建表（初始化）先于该事务，不等于整个目标库已经过生产级迁移验收。
+
+## 四、多 Worker / Redis
+
+PostgreSQL 是权威任务队列，Redis 只负责唤醒通知；Redis 不可用时 Worker 回退数据库轮询，不能把 Redis 看作持久化任务存储。V8.18 对发布任务加上“结果不确定则不重试”防护，但**未获得真实 Docker 2+ Worker 并发、断电、丢包和故障切换证明**，不能宣布多实例高可用。
+
+## 五、本轮验收证据限制
+
+本地环境未安装 Docker Engine、PostgreSQL 客户端或 psycopg，无法声称完成真实 PG/Redis Docker 验收。新增脚本和自动化测试提供代码及 CI 入口；应在 GitHub Actions 隔离 postgres 服务上实际运行 `scripts/verify_pg_bootstrap.py` 和 `scripts/verify_sqlite_pg_transfer.py`，保存日志，然后在运维侧完成正式恢复演练。
+
+## 六、尚未关闭的 V9.0 要求
+
+Art Design Pro 官方前端完整工程编译集成、复杂 WordPress 插件迁移、企业 SSO/MFA、长期容灾、同域路径多语言、真实服务器发布验收，以及完整移动端体验均仍在后续工作范围内。
@@ -0,0 +1,78 @@
+# SiteForge Enterprise V8.19 — 统一管理后台集成与验收手册
+
+**版本**：8.19.0-dev.1（开发集成版）  
+**基线**：V8.18 完整源码  
+**日期**：2026-10-23  
+**状态**：业务代码、路由适配及后端接口已集成；Art Design Pro 官方完整源码不在交付包内，因此未执行官方 `pnpm build`，也未通过真实浏览器/线上反代验收。
+
+## 1. 范围与已实现
+
+- 新增 FastAPI `GET /api/console/bootstrap`：会话绑定的管理菜单、可见站点清单、指定站点权限能力清单；未授权站点返回 403。纯查询，不传递密钥或 CSRF token。
+- 新增 Vue `ConsoleHome.vue` 工作台、`ContentCenter.vue` 内容 CRUD 页面（调用已有 API，不复制业务数据库逻辑）。
+- 统一 Art 前端七个既有页面的请求错误/CSRF 同源处理与当前网站选择；通过 `_shared.ts` 获取服务端会话，权限**仍由后端检查**。
+- 官方路由只注册 **一个 `/siteforge` 导航树**，含工作台、网站管理、内容管理、网站设计、数据与迁移、构建与发布、系统管理；主题与 V8 高级工具隐藏为子路由，避免重复一级菜单。
+- 安装器支持 dry-run、幂等、文件冲突保护、备份、显式升级旧标记、SHA-256 安装核对。
+- SiteForge 登录页支持同站安全 `next=/siteforge/...` 返回路径；无跨域任意跳转。
+
+## 2. 前置要求
+
+1. 从官方网站获取 **Art Design Pro 官方完整源代码**、合法依赖和版本锁文件，确认对应的 `src/router/routes/asyncRoutes.ts` 结构。未提供源码时不得称为官方已经集成、编译成功。
+2. Node、pnpm 版本以该 Art 官方提交/锁文件要求为准。
+3. 采用 **一个 HTTPS 域名**承载 Art SPA 和 FastAPI API，统一 Session Cookie、CSRF 与 Host；不要通过跨域代理绕过后端 Session 与 CSRF。
+4. FastAPI 需保留 `/api/auth/login`、`/api/auth/me`、`/api/auth/logout` 权威登录路径。Art 演示账户和假 Token 不可作为正式 SiteForge 认证。
+
+## 3. 安装程序
+
+```bash
+# 在 SiteForge 根目录（以下路径自行替换）
+python scripts/install_into_art_design_pro.py /path/to/art-design-pro
+python scripts/install_into_art_design_pro.py /path/to/art-design-pro --apply
+python scripts/verify_art_design_pro_v819.py /path/to/art-design-pro
+
+# 安装了官方 npm 依赖后运行真正的编译（不是模拟）
+cd /path/to/art-design-pro
+pnpm install --frozen-lockfile
+cd /path/to/siteforge
+python scripts/verify_art_design_pro_v819.py /path/to/art-design-pro --build --report reports/v819-art-build.json
+```
+
+如果官方源码里已经存在旧 SiteForge 路由，**先备份源码**，并显式执行：
+
+```bash
+python scripts/install_into_art_design_pro.py /path/to/art-design-pro --apply --migrate-legacy --overwrite-views
+```
+
+安装器不会删除第三方业务路由；当人工调整过已经安装的 V8.19 路由时，会拒绝自动覆盖，并要求人工审查差异。若旧业务页面曾被人工修改，升级前先对比 `.siteforge-backup`。
+
+## 4. 同源反代
+
+使用 `deploy/art-design-pro/siteforge-nginx.conf.example` 作为 **示例**，人工配置证书、SPA 根目录、Host、上游 IP。正式生产必须启用 `SITEFORGE_COOKIE_SECURE=true`。完整反向代理后逐一检查：
+
+- 登录页 `/login`、认证 `/api/auth/me`、管理接口 `/api/console/bootstrap`；
+- Art 页面 `/siteforge/dashboard` 与 `/siteforge/content`；
+- 页面设计 `/editor/{site}/{entry}`、预览 `/preview/...`、媒体 `/local-media/...`；
+- 静态站构建与文件下载；
+- 401/403 行为、CSRF POST 保护、Session 过期后跳转，以及移动端导航。
+
+注意：Art 自带演示登录/用户菜单与 SiteForge 账户是**两套系统**。正式部署时必须关闭演示权限作为真实权限的假设，使用 SiteForge 会话作为权威身份；Art 路由的可见性只是界面提示，不可替代服务端授权。尚未实施企业 SSO。
+
+## 5. 已完成/未完成门禁
+
+| 验收项 | 状态 |
+|---|---|
+| 原项目自动化测试 | 本地可重复回归通过；原始日志随包交付 |
+| 新工作台授权 API | 自动化测试通过 |
+| Art 安装器模拟工程测试 | 自动化测试通过（仅验证适配逻辑） |
+| HTTP 站点创建 → Worker 构建 → 下载 → 预览 | 本地端到端通过 |
+| Art 官方 `pnpm build` | **未执行**（官方完整源码/依赖未提供） |
+| PC 与移动端真实 Art UI | **未执行**（需官方工程构建和正常浏览器环境） |
+| Nginx HTTPS + SameSite + Cookie/CSRF | **未执行**（需独立测试域名） |
+| PostgreSQL/Redis/多 Worker/发布灾备 | 延续 V8.18 的独立生产验收门禁 |
+
+## 6. 尚需完善（下阶段）
+
+- 将 Art 登录体验与 SiteForge 后端 Session 完整合一（实际官方仓库必须可编译、完成端到端路由守卫）。
+- 企业功能导航按站点角色动态显示（本轮后端已提供能力清单，但 Art 全局动态菜单权限筛选未能在官方工程中实测）。
+- 完整移动端和桌面端视觉验收、内容编辑历史、发布审批操作的一致性审查。
+- 将高级生产控制台原有大部分遗留界面彻底迁入统一模块，避免跳出 SPA。
+- 生产 Nginx、真实 Art build、数据库、Redis 和部署回滚的独立环境验收。
@@ -0,0 +1,48 @@
+# SiteForge Enterprise V8.20 — WordPress 复杂迁移增强
+
+版本：`8.20.0-dev.1`。此版本属于**开发集成版**，在 V8.19 完整源码上增加离线兼容预检、简单 ACF Repeater 结构保留、CSS 背景图本地化、批次暂存路径阻断。**不代表复杂 Elementor/ACF/WooCommerce 功能或设计已实现无损迁移。**
+
+## 1. 新增实际功能
+
+- 新增 `app/wp_complex_v820.py`，使用 `defusedxml` 安全解析最多 16 MB、20,000 条记录的 WXR，按已发布内容发现 URL 冲突、动态参数 URL、复杂 Elementor、ACF 字段、PHP 序列化、自定义文章类型、WooCommerce 和动态短代码。
+- 新增后台 `POST /api/migrations/sites/{site_id}/wordpress/wxr-preflight`：`multipart/form-data` 的 `file` 字段，登录、CSRF 和站点 Editor 权限均必需。只读返回 JSON，不写站点数据，不访问外网。
+- 现有 `/production-v8` WordPress 面板新增“兼容性预检”按钮和结果区。
+- `app/importers.py` 直接 WXR 导入：带参数的动态 URL 或缺失原始路径现在拒绝导入，不再凭 slug 猜测路径；ACF 简单 Repeater 结构保留在 `meta.fields` 和 `meta.acf_repeaters` 中，原始字段仍保留供核对。
+- `app/v8_workflows.py` WXR 暂存：复用预检阻断危险旧 URL；不再将自定义文章类型错当成分类；复杂组件形成发布审核项。
+- `app/wp_migration_v82.py` 媒体本地化扩展至行内 CSS `url(https://...)`、`data-background`、`data-background-image` 与已有 `srcset`。只允许已授权主机的资源进入自动下载，其他 URL 需要单独审核。
+- 新增 `scripts/wp_v820_preflight.py`：离线生成 JSON/HTML 风险报告；可选 `--dist` 对比静态 HTML 路径覆盖。
+
+## 2. 直接运行
+
+在项目根目录：
+
+```bash
+python scripts/wp_v820_preflight.py fixtures/v820/wordPress-complex-sample.xml --output reports/v820-demo.json
+# 可选，待已经执行静态构建后：
+python scripts/wp_v820_preflight.py export.xml --dist /absolute/path/to/build/dist --output reports/my-site.json
+```
+
+脚本返回码：`0` 表示没有识别到阻断问题且（如指定 `--dist`）没有发现缺失的 HTML 路径；`1` 表示出现阻断或缺失路径；`2` 表示输入、读取或 XML 解析失败。**退出码 0 不意味着布局或业务功能无损，人工审核仍是发布条件。**
+
+在统一后台选择网站 → 网站生产控制台 → WordPress 迁移 → 选择 WXR 文件 → 点击“检查旧 URL / Elementor / ACF / 动态功能”。
+
+## 3. 风险与未完成项目
+
+| 方向 | 当前实现 | 未完成的生产验收 |
+|---|---|---|
+| Elementor | 识别已支持/未知组件，有限静态 HTML 转换，保留原始 JSON | 容器布局、动态标签、全局样式、响应式精确还原、交互插件 |
+| ACF | 单值字段、简单 Repeater 的有界结构提取；PHP 序列化只标记，不执行 | 字段组 schema、Flexible Content、嵌套 Repeater、关系字段、文件字段 |
+| WooCommerce | 识别产品相关数据并列入审核 | 变体、价格策略、库存、购物车、结算、订单等动态服务 |
+| 媒体 | 同源 HTTPS/HTTP 图片与 CSS 背景图引用分析及本地化 | 跨域 CDN 授权、尺寸变体资源、未引用附件、CSS 外链文件及版权许可 |
+| URL/SEO | WXR 旧路径预检，静态构建路径核查，原有 SEO 差异工具 | 真正旧站的完整 Sitemap + robots + 分页 + 301 + Canonical 实测核对 |
+| 插件功能 | 表单、动态短代码、iframe 标为风险 | CRM/表单业务重建与实际浏览器 E2E |
+
+WXR XML **不包含附件原文件，也不包含完整站点设置和全部插件配置**；需另行取得对应 WordPress 资源以及已获授权的插件数据。
+
+## 4. 迁移作业建议
+
+先备份 WordPress 原站、数据库与媒体文件；离线预检 WXR 和 Sitemap；修复阻断问题后按站点逐步暂存/提交数据；迁移 CSS/响应式图片及全部媒体；新旧站逐 URL 对账，再在独立预生产环境实测 PC/移动端布局、交互、SEO、动态表单及发布回滚。上线前必须完成每一个已识别风险的人工复核。
+
+## 5. 测试证据边界
+
+自动化使用本地固定 WXR、TestClient 和模拟媒体，禁止把这些结果描述为真实客户网站的迁移通过。V8.18 生产 PostgreSQL/Redis/Docker 多 Worker 与 Art Design Pro 官方工程编译仍未完成真实现场验收。本包不会自行连接或更改用户的生产网站。
@@ -0,0 +1,51 @@
+# SiteForge V8.21.1 — 可视化编辑器体验增强
+
+状态：`8.21.1-dev.1`，在 V8.21 源码基础上做前端编辑器的向后兼容升级。
+
+## 已实际开发的内容
+
+1. **页面区块面板**：按标题、类型、嵌套区块内容搜索；拖拽排序继续保留；新增上/下移动、显隐、复制和删除快捷操作；支持 Alt+↑/↓ 按键移动聚焦的结构行。
+2. **属性分区**：从单一长滚动面板拆分为「内容」「样式」「响应式」，多列布局与平板/手机跨度和显隐均放在响应式面板。
+3. **PC/平板/手机预览**：桌面自适应宽度、平板 780px、手机 390px；展示明确设备标签，窄屏可分别展开区块侧栏和属性侧栏。
+4. **页面刷新安全性**：所有预览请求使用 `AbortController` 取消上一个请求，并通过请求序号和页面 ID 双重核对；旧请求不得覆盖新预览。
+5. **草稿可靠保存**：调用保存接口前冻结请求数据，写入过程中若发生额外本地修改不会错误清除 dirty 标志；同一时间仅处理一项保存请求，页面切换时阻止混淆。
+6. **撤销与重做**：历史操作按钮可用状态实时更新；连续输入编辑合并短时间内的快照，提供 Ctrl/Cmd+S 快捷保存（前端输入框内保留浏览器默认编辑撤销行为）。
+7. **顶部操作层级**：保留高频保存/发布操作，低频的版本历史、全站设计、构建等放入「更多操作」菜单。移动端保存按钮仍可见。
+8. **测试辅助**：纯函数 `editor-helpers.js` 以 Node Test Runner 检验，新增浏览器烟测脚本（需要运行环境允许本机 HTTP）和可离线打开的静态交互演示。
+
+## 安全与兼容约束
+
+- 不修改已有页面 `blocks` JSON 数据模型、不新增生产数据库迁移；旧页面和已有 V8.21 草稿可以继续使用。
+- 仍使用原有 `PUT /studio-draft` 的 `expected_revision` 乐观锁、发布接口、站点权限及审批逻辑。页面草稿保存不会自动发布静态网站。
+- 编辑器 iframe 仍使用 `sandbox="allow-scripts"`，未添加 `allow-same-origin`。UI 表单不执行用户自定义代码。
+- **没有**实现无限自由定位、Figma 式像素编辑、复杂组件级协作锁、跨页面模板继承或官方 Art Design Pro 全工程真实编译。相关模块需要后续专项开发。
+
+## 本次验证结果
+
+- JavaScript 纯函数：6/6 通过（`node --test tests_js/editor_ux.test.cjs`）。
+- Python 编辑器专项和既有历史/映射：9/9 通过；新静态界面测试：3/3。
+- 现有 39 个 Python 测试模块**分段或独立运行**，累计 328 个用例通过；其中前六批计 215 项、批次 7 拆分运行计 26 项、余下独立模块 87 项。
+- HTTP + Worker 实际建站构建：通过（隔离临时 SQLite 环境）。
+- Python 编译、全部 `app/static/*.js` 语法校验、工程静态发布检查：通过。
+- 一键完整回归：**未通过完整单次执行门槛**，第七批发生进程停滞，已记录。独立模块通过不代表一键执行器稳定。
+- 真实 Chromium 操作：当前执行环境 `ERR_BLOCKED_BY_ADMINISTRATOR`，不计为通过；保留 `scripts/browser_studio_v8211.py` 供在 CI/开发机复测。
+- Docker/PostgreSQL/Redis/Art Design Pro 官方工程：未进行本轮真实环境验收。
+
+## 运行与使用
+
+```bash
+python scripts/http_end_to_end.py
+node --test tests_js/editor_ux.test.cjs
+python -m pytest -q tests/test_editor_ux_v8211.py
+python scripts/browser_studio_v8211.py  # 需本地 Chromium、Playwright、本机 HTTP 访问权限
+```
+
+网站编辑器继续通过 `/editor/{site_id}/{entry_id}` 访问。单独查看视觉交互可直接在浏览器打开 `examples/Studio_V8_21_1_交互预览.html`，该文件为**示例 UI**，不访问数据库也不是真实发布端。
+
+## 后续计划
+
+- 进行真实浏览器的 PC/平板/手机 E2E，并按操作可用性修复视觉缺陷；
+- 实现嵌套 layout 子组件的独立属性选择、拖拽落点可视化与组件版本继承；
+- 增加数据源联动的结构化表单编辑，而非复杂 JSON 文本框；
+- 拿到 Art Design Pro 官方项目后进行完整编译及权限/路由集成验收；
+- 排查一键测试执行器跨模块进程停滞并在 CI 设置稳定性门槛。
@@ -0,0 +1,61 @@
+# SiteForge V8.21.2 — 新手友好可视化编辑器
+
+> 基于 V8.21.1 完整源码的易用性专项迭代。交付性质：**开发集成版**，未改动正式生产数据和已有网站区块 JSON 模型。
+
+## 一、面向使用者的新操作流程
+
+**1. 选择内容**：左侧选择正在编辑的页面；点击一个已有内容区块，或点击醒目的「＋ 添加内容区块」。区块库在不使用时自动折叠，左侧结构支持搜索和排序。
+
+**2. 修改内容**：右侧默认展示内容字段；只有需要时才点击「样式」或「手机/平板」。支持在中间预览区直接单击一个带有 `data-block` 的区块，自动定位到右侧属性面板；原有双击文字编辑继续保留。
+
+**3. 保存与发布**：右上角固定显示「保存草稿」「发布设计」。保存草稿使用原有 CSRF 与 `expected_revision` 乐观锁，不会自动改变正式构建；发布设计更新内容库，网站仍需完成后续静态构建与正式部署。版本历史、全站设置、构建等较少使用的操作集中在「更多」。
+
+页眉下方新增 3 步提示，以及自愿打开的「新手使用指南」对话框，避免强制遮挡使用者。
+
+## 二、实现改动
+
+| 文件 | 说明 |
+|---|---|
+| `app/templates/editor.html` | 重排顶部主操作、三级简洁步骤、左侧页面/内容优先、结构化侧栏、帮助对话框；修复旧版更多菜单标记不清晰问题 |
+| `app/static/editor.css` | 桌面/平板/手机布局、表单可读性、强调主操作、低频内容折叠、表单列表样式 |
+| `app/static/editor.js` | 区块库显隐、步骤反馈、选择后定位属性面板、逐项编辑重复内容、预览点击区块的父页面消息处理 |
+| `app/main.py` | 对编辑器预览中的 `[data-block]` 添加点击选择的桥接消息，并保持 `sandbox="allow-scripts"`（不启用同源权限） |
+| `tests/test_editor_easy_v8212.py` | 布局唯一 ID、主操作位置、预览消息限制、后端兼容性等静态检查 |
+| `examples/Studio_V8_21_2_新手友好版交互预览.html` | 离线、模拟数据的可操作示例；不写入任何真实站点 |
+
+### 对非技术人员的重大改善
+
+- `features` 核心优势、`stats` 数字指标、`faq` 常见问题、`gallery` 图片画廊、`carousel` 轮播、`tabs` 标签页、`pricing` 服务方案：从 JSON 数组文本框改为「第 N 项 / 普通输入框 / 添加 / 删除 / 上下移动」。
+- 原有项目后台接口、页面数据结构、草稿快照及发布审批流程保持兼容；列表编辑只是前端输入方式改变。
+- 中间预览可点击区块实现选中；安全边界在父窗口同时检查 `event.source === frame.contentWindow` 与真实已加载 block ID。
+
+## 三、当前测试记录
+
+- 编辑器/设计器相关 pytest：28 项通过。
+- 内容历史、核心业务、旧版流程 pytest：30 项通过。
+- Node.js 编辑器工具函数：6 项通过。
+- Python 源码编译和 `editor.js` 语法检查通过；离线示例 JS 通过 Node.js 语法检查。
+- `python scripts/http_end_to_end.py`：通过 HTTP/CSRF/建站/Worker 构建/ZIP/预览。
+- **未执行**全项目一次性回归；既有版本的回归执行器有过偶发进程停滞，需在隔离 CI 上再做全量测试。
+- **未完成**完整 Chromium PC/移动端操作验收：本运行环境的 Chromium 截图启动超时，故不能宣称浏览器 E2E 通过。
+- **未完成**官方 Art Design Pro 全工程编译、生产 PostgreSQL/Redis 与真实发布环境验收。
+
+## 四、运行方法
+
+```bash
+# 运行原 SiteForge 后端（环境配置保持原项目方式）
+# 编辑器入口：/editor/{site_id}/{entry_id}
+python -m pytest -q tests/test_editor_easy_v8212.py tests/test_editor_ux_v8211.py tests/test_studio_v86.py tests/test_site_design_v87.py
+node --test tests_js/editor_ux.test.cjs
+python scripts/http_end_to_end.py
+```
+
+离线预览可直接双击 `examples/Studio_V8_21_2_新手友好版交互预览.html`。演示中的保存/发布仅改变页面临时示例状态，不会调用任何线上 API。
+
+## 五、仍需产品验收的体验问题
+
+1. 真实 PC/移动端浏览器中验证侧栏展开、点击画布选中、键盘和焦点移动。
+2. 对复杂 `layout` 嵌套子组件实现更细的画布选中与属性编辑（当前点击子组件会定位其父布局区块）。
+3. 对图片上传和媒体选择增加直观的缩略图与拖拽；当前仍沿用旧媒体库交互。
+4. 组织非技术同事完成一次创建区块→修改→保存→发布的实操测试，依据其反馈再做收敛。
+5. 后续将本版业务页面真正装入 Art Design Pro 官方工程并执行 `pnpm build` 与浏览器集成。
@@ -0,0 +1,46 @@
+# SiteForge V8.21.3 — 四套主题移动端统一优化说明
+
+## 当前基线结论
+
+原 V8.21.2 的 automotive、industrial、corporate、minimal 四套内置专业主题具有基本响应式 CSS（移动端单列卡片、缩小标题、部分间距调整），但原导航在手机上是页眉下方的纵向展开列表，**不是独立抽屉**；没有底部快捷 Tabs 配置；因此不能将旧版称为全面完成移动端优化。V8.21.3 针对这些明确缺口做了源码级修改，并完成指定场景的浏览器验收。不能把 4 种代表页的验收当成所有页面和所有机型的充分验收。
+
+## 新版功能
+
+- 四套主题在 1024px 及以下使用右侧抽屉，点击汉堡按钮展开，多级目录可单独展开；移动端原“分类 Mega 菜单”链接合并进入抽屉。
+- 抽屉支持关闭按钮、遮罩、Escape、Tab 焦点约束以及关闭时焦点返回；支持页面跳转时关闭菜单。桌面导航保持原有样式。
+- 手机 767px 及以下可显示可选底部 Tabs，**默认关闭**，无任何按钮时也无需配置。启用后可添加 1–5 项，删除、上下排序、选择标题和预置图标、填写 URL，也可以配置一个“打开菜单”操作。
+- 链接允许站内路径（`/products/`）、`https://` 安全外链（如 WhatsApp）、`tel:` 与 `mailto:`；不允许 `javascript:`、`data:`、`http:`、协议相对地址或带用户名/密码的 HTTPS URL。存入数据库前全部由服务端校验。
+- 底栏自动适配设备安全区，启用时为页面底部预留空间以免遮挡内容；停用后没有额外留白。
+- 手机端卡片、图片、标题和文字区域增强窄屏 CSS；保留桌面模板、页面路径、SEO 数据、全站设计版本及发布审批模型。
+
+## 管理后台操作
+
+1. 进入目标网站的“可视化编辑器”，打开“全站页眉与页脚”。
+2. 找到“手机底部快捷导航 Tabs（可选）”。不开启时，手机页面**不显示**底栏。
+3. 开启后添加 1–5 个项目，分别填写文字、选择图标和点击操作；可上移、下移和删除。
+4. 可点击“预览草稿”查看当前编辑器预览；“保存全站草稿”**不会**修改已生成的网站；“发布全站设计”后，还需要重新构建网站并按既有流程部署。
+5. 手机菜单仍使用全站导航树，并继承二级、三级菜单结构。高级导航树的内容编辑入口仍保留原有 JSON 编辑方式；本轮重点是手机导航呈现，不是完全替换所有导航的配置方式。
+
+## 实现文件
+
+- `app/site_design_v87.py`：增加 `mobile_tabs` 配置、默认关闭、链接与图标字段校验、草稿隔离。
+- `app/theme_pro.py`：四套主题渲染上下文与预置图标。
+- `themes/{automotive,industrial,corporate,minimal}/pro.html`：按配置渲染底部栏与激活态。
+- `app/static/commercial.css`：统一右侧抽屉、遮罩、Tabs、手机端布局。
+- `app/static/pro.js`：菜单打开/关闭、焦点管理、Esc、滚动锁定、抽屉分类链接及底部菜单按钮。
+- `app/templates/editor.html`、`app/static/editor.js`：非 JSON 的 Tabs 增删、排序、名称、图标、路径配置。
+- `tests/test_mobile_tabs_v8213.py`、`scripts/browser_mobile_v8213.py`：专项验证。
+
+## 验证范围
+
+- Python：四个内置主题的真实静态构建、草稿隔离、发布生效、关闭后无 Tabs、非法链接与数据结构拦截。
+- Chromium：利用实际模板 HTML/CSS/JS 在 `page.set_content` 离线渲染，验证抽屉、遮罩、Esc、底栏菜单、桌面隐藏、脚本错误。对首页、产品列表、产品详情、文章详情分别用 375/390/430px 宽度检测水平溢出。
+- HTTP+Worker：原有登录、CSRF、建站、后台任务、构建、ZIP 和预览链路再次通过。
+- 浏览器执行环境不允许 Chrome 导航到 `file://` 和 localhost，因此浏览器检查采用 HTML/CSS/JS 内联加载方式；这**不等于**真实域名/CDN/移动设备端到端验收。
+
+## 未关闭事项
+
+- 用户上传的自定义第三方主题不在本轮四套内置主题的统一抽屉改造范围内。
+- 真实 iOS Safari、Android Chrome 实机和全部内页（如询盘、搜索、案例、FAQ）仍需专项验收。
+- Art Design Pro 官方完整工程的构建验证、正式 PostgreSQL/Redis/Docker 生产环境验收沿用前一版未关闭项。
+- 本版本只是开发集成版；发布静态站不会自动覆盖线上生产数据。
@@ -0,0 +1,50 @@
+# SiteForge V8.21：可执行开发说明和验收边界
+
+状态：**8.21.0-dev.1 开发集成版**。基于 V8.20 完整源码开发，未对用户生产环境执行升级。
+
+## 页面编辑器历史
+
+- 数据表 `studio_history`：site_id / entry_id / revision / kind(draft,published) / snapshot_json / snapshot_hash / actor / created_at。支持删除站点/页面后的级联清理，不额外泄露其他站点记录。
+- `GET /api/sites/{site}/pages/{entry}/studio-history?limit=30`：查看当前网站当前页面最近版本（1–100）；最低 viewer 权限。
+- `GET .../studio-history/{history_id}`：读取单个历史快照并验证 SHA-256；最低 viewer 权限。
+- `POST .../studio-history/{history_id}/restore`：请求体 `{"expected_revision":2}`；最低 editor 权限；采用乐观修订检查，只创建新的 studio_drafts 草稿，不调用静态构建，也不修改已发布内容。
+- 发布仍需要 owner 权限；发布后的页面必须单独执行正式静态构建和审批才能上线。
+- 历史表目前**未配置保留上限/外部归档**，大规模多人协作前应定义存储周期与审计导出策略。原先保存在本机浏览器会话里的撤销/重做仍可用，不属于持久化历史。
+
+## 数据映射
+
+旧式 `{ "title": "name" }` 规则保持兼容。新增可声明的字段处理（不能传入任意 SQL、JavaScript 或 Python）：
+
+```json
+{
+  "title": {"source":"name", "trim":true, "case":"upper", "prefix":"MODEL: "},
+  "brand": {"source":"brand", "case":"lower", "default":"Unspecified"},
+  "route": "old_url"
+}
+```
+
+- `POST /api/factory/sites/{site}/mapping/run` 带 `dry_run:true` 返回 `plan_hash`、冲突列表、错误、示例数据。
+- 再调用该 API，传 `dry_run:false`、`expected_plan_hash` 及 `on_conflict: "abort"|"skip"|"replace"`。预检被其他人修改后拒绝旧指纹。建议以 `abort` 开始试点，数据修改需要明确选择 `replace`。
+- `plan_hash` 包含映射后的内容及相关已有记录完整状态，不包含远程认证信息；它是乐观变更检查**不是防篡改签名**，也不是跨进程数据库锁。
+- **限制**：当前装配持久化沿用原有逐条 `save_entry` 路径，不保证批次级 ACID 原子回滚。`abort` 可阻止预检时已知的错误和冲突，但不能承诺极端并发写入期间整批原子提交。批次回滚及并发事务化属于后续 P1 任务。
+- 每批最多 1,000 条，保持原有容量上限；映射不运行代码，也不会自动创造业务数据。
+
+## UI
+
+- 原生编辑器 `/editor/{site}/{entry}` 新增「版本历史」弹窗与确认恢复；所有文案提示恢复仅生成草稿。
+- 原生网站工厂 `/factory-studio` 的内容导入新增字段变换、严格冲突策略和预检绑定；原有 Art Design Pro 官方工程尚未获得，因此未验证其实际 `pnpm build` 和完整业务端集成。
+
+## 本地验收记录
+
+- `38` 个测试模块分 10 组独立运行，共 `325 passed`；所有分组原始输出见 `reports/v821_manual_verified/`。
+- `python scripts/http_end_to_end.py`：通过登录/CSRF → 创建网站与页面 → Worker 构建 → ZIP → 预览。
+- `python scripts/verify_release.py`、`python -m compileall -q app` 以及 `node --check app/static/*.js`：通过。
+- 一键长流程在当前环境出现过停滞。已对 V8.21 执行器增加进程组超时清理，但其完整单次运行稳定性仍需独立 CI 复验；不计入上面的“通过”判定。
+- **未验收**：真实 PostgreSQL/Redis、Docker 多 Worker、浏览器/移动端视觉交互、真实 WordPress 复杂迁移、官方 Art Design Pro 编译、远程发布与回滚。
+
+## 后续门槛
+
+1. 建立隔离生产仿真环境，在 PostgreSQL 模式跑迁移/数据装配/编辑历史多进程用例并演练恢复。
+2. 使批量导入具有数据库级事务一致性、导入版本差异和可回滚工作流。
+3. 将编辑器版本历史组件并入 **官方** Art Design Pro 工程，覆盖桌面与移动端真实浏览器 E2E。
+4. 扩展整站模板与组件级版本继承、协作审批及内容设计依赖图。