コンテンツにスキップ

生成のキャンセル

メソッド

このAPIはRESTメソッドを採用しています。

HTTPメソッド

POST: wf2des 生成をキャンセルする

命名規則

一貫性と可読性を確保するため、リクエストとレスポンスのJSONノードにはcamelCaseを使用します。SQSペイロードのノードにはsnake_caseを使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダーに設定されます。

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

wf2des 生成をキャンセルする

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/{wf2des_id}/cancel

パスパラメータ

Name Type Required Description
organization_id integer Required 組織ID
project_id integer Required プロジェクトID
wf2des_id string Required wf2des ID

リクエストボディ

リクエストボディは不要です。ボディが含まれていても無視され、キャンセルはパスのみで完全に処理されます。

レスポンス

レスポンスはJSONです（HTTPステータス: 200 OK）。

{
  "projectId": "proj-123",
  "wf2desId": "wf2des-001",
  "status": "4",
  "phase": null,
  "attempt": 1,
  "cancelledAt": "2026-07-06T09:35:00Z"
}

レスポンスフィールド

Name Type Description
projectId string プロジェクトID
wf2desId string wf2des ID
status string キャンセル後の終端ステータス — 常に "4"（cancelled）
phase string | null 生成フェーズ — 行が終端ステータスに達すると null にクリアされる
attempt integer キャンセルされた実行のフェンシングカウンタ（キャンセルによって変化しない）
cancelledAt string 行が cancelled に切り替えられたISO 8601タイムスタンプ（updatedAt のミラー）

すでに status "4" の行に対する再度のキャンセルは、同じボディで200 OKを返します（冪等）。それ以外の終端行（"1" completed / "2" failed / "3" rejected）に対するキャンセルは409 Conflictを返します。

認証

認証はAmazon Cognitoが発行するJSON Web Token（JWT）を使用して行われます。

プロジェクトにWriteアクセス権を持つ認証済みセッションであれば、生成をキャンセルできます。キャンセルはそれをトリガーしたセッションに限定されません。生成は phase "1" awaiting_confirm でパークされており、キャンセルするためにconfirm判定は不要です。

例外処理

エラー時には以下のステータスコードが返却されます。

Description Status Code Status Name
認証情報が欠落している 401 Unauthorized
権限が不足している 403 Forbidden
wf2des、プロジェクト、または組織が見つからない 404 Not Found
生成がキャンセル不可 — すでに終端（"1" / "2" / "3"） 409 Conflict
内部サーバーエラー 500 Internal Server Error

処理フロー

バックエンドが wf2des PostgreSQL行を所有し、唯一の書き込み者です。キャンセルはバックエンド側で適用される単一のattemptガード付き状態遷移です。workerはPostgreSQLの認証情報を持たず、一切関与しません。この遷移は現在の行に対するCASであり、行がまだ status "0"（processing）であり phase "1"（awaiting_confirm）でパークされている場合にのみ、status "4"（cancelled）を書き込み、phase を NULL にクリアします。

  1. パスパラメータから組織ID、プロジェクトID、wf2des_id を抽出
  2. ユーザーがプロジェクトへのWriteアクセス権を持つことを確認
  3. wf2des_id で wf2des 行を取得。存在しない（またはソフトデリートされている）場合は404を返却
  4. 行の organization_id と project_id がパスと一致することを確認。一致しない場合は404を返却
  5. 現在の status / phase を検査:
  6. すでに status "4"（cancelled）→ 既存の行とともに200を返却（冪等、書き込みなし）
  7. それ以外の終端 status（"1" completed / "2" failed / "3" rejected）→ 409を返却（キャンセル不可）
  8. status "0"（processing）だが phase "1" awaiting_confirm でパークされていない → 409を返却（キャンセル不可）
  9. status "0" かつ phase "1" awaiting_confirm → 続行
  10. 1つのPostgreSQLトランザクションでCAS更新を適用 — status = "4" を設定し、phase を NULL にクリアし、updated_at / updated_by をスタンプ。CASは行がまだ status "0" + phase "1" であることをガードとする（すでに行を進めた並行confirm / webhookはレースに敗れ409となる）
  11. キャンセルされたwf2des情報を返却

このエンドポイントはSQSメッセージを発行しません。生成はconfirmチェックポイントでパークされており、シグナルすべき進行中のworkerは存在しません。キャンセルは単に行を退役させ、confirmエンドポイントがそれを phase "2"（assemble）へ進められないようにするだけです。キャンセルされた行を対象とする遅延または上書きされたai-status webhookは、それ自身のattemptガードの下でno-opとなります。

詳細フローチャート

flowchart TD
    Start([POST Request]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Write Access?}
    HasAccess -->|No| Err403[403 Forbidden]
    HasAccess -->|Yes| FetchRow[Fetch wf2des Row<br/>WHERE id = :wf2des_id]

    FetchRow --> RowExists{Exists &<br/>org/project match?}
    RowExists -->|No| Err404[404 Not Found]
    RowExists -->|Yes| StatusCheck{Current status?}

    StatusCheck -->|status '4' cancelled| Idempotent[200 OK<br/>existing row, no write]
    StatusCheck -->|status '1' / '2' / '3'<br/>terminal| Err409[409 Conflict<br/>not cancellable]
    StatusCheck -->|status '0' processing| PhaseCheck{phase '1'<br/>awaiting_confirm?}

    PhaseCheck -->|No| Err409
    PhaseCheck -->|Yes| CAS[CAS Update in one PG txn<br/>status = '4' cancelled<br/>phase = NULL<br/>guard: status '0' + phase '1']

    CAS --> CASResult{CAS won?}
    CASResult -->|No — concurrent confirm/webhook| Err409
    CASResult -->|Yes| Success[200 OK<br/>cancelled wf2des info]