ワイヤーフレームフレームの登録

メソッド

この API は REST の方法論に従います。

HTTP メソッド

POST: ワイヤーフレームのフレームを登録します — スナップショットをサーバー側で取得し、frame_registration イベントをエンキューします。このイベントはワーカーの wf_parse 実行にルーティングされ、パース済みのワイヤーフレームツリーをキャッシュします。

登録は ウォームアップ であり、生成ではありません。wf2des の PostgreSQL 行もデザインも作られません。後続のトリガーがキャッシュ済みツリーを再利用できるよう、事前にフレームをパースするだけです。

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

Authorization
Content-Type
Accept
Accept-language

レスポンスヘッダー

Content-Type

フレーム登録

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/frames

パスパラメータ

名前	型	必須	説明
organization_id	integer	必須	組織 ID
project_id	integer	必須	プロジェクト ID

リクエストボディ

リクエストボディは JSON です。

{
  "figmaFileKey": "abc123XYZ",
  "nodeId": "2:264664"
}

リクエストパラメータ

名前	型	必須	説明
figmaFileKey	string	必須	フレームが存在する Figma ファイル。Figma 逐語 — 英数字のみ、アンダースコア不可（`^[A-Za-z0-9]+$`）。
nodeId	string	必須	登録するワイヤーフレームフレームのノード ID（`^[A-Za-z0-9:;_-]+$`）。

レスポンス

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

{
  "figmaFileKey": "abc123XYZ",
  "nodeId": "2:264664",
  "snapshotUrl": "s3://dev-guinness-backend/1/7/wf2des/2_264664/wireframe.json",
  "wfContentHash": "8f14e45fceea167a5a36dedd4bea2543"
}

レスポンスフィールド

名前	型	説明
figmaFileKey	string	リクエストのエコー。
nodeId	string	リクエストのエコー。
snapshotUrl	string	バックエンドが取得したワイヤーフレームスナップショット（`s3://`）。`wf_parse` 用にエンキューされる。
wfContentHash	string	取得したワイヤーフレームのコンテンツハッシュ。キャッシュ内のパース済みツリーを識別する。

200 ではなく 202 です — レスポンスはイベントがエンキューされたことを示すもので、パースの完了を示すものではありません。このエンドポイントは eventRunId を返しません。wf_parse はライブステータスドキュメントを持たない内部実行のため、ポーリング対象がありません。効果は間接的に観測されます: 同じフレームに対する後続の生成トリガーがキャッシュ済みパースを再利用します。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへの Write 権限を保持している必要があります。

エラーハンドリング

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

説明	ステータスコード	ステータス名
不正なボディ（`figmaFileKey` / `nodeId` の欠落、またはパターン不一致）	400	Bad Request
認証情報の欠落	401	Unauthorized
権限不足（プロジェクトへの Write 権限なし）	403	Forbidden
プロジェクトまたは組織が見つからない	404	Not Found
スナップショット取得の失敗、または SQS 送信の失敗	500	Internal Server Error

処理フロー

パスパラメータから組織 ID とプロジェクト ID を、リクエストボディから figmaFileKey と nodeId を取得する。
ユーザーがプロジェクトへの Write 権限を持つことを検証する。
サーバー側でワイヤーフレームスナップショットを取得する — ノードを解決し、サブツリーを走査し、ワイヤーフレーム JSON を S3 に書き込む。スナップショットのスコープは ボード であり、キャンバス全体ではない。
frame_registration イベントを wf2des-events SQS キューへ送信する。
スナップショットのポインタとコンテンツハッシュとともに 202 を返す。

非同期処理

frame_registration イベントはワーカーの wf_parse 実行にルーティングされ、スナップショットを読み、ワイヤーフレームをロールと意図にパースし、結果をコンテンツハッシュをキーとして wireframe DocumentDB コレクションに書き込みます。

wf_parse は内部実行です: ai-status Webhook を発行せず、PostgreSQL への効果もありません。失敗は出力ドキュメントの鮮度と SQS デッドレターキューを通じてのみ可視化されます。

SQS ペイロード

{
  "event_type": "frame_registration",
  "organization_id": 1,
  "project_id": 7,
  "figma_file_key": "abc123XYZ",
  "node_id": "2:264664",
  "snapshot_url": "s3://dev-guinness-backend/1/7/wf2des/2_264664/wireframe.json"
}

SQS ペイロードフィールド

名前	型	必須	説明
event_type	string	必須	常に `frame_registration`。キューの判別子。
organization_id	integer	必須	組織 ID。
project_id	integer	必須	プロジェクト ID。
figma_file_key	string	必須	Figma ファイル（逐語）。
node_id	string	必須	登録されたワイヤーフレームフレームのノード ID。
snapshot_url	string	必須	ワーカーが読むスナップショット。