---
{
  "id": "platform.form.versions-and-restore",
  "topic": "form",
  "title": "Form 版本與未發布還原",
  "locale": "zh-TW",
  "version": "2026-08-25",
  "summary": "Restore 以 optimistic concurrency 建立新的未發布 draft，先保留 pre-restore checkpoint，不會發布或重寫 responses。",
  "content": "Form 有 5 個私有 version Actions：`list_versions`、`get_version`、`create_named_version`、`restore_version`、`copy_version`。history 需 user edit-grade access 與 Agent write grant；archived 或 frozen-space form 不能修改，全部都是 `allow_in_public: false`。\n\ncheckpoints 的可見種類為 `baseline`、`automatic`、`named`、`published`、`pre_restore`、`restored`、`legacy_response`；一般編輯會產生 automatic checkpoint。`create_named_version` 無需確認，但只應在使用者明確要求時使用；支援 dry-run 與 idempotency key，重試回同一 version。\n\n`restore_version` 需要 UserConfirm，以及 `formId`、`versionId`、`expectedHeadVersionId`。先以 `list_versions` 取得最新 head；不一致時回 `HISTORY_CONFLICT`，需 reload 後重試。restore 會先建 `pre_restore`，再把選定 definition 寫成新的 `restored` 未發布 draft；`published_revision_id` 與公開表單不變，responses 也不重寫。成功 result 的 `publishRequired: true` 表示必須另外確認 `publish_form` 才會公開。\n\n若 field id 衝突，`fieldIdMap` 可能重新配置部分 id，後續 field Actions 要用 map 後 id。`legacy_response` 不可 restore，會回 `VERSION_PAYLOAD_INVALID`；依 list result 的 `canRestore`／`canCopy` 判斷。restore 對同 key 與來源具 idempotency；dry-run 回 `wouldCreateUnpublishedDraft` 與 `wouldRequireConfirmation`。`VERSION_NOT_FOUND`、`VERSION_FORBIDDEN`、`HISTORY_CONFLICT`、`FORM_PUBLISH_REQUIRED` 等皆以 runtime 為準。\n\n`copy_version` 可在不改動來源時救援歷史。它需 `formId` 與 `versionId`，建立具全新 history 的另一份 Form，不需 confirmation、採 Strict drift；公開副本仍須另行確認 publish。\n",
  "aliases": [
    "表單版本紀錄",
    "還原表單",
    "頭版本衝突",
    "還原前檢查點",
    "未發布草稿",
    "expectedHeadVersionId",
    "fieldIdMap",
    "publishRequired"
  ],
  "tags": [
    "form",
    "versions",
    "restore",
    "concurrency",
    "publish"
  ],
  "relatedActions": [
    "arinova.form.list_versions",
    "arinova.form.get_version",
    "arinova.form.create_named_version",
    "arinova.form.restore_version",
    "arinova.form.copy_version",
    "arinova.form.publish_form"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/form/versions-and-restore/"
}
---

Form 有 5 個私有 version Actions：`list_versions`、`get_version`、`create_named_version`、`restore_version`、`copy_version`。history 需 user edit-grade access 與 Agent write grant；archived 或 frozen-space form 不能修改，全部都是 `allow_in_public: false`。

checkpoints 的可見種類為 `baseline`、`automatic`、`named`、`published`、`pre_restore`、`restored`、`legacy_response`；一般編輯會產生 automatic checkpoint。`create_named_version` 無需確認，但只應在使用者明確要求時使用；支援 dry-run 與 idempotency key，重試回同一 version。

`restore_version` 需要 UserConfirm，以及 `formId`、`versionId`、`expectedHeadVersionId`。先以 `list_versions` 取得最新 head；不一致時回 `HISTORY_CONFLICT`，需 reload 後重試。restore 會先建 `pre_restore`，再把選定 definition 寫成新的 `restored` 未發布 draft；`published_revision_id` 與公開表單不變，responses 也不重寫。成功 result 的 `publishRequired: true` 表示必須另外確認 `publish_form` 才會公開。

若 field id 衝突，`fieldIdMap` 可能重新配置部分 id，後續 field Actions 要用 map 後 id。`legacy_response` 不可 restore，會回 `VERSION_PAYLOAD_INVALID`；依 list result 的 `canRestore`／`canCopy` 判斷。restore 對同 key 與來源具 idempotency；dry-run 回 `wouldCreateUnpublishedDraft` 與 `wouldRequireConfirmation`。`VERSION_NOT_FOUND`、`VERSION_FORBIDDEN`、`HISTORY_CONFLICT`、`FORM_PUBLISH_REQUIRED` 等皆以 runtime 為準。

`copy_version` 可在不改動來源時救援歷史。它需 `formId` 與 `versionId`，建立具全新 history 的另一份 Form，不需 confirmation、採 Strict drift；公開副本仍須另行確認 publish。