# 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. 扩展整站模板与组件级版本继承、协作审批及内容设计依赖图。