cms-SiteForge/docs/V8_21_EDITOR_AND_MAPPING.md

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）：

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