cms-SiteForge/docs/HISTORY_V8_12_README.md

# 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 实机与浏览器跨设备回归仍需部署后完成。