AI Des2WF — ストアと DB 定義
Des2WF は WF2Des とプラットフォームのストアを共有し、キット・結果・グラフィック override のデータを所有します。本ページは des2wf
スコープの契約であり、development/database/ 配下の正式なテーブル別ページは凍結された形状に従います。
所有権の規則は不変かつ譲れません。PostgreSQL は backend が所有し、ワーカーは書き込みません。 ワーカーは PG
クレデンシャルを持たず、すべての PG 効果は ai-status ハンドラまたはプロダクトエンドポイントが適用します。
PostgreSQL — 共有 wf2des generation 行
Des2WF は専用テーブルを持ちません。既存テーブルを拡張します。1 テーブルにすることで job id が両 edge を通じて一意に なり、それがプラグインの単一冪等性インデックスを構造的に安全に保つからです。
| カラム | 型 | 備考 |
|---|---|---|
edge |
enum | '0' wf2des、'1' des2wf、既定 '0'。名前は direction ではなく edge。direction はワーカーのスキーマで auto-layout の軸として既に使用済み。ディスパッチはこの値をタグ付き共用体として分岐し、どのオプションフィールドが埋まっているかでは分岐しない |
wf_node_id |
string | 入力ノード。wf2des ではワイヤーフレームのノード、des2wf ではデザインフレーム。カラムは 1 つで、隣の edge と併せて読む |
screen_id |
string | 共有行では NOT NULL であり、この edge では screen グラマーとの一致として読まれることがないため、des2wf の実行はソースノード id を格納する |
score, score_version |
numeric, text | ソート可能なスカラー + 式バージョン。flag_count と同じ役割。ワーカーが報告したときだけ書かれるので、スコアを報告しない wf2des の実行がソート可能なカラムで 0 と刻まれることはない。バンドは意図的に PG に置かず、ラチェットが読む結果ドキュメントに置く |
| その他のカラム | — | status / phase / attempt / 結果参照 / タイムスタンプ / 監査項目 — 両 edge で 1 つの形状 |
open-generation フェンス。 部分ユニークインデックスは
(project_id, figma_file_key, wf_node_id, edge) WHERE status = '0' であり、プロジェクト単位・ノード単位・edge
単位で同時に生きる実行は高々 1 つです。帰結は 2 つ。
edgeは鍵の一部なので、実行中の run が同じノードをブロックするのは 同じ edge に対してだけ です。 デザインフレームが des2wf を通っている間に、そのワイヤーフレームが wf2des を通ることは妨げられません;- フェンスに掃除の仕組みはありません。
status = '0'のまま取り残された行は、その実行がキャンセルされるまでノード鍵を 占有し続けます。des2wf のキャンセルは phase を問わず processing 中の実行を受け付けます — wf2des 自身のキャンセルは 確認チェックポイントを追加で要求しますが、ワンショットの edge はそこに到達しません。
DocumentDB
| コレクション | 共有 | Des2WF での用途 |
|---|---|---|
wireframe |
WF2Des と共有 | 出力。生成した WireframeDoc: based_on = 1（design）、type = 0（page）、memos = []、summaries を算出 |
wireframe_component |
des2wf 所有 | ワイヤーフレームキット。出力の構成部品。共有のコンポーネントスイープが wireframe ターゲットで書き込み、選択が実行時に読む |
design_component |
共有・WF2Des 所有 | ここでは読み取り専用。選択は、表現すべきデザインコンポーネントの名前・スロット・サイズ・軸を参照するだけで、書き戻しません |
project_figma_file |
共有 | ファイル単位の style キャプチャとスイープ基準点。スイープの走査範囲を定める |
des2wf_generation_result |
des2wf 所有 | 実行自身のドキュメント。_id は共有行の id。(_id, attempt) でフェンスされ、再配信された古い attempt が新しいものを上書きすることはない。レンダーレビューはこのドキュメントをその場で更新し、render_review ブロックをマージして、既存のものがあれば render_review_previous に残す。wf2des の結果コレクションとは別コレクション — 両 edge が答える形状が異なり（ワイヤーフレーム spec + score とデザイン spec + confidence）、1 つに同居させるとすべての読み手が edge で分岐することになるため |
des2wf_verdict |
des2wf 所有 | 明示的な人手 override：record_type=graphic_override_v1 を organization・project・file で限定。生成は旧 verdict を無視し、AI 判断を自動キャッシュしない |
明示的なグラフィック override
保存名は des2wf_verdict（設定：DES2WF_VERDICT_TABLE_NAME）のままです。
現在の実行が読むレコードは graphic_override_v1 であり、旧 metadata-only verdict スキーマではありません。
| フィールド | 契約 |
|---|---|
_id |
キーをソートした JSON [organization_id, project_id, file_key, target, identity, variants] の SHA256 に graphic: を付ける |
record_type |
graphic_override_v1 |
organization_id、project_id、file_key |
読み取りと運用者の変更に必要なスコープ。tenant／file をまたいで再利用しない |
target |
node または component |
identity |
元ノード ID、または実際のマスターコンポーネント ID の完全一致 |
variants |
コンポーネントの完全一致バリアント。既定 {} はワイルドカードではない |
action |
preserve または simplify |
reason |
1〜600 文字の必須説明 |
ノード指定がコンポーネント指定より優先され、重複が競合した場合は preserve を優先します。
コンポーネント指定は当該ファイルの一致する全出現箇所に適用されます。文脈固有の例外にはノード指定を使います。
明示的な simplify は ink プレースホルダー化であり、装飾の削除ではありません。
分類処理自身は override を書きません。
guinness-ai-v2 からワーカーと同じ DOCUMENTDB_* 環境で運用 CLI を実行します。
以下の set と clear は意図的な DB 書き込みです。対象スコープを置き換え、確認してから実行してください。
clear は指定したスコープの override だけを削除し、別バリアントや旧レコードには触れません。
uv run python apps/des2wf/scripts/graphic_override.py --org 1 --project 7 --file FIGMA_FILE_KEY list
uv run python apps/des2wf/scripts/graphic_override.py --org 1 --project 7 --file FIGMA_FILE_KEY set --node '123:456' --action preserve --reason 'Navigation meaning'
uv run python apps/des2wf/scripts/graphic_override.py --org 1 --project 7 --file FIGMA_FILE_KEY set --component '123:400' --variants '{"State":"Default"}' --action simplify --reason 'Redundant artwork beside its label'
uv run python apps/des2wf/scripts/graphic_override.py --org 1 --project 7 --file FIGMA_FILE_KEY clear --node '123:456'
旧 verdict.py／propose_verdicts.py のレコードは生成で使いません。
override の読み取り失敗時も best-effort で処理し、旧判定を復活させません。
結果の graphic_classification は、この人手ルールとは別に出現箇所ごとの根拠と判断を保存します。
元図形が実際に置換されたかは、提案だけでなくキット適用後の rendered_kind／covered_by も確認します。
I/O 定義 を参照してください。
wireframe_component を別コレクションにする理由
WF コンポーネントライブラリはデザインシステムとは 別のライブラリ であり、その部分集合ではないため、design レジストリには属しません。さらに機構上の理由が 2 つあります。
- WF2Des の候補生成はすべてのセクションに レジストリ全体 を渡し、kind ゲートは設定既定で off です。 このコレクションに第 2 の語彙を入れると、WF2Des の挙動がすべての読み出し箇所でフィルタが正しいことに依存します。 しかも WF2Des は 2 方向のうち弱い側です。
- その方向への混入はプラグインのコード自身が既に観測し、自己強化的な破損と呼んでいます。別コレクションにすれば、 フィルタで防ぐのではなく、そもそも起こり得なくなります。
スイープは 1 つで両方のライブラリを扱います。異なる 3 つの事実 — コレクション、identity 規則（キットは
{project_id}_{component_key}、デザインシステムは node 複合 id）、そして意味付け（enrichment）パスを適用するか —
を束ねたレジストリターゲットでパラメータ化されているからです。キットには enrichment を適用しません: キットのアトムは
既に自身の形状で名付けられており、デザインの語彙を被せればキットが主張していない意味を捏造することになります。
レジストリの 読み出し は design アクセサに束縛されたままなので、読みがキット側へ漂い、キットのアトムが design の
候補になることはありません。
wireframe_component — フィールド
ドキュメントの形状はスイープのものであり、design_component と共通です。選択がそこから読むもの:
| フィールド | 目的 |
|---|---|
_id |
{project_id}_{component_key} — componentSet の publish key による複合 id。node id は不可（ファイル複製ごとに変わる）、名前も不可（実測の衝突が使用実績でインスタンスの 56% を覆う）。publish key をまだ持たないマスターは未登録にせず node 複合 id にフォールバックする。セットのすべてのバリアントで共有される ため、選択が投票する対象ではない |
name |
表示専用。明示的に identity ではない |
family |
そのエントリがスイープされた元のボード — キット自身のグルーピング。互換的なスタンドインをまとめるために使い、デザイン側のレイヤー名と突き合わせることはない |
component_key, component_node_id |
プラグインがマスターに到達する手段。キットのページは作業ファイル 内へ コピーされるためマスターはローカルであり、importComponentByKeyAsync には取り込む対象が無く、node id だけがインスタンス化の手段になる。どちらも持たないエントリは読み込み時に unreachable として落とす |
variant_properties, variant_defaults |
セットの軸と、各軸が既定で取る値。セットが列挙していないバリアント値はモデルから受け取らない — materialize 時に Figma が拒否するため |
variants |
バリアントごとの variant_props / size / text_slots / nested_components — 選択対象となる行 |
text_slots, default_size |
セット自身のもの。variants を持たないドキュメントのときだけ読む |
lineage |
ソースファイル、ハッシュ、processor version、index_schema_version — どのキット（のどの版）由来かを識別する: キットはデザイナーが選び変わるものなので、入れ替えは再登録であり、stale なエントリと現行のエントリを区別できなければならない |
選択の単位はコンポーネントではなくバリアントです。 コンポーネント セット はインスタンス化できず、できるのは
その中のバリアント 1 つです。したがって選択は各ドキュメントを variants の要素ごとに 1 行へ展開し（variants を
持たないドキュメントのときだけトップレベルへフォールバックします）、その行に固有の鍵で投票し解決します。_id で
鍵付けすると、ショートリストに載ったバリアントとは無関係な兄弟をガードに渡すことになり、しかも測っている対象自体が
違います。トップレベルが述べるのは既定バリアントのスロットとサイズであり、レジストリ 415 ドキュメントのうち 44 は
トップレベルより 多い テキストスロットを持つバリアントを含みます。
スロット容量は、異なるスロットレイヤーパスの数です。 マテリアライザはスロットをパスで指定して書き込むため、 同じパスを宣言する 2 つのスロットは 1 つの宛先 です。2 つ目の書き込みが 1 つ目を上書きし、そのデザイン文字列は 失われます。ガードは宣言数ではなくパス数を数えます: 実キットでは 52 のバリアントが重複したパスを宣言し、うち 1 つは 5 つのスロットがすべて同じレイヤーを指しています。
キットのページは作業ファイル内へコピーされるため、マスターはローカルです — wf2des 側でデザインシステムが 取る設置と同じです。セットアップ画面は登録済みのキットを要約として読み戻します: node id を持つエントリ数 （無ければそもそもインスタンス化できません）、publish key を持つ数、そして variant 軸とテキストスロットを 宣言する数です。
wireframe コレクション — 2 つの危険
_id衝突 — 構造上不可能。 Des2WF は edge スコープ付きの{project_id}_{figma_file_key}_{node_id}~des2wfを書き、wf_parseは既存の非スコープ id を使い続けます。 両エッジ間の黙った last-write-wins 上書きは構造上不可能になり、wf2des の parse キャッシュ参照は無変更です。based_onは書かれるだけで読まれない。 出力はbased_on = 1（design）を持ち、これが機械生成の ワイヤーフレームとデザイナーが描いたものを区別する唯一の印です。消費側にそれを拒む仕組みは無く、des2wf の ワイヤーフレームはデザイナー作であるかのように WF2Des へ渡り得ます。止められるのは、このフィールドを見る 消費側のチェックだけです。
キットの可変性
キットはプロジェクト単位のデータであり、変わります。ストア水準の規則が 2 つ従います:
- 選択は事前計算した表ではなくレジストリを実行時に読むので、キットの入れ替えは次の実行から効く。現在登録されて いるキットに存在しないエントリは実行が読み込むアトムに単に含まれず、それが表現していたコンポーネントは改めて 決め直される;
- キット固有の内容をコードやスキーマ既定値に決して埋め込まない。キットの入れ替えは
wireframe_componentの データ変更だけで表現できなければならない。
S3
| パス | 内容 |
|---|---|
{org}/{proj}/des2wf/snapshots/{file}/{node}.{source_hash}.json |
フレームのみの REST envelope。参照された components／componentSets／styles を保持 |
{org}/{proj}/des2wf/snapshots/{file}/{node}.{source_hash}.{render_hash}.png |
同じ Figma version・absolute bounds の任意の不変元画像。生成の design_png_url |
{org}/{proj}/des2wf/{job_id}/parse.json |
実行で使う解析済みツリー |
{org}/{proj}/des2wf/{job_id}/result.json |
spec、score フィールド、graphic_classification 監査 |
{org}/{proj}/des2wf/{job_id}/manifest.json |
Webhook が参照する成果物一覧と row_effects.wf2des |
{org}/{proj}/des2wf/renders/{job_id}/design.png |
完了後レビュー用にプラグインが送るデザイン画像 |
{org}/{proj}/des2wf/renders/{job_id}/wireframe.png |
同レビュー用にプラグインが送る生成ワイヤーフレーム画像 |
元画像の根拠キーには content hash を含みます。レビュー用ペアはジョブ単位のパスであり、
不変の content-addressed key ではなく、再レビューで置き換わり得ます。2 つの画像ライフサイクルを混同しないでください。
元画像の export／upload が失敗したら、存在しないオブジェクトを指さず design_png_url を省略します。
ワーカーは元 PNG の取得サイズを 20 MiB、デコード後を 32,000,000 ピクセルに制限し、失敗時は図形を保持します。
snapshot のマップは identity 契約の一部です。publish key と名前付き style identity は、破棄すると復元できません。