WF2Des ステータス取得

メソッド

RESTメソッドを採用しています。

HTTPメソッド

GET: wf2des ステータス取得

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

Authorization
Content-Type
Accept
Accept-language

レスポンスヘッダー

Content-Type

wf2des ステータス取得

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/{wf2des_id}

パスパラメータ

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

リクエストボディ

なし。このエンドポイントはリクエストボディを受け取りません。

レスポンス

レスポンスはJSONです（HTTPステータス: 200 OK）。wf2des PostgreSQL行の現在の状態を反映し、生成実行のポーリング対象となります。

{
  "wf2desId": "wf2des-001",
  "status": "0",
  "phase": "1",
  "attempt": 1,
  "error": null,
  "resultUrl": null,
  "flagCount": null,
  "materializedAt": null,
  "feedbackStatus": null,
  "screenId": "MEM_REGISTER"
}

完了した実行の例:

{
  "wf2desId": "wf2des-001",
  "status": "1",
  "phase": null,
  "attempt": 1,
  "error": null,
  "resultUrl": "1/3/wf2des/runs/wf2des-001/20260706T093000Z/result.json",
  "flagCount": 3,
  "materializedAt": "2026-07-06T09:35:00Z",
  "feedbackStatus": null,
  "screenId": "MEM_REGISTER"
}

レスポンスフィールド

Name	Type	Description
wf2desId	string	wf2des ID（ポーリング対象の行ID。worker/webhook には `job_id` としてエコーされる）
status	string	実行ステータス — `0` processing / `1` completed / `2` failed / `3` rejected / `4` cancelled（Status Codes を参照）
phase	string \| null	`status 0` 内の生成フェーズ — `0` parse / `1` awaiting_confirm / `2` assemble。行が終端ステータスに到達すると null になる
attempt	integer	単調増加のフェンシングカウンター。現状は `1` 固定で、これを増加させるものは存在しない
error	string \| null	クライアントに表示される失敗詳細。失敗した webhook manifest から記録される。`status` が `2` failed でない限り null
resultUrl	string \| null	終端結果（または失敗）アーティファクトの S3 キー。実行が終端ステータスに到達するまで null
flagCount	integer \| null	完了時点における結果ドキュメントの `confidence.flag_count` のコピー。completed になるまで null
materializedAt	string \| null	Figma プラグインが placement エンドポイント経由でフレームを構築した時点で設定されるタイムスタンプ。materialize されるまで null
feedbackStatus	string \| null	`0` fixed / `1` adopted。feedback エンドポイントが記録する（記帳目的のみ）。feedback が記録されていない場合は null
screenId	string \| null	Screen ID。フレーム名から事前入力され、ユーザーによって確認される

Status Codes

status:

Value	Meaning
`0`	processing
`1`	completed
`2`	failed
`3`	rejected（デザイナーが parse を却下した。failed ではない）
`4`	cancelled

phase — status 0 内に名前空間化され、status コードとは独立。終端に到達すると null:

Value	Meaning
`0`	parse
`1`	awaiting_confirm
`2`	assemble

データソース

すべてのフィールドは、wf2des_id で識別される wf2des PostgreSQL行 から直接読み取られます。このエンドポイントはステータスポーリングのみであり、生成されたデザインは返しません。

生成されたデザインはネイティブ Figma の DesignSpec であり、design_generation_result ドキュメント（DocumentDB）に保存され、その永続アーティファクトは resultUrl（S3）にあります。クライアントは wf2des-api を通じて DesignSpec を取得し、Figma プラグインがそれを materialize して対象ファイルに展開します。この backend エンドポイントはデザインコンテンツを一切返さず、行のステータス、phase、および結果ポインターのみを返します。

認証

認証はAmazon Cognitoから発行されるJSON Web Tokens (JWT)を使用して行われます。

例外処理

例外処理のステータスコードは以下の通りです。

Description	Status Code	Status Name
認証情報不足	401	Unauthorized
実行権限不足	403	Forbidden
wf2des、プロジェクト、または組織が見つかりません	404	Not Found
内部サーバーエラー	500	Internal Server Error

処理フロー

パスパラメータから組織ID・プロジェクトID・wf2des_idを抽出
ユーザーがプロジェクトへのRead権限を持つか検証
PostgreSQL から id が wf2des_id に一致する wf2des 行を取得
行が存在しない場合は404を返却
行の organization_id と project_id がパスパラメータと一致することを検証
行のステータス、phase、結果フィールドをレスポンスに整形して返却

詳細フローチャート

flowchart TD
    Start([GET Request]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Read Access?}
    HasAccess -->|No| Err404[404 Not Found]
    HasAccess -->|Yes| QueryRow[Query PostgreSQL<br/>wf2des row<br/>WHERE id = :wf2des_id]
    QueryRow --> Exists{Row Exists?}
    Exists -->|No| Err404
    Exists -->|Yes| ScopeCheck{organization_id &<br/>project_id match?}
    ScopeCheck -->|No| Err404
    ScopeCheck -->|Yes| Format[Format Response<br/>status / phase / attempt / error /<br/>resultUrl / flagCount / materializedAt /<br/>feedbackStatus / screenId]
    Format --> Success[200 OK]