AI Code2WF — 概要

Code2WFは、完了したPage Import 1件を低忠実度のワイヤーフレーム仕様へ変換します。コードベースの実行とブラウザキャプチャはPage Importが担当します。Code2WFが受け取るソース指定は pageImportId のみで、リポジトリ、公開URL、HTML、CSS、実行可能なJavaScriptは受け取りません。

完了した仕様はFigmaプラグインがネイティブFigmaノードとしてマテリアライズします。プラグインが閉じている間に生成が完了した場合、行は検出可能なまま残り、対象ファイルで次にプラグインを開いたときにマテリアライズします。

MVPは次をサポートします。

Code2WFジョブごとに、インポート済みの1ルート、1つのquery/state、1 viewport
1つのFigmaファイルに1画面を生成
可視構造、文言、コントロール、メディアplaceholder、根拠に基づく注釈
既存WF2Des Figma-generation lifecycleと共通のstatus値
既存WF2Des規約に従う行レベルのplacement完了記録

MVPでは、ルートのクロール、ページグラフ、ナビゲーション/プロトタイプ接続、レスポンシブバリアント、または高忠実度デザインの再現は行いません。

技術スタック

レイヤー	技術
変換ランタイム	Python 3.12コンテナworker
Queue	backendが送信するCode2WF SQS queueとDLQ
入力	S3上の不変な完了済みPage Import result
出力	WF2Des envelope命名を使い、既存WF2Des `DesignSpecModel` を含むS3上の不変なresult artifact
プロダクト状態	backend所有のPostgreSQL `code2wf` 行
状態通知	`type: "code2wf"` を使う共通 `POST /v1/webhooks/ai-status`
Figma書き込み	認証済みFigmaプラグイン

責務境界

flowchart LR
  SRC["コードベースのページ"] --> PI["Page Import"]
  PI -->|"完了済み pageImportId"| API["Backend Code2WF API"]
  API --> Q["Code2WF queue"]
  Q --> W["Code2WF worker"]
  W --> SPEC["S3上のDesignSpecModelを含むresult artifact"]
  SPEC --> PL["Figmaプラグイン"]
  PL ==>|"ネイティブノード"| FIG["Figmaファイル"]
  PL -->|"placement"| API

Page Importの責務

リポジトリ/ランタイムの来歴と選択したページentry
route、query/state、viewport、build/start、JavaScript実行後のcapture
正規化した可視階層、geometry、semantics、screenshot、assets
import固有のライフサイクルと不変result

Code2WFの責務

同じorganization/project内の完了済みPage Importを検証
不変resultを上限付きのlow-fiノードツリーへ変換
通常のlayout/text nodeとしての決定的な根拠ベースの注釈生成
既存 DesignSpecModel をnestedに持つ不変なresult artifactの保存と完了通知
プラグインによるマテリアライズ用resultの公開

Figmaプラグインの責務

開いているFigmaファイルに対して、materializedAt がnullの完了済み行を検出
計画中のCode2WF plugin pathでstaging rootを構築し、既存WF2Desのswap-on-success pluginData contractを適用
生成画面の placedNodeId を送信
後続のプラグインsessionまたは明示的なユーザー操作で未完了マテリアライズを再試行

Code2WFにはサーバー側のマテリアライズ状態機械やretry schedulerはありません。

ライフサイクル

Code2WFはFigma generation rowで使用中の既存 wf2des_status 型を再利用します。MVPで使用するのは次のsubsetのみです。

`status`	意味
`"0"`	processing
`"1"`	completed
`"2"`	failed

MVPの attempt は常に 1 で、Code2WFに phase はありません。再生成する場合、clientが別のtriggerを送信し、backendが別のUUIDv7 jobを作成します。

生成完了とFigmaマテリアライズは分離されています。

clientが完了済み pageImportId とFigma destination fieldを送信します。
backendが code2wfId をUUIDv7で生成し、行をinsertし、Page Importの不変resultを解決してattempt 1 をdispatchします。
workerがWF2Desの job_id / status / generated_at 規約を使い、既存 DesignSpecModel を含むresult artifactを書き込み、completedまたはfailedを通知します。
pluginが完了済みかつ未マテリアライズの行を検出し、ネイティブノードを構築します。
placement endpointがWF2Desと同じ行レベル規約で materialized_at を記録します。

有効なtriggerごとに新しいrowとworker jobを作成します。Code2WFはcaller指定IDを受け付けず、同一trigger bodyをdeduplicateしません。

生成ルール

Page Importのfull document heightにわたって可視grouping、相対geometry、copy、control semanticsを保持し、共有auto-layout treeでrelationshipを表現できない場合は既存schemaの可視placeholderを使います。
ページ固有のpresentationはneutralなwireframe paletteとtypographyに置換します。
注釈は観測できるlink、form、control、ARIA state、capture warningからのみ作成し、captureされたcontrol labelを変更しないsibling marker付きの通常の layout_frame / text subtreeとしてrenderします。
隠れた画面や挙動を推測しません。
Annotation wordingは決定的に生成し、Code2WF専用のannotation modelやschemaは追加しません。
result保存前に、共有spec shape、既知node union、固定V1上限を検証します。

workerとresultの正確な契約はCode2WF I/O定義に記載します。

Figmaマテリアライズ

PluginはCode2WF discovery、result fetch、placement wiringを追加し、既存 DesignSpecModel をWF2Des planner/materializerへ渡します。このpathはprior outputに触れる前に新しいstaging rootをbuildし、root.setPluginData("wf2des", JSON.stringify({jobId, specVersion, role: "root"})) を保存し、document-root key wf2des_index に {[jobId]: rootId} を記録し、replacement成功後にのみprior rootを削除します。共有builderはすでに定義済みのtext fallbackとlayout sizing/wrap fieldのサポートを完了する必要があり、Code2WF専用fieldは追加しません。既存 placeRoot pathは placementTarget のcurrent-page rectangleを受け取り、targetを変更せずrootをそのrectangleのx/yに配置します。Targetが未指定、stale、またはother-pageなら既存のviewport-center fallbackを使います。Code2WFのdiscovery/API wiringとそれらの共有field optionはまだ存在しませんが、2つ目のnode schemaやrendererは不要です。MVPでは既存の wf2des · 1.0 root labelとplugin-data namespaceを維持します。

ネイティブ画面が完成した後、pluginは placedNodeId を指定してCode2WF placement endpointを呼びます。Backendは既存WF2Des placement規約に従い、完了済み行へ materialized_at を記録します。Timestamp設定後のplacement再送は既存timestampを返します。

Caught build failureではcurrent materializerがstaging treeを削除します。Ungracefulなplugin shutdownについてはintegration testが必要です。Placement成功まではPostgreSQLを変更しません。再オープン時、計画中のdiscovery flowはimmutable resultを取得して再buildし、既存swap-on-success pathがreplacement完了後にprior rootを置き換えるため、重複outputを意図的に残しません。