インポート済みページからワイヤーフレームを生成（トリガー）

Method

この計画APIはREST methodologyに従います。完了済みPage ImportからCode2WF生成行を1件作成し、非同期worker messageを1件dispatchします。

HTTP Method

POST: インポート済みページからワイヤーフレームを生成

Naming Convention

Request/response JSONは camelCase、SQS payloadは snake_case を使用します。

Request and Response

Headers

Request Headers

Authorization
Content-Type
Accept
Accept-language

Response Headers

Content-Type

インポート済みページからワイヤーフレームを生成

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/code2wf

Path Parameters

Name	型	必須	説明
organization_id	integer	必須	Organization ID
project_id	integer	必須	Project ID

Request Body

{
  "pageImportId": "0195f16e-6f11-7ea8-b45c-f6712ed9d8a3",
  "figmaFileKey": "aBc1DeFg2HiJ3kLmNoPqRs",
  "screenId": "AUTORACE_DATABASE",
  "placementTarget": "128:9001"
}

Request Parameters

Name	型	必須	説明
pageImportId	string (UUID)	必須	URIのorganization/project内にある完了済みPage Import。
figmaFileKey	string	必須	対象Figma file。WF2Desと同じvalidationに従う。
screenId	string	必須	通常はimport済みpage nameからprefillし、callerが確認するscreen ID。`wf2des.screen_id` と同様にverbatim保存。
placementTarget	string	任意	`wf2des.placement_target` に従うplacement contextのFigma node。未指定はnullに正規化。Current pageでは共有`placeRoot`がtargetを変更せずabsolute `x/y`を使い、解決できないtargetはviewport centerへfallbackする。

Code2WFはrepository、public URL、HTML/CSS、viewport、source hash、status、attempt、result、materialization fieldを受け付けません。

Response

新規row（HTTP status: 201 Created）:

{
  "code2wfId": "019ffa75-01c0-75a2-8123-456789abcdf0",
  "pageImportId": "0195f16e-6f11-7ea8-b45c-f6712ed9d8a3",
  "figmaFileKey": "aBc1DeFg2HiJ3kLmNoPqRs",
  "screenId": "AUTORACE_DATABASE",
  "placementTarget": "128:9001",
  "status": "0",
  "attempt": 1,
  "createdAt": "2026-08-13T09:30:00Z"
}

Response Fields

Name	型	説明
code2wfId	string	Backend生成UUIDv7 row IDとpoll key。
pageImportId	string	Import済みpage source row。
figmaFileKey	string	対象Figma file。
screenId	string	Caller提供screen ID。
placementTarget	string \| null	任意のplacement context。
status	string	`"0"` processing、`"1"` completed、`"2"` failed。
attempt	integer	MVPでは常に `1`。
createdAt	string	Row作成時刻（ISO 8601）。

Code2WFはplatform wf2des_status 型を再利用し、このflowではprocessing/completed/failedのみを使います。Phase、reject、cancel transitionは持ちません。

Authentication

Amazon Cognito JWTで認証します。Callerにはprojectへの Write accessが必要です。

Trigger Identity

Backendが有効なtriggerごとに新しいUUIDv7 code2wfId を生成します。同一bodyの2 requestは2 rowを作成し、2 jobをdispatchします。APIはcaller生成IDを受け付けず、request-deduplication indexも持ちません。

Error Handling

説明	Status Code	Status Name
Figma fieldまたはcaller所有fieldが無効	400	Bad Request
Authentication credentialなし	401	Unauthorized
Page Import、organization、project、または認可済みscopeがない	404	Not Found
Page Import未完了	409	Conflict
Page Import result解決またはSQS dispatch失敗	500	Internal Server Error

Row作成後にPage Import result解決またはdispatchが失敗した場合、backendはbest-effortでrowをfailedにし、共通API error envelopeを返します。

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal Server Error"
  }
}

Failed rowはscoped history listから確認できます。MVPでは再dispatchせず、別の有効なtriggerが新しいbackend生成 code2wfId を作ります。

Processing Flow

Authenticateし、Write accessを確認する。
Figma fieldを検証する。
Pathのprojectがorganizationに属することを検証し、(page_import.id, page_import.project_id = project_id)で未削除Page Importを取得し、completed statusを必須にする。このservice checkでindependent foreign keyだけでは強制できないscopeを保証する。
UUIDv7を生成し、status="0"、attempt=1 の最小 code2wf rowをinsertする。
不変normalized manifestを1回readして検証し、その正確なbytesから一貫した page_result_url、page_result_hash、capture_hash のpin setを導出する。Bytesがmissing/corruptならdispatch前に失敗する。
それらの正確なsource値を含むSQS messageを1件送る。
解決/dispatch失敗時は (id, attempt=1, status="0") をfailedへCASし、安全な error_message を記録する。
作成したrowを返す。

PostgreSQL rowが保存するのは page_import_id のみで、Page Import result pointer/hashをcopyしません。この検証済みS3 readはPostgreSQL/S3 transactionではありません。

Detailed Flowchart

flowchart TD
  Start([POST]) --> Auth[Authenticate and authorize]
  Auth --> Source[Validate completed Page Import]
  Source --> Row[Generate UUIDv7; insert status 0; attempt 1]
  Row --> Resolve[Resolve immutable Page Import result]
  Resolve --> Queue[Send SQS message]
  Queue -->|Success| Created[201 Created]
  Queue -->|Failure| Failed[CAS row to status 2; return 500]

Asynchronous Processing

WorkerはSQSで参照されたPage Import resultのみを読み、S3に不変なCode2WF resultを1件書き、共通AI-status webhookで通知します。WorkerはPostgreSQLへ書きません。

SQS Payload

{
  "code2wf_id": "019ffa75-01c0-75a2-8123-456789abcdf0",
  "organization_id": 1,
  "project_id": 7,
  "attempt": 1,
  "nonce": "8bed02b2-c93d-4854-8f4f-1c91744dc419",
  "page_import_id": "0195f16e-6f11-7ea8-b45c-f6712ed9d8a3",
  "page_result_url": "s3://bucket/1/7/page-import/0195f16e-6f11-7ea8-b45c-f6712ed9d8a3/normalized/manifest.json",
  "page_result_hash": "sha256:44a7f61a6f90f476c349b264c0cbd824ce45ecad0d9985f0750f8a251aa9592a",
  "capture_hash": "sha256:90e54d8b9cf4ff0fdc2b927b4453d59f4c3e219c236bb398e660aca50a62ae27",
  "screen_id": "AUTORACE_DATABASE"
}

nonce はtransport correlation専用です。PostgreSQLに保存せず、webhook row transitionはnonceではなく (id, attempt, current status) を比較します。