WF2Des Table
概要
いずれかのエッジ（ワイヤーフレームからデザイン、またはデザインからワイヤーフレーム）の生成実行に対するクライアント向けステータス行で、どちらのエッジかは edge が判別する。生成リクエスト 1 件につき 1 行で、バックエンドの wf2des-api が作成し、POST（201）で返され GET でポーリングされる。両エッジの生成実行に対する唯一の PostgreSQL 面であり、あらゆる書き込みはバックエンドが担う（行の作成に加えて ai-status webhook／confirm／placement／feedback の各エンドポイント）。ワーカーは決して書き込まない。
テーブル定義
| 論理名 | 物理名 | カラム名 | データ型 | 主キー | リレーション | ユニーク | NULL許可 | デフォルト値 | 備考 |
|---|---|---|---|---|---|---|---|---|---|
| WF2Des | wf2des | id | string | ◯ | uuid（varchar(255)）。クライアント向けリクエスト ID — POST 201 の対象かつ GET ポーリングのキーで、ワーカー／webhook には job_id として引き渡される。クライアント向けステータス行であり、更新はバックエンド側からのみ行う |
||||
| organization_id | number | organization:id | テナントスコープ。現状は DEFAULT_ORGANIZATION_ID=1 |
||||||
| project_id | number | project:id | テナントスコープ。セカンダリ探索インデックス (organization_id, project_id, figma_file_key, status) の一部 — 遅延マテリアライズの探索用 |
||||||
| figma_file_key | string | 対象 Figma ファイル。部分ユニーク (figma_file_key, wf_node_id) WHERE status = '0' の一部 — WF ノードごとに 1 件のみ稼働中の生成を許可（重複トリガー → 409 と既存 id を返す） |
|||||||
| wf_node_id | string | 対象 WF フレームのノード id（稼働中生成の重複排除キーの後半） | |||||||
| screen_id | string | 画面 ID。フレーム名から事前入力しユーザーが確定する | |||||||
| prompt | string | ◯ | 任意の生成プロンプト（選択入力。memo intent より下位にランク付け） | ||||||
| placement_target | string | ◯ | 任意の配置ノード id。結果ドキュメントの request ブロックに引き写される |
||||||
| auto_confirm | enum | '0' | wf2des_auto_confirm — '0' normal（parse-confirm ステップ）／'1' auto-confirm（parse と assemble を 1 回の呼び出しで実行） |
||||||
| trigger_surface | enum | wf2des_trigger_surface — '0' api／'1' plugin（認証された surface からバックエンド側で導出） |
|||||||
| status | enum | '0' | wf2des_status（Type Codes を参照） |
||||||
| phase | enum | ◯ | wf2des_phase — status '0' 内部の生成オーケストレーション（Type Codes を参照）。終端に達すると NULL。GET／一覧で表示される |
||||||
| attempt | number | 1 | 単調増加のフェンシングカウンター（現状は 1 固定 — これをバンプするエンドポイントは存在しない） — バックエンドの再キュー投入時のみ増加する。DocumentDB の結果ドキュメント書き込みと webhook の作用はこれを比較する（(_id, attempt) の CAS） |
||||||
| error_message | string | ◯ | クライアントに可視な失敗詳細（text）。失敗 webhook のマニフェストから記録される |
||||||
| result_url | string | ◯ | 終端の結果／失敗アーティファクトの S3 キー | ||||||
| flag_count | number | ◯ | 結果ドキュメントの confidence.flag_count を完了時点でコピーしたもの。GET／一覧に表示され、データプレーン呼び出しなしでフラグを確認できる |
||||||
| materialized_at | datetime | ◯ | プラグインがフレームを構築した後、バックエンドの placement エンドポイントで設定される | ||||||
| feedback_status | enum | ◯ | wf2des_feedback_status — '0' fixed／'1' adopted（バックエンドの feedback エンドポイントが記録。記帳のみ） |
||||||
| created_at | datetime | ||||||||
| updated_at | datetime | ||||||||
| deleted_at | datetime | ◯ | 論理削除 | ||||||
| created_by | string | user:cognito_sub | システム書き込み（webhook／enqueue）はサービスアカウントの cognito_sub を使用 |
||||||
| updated_by | string | user:cognito_sub | |||||||
| deleted_by | string | user:cognito_sub | ◯ | ||||||
| edge | enum | '0' | wf2des_edge — 行を生成したエッジ: '0' wf2des／'1' des2wf。稼働中生成の部分ユニークキーの一部であり、一方のエッジで稼働中の実行がもう一方をブロックすることはない |
||||||
| score | number | ◯ | 実行のスコアを完了時点でコピーしたもの（numeric(5,4)）。GET／一覧に表示され、データプレーン呼び出しなしでスコアを確認できる。完了エフェクトがスコアを含まない場合は NULL |
||||||
| score_version | string | ◯ | varchar(32) — スコアを算出したフォーミュラのバージョン（des2wf エッジでは ds@1.0）。バージョンをまたいでスコアを比較することはなく、追跡のためのフィールド |
リレーション
organization_id→organization.idproject_id→project.id- 監査フィールド（
created_by／updated_by／deleted_by）はuser.cognito_subを参照する。システム側の書き込みはサービスアカウントのcognito_subを使用する (figma_file_key, wf_node_id)が対象 WF フレームを特定する。組み立て済みの結果は完了フローを通じて共有プラットフォームのdesignレジストリ（type=componentコンテキスト）に着地し、ここの外部キー経由ではないdesign_generation_resultDocumentDB ドキュメントと 1:1。そのドキュメントの_idはこのidと等しい
インデックス
- PRIMARY KEY (id)
- PARTIAL UNIQUE INDEX
wf2des_open_generation_uq(project_id, figma_file_key, wf_node_id, edge) WHERE status = '0' — プロジェクト単位かつエッジ単位で WF ノードごとに 1 件のみ稼働中（進行中）の生成を許可。重複トリガーは 409 と既存 id を返す。終端状態に到達しないまま残った実行は、そのワイヤーフレームの新規トリガーをブロックし続ける - INDEX
wf2des_org_project_file_status_idx(organization_id, project_id, figma_file_key, status) — 遅延マテリアライズの探索／一覧クエリ deleted_by／deleted_atの UNIQUE 扱いは標準的な論理削除の監査パターンに従う
Type Codes
status（wf2des_status）— 生成のみ。内部 wf2des ワーカーの実行は行を持たない。
| 値 | 意味 |
|---|---|
'0' |
processing |
'1' |
completed |
'2' |
failed |
'3' |
rejected（デザイナーが parse を却下。failed ではない） |
'4' |
cancelled（cancel エンドポイントが設定） |
phase（wf2des_phase）— status '0' の内部で名前空間化され、status コードとは独立。行が終端 status に達すると NULL にクリアされる。
| 値 | 意味 |
|---|---|
'0' |
parse |
'1' |
awaiting_confirm |
'2' |
assemble |
auto_confirm（wf2des_auto_confirm）: '0' normal（parse-confirm ステップ）・'1' auto-confirm（parse と assemble を 1 回の呼び出しで実行）。
trigger_surface（wf2des_trigger_surface）: '0' api・'1' plugin（認証された surface からバックエンド側で導出）。
feedback_status（wf2des_feedback_status）: '0' fixed・'1' adopted（バックエンドの feedback エンドポイントが記録。記帳のみ）。
edge（wf2des_edge）: '0' wf2des・'1' des2wf — 行を生成したエッジ。稼働中生成の部分ユニークキーの一部。
注記
- バックエンド所有:
wf2desワーカーは PostgreSQL の認証情報を持たず、このテーブルを決して書き込まない。すべての PG への作用はバックエンド側で適用される — ai-status webhook ハンドラが完了時点の唯一の書き込み者であり（status／phaseを反転し、result_url／error_message／flag_countを記録、1 トランザクション内で attempt ガード）、confirm／placement／feedback の各エンドポイントが対話的な遷移を扱う。 - 行が先で SQS が後: バックエンドは生成メッセージを enqueue する前に行を
INSERTする（status '0'、phase '0'parse）ため、クライアントには常にポーリング対象がある。 - confirm エンドポイントは
phase '2'assemble に進める前にphase '1'awaiting_confirm ＋ attempt を CAS でマッチさせる。parse の却下はプラグインが書き込み（parse.rejected）、confirm エンドポイントがstatus '3'に反転する — これは webhook 経路ではない。 attemptは DocumentDB のdesign_generation_resultドキュメントと共有するフェンシングカウンター（(_id, attempt)の CAS）。取って代わられた attempt の webhook は no-op となる。flag_countとresult_urlは完了時点で終端のdesign_generation_resultドキュメントを写し取り、コンシューマがデータプレーン読み取りを回避できるようにする。- enum は数値文字列値（
'0'、'1'、…）として格納され、design／wireframeで用いられるプラットフォーム規約に一致する。