Code2WF生成一覧

Method

この計画APIはhistory、polling、遅延Figma placement検出用にscoped Code2WF rowを一覧します。

HTTP Method

GET: Code2WF生成を一覧

Naming Convention

Query/response fieldは camelCase を使用します。

Request and Response

Headers

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

Request Headers

Authorization
Content-Type
Accept
Accept-language

Response Headers

Content-Type

Code2WF生成一覧

URI

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

Path Parameters

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

Query Parameters

Name	型	必須	説明
status	string	No	`0`、`1`、`2`
pageImportId	UUID	No	Import済みpageでfilter
figmaFileKey	string	No	対象Figma fileでfilter
materialized	boolean	No	`false` は `materialized_at IS NULL`
limit	integer	No	1～100のpage size。current WF2Des list実装に従いdefault `50`
offset	integer	No	非負row offset。default `0`

遅延placement検出には次を使います。

?figmaFileKey=aBc1DeFg2HiJ3kLmNoPqRs&status=1&materialized=false&limit=50&offset=0

Response

{
  "code2wfList": [
    {
      "code2wfId": "019ffa75-01c0-75a2-8123-456789abcdf0",
      "organizationId": 1,
      "projectId": 7,
      "pageImportId": "0195f16e-6f11-7ea8-b45c-f6712ed9d8a3",
      "figmaFileKey": "aBc1DeFg2HiJ3kLmNoPqRs",
      "screenId": "AUTORACE_DATABASE",
      "placementTarget": "128:9001",
      "status": "1",
      "attempt": 1,
      "error": null,
      "resultUrl": "1/7/code2wf/019ffa75-01c0-75a2-8123-456789abcdf0/1/result/result.json",
      "flagCount": 0,
      "materializedAt": null,
      "createdAt": "2026-08-13T09:30:00Z",
      "updatedAt": "2026-08-13T09:31:12Z"
    }
  ],
  "total": 1
}

Response Fields

Name	型	説明
code2wfList	array	FilterにmatchするCode2WF row projection。
total	integer	`limit` / `offset` 適用前の全matching row数。

code2wfList Element Fields

Name	型	説明
code2wfId	string	Job UUIDとpoll key。
organizationId	integer	Organization scope。
projectId	integer	Project scope。
pageImportId	string	Import済みpage row ID。
figmaFileKey	string	対象Figma file。
screenId	string	Caller確認済みscreen ID。
placementTarget	string \| null	任意のWF2Des-compatible placement node。Targetを変更せずcurrent-page absolute `x/y`を使う。
status	string	`"0"` processing、`"1"` completed、`"2"` failed。
attempt	integer	MVPでは常に `1`。
error	string \| null	安全なfailure detail。
resultUrl	string \| null	Client向けの不変な `result.json` またはfailed-artifact S3 key。
flagCount	integer \| null	Completion時の既存spec内 `flagged=true` outcome数。
materializedAt	string \| null	Figma placement completion timestamp。
createdAt / updatedAt	string	Audit timestamp（ISO 8601）。

各 code2wfList elementはCode2WF status取得と同じrow projectionに加え、WF2Des list elementと同様にscoped organization/project IDを含みます。Current WF2Des実装と同様にbounded default pageを適用し、全件数 total を返します。ListはPostgreSQLのみを読み、Page ImportやS3を読みません。

Data Source

全dataはbackend所有PostgreSQL code2wf tableから取得します。Queryはorganization/projectでscopeし、soft-deleted rowを除外し、current WF2Des listと同じcreated_at DESC順にします。Figma file discoveryには code2wf_org_project_file_status_idx、Page Import filterには code2wf_page_import_id_idx を使います。このendpointはPage Import manifest、S3 result、DocumentDB document、Figma APIを読みません。

Authentication

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

Error Handling

説明	Status Code	Status Name
Filter、limit、offsetが無効	400	Bad Request
Authentication credentialなし	401	Unauthorized
Organization、project、または認可済みscopeがない	404	Not Found
Internal database error	500	Internal Server Error

Processing Flow

Authenticateしproject Read accessを確認する。
Filterと limit / offset をvalidationする。
Scopedかつ未削除のPostgreSQL rowをqueryし、page bound適用前に total を計算する。
S3 hydrationなしでrow projectionを返す。

Deferred Materialization Flow

認証済みpluginを開いたとき、current fileを status=1&materialized=false&limit=50&offset=0 でlistする。
返却rowをsequentialに処理する。各immutable resultを取得して新しいstaging rootをbuildし、任意placementTargetを共有placement pathで解決する。
既存WF2Desのjob-ID indexとstampを使い、新しいbuild成功後にのみprior completed rootを置き換え、生成screen node IDでplacementを呼ぶ。
Pageがemptyになるまで、同じfilterをoffset=0で再queryする。成功したplacementごとにrowがfiltered setから外れるため、offsetを進めるとworkをskipし得る。このflowでtotalは情報用とする。
Session内でjob IDをdedupeする。Failure rowはunmaterializedのままとし、後続rowの処理は続行する。Bounded no-progress guardで同じfailureの反復を停止する。
Authenticationがexpireした場合はloginを促してdiscoveryをretryする。別のFigma fileのrowはfetch/materializeしない。

Server側materialization claim、lease、status、retry scheduleはありません。2つのplugin sessionが、どちらかがplacementを記録する前に同じrowをdiscoverする場合があります。Job-ID stamp/indexと冪等placementはduplicateを減らしますが、atomic cross-session claimではありません。Open-time Code2WF discoveryは計画中のplugin/API-client extensionであり、current WF2Des pluginには含まれません。

Detailed Flowchart

flowchart TD
    Start([GET Code2WF List]) --> Auth[Authenticate and Check Read Access]
    Auth --> Validate[Validate Filters Limit Offset]
    Validate --> Query[Query Scoped Non-Deleted Rows]
    Query --> Count[Calculate Total]
    Count --> Page[Apply Limit and Offset]
    Page --> Success[200 code2wfList + total]