コンテンツにスキップ

Design Generation Result コレクション

概要

主たる生成出力コレクション — wf2des の生成実行 1 件につき 1 ドキュメントで、固定された入力、確定済みの parse、組み立て済みの DesignSpec、バリデータ／確信度の記録、そしてプラグインの placement ＋ feedback の帳簿を保持する。wf2des ワーカーが parse フェーズと assemble フェーズにまたがって書き込む（(_id, attempt) でフェンス）。wf2des-api はプレビュー、レビュー、マテリアライズのためにこれを読み取る。決してドロップされない。

テーブル定義

論理名 物理名 カラム名 データ型 主キー リレーション ユニーク NULL許可 デフォルト値 備考
Design Generation Result design_generation_result _id string ◯ wf2des:id wf2des の PG 行 id（実行の同一性 — 生成 1 件につき結果ドキュメント 1 つ、wf2des 行と 1:1。(_id, attempt) の CAS 書き込みフェンス）。主コレクションであり、決してドロップされない
organization_id number テナント所有者。すべての読み書きがこれでフィルタする
project_id number project:id テナントスコープ。すべての読み書きがこれでフィルタする
attempt number 実行 attempt — 書き込みフェンス（(_id, attempt) の CAS）がこれを比較して取って代わられた書き込みを拒否する。現在は常に 1 — これを増加させるものはない
screen_id string ◯ 生成リクエスト由来（例: AC_RGST01）。生成行は常にこれを持つ
request object SQS メッセージから引き写したリクエストのスナップショット。形状: { screen_id: string, prompt: string \| null, placement_target: string \| null, auto_confirm: boolean }
request.screen_id string リクエストされた画面 id
request.prompt string ◯ 任意の選択プロンプト。memo intent より下位にランク付け
request.placement_target string ◯ placement 用に引き写された任意のノード id
request.auto_confirm boolean false normal／true auto → parse と assemble を 1 回の呼び出しで実行
inputs object 固定された生成入力（parse 呼び出しの最初の行為。assemble 時のいかなるハッシュ不一致でも fail-closed で再水和される）。components = 選択元となった正確なセットであり、生成はどのコンポーネントが使われたかを再現する（レジストリハッシュだけではない）。形状: { wireframe {figma_file_key, node_id, source_hash}, design_rule {design_rule_id, content_hash}, components [{platform_design_id, content_hash}], llm {model_id, prompt_version, screen_review_model_id, screen_review_reasoning_effort, screen_review_enabled} }
inputs.wireframe object { figma_file_key, node_id, source_hash } — 固定されたワイヤーフレームの同一性。source_hash ≡ parse キャッシュキー wf_content_hash かつ lineage.source_hash
inputs.design_rule object ◯ { design_rule_id, content_hash } — 固定されたバリデータプログラムのリビジョン（design_rule ドキュメントキー）
inputs.components object[] [{ platform_design_id, content_hash }] — フラット。選択元となった正確なレジストリコンポーネントセット（レジストリハッシュなし）。platform_design_id = design（type=component）行 id／design_component._id
inputs.llm object { model_id, prompt_version, screen_review_model_id, screen_review_reasoning_effort, screen_review_enabled } — 固定されたモデル ＋ プロンプトバージョン（例: mp@0.4）と screen review 設定。retry で provider/model behavior が変わらないよう matching/review config を pin
parse object 確定済みの parse 記録。完全な parse ツリーは不変の parse.json アーティファクト（S3、artifact_urls.parse）に置かれる — このブロックは確認 ＋ スナップショットされた memo の影響のみを保持する。形状: { confirmed: boolean, confirmed_by: string \| null, confirmed_at: datetime \| null, rejected: {reason_code, note} \| null, memo_influences: [{memo_node_id, text}] }
parse.confirmed boolean デザイナーが確認するまで対話的に false
parse.confirmed_by string ◯ 確認したユーザー（user:cognito_sub）。確認まで null
parse.confirmed_at datetime ◯ 確認タイムスタンプの唯一の置き場。確認まで null
parse.rejected object ◯ 却下時に記録される { reason_code, note }（行ステータス 3）。キュレーションに供給される。reason_code: wrong_roles／wrong_memos／wrong_sections／other。却下されない限り null
parse.memo_influences object[] [{ memo_node_id, text }] — memo の text をスナップショットし、後のワイヤーフレーム再パースを生き延びられるようにする
spec object DesignSpec — 組み立て済みで自己完結したスペック。root は 5 つのノード型（layout_frame／instance／compose／text／unmatched）からなる SpecNode ツリー。約 1MB を超えるスペックは S3 ポインタ（artifact_urls.spec）へ退避する。形状: { spec_version, parse_confirmed, style_bindings {<token>: string}, root: SpecNode }
spec.spec_version string スペックスキーマのバージョン
spec.parse_confirmed boolean parse 確認のミラー
spec.style_bindings object { <token>: styleId } — token → Figma のスタイル／変数 id。project_figma_file.style_captures から派生
spec.root object SpecNode ツリーのルート。layout_frame { auto_layout, children }。instance { component_key, component_node_id, component_name, variant_props, text_slots, assets, confidence, flagged, source{kind:registry, component_key}, lineage_wf_node_ids }（platform_design_id は spec_nodes_flat ではなくここの instance ノードに置かれる）。compose { primitives + small components composed under rules; ALWAYS flagged; source{kind:composed}, lineage_wf_node_ids }。text { content, style_token, confidence, flagged, lineage_wf_node_ids }。unmatched { placeholder{role,text,bbox}, confidence, flagged:true, source{kind:none}, lineage_wf_node_ids }
spec_nodes_flat object[] チューニング／フラグクエリ用の、コンテンツノード単位のフラット化ビュー。要素: { layer_path: string, case: string, component_key: string, wf_role: string, confidence: number, flagged: boolean, lineage_wf_node_ids: [string] }。case: instance／compose／text／unmatched。platform_design_id は含まない（それは spec.root の instance ノードに留まる）。spec が退避してもここはインラインに留まる
selection object セクション単位の選択記録（決定論的フィルタ ＋ セクション並列の LLM 選択。類似／検索なし）。形状: { sections, candidates_considered, composed_count, unmatched_count, asset_fills, truncated }
selection.sections number セクション数
selection.candidates_considered number 全セクションで検討された候補数
selection.composed_count number compose ケースのノード数
selection.unmatched_count number unmatched ケースのプレースホルダー数
selection.asset_fills number 固定されたアセットセットから埋められた画像スロット数
selection.truncated boolean 候補セットの切り詰めフラグ
screen_plan object ◯ replay 用に保持する grounded whole-screen review と accepted/rejected proposal
spec_hash string ◯ base spec の canonical SHA-256。plugin render review identity fence
assembly_state_hash string ◯ artifact_urls.assembly に保存した pin 済み stitch/validation state の hash
layout_fidelity object ◯ layout preservation metric: {frames_total, frames_preserved, wrap_total, wrap_preserved, units_collapsed, lost[]}
validator_report object ルールバリデータの結果（違反は安全な範囲で自動修正、さもなければフラグ付け）。status: ok／no_rules — no_rules は登録済みルールドキュメントがないことを意味し、バリデータは no-op となりすべてのノードが rules_unvalidated とフラグ付けされる。形状: { status, violations: [{rule, layer_path, action, detail}], unfixed_flagged }
validator_report.status string ok／no_rules
validator_report.violations object[] [{ rule, layer_path, action, detail }]。action: auto_fixed／flagged
validator_report.unfixed_flagged number フラグ付けのまま残された（自動修正されなかった）違反の数
confidence object 計算された確信度のみ（モデルの自己申告は禁止）。flag_count は完了 webhook を通じて wf2des 行に到達する。形状: { min, avg, flag_count, formula_version }
confidence.min number ノード確信度の最小値
confidence.avg number ノード確信度の平均値
confidence.flag_count number フラグ付けされたノード数。マニフェストの row_effects.wf2des を通じて wf2des.flag_count にミラーされる
confidence.formula_version string 確信度計算式のバージョン（例: cf@0.2）
placement object plugin build record。形状: { design_area, placed_node_id, materialized_at, revision, spec_hash, review_id, materializer_report }。design_area は worker、残りは plugin が fingerprint fence 付きで書く
placement.design_area object { x, y, w, h } — 解決された DESIGN 領域の矩形（ワーカー書き込み）
placement.placed_node_id string ◯ マテリアライズされたノード id（プラグイン書き込み）
placement.materialized_at datetime ◯ マテリアライズタイムスタンプ（プラグイン書き込み）
placement.materializer_report object[] ◯ [{ layer_path, event, detail }]。event: name_fallback / ordinal_fallback / build_error / font_fallback / prop_rejected / unmatched / preserved
feedback object ◯ feedback の帳簿のみ — 進捗／品質追跡用の changed_nodes ＋ diff。学習ループはない。status はバックエンドの feedback エンドポイントによって wf2des.feedback_status に記録される。形状: { status, changed_nodes: [string], diff_url, at, by }
feedback.status string fixed／adopted
feedback.changed_nodes string[] 変更されたレイヤーパス
feedback.diff_url string feedback diff の S3 キー（≡ artifact_urls.feedback_diff）
feedback.at datetime feedback タイムスタンプ
feedback.by string feedback の作成者（user:cognito_sub）
llm_usage object この実行のコスト（プロバイダ自身の報告値）: { calls, requests, input_tokens, output_tokens, cached_input_tokens, stages: [{stage, calls, requests, input_tokens, output_tokens, cached_input_tokens}] } — ステージ別、入力トークンの多い順。高コストな呼び出しを担う assemble フェーズが書き込む。parse のみのドキュメントは空のデフォルトを持つ
timings object 実行ライフサイクルのタイムスタンプ + フェーズごとの所要時間。形状: { created_at, parse_done_at, assembled_at, <phase>_ms } — created_at は実行開始のアンカー（lineage.processed_at、終端書き込み時刻とは別物）。parse が created_at／parse_done_at を、assemble が assembled_at を刻む。<phase>_ms はフェーズごとのレイテンシ（例: snapshot_ms、parse_ms、selection_ms、assemble_ms、validate_ms）
artifact_urls object immutable artifact S3 key。形状: { result, assembly, spec, parse, feedback_diff }。assembly は bounded rendered-output review 用の hash-pinned stitch input
artifact_urls.assembly string ◯ canonical hash が assembly_state_hash の pin 済み assembly-state artifact
artifact_urls.result string ◯ クライアント向け結果アーティファクトのキー（{org}/{proj}/wf2des/{id}-{ts}-result.json）
artifact_urls.spec string ◯ スペック退避のキー。spec > ~1MB のときのみ存在する
artifact_urls.parse string ◯ 不変の parse.json キー — ある実行が使用した権威ある parse
artifact_urls.feedback_diff string ◯ feedback diff のキー
lineage object 全ドキュメント共通の lineage ブロック（ソース S3 キー／ハッシュ、プロセッサバージョン、処理時刻）。job_id = 生成元の実行 id: 生成実行では wf2des 行 id、内部実行ではジョブドキュメントの _id。形状: { source_url, source_hash, processor_version, index_schema_version, processed_at, job_id }
lineage.source_url string ソーススナップショットの S3 キー
lineage.source_hash string ソースコンテンツハッシュ（≡ inputs.wireframe.source_hash）
lineage.processor_version string 生成元のプロセッサバージョン（例: wf-parse@1.0）
lineage.index_schema_version number このコレクションのドキュメントスキーマバージョン
lineage.processed_at datetime 終端書き込みタイムスタンプ（timings.created_at、実行開始のアンカーとは別物）
lineage.job_id string 生成元の実行 id

リレーション

  • _id = wf2des の PostgreSQL wf2des 行 id — 行と 1:1（行が先に作成され、ドキュメントは実行が書き込む）。
  • project_id → project.id。organization_id → テナント所有者。
  • inputs.components[].platform_design_id → プラットフォームの design（type=component）行 id／design_component._id。
  • inputs.design_rule.design_rule_id → design_rule ドキュメントのビジネスキー（content_hash と併せて）。
  • inputs.wireframe.{figma_file_key, node_id} は wireframe キャッシュドキュメント（複合 _id = {project_id}_{figma_file_key}_{node_id}）を特定する。
  • parse.confirmed_by と feedback.by は Cognito sub（user:cognito_sub）であり、値で格納される。
  • DocumentDB 内ではリレーションは強制されない。論理リレーションであり、アプリケーションコードで検証する。

インデックス

  • PRIMARY KEY (_id) — ユニーク。_id そのものが wf2des 行 id（代理キーなし）。
  • 書き込みフェンスは (_id, attempt) の CAS — ゾンビ／取って代わられた attempt の書き込みは拒否される（DB のユニークインデックスではなく、ワーカーの条件付き書き込みで強制される）。
  • セカンダリインデックスは定義しない。spec_nodes_flat と confidence.flag_count がフラグ／チューニングのクエリフィールドだが、実行ごとに 1 ドキュメントというモデル内でスキャンされ、ドキュメント横断でインデックスされない。

注記

  • 生成ワーカーが 2 フェーズにまたがって書き込む: parse は inputs ＋ parse（＋ artifact_urls.parse、timings、lineage）を書き込み、assemble は spec／spec_nodes_flat／selection／validator_report／confidence／placement.design_area（＋ artifact_urls.result、スペック退避）を書き込む。すべての書き込みは (_id, attempt) でフェンスされる。
  • プレビュー、memo レビュー、マテリアライズのため wf2des-api 経由で読み取られる。プレビュー／レビューの面はこのドキュメント ＋ 不変の parse.json アーティファクトを読み取り、上書き可能な wireframe キャッシュドキュメントは決して読まない。
  • ワーカーは決して PostgreSQL を書き込まない。confidence.flag_count、完了ステータス、結果参照は、S3 の結果マニフェストから供給される ai-status webhook ハンドラ（完了時点の唯一の PG 書き込み者）を通じてのみ wf2des 行に到達する。
  • parse.confirmed_at は確認タイムスタンプの唯一の置き場である（timings に重複させない）。parse.memo_influences[].text はスナップショットされ、後のワイヤーフレーム再パースを生き延びる。
  • placement.placed_node_id／materialized_at／materializer_report と feedback ブロックは、生成ワーカーではなく後にプラグイン経路が wf2des-api を通じて書き込む。
  • 完了した生成は決して再処理されない — 全置換は主たる人間イベントのデータを別の非決定論的スペックで上書きしてしまう。終端の行は最終であり、ワイヤーフレームを再実行すると新しい行が作成される。
  • 約 1MB を超える spec は artifact_urls.spec へ退避する。spec_nodes_flat と要約ブロックはインラインに留まる。これがこのドキュメントに適用される唯一のバイト上限である。