書類提出 — DocumentSubmission

これは何か

サークルが実際に書類を提出し、運営スタッフが審査する流れ全体を管理します。

書類定義（DocumentType）がひな形なら、書類提出（DocumentSubmission）はそのひな形に対してサークルが記入して送ってきた実体です。

NOT_SUBMITTED → PENDING → APPROVED
                    ↓
                REJECTED

書類は「バージョン」単位で管理されます。サークルが修正して再提出するたびにバージョンが上がります。

各バージョンには4種類の状態があります。

DocumentTypeに複数の承認ステージが定義されている場合、1段階目のステージが承認されると2段階目に進みます。すべてのステージを通過して初めてステータスが APPROVED になります。

DocumentApprovalRecord は「誰が・いつ・どのバージョンに対して・どのステージで・どんな判断をしたか」を記録する監査ログです。

運営スタッフが承認または却下を誤った場合は、最新の有効な提出バージョンに対する直近の審査操作を取り消せます。対象ステージの requiredRoles を満たすスタッフだけが操作できます。

POST /api/v1/document-submissions/{submission_id}/approval-records/{approval_record_id}/cancel

{
  "reason": "誤って承認したため"
}

中間ステージの承認を取り消すと、提出状態は PENDING のまま currentStage が対象ステージへ戻ります。
最終承認を取り消すと、提出と最新バージョンを APPROVED から PENDING へ戻し、バージョンの承認者と承認日時をクリアします。
却下は、企画メンバーが新しい再提出バージョンを一度も作成していない場合に限り取り消せます。提出を PENDING に戻し、currentStage を却下した段階へ、最新バージョンの approvalStatus を PENDING へ復元して rejectionReason をクリアします。
却下を取り消しても、先行ステージの有効な承認は維持します。
承認・却下記録は削除せず、cancelledAt、cancelledById、cancellationReason を監査履歴として保持します。元のコメントや却下理由も変更しません。
状態計算では cancelledAt IS NULL の承認・却下記録だけを有効として扱います。
User.groups のロール判定は、カンマ区切りのグループ名を分割して完全一致で行います。

管理画面では、取消条件を満たす直近の記録に対して「承認を取り消す」または「却下を取り消す」を表示します。確認モーダルで対象ステージを示し、必須の取消理由を入力して実行すると、提出詳細を再取得して復元後の審査状態と取消情報を含む履歴を表示します。

企画メンバーは、審査が始まっていない最新バージョンを次のAPIで取り下げられます。

POST /api/v1/document-submissions/{submission_id}/withdraw

{
  "reason": "誤ったファイルを再提出したため"
}

リクエストボディと reason は省略できます。

初回提出を取り下げた場合は NOT_SUBMITTED に戻ります。従来どおり提出期限後は実行できません。
再提出を取り消した場合は、直前の取消済みでないバージョンを再び有効にし、その内容・提出日時・審査状態を復元します。この操作は提出期限後も実行できます。
復元元が APPROVED なら提出状態も APPROVED、REJECTED または REVISION_REQUESTED なら REJECTED に戻ります。
ファイルとフリーテキストはどちらもバージョンとして保存されます。フリーテキストの現在値は有効バージョンと同期します。
取り消したバージョンには cancelledAt、cancelledById、cancellationReason を記録し、行とR2上のファイルは削除しません。
最新バージョンに cancelledAt IS NULL の承認・却下記録がある場合は取り消せません。
各提出で isActive = true のバージョンは常に1件以下です。