レコード配置（マテリアライズ済み）

メソッド

この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}/placement

パスパラメータ

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

リクエストボディ

リクエストボディはJSONです。Figmaプラグインは、wf2des-api を通じて完全なマテリアライザ詳細（placed_node_id、materializer_report）を design_generation_result ドキュメントの placement ブロックに既に書き込んだ上で、このエンドポイントを呼び出して行レベルの materializedAt フラグを立てます。ボディには、完了を呼び出し元にエコーバックするために必要なノード参照のみが含まれます。重要な詳細はPostgreSQLの行ではなく、DocumentDBの placement ブロックに格納されます。

{
  "placedNodeId": "1204:57"
}

リクエストパラメータ

Name	Type	Required	Description
placedNodeId	string	Required	プラグインが構築したフレームのFigmaノードID（DocumentDBの `placement.placed_node_id` に対応）

レスポンス

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

{
  "projectId": "proj-123",
  "wf2desId": "wf2des-001",
  "status": "1",
  "phase": null,
  "placedNodeId": "1204:57",
  "materializedAt": "2026-07-06T09:35:00Z"
}

レスポンスフィールド

Name	Type	Description
projectId	string	プロジェクトID
wf2desId	string	wf2des ID
status	string	実行ステータス — マテリアライズ可能な行では常に `"1"`（完了）（ステータスコード参照）
phase	string \| null	生成フェーズ — 完了した行では既に `null` にクリア済み
placedNodeId	string	構築されたフレームのFigmaノードID（リクエストのエコー）
materializedAt	string	行がマテリアライズ済みに切り替わったISO 8601タイムスタンプ（`materialized_at` に対応）

既に materializedAt を持つ行に対して配置呼び出しを繰り返した場合、既存のタイムスタンプとともに 200 OK を返します（冪等 — フラグは再スタンプされません）。繰り返し呼び出しの placedNodeId は行のフラグ更新では無視されます。正となるノード参照は、プラグインが既にDocumentDBの placement ブロックに書き込んだものです。

ステータスコード

status:

Value	Meaning
`0`	処理中
`1`	完了
`2`	失敗
`3`	却下（デザイナーが解析を拒否した。失敗ではない）
`4`	キャンセル

status "1"（完了）の行のみがマテリアライズ可能です。phase は status "0" の内部で名前空間化されており、完了した行を含むあらゆる終端状態の行では既に null です。

認証

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

Figmaプラグインは、プロジェクトへのWriteアクセス権を持つ認証済みセッションでこのエンドポイントを呼び出します。配置の記録は生成をトリガーしたセッションに限定されません — いかなるWriteセッションもフレームが構築されたことを確認できます。このバックエンドエンドポイントは、プラグインの wf2des-api へのデータプレーン書き込み（Cognito JWT ではなくプラグインセッショントークンを持つ）とは別物です。マテリアライザ詳細はまずそのデータプレーン経路を通じてDocumentDBに到達し、このフラグ更新のみがPostgreSQLの行に到達します。

例外処理

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

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

処理フロー

backend は wf2des PostgreSQL row の唯一の writer です。plugin は先に placed_node_id と 7 種の materializer report（name_fallback、ordinal_fallback、build_error、font_fallback、prop_rejected、unmatched、preserved）を DocumentDB に書き、その後この endpoint で row-level materializedAt を設定します。

パスパラメータから組織ID、プロジェクトID、wf2des_id を抽出
リクエストボディから placedNodeId を抽出
ユーザーがプロジェクトへのWriteアクセス権を持つことを確認
wf2des_id で wf2des の行を取得。存在しない（または論理削除されている）場合は404を返却
行の organization_id と project_id がパスと一致することを確認。一致しない場合は404を返却
現在の行を検査:
materializedAt が既に設定されている status "1"（完了）→ 既存のタイムスタンプとともに200を返却（冪等、書き込みなし）
materializedAt が未設定の status "1"（完了）→ 続行
完了以外のいずれかの status（"0" 処理中 / "2" 失敗 / "3" 却下 / "4" キャンセル）→ 404を返却（この行にはマテリアライズ可能な結果が存在しない）
単一のPostgreSQLトランザクションで更新を適用 — materialized_at を現在のタイムスタンプに設定し、updated_at / updated_by をスタンプ。status は "1" のまま、phase は null のまま
マテリアライズされた wf2des 情報を返却

このエンドポイントはSQSメッセージを発行しません。生成は既に終端状態にあります。この呼び出しはクライアント側のマテリアライズステップが完了したことを記録するだけです。DesignSpec を読み取ったり取得したりはしません — DesignSpec は design_generation_result ドキュメント（DocumentDB）内のネイティブFigma仕様であり、プラグインが wf2des-api を通じて取得し、対象のFigmaファイルにマテリアライズします。バックエンドはここでデザインコンテンツを一切扱いません。

詳細フローチャート

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{status '1'<br/>completed?}

    StatusCheck -->|No — '0' / '2' / '3' / '4'| Err404
    StatusCheck -->|Yes| MatCheck{materializedAt<br/>already set?}

    MatCheck -->|Yes| Idempotent[200 OK<br/>existing timestamp, no write]
    MatCheck -->|No| Update[Update in one PG txn<br/>materialized_at = now<br/>status '1' / phase null unchanged]

    Update --> Success[200 OK<br/>materialized wf2des info]

詳細先行・フラグ後続ハンドシェイク

配置は、2つのサーフェスにまたがる2つの書き込みで、固定された順序で記録されます:

詳細（data plane、wf2des-api）。 plugin は placed_node_id、materialized_at、fingerprint/review field、7 種の materializer_report を DocumentDB に書きます。PostgreSQL には触れず、placement.design_area は worker-written のままです。
フラグ（このエンドポイント、バックエンド）。 プラグインは続いて POST …/wf2des/{wf2des_id}/placement を呼び出し、行レベルの materializedAt を立てます。フラグは最後にスタンプされるため、wf2des 行の設定済み materializedAt は、より完全な placement 詳細が既にDocumentDBで永続化されていることを保証します。GET とリストは行から materializedAt を提示します。レポート自体は wf2des-api 経由で placement ブロックから読み取られます。

この順序付けにより、行のフラグは信頼できるポインタであり続けます。GET をポーリングする消費者は、マテリアライザ詳細がコミットされた後にのみ materializedAt を見ることになり、その前に見ることは決してありません。