ルールボードのアップロード
メソッド
この API は REST の方法論に従います。
HTTP メソッド
POST: ガイドラインボードをアップロードします — rule_upload イベントをエンキューし、ワーカーの rule_process 実行にルーティングして 1 つのイミュータブルなルールリビジョン を作成します。
アップロードのたびに 新しいリビジョン が作られます。過去のリビジョンが変更・削除されることはありません。また、新規アップロードは「これが現行である」という意図的な操作のため、有効な revert ピンを解除します。
命名規則
一貫性と可読性のため、リクエスト / レスポンスの JSON ノードは camelCase、SQS ペイロードのノードは snake_case を使用します。
リクエストとレスポンス
ヘッダー
メタ情報はレスポンスボディではなく HTTP ヘッダー に設定されます。
リクエストヘッダー
AuthorizationContent-TypeAcceptAccept-language
レスポンスヘッダー
Content-Type
ルールボードのアップロード
URI
パスパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| organization_id | integer | 必須 | 組織 ID |
| project_id | integer | 必須 | プロジェクト ID |
リクエストボディ
リクエストボディは JSON です。
{
"figmaFileKey": "abc123XYZ",
"boardNodeIds": ["2:100", "2:101", "2:102"],
"designRuleId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f"
}
リクエストパラメータ
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| figmaFileKey | string | 必須 | ボードが存在するガイドラインファイル。Figma 逐語（^[A-Za-z0-9]+$）。 |
| boardNodeIds | string[] | 必須 | 選択されたガイドラインボードフレーム — 1 件以上。CANVAS / SECTION コンテナも受け付け、ワーカーが子ボードフレームへ展開する。 |
| designRuleId | string | 任意 | リビジョンを追加する既存の design_rule id。省略時は新しい UUID を採番し、version 1 から新しいルール系列を開始する。 |
レスポンス
レスポンスは JSON です（HTTP ステータス: 202 Accepted）。
{
"eventRunId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e70",
"designRuleId": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
"figmaFileKey": "abc123XYZ",
"boardNodeIds": ["2:100", "2:101", "2:102"]
}
レスポンスフィールド
| 名前 | 型 | 説明 |
|---|---|---|
| eventRunId | string | GET …/wf2des/events/{eventRunId}/status をポーリングして進行状況を取得する。この実行は長時間 — 下記参照。 |
| designRuleId | string | 新リビジョンが属するルール系列（エコー、または新規採番した id）。 |
| figmaFileKey | string | リクエストのエコー。 |
| boardNodeIds | string[] | リクエストのエコー — ワーカーがコンテナを展開する 前 の選択内容。 |
認証
認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへの Write 権限を保持している必要があります。
エラーハンドリング
エラー時には以下のステータスコードが返されます。
| 説明 | ステータスコード | ステータス名 |
|---|---|---|
不正なボディ（figmaFileKey の形式不正、boardNodeIds が空または形式不正） |
400 | Bad Request |
| 認証情報の欠落 | 401 | Unauthorized |
| 権限不足（プロジェクトへの Write 権限なし） | 403 | Forbidden |
| プロジェクトまたは組織が見つからない | 404 | Not Found |
| SQS 送信の失敗 | 500 | Internal Server Error |
処理フロー
- パスパラメータから組織 ID とプロジェクト ID を、リクエストボディを取得する。
- ユーザーがプロジェクトへの Write 権限を持つことを検証する。
designRuleIdが省略されていれば採番し、新しいeventRunIdを採番する。rule_uploadイベントをwf2des-eventsSQS キューへ送信する。- ポーリング用ハンドルとともに 202 を返す。
非同期処理
rule_upload イベントは rule_process にルーティングされます。ワーカーはボードごとに画像をレンダリングし、ノードテキストを読み、ボードを理解（comprehend）し、内容に応じたエクストラクタへルーティングして逐語抽出します。その後、全ボードを決定論的にマージし（権限ゲート方式、LLM ジャッジなし）、マージ済みルールセットとソースボードの双方を保持する 1 つのイミュータブルなリビジョンを作成します。
これはシステム内で最も長い実行です。 ボードは並行処理されますが、大規模なガイドラインでは依然として数分かかります。プラグインの進行ステッパーは eventRunId のポーリングで駆動されます。抽出された文字列は必ずボード自身のノードテキストの部分文字列であるため、捏造は構造的に不可能です。
rule_process は 内部 実行です — ai-status Webhook も PostgreSQL 効果もありません。出力は design_rule コレクション内の新リビジョンであり、GET …/wf2des/rules/latest から観測できます。
SQS ペイロード
{
"event_type": "rule_upload",
"organization_id": 1,
"project_id": 7,
"event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e70",
"design_rule_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e6f",
"figma_file_key": "abc123XYZ",
"board_node_ids": ["2:100", "2:101", "2:102"]
}
SQS ペイロードフィールド
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| event_type | string | 必須 | 常に rule_upload。キューの判別子。 |
| organization_id | integer | 必須 | 組織 ID。 |
| project_id | integer | 必須 | プロジェクト ID。 |
| event_run_id | string | 必須 | プラグインがポーリングするライブステータス文書と対応付ける。 |
| design_rule_id | string | 必須 | 新リビジョンが属するルール系列。 |
| figma_file_key | string | 必須 | ガイドラインファイル（逐語）。 |
| board_node_ids | string[] | 必須 | 選択されたボード。コンテナはワーカー側で展開される。 |