AI Des2WF — インフラ構成
Des2WF 固有のデプロイ面です。共通のプラットフォーム基盤は インフラ構成 にあります。
コンピュート
| 項目 | 値 |
|---|---|
| ランタイム | AWS Lambda 上の Python 3.12、コンテナイメージ |
| アプリ | apps/des2wf — apps/wf2des の ピア Lambda。内部の実行ファミリーではない |
| バッチ | SQS + ReportBatchItemFailures、部分バッチ失敗 |
| 共有コード | packages/figma-ir — 両アプリから一方向に import。逆方向は不可 |
なぜ実行ファミリー追加ではなく 2 つ目の Lambda なのか。 WF2Des の generation モジュールは約 2,700 LOC で、 5 つのインライン後段パスを持ち、選択経路は実測で非決定的です（同一画面 3 回の実行で 3 つの異なる spec）。Des2WF の エンジンはその機構を一切共有しないため、同じモジュールに置けばガードの山を継承するだけで得るものがありません。 デプロイ衛生ではなく分離が理由です。
キューとトリガー
| トリガー | 所有 | Des2WF での用途 |
|---|---|---|
| DES2WF キュー | backend | 生成と完了後レビューの専用 transport。edge=des2wf を保持し、review は kind=render_review も持つ |
wf2des-events 取り込みキュー |
AI 側 | プラグイン起点イベントに再利用。backend は送信権限のみ |
| EventBridge スケジュール | AI 側 | des2wf 用は無し。 定期スイープの対象が無く、WF コンポーネントライブラリはプラグインからオンデマンドで登録する |
job ID の共有元は PostgreSQL の wf2des テーブルであり、キューの共有ではありません。
backend は queueType=des2wf を SQS_DES2WF_QUEUE_URL へ送り、worker は
kind で生成と review を区別します。キット登録は引き続き共有 events 経路を使います。
ストレージとシークレット
| 項目 | 値 |
|---|---|
| 結果バケット | backend 所有の AI バケット、プレフィックス {org}/{proj}/des2wf/ |
| スナップショット保存 | per-node REST エンベロープ全体、マップ保持 |
| DocumentDB | guinness_v2。結果、キット、共有、スコープ付き override の各コレクションは ストア を参照 |
| Figma アクセス | 処理の起点が誰かで分割 — 下記参照 |
クレデンシャルは起点で 2 つに分割される。 リクエストした本人と無関係な権限でスナップショットを取ると、 ユーザーが開けないファイルをトリガーでき、逆にユーザーが開けるファイルがサービスアカウント未参加のため 404 になる — いずれも実ファイルでの実測であり、この経路にサービスアカウント PAT が存在しない理由である。分割:
| 経路 | クレデンシャル |
|---|---|
| デザインスナップショット取得（ユーザー操作、backend 側） | プラットフォーム figma_token テーブルにあるリクエストしたユーザー自身の PAT |
| ワーカー側の Figma 読み込み（登録 sweep — この経路にユーザーは存在しない） | 組織のプライベート OAuth アプリ許諾（Authorization: Bearer）。figma_oauth_grant に AI 所有鍵で暗号化して保存。アプリ未設定のデプロイ向けフォールバックとして figma_pat 環境変数 |
当初の観測は今も有効であり、この分割の理由そのものである: 2 つのクレデンシャルは到達性が異なるため、 片方の経路の失敗は他方の証拠にならず、エラーはどのクレデンシャルを使ったかを明示しなければならない。
環境変数
| 変数 / 設定 | 説明 |
|---|---|
DOCUMENTDB_CONNECTION_STRING, DOCUMENTDB_NAME, DOCUMENTDB_CA_PATH |
DocumentDB 接続、guinness_v2 |
| コレクション名 | 環境変数で上書き可能。新規の wireframe_component を含む |
SQS_DES2WF_QUEUE_URL |
backend の専用生成／review キュー設定 |
wf2des-events キュー URL |
AI 所有の取り込み |
WEBHOOK_BASE_URL, WEBHOOK_API_KEY |
ai-status エンドポイントと X-API-Key |
| 結果バケット + キープレフィックス | {org}/{proj}/des2wf/ |
FIGMA_OAUTH_* + 許諾の暗号化鍵 |
ワーカー側 Figma 認証 — OAuth アプリ許諾（client id/secret は backend 側に置き、ワーカーは AI 所有の暗号化鍵を保持してリフレッシュのみ行う）。フォールバックとして figma_pat |
| スナップショットのバイト上限 | 既定 20 MB、環境変数で上書き可能。des2wf の取得経路で強制 — wf2des にこのゲートは存在しない |
DEFAULT_ORGANIZATION_ID |
シングルテナント既定 |
| モデルティア | parse は決定的。両 mode は元画像 PNG があれば設定済み strong model で文脈分類を行い、kit はバリアント選択も追加。完了後のレンダーレビューは別の画像呼び出し。model／prompt version を記録し、どちらの mode も再実行の一致は保証しない |
PROMPT_VERSION, SPEC_VERSION |
ピン留め。ただし SPEC_VERSION を比較している箇所はシステム内に無く、安全ゲートではなく追跡用 |
グラフィック分類の実行環境
STRONG_MODELが画像モデルを指定します。ワーカーには対応する provider の資格情報が必要です。DES2WF_VERDICT_TABLE_NAMEの既定コレクション名はdes2wf_verdictのままですが、 生成が読むのはスコープ付きrecord_type=graphic_override_v1であり、旧 verdict ではありません。- 元画像は任意の S3 PNG です。backend が要求ユーザーの PAT を使い、JSON と同じ Figma version と absolute bounds で取得します。ワーカーは S3 を読み、自身の Figma 資格情報で生成用画像を再取得しません。
- 元画像 PNG は source hash と render hash による content-addressed key です。 レビュー PNG は別のジョブ単位オブジェクトです。ストア を参照してください。
- 現在の分類定数は 1 バッチ 6 候補、3 並列、180 秒、元画像最大 32,000,000 ピクセルです。 これは分類処理の制限であり、ジョブ全体のタイムアウトではありません。
- 元 PNG の取得には 20 MiB のバイト上限もあります。snapshot の 20 MB 制限と PNG のピクセル上限は別です。不正画像、provider 障害、分類時間切れでは 図形を保持してフォールバックを記録し、生成全体を必ず失敗させるわけではありません。
- 構造化ログと
graphic_classificationで complete／partial／fallback を区別します。 生成完了だけでは、全候補の分類完了を意味しません。
デプロイ順序
ここでの順序は重要です。この理由で本プロジェクトは一度痛い目を見ています。投入時点で ack するルートは、クライアントに 成功を表示しながらエンベロープを DLQ へ送ります。
- マイグレーション最初 —
edgeカラム、source_node_id、部分ユニークインデックスの再作成。 - ワーカーを backend より先 — 送る前に、ワーカーが
edge=des2wfを消費できる状態にする。 - backend をプラグインより先 — エンドポイントが応答する前に、プラグインの des2wf 操作を到達可能にしない。
events拡張は 3 リポジトリ同時 — プラグインのフィールド、backend の enum、internal-api のリテラルを同時に 出す。さもなければ MVP のスコアがサーバーへ到達しない。
CI
WF2Des のワークフローに準じます（lint、型チェック、unit / component テスト、コンテナビルド、マージ時デプロイ）。 本ビルド固有の追加は 2 点です。
- 共有パッケージは 再エクスポートのシム越しに 着地させ、初日は既存スイートを無変更に保つ。シム削除のコミットは 別で、単独で revert 可能であり、import の変更量を担うのはそのコミットである;
- des2wf の実行が PostgreSQL に書けてしまう場合に落ちるガードテスト。この境界がシステムの主要な不変条件だからである。