版 API

案件の版（バージョン）を扱うエンドポイント。

新しい版の作成は案件 API の「保存して新しい版を作成」で行います。ここでは版の参照・ロールバック・版からの複製を扱います。

認証・レスポンス形式・エラーの扱いは API 定義を参照。

メソッド

HTTP メソッド

メソッド	URI	概要
GET	`/api/surveys/{surveyId}/versions`	版一覧取得
POST	`/api/surveys/{surveyId}/versions/{versionNo}/rollback`	指定版からロールバック
POST	`/api/surveys/{surveyId}/versions/{versionNo}/duplicate`	指定版から複製

リソース定義

版スキーマ

フィールド	データ型	備考
id	string	版の UUID
versionNo	number	版番号。案件内で一意
createdAt	string	作成日時（ISO 8601）
createdBy	string	作成者のユーザー ID
status	enum	版が作られた時点のステータス
snapshotSections	Section[]	その版のセクション・設問一式
sourceVersionId	string	複製元の版 ID
rollbackFromVersionId	string	ロールバック元の版 ID（ロールバックで作られた版のみ）

認証要件

x-user-email / x-user-name ヘッダによるユーザー認証が必要です。

操作	必要な権限
版一覧取得・版から複製	`view`
ロールバック	`edit`

権限がない場合は 404 Not Found を返します。

版一覧取得

概要

案件の版履歴を取得します。各版のスナップショット（セクション・設問）も含まれます。

URI

GET /api/surveys/{surveyId}/versions

パラメータ	データ型	必須	備考
surveyId	string	◯	案件の UUID

レスポンス（200 OK）

{
  "ok": true,
  "data": [
    {
      "id": "…",
      "versionNo": 1,
      "createdAt": "2026-08-01T00:00:00.000Z",
      "createdBy": "…",
      "status": "下書き",
      "snapshotSections": []
    },
    {
      "id": "…",
      "versionNo": 2,
      "createdAt": "2026-08-05T00:00:00.000Z",
      "createdBy": "…",
      "status": "下書き",
      "snapshotSections": [],
      "sourceVersionId": "…"
    }
  ]
}

例外処理

説明	ステータスコード	ステータス名
案件が存在しない、または `view` 権限がない	404	Not Found

処理フロー

view 権限を確認する
案件に紐づく版を版番号順に取得する
各版のスナップショット（セクション・設問・選択肢・分岐ルール・表示ロジック）を読み込む

指定版からロールバック

概要

指定した版の内容を復元した 新しい版 を作成し、それを最新版にします。

過去の版は削除されません。ロールバック自体も版として履歴に残ります。

URI

POST /api/surveys/{surveyId}/versions/{versionNo}/rollback

パラメータ	データ型	必須	備考
surveyId	string	◯	案件の UUID
versionNo	string	◯	復元したい版の版番号（数値の文字列）

バリデーションルール

フィールド	ルール
versionNo	必須。数字のみで構成される文字列（`^\d+$`）

レスポンス（201 Created）

新しく作られた版スキーマを返します。rollbackFromVersionId に復元元の版 ID が入ります。

例外処理

説明	ステータスコード	ステータス名
`versionNo` が数値でない	400	Bad Request
案件または版が存在しない、`edit` 権限がない	404	Not Found

処理フロー

シーケンス図

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: POST .../versions/{versionNo}/rollback
    API->>API: edit 権限を確認
    API->>DB: 指定版を取得
    alt 見つからない
        API-->>Client: 404 Not Found
    else
        API->>DB: 指定版のスナップショットを読み込み
        API->>DB: 新しい版を作成 (rollbackFromVersionId を記録)
        API->>DB: スナップショットを複製 (安定 ID は引き継ぐ)
        API->>DB: 最新版番号・最新版ポインタを更新
        API-->>Client: 201 Created
    end

指定版から複製

概要

指定した版の内容を初期状態とする 別の案件 を作成します。元の案件は変更されません。

案件 API の「案件または指定版から複製」に sourceVersionNo を指定した場合と同じ処理です。

URI

POST /api/surveys/{surveyId}/versions/{versionNo}/duplicate

パラメータ	データ型	必須	備考
surveyId	string	◯	複製元の案件 UUID
versionNo	string	◯	複製元の版番号（数値の文字列）

レスポンス（201 Created）

複製された案件スキーマを返します（版ではありません）。

例外処理

説明	ステータスコード	ステータス名
`versionNo` が数値でない	400	Bad Request
案件または版が存在しない、`view` 権限がない	404	Not Found

処理フロー

view 権限を確認する
指定された版番号の版とスナップショットを取得する
トランザクションで新しい案件（版 1）を作成する
複製元の権限を引き継ぐ
スナップショットのセクション・設問を挿入する