Code2WF Placement記録

Method

この計画APIは既存WF2Desの行レベルplacement規約に従います。Pluginがnative Figma screenを構築した後に呼び、backendは materialized_at のみを記録します。

HTTP Method

POST: Code2WF placementを記録

Naming Convention

Request/response JSONは camelCase を使用します。

Request and Response

Headers

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

Request Headers

• Authorization
• Content-Type
• Accept
• Accept-language

Response Headers

• Content-Type

Code2WF Placement記録

URI

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

Path Parameters

Name	型	必須	説明
organization_id	integer	必須	Organization ID
project_id	integer	必須	Project ID
code2wf_id	string	必須	Code2WF UUID

Request Body

{
  "placedNodeId": "1204:57"
}

Request Parameters

Name	型	必須	説明
placedNodeId	string	必須	生成screenのFigma node ID。Responseへechoし、PostgreSQL rowには保存しない。

Response

{
  "projectId": "7",
  "code2wfId": "019ffa75-01c0-75a2-8123-456789abcdf0",
  "status": "1",
  "placedNodeId": "1204:57",
  "materializedAt": "2026-08-13T09:35:00Z"
}

Response Fields

Name	型	説明
projectId	string	既存WF2Des placement responseと同じ形式でserializeするproject scope。
code2wfId	string	Code2WF job UUID。
status	string	Completed statusの "1"。
placedNodeId	string	Pluginが渡し、永続化せずechoするFigma node ID。
materializedAt	string	Placement completion timestamp（ISO 8601）。

materializedAt 設定後の再送は、既存timestampを 200 OK で返し、rowを再stampしません。WF2Desと同様、再送requestのnode IDはechoのみでPostgreSQLには保存しません。

Status Codes

Value	Meaning
"1"	completedでplacement可能

Status "0" と "2" はplacement対象外で、WF2Des placement behaviorに合わせnot-found surfaceで返します。

Authentication

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

Error Handling

説明	Status Code	Status Name
placedNodeId が無効	400	Bad Request
Authentication credentialなし	401	Unauthorized
Project scopeまたはjobがunknown、unauthorized、soft-deleted、processing、またはfailed	404	Not Found
Database update失敗	500	Internal Server Error

Processing Flow

1. AuthenticateしWrite accessを確認する。
2. Scopedかつ未削除のCode2WF rowを取得する。
3. status="1" を要求する。
4. materialized_at が既に設定済みならwriteせず返す。
5. 未設定ならbackend transaction 1件で materialized_at、updated_at、updated_by を設定する。
6. Timestampを返し、placedNodeId をechoする。

SQS messageは送信しません。Endpointは追加のmaterialization state、report、child-node ID、Figma page IDを保存しません。計画中のCode2WF plugin pathが再buildを所有し、既存WF2Desのstamp/indexを使って完了済みreplacementをprior outputとswapします。

Detailed Flowchart

flowchart TD
    Start([POST Code2WF Placement]) --> Auth[Authenticate and Check Write Access]
    Auth --> Row[Fetch Scoped Completed Row]
    Row --> Placed{materialized_at exists?}
    Placed -->|Yes| Existing[200 Existing Timestamp]
    Placed -->|No| Stamp[Set materialized_at + Audit Fields]
    Stamp --> Success[200 Placement]