AI Des2WF — システムワークフロー

プラグイン、backend コントロールプレーン、ワーカー、各ストアをまたぐ Des2WF の動作。フィールドレベルの契約は I/O 定義。

本プロダクトは入力を 到着タイミング で分けており、フローもその分割に従います。

タイミング	入力	フロー
データ構築時	デザインページ、WF コンポーネント	下記「1. 登録（データ構築時）」
生成時	1 つのデザインフレーム	下記「2. 生成（one-shot）」

1. 登録（データ構築時）

flowchart TD
    A["デザイナーがプラグインでキットのコンポーネントページを選択<br/>（キットはデザインシステムと同様、作業ファイル内に置く）"] --> B["プラグイン: スコープ付きコンポーネントスイープ"]
    B --> C["ワーカー: COMPONENT_SET ごとに derive_component_context<br/>(variant axes / slots / sizes / publish keys)"]
    A --> B2["プラグイン: コンポーネントキャプチャ<br/>（key とバリアントを実マスターから読む —<br/>スイープ単独ではローカルマスターに key を付けられない）"]
    B2 --> D
    C --> D[("DocumentDB wireframe_component<br/>componentSet の PUBLISH KEY で採番<br/>+ component_node_id（キットのマスターは<br/>ローカルコピーのため）")]
    D --> E["assemble が実行時に読む<br/>（バリアント単位の選択 + ガード、事前計算テーブル無し）"]
    D2 --> E
    A2["デザインページの取り込み"] --> D2[("design レジストリ（共有プラットフォームテーブル）")]

キットはデザイナーが選び、変わるものです — キットの入れ替えはこの同じフローの再実行であり、コードのリリースでは決してありません。したがって登録は安価かつ冪等であり続ける必要があります。選択はレジストリを実行時に読むため、入れ替えに再マッピング手順は不要で、陳腐化したものも残りません。

このフローが担保すべき 3 つの規則:

componentSet の publish key で採番する。 node id は不可（ファイル複製ごとに変わり、同一ライブラリを 2 ボードへ複製すると同じマスターが別 id になる）。名前も不可（入手可能なコーパスでの実測では、衝突する名前が使用実績ベースでインスタンスの 56% を覆い、1 つの名前が 3 つの異なるマスターを指していました）。
別コレクションに置く。 WF コンポーネントライブラリはデザインシステムとは別のライブラリであり、design レジストリには属しません。そこへ入れると、全レジストリを候補として渡され kind ゲートが既定 off の WF2Des の候補集合が、すべての読み出し箇所でフィルタが正しいことに依存してしまいます。
マスターは derive_component_context で読む。 ツリー抽出は COMPONENT_SET のバリアント境界を平坦化します。

レジストリのドキュメントが記述するのはコンポーネントセットですが、実際にインスタンス化できる単位は バリアントです。したがって実行時にはドキュメントをバリアント単位へ展開し、バリアント固有のキーに投票します。 1 つのセットの全バリアントはドキュメントの _id を共有するため、_id で引くと候補に挙がったものとは別の兄弟バリアントがガードへ渡ってしまいます。

キットは Figma Community の既存オープンソースワイヤーフレームキットで、そのページを作業ファイル内へコピーして設置します — wf2des 側でデザインシステムが取る設置と同じです。したがってマスターはローカルであり、 node-id 解決が直接機能し、ライブラリのインポートもインスタンスアンカーも不要で、登録にはスイープに加えて プラグインキャプチャ経路が必要です（wf2des での実測: サーバースイープ単独ではローカル 279 件中 106 件しか key を取得できず、残りはキャプチャが埋めた）。

キットのマスターが作業ファイル内で使えるバリアントを持つかどうかは、設置後に一度だけ検証します。

2. 生成（one-shot）

flowchart TD
    A["Plugin: 元フレーム 1 件 + mode + layout=auto"] --> B["Backend: 共有 PG 行 + scoped snapshot"]
    B --> C["同一 version の元 PNG を best-effort 取得"]
    C --> D["専用 DES2WF キュー"]
    D --> E["Worker: 決定的 parse"]
    E --> F["任意のキット選択 + 文脈画像分類"]
    F --> G["census → apply_kit → 描画方針記録 → emit → score"]
    G --> H["S3 成果物 + DocumentDB wireframe/result + manifest"]
    H --> I["終端 Webhook → backend が PG 更新"]
    I --> J["Plugin: des2wf · 元の名前 を構築"]
    J --> K["元デザイン + 生成結果の PNG ペア"]
    K --> L["scope と状態を検証 → 同じ DES2WF キュー"]
    L --> M["Worker: 結果 scope 検証 → review → findings 更新"]

backend は投入前に共有 wf2des 行を edge=des2wf で作成します。送信先は専用 DES2WF キュー（SQS_DES2WF_QUEUE_URL）であり、WF2Des 生成キューではありません。生成と完了後レビューはこの DES2WF キューを共有し、レビューには kind=render_review を付けます。ワーカーは PostgreSQL に触れません。

公開 API の既定は mode=primitives、layout=absolute です。現在のプラグインは選択 UI なしで layout=auto を送信します。両 mode が画像分類を行い、kit だけがキット選択を追加します。 parse は決定的ですが、生成全体の再現性は保証しません。

フェーズ	処理	出力
行 + snapshot	要求ユーザーの PAT、参照マップを絞ったフレーム JSON、同一 version・absolute bounds の PNG を best-effort 取得	共有行、snapshot URL／hash、任意 `design_png_url`
Parse	元の identity、文言、layout、組版を抽出	解析済みツリーと `parse.json`
Assemble	任意のキット選択、出現箇所ごとの vision／override、census、ガード付き kit 適用、描画監査、出力、採点	spec、score、`graphic_classification`
Complete	終端 Webhook 前に成果物と出力／結果ドキュメントを保存	完了 PG 行と結果参照
Materialize	元の layout／text と同一ファイルの glyph を再現	キャンバスのフレーム。既定 `des2wf · {source_name}`
Render review	生成開始時の元ノードとプロジェクトへ固定。upload 前に完了ジョブを検証	scope 付き `render_review` を追加し、前回レビューを保持

3. 失敗とリトライ

条件	挙動
非 FRAME、空、snapshot 上限超過	型付き parse error
元 PNG の欠落／不正、model 障害、不正回答、分類時間切れ	対象図形を保持し、理由を記録して生成を継続
確認済みの装飾	クロス付き placeholder にせず非描画。必要な透明フロースロットは保持
キットが使えない、またはガードが variant を拒否	プリミティブを保持し、生成全体を失敗させない
kit variant が文言や独立描画の子孫を表現できない	その置換を適用しない
描画行の対応がない	lineage／postcondition の失敗。黙って削除しない。明示的 `ornament` 抑止は別途扱う
プリミティブでも表現できないノード	可視 `unmatched` と score gate 0
元 glyph の clone 失敗	実際の元 PNG を試す。元ノード欠落／別ファイルなら可視 fallback と診断
フォント代替や必要な再フロー	文言は保持。改行とジオメトリを確認し、ピクセル一致を前提にしない
job ID 不一致／未完了で review	upload／enqueue 前に backend が拒否：400／409
結果が別 tenant／project、または存在しない	画像／model 処理や結果変更より前に worker が拒否
review 画像が対応寸法を超過	`skipped`、理由、null の finding count を記録
review provider 障害	レビュー失敗であり、問題なしとも生成取消とも扱わない
キュー再配信／古い結果書き込み	job／attempt fence と終端冪等性を適用。再配信だけで新しい attempt を上書きしない
open-generation fence が有効	拒否または既存 run に接続。終端または明示的 cancel で解放

4. プリミティブのみの経路

primitives はキット不要の完全な出力語彙ですが、根拠があれば文脈による画像分類を使います。方向・操作・状態・識別・リストマーカー・不確かな図形は形を保ちます。ガードを通過した不要な画像だけをプレースホルダー化し、確認済みの装飾は ornament にします。明示的なスコープ付き override はストアを参照してください。

auto layout は元の階層、子が 1 つのラッパー、item spacing、軸ごとの sizing を保ち、実測した間隔から別のレイアウトを推論しません。プラグインはマスターへ戻すのではなく、実インスタンスの override を保ち、縦横比を維持して図形を中央に配置します。

1.0 は構造と文言の条件を検証するスコアであり、アイコン精度や背景の正しさを証明しません。 JSON のみの corpus は保守的 fallback と layout を検証します。分類品質は元画像と実 provider を使い、再生成したプラグイン出力を目視で確認します。