コンポーネントレジストリの再同期

メソッド

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

HTTP メソッド

POST: ファイル全体 のコンポーネントレジストリ再同期をトリガーします — resync イベントをエンキューし、スコープなしの component_sweep にルーティングします。

POST …/wf2des/components が追加的でデザイナーが選択したボードのみを走査するのに対し、resync はプロジェクトに登録された Figma ファイルすべてを再走査します。ライブラリが広範に変更され、レジストリをそれに合わせて整合させたい場合に使用します。

リクエストは ボディを取りません — スコープは「このプロジェクトに登録されたすべて」であり、ワーカーがプロジェクトの Figma ファイル一覧（GET …/figma-files 参照）から読み取ります。

命名規則

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

リクエストとレスポンス

ヘッダー

リクエストヘッダー

Authorization
Accept
Accept-language

レスポンスヘッダー

Content-Type

レジストリの再同期

URI

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

パスパラメータ

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

リクエストボディ

なし。 このエンドポイントはリクエストボディを取りません。

レスポンス

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

{
  "organizationId": 1,
  "projectId": 7,
  "event": "resync",
  "eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e73"
}

レスポンスフィールド

名前	型	説明
organizationId	integer	パスのエコー。
projectId	integer	パスのエコー。
event	string	常にリテラル `resync`。
eventRunId	string	`GET …/wf2des/events/{eventRunId}/status` をポーリングして進行状況を取得する。

認証

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

エラーハンドリング

リクエストボディが存在しないため、400 はありません。

説明	ステータスコード	ステータス名
認証情報の欠落	401	Unauthorized
権限不足（プロジェクトへの Write 権限なし）	403	Forbidden
プロジェクトまたは組織が見つからない	404	Not Found
SQS 送信の失敗	500	Internal Server Error

処理フロー

パスパラメータから組織 ID とプロジェクト ID を取得する。
ユーザーがプロジェクトへの Write 権限を持つことを検証する。
新しい eventRunId を採番する。
resync イベントを wf2des-events SQS キューへ送信する。
ポーリング用ハンドルとともに 202 を返す。

非同期処理

resync イベントはファイル全体の component_sweep にルーティングされます。ワーカーはプロジェクトに登録された Figma ファイルを読んで走査範囲を決め、各ファイルから COMPONENT / COMPONENT_SET の定義とリモートライブラリのインスタンスを走査し、すべてを design_component へ upsert します。

同じ スケジュール実行 の sweep が AI 側の EventBridge スケジュールで動作します。このエンドポイントは同一の実行をオンデマンドで起動するものです。

resync は provenance: "plugin-observed" を持つレコードを 格下げできません — POST …/wf2des/component-captures で送信されたキャプチャは resync を生き延びます。この性質により、キャプチャのパス後に resync を実行しても安全です。

component_sweep は内部実行です — ai-status Webhook はなく、バックエンド自身のコンポーネントレジストリ upsert を除いて PostgreSQL 効果もありません。

SQS ペイロード

{
  "event_type": "resync",
  "organization_id": 1,
  "project_id": 7,
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e73"
}

SQS ペイロードフィールド

名前	型	必須	説明
event_type	string	必須	常に `resync`。キューの判別子。
organization_id	integer	必須	組織 ID。
project_id	integer	必須	プロジェクト ID。
event_run_id	string	必須	プラグインがポーリングするライブステータス文書と対応付ける。

ペイロードにはファイルキーやノード ID は含まれません — sweep のスコープはプロジェクトに登録された Figma ファイル一覧であり、ワーカーが自ら読み取ります。