WF2Des 一覧

メソッド

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

HTTPメソッド

GET: wf2des 生成ランの一覧取得

組織およびプロジェクトにスコープされた wf2des 生成ラン（wf2des の1行につき1要素）のフィルタ可能な一覧を返します。この一覧は以下のディスカバリ用サーフェスとして機能します。

遅延マテリアライズ — 結果フレームがまだ構築されていない完了済みラン（status=completed かつ materializedAt 未設定）。
保留中プレビュー — 確認チェックポイントで待機中のラン（status=processing かつ phase=awaiting_confirm）。
プロジェクト履歴 — プロジェクトの全生成レコード。クライアント側でのステータス／日付フィルタリングに対応。

命名規則

一貫性と可読性を確保するため、レスポンス内のJSONノードにはcamelCaseを使用します。クエリパラメータにはcamelCaseを使用します。

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

Authorization
Content-Type
Accept
Accept-language

レスポンスヘッダー

Content-Type

wf2des 生成ランの一覧取得

URI

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

パスパラメータ

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

クエリパラメータ

すべてのクエリパラメータは論理ANDで結合される任意のフィルタです。すべてのフィルタを省略すると、プロジェクトの削除されていないすべてのランを返します。列挙型フィルタは、行に格納された数値文字列のコード値を受け付けます（Status and Phase Codes を参照）。

Name	Type	Required	Description
status	string	Optional	ランのステータスコードでフィルタ — `0` processing / `1` completed / `2` failed / `3` rejected / `4` cancelled
phase	string	Optional	生成フェーズコードでフィルタ（`status=0` の範囲でのみ意味を持つ） — `0` parse / `1` awaiting_confirm / `2` assemble
screenId	string	Optional	画面IDでフィルタ
feedbackStatus	string	Optional	フィードバックステータスコードでフィルタ — `0` fixed / `1` adopted
materialized	boolean	Optional	`true` は `materializedAt` が設定されたランを返し、`false` は `materializedAt` が未設定のランを返す（遅延マテリアライズのディスカバリ）
createdFrom	string	Optional	`createdAt` の下限（両端含む、ISO 8601、例: `2026-07-01T00:00:00Z`）
createdTo	string	Optional	`createdAt` の上限（両端含む、ISO 8601）

リクエストボディ

なし。これは GET リクエストであり、すべてのフィルタリングはクエリパラメータで表現されます。

レスポンス

レスポンスはJSONです（HTTPステータス: 200 OK）。ボディは wf2desList 配列を持つオブジェクトであり、各要素は GET /…/wf2des/{wf2des_id} が返すものと同じ行の射影です。

{
  "wf2desList": [
    {
      "wf2desId": "8f14e45f-ceea-467d-9c7b-1a2b3c4d5e6f",
      "organizationId": 1,
      "projectId": 3,
      "figmaFileKey": "aBcDeFgHiJkLmNoPqRsTuV",
      "wfNodeId": "1:42",
      "screenId": "MEM_TOP",
      "prompt": null,
      "placementTarget": null,
      "autoConfirm": "0",
      "triggerSurface": "1",
      "status": "1",
      "phase": null,
      "attempt": 1,
      "error": null,
      "resultUrl": "1/3/wf2des/runs/8f14e45f-ceea-467d-9c7b-1a2b3c4d5e6f/20260706T093000Z/result.json",
      "flagCount": 3,
      "materializedAt": null,
      "feedbackStatus": null,
      "createdAt": "2026-07-06T09:29:12Z",
      "updatedAt": "2026-07-06T09:30:44Z"
    }
  ]
}

レスポンスフィールド

Name	Type	Description
wf2desList	array	フィルタに一致する wf2des ランの射影一覧（一致がない場合は空配列）

wf2desList 要素フィールド

各要素は1つの wf2des PostgreSQL 行の射影です。

Name	Type	Description
wf2desId	string	wf2des ランID（行の `id`）。ポーリングキーであり、worker/webhook の `job_id`
organizationId	integer	組織ID（テナンシースコープ）
projectId	integer	プロジェクトID（テナンシースコープ）
figmaFileKey	string	対象の Figma ファイルキー
wfNodeId	string	対象のワイヤーフレームフレームのノードID
screenId	string \| null	画面ID。フレーム名から事前入力され、ユーザーが確認済み
prompt	string \| null	任意の生成プロンプト（選択入力。メモの意図より下位にランク付け）
placementTarget	string \| null	結果ドキュメントのリクエストブロックに反映される任意の配置ノードID
autoConfirm	string	`0` normal（parse-confirm ステップ）/ `1` auto-confirm（1回の呼び出しで parse + assemble）
triggerSurface	string	`0` api / `1` plugin（認証済みサーフェスからバックエンド側で導出）
status	string	ランのステータスコード — `0` processing / `1` completed / `2` failed / `3` rejected / `4` cancelled
phase	string \| null	`status=0` 内の生成フェーズ — `0` parse / `1` awaiting_confirm / `2` assemble。終端状態になると `null`
attempt	integer	単調増加するフェンシングカウンタ。バックエンドの再キューイングでのみインクリメントされる
error	string \| null	クライアントに表示される失敗の詳細。failed webhook マニフェストから記録
resultUrl	string \| null	終端の結果／失敗アーティファクトの S3 キー（完了時に設定）
flagCount	integer \| null	完了時点でコピーされた結果ドキュメントの `confidence.flag_count`
materializedAt	string \| null	プラグインがフレームを構築した後、配置エンドポイント経由で設定されるタイムスタンプ。マテリアライズされるまで `null`
feedbackStatus	string \| null	`0` fixed / `1` adopted（記録用のみ）
createdAt	string	行の作成タイムスタンプ（ISO 8601）
updatedAt	string	最終更新タイムスタンプ（ISO 8601）

Status and Phase Codes

status および phase フィールドは、プラットフォームの規約に合わせた数値文字列の列挙値として格納されます。

status — ランのライフサイクル（生成のみ）:

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

phase — status=0 内で名前空間化され、ステータスコードとは独立。行が終端ステータスに達すると null:

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

データソース

すべての一覧データは wf2des PostgreSQL テーブルから読み取られます。これは生成ランにおける唯一のクライアント向けステータスサーフェスです。クエリは organization_id + project_id（テナンシースコープ）でフィルタし、ソフト削除された行（deleted_at IS NULL）を除外します。ディスカバリフィルタはセカンダリインデックス wf2des_org_project_file_status_idx (organization_id, project_id, figma_file_key, status) によって処理されます。

このエンドポイントは DocumentDB の読み取りを行いません。flagCount と resultUrl は完了時に行へミラーされるため、コンシューマはデータプレーンの呼び出しなしにランのディスカバリとトリアージを行えます。native-Figma DesignSpec 本体（結果アーティファクト）は wf2des-api 経由で個別に取得され、Figma プラグインによってマテリアライズされます。これは一覧の射影には含まれません。

認証

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

例外処理

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

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

どの行にも一致しないフィルタはエラーではありません — エンドポイントは空の wf2desList 配列とともに 200 OK を返します。

処理フロー

パスパラメータから組織IDとプロジェクトIDを抽出
クエリパラメータから任意のフィルタ（status、phase、screenId、feedbackStatus、materialized、createdFrom、createdTo）を抽出
ユーザーがプロジェクトへの読み取りアクセス権を持つことを検証
組織およびプロジェクトが存在することを確認
wf2des テーブルに対してクエリを構築: organization_id + project_id でフィルタし、ソフト削除された行を除外し、指定された各フィルタを適用（materialized=true → materialized_at IS NOT NULL、materialized=false → materialized_at IS NULL、日付範囲は created_at に対して適用）
ディスカバリインデックスに対してクエリを実行
各行を camelCase の要素へ射影し、wf2desList 配列を返却

詳細フローチャート

flowchart TD
    Start([GET Request]) --> Auth[Auth & Parameter Extraction]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[Access Check]
    AccessCheck --> HasAccess{Read Access?}
    HasAccess -->|No| Err403[403 Forbidden]
    HasAccess -->|Yes| VerifyScope[Verify Organization / Project Exist]

    VerifyScope --> ScopeExists{Exists?}
    ScopeExists -->|No| Err404[404 Not Found]
    ScopeExists -->|Yes| BuildQuery[Build Query on wf2des table<br/>filter org_id + project_id<br/>exclude deleted_at<br/>apply status / phase / screenId /<br/>feedbackStatus / materialized / date filters]

    BuildQuery --> Execute[Execute Query<br/>discovery index]
    Execute --> Project[Project Rows to camelCase<br/>Build wf2desList array]
    Project --> Success[200 OK<br/>wf2desList array]