Project Figma File コレクション

概要

プロジェクト ↔ Figma ファイルの帳簿管理のためのコレクション（PostgreSQL から移設 — AI 所有）。プラグインのファイル登録が wf2des-api を通じて role／config_url を書き込み、component_sweep が同期フィールド（components_synced_at／sweep_error）を書き込み、style_captures を捕捉し、single-flight の sweep_marker を保持する。assemble フェーズは style_captures（派生スペック style_bindings の出所）と config_url（DESIGN 領域の矩形）を読み取る。

テーブル定義

論理名	物理名	カラム名	データ型	主キー	リレーション	ユニーク	NULL許可	デフォルト値	備考
Project Figma File	project_figma_file	_id	string	◯					DocumentDB の _id に格納する uuid。プロジェクト ↔ Figma ファイルの帳簿管理（PG から移設 — AI 所有）
		organization_id	number		organization:id				テナント所有者。UNIQUE (organization_id, project_id, figma_file_key) の一部
		project_id	number		project:id				プロジェクトスコープ。UNIQUE (organization_id, project_id, figma_file_key) の一部
		figma_file_key	string						Figma ファイルキー（原文ママ。英数字、アンダースコアなし）。UNIQUE (organization_id, project_id, figma_file_key) の一部
		role	number						ファイルの役割 — プラグインのファイル登録が wf2des-api を通じてこれを書き込む。 0: working（生成出力ファイル） 1: library（コンポーネント／ルールの出所）
		components_synced_at	datetime						最後に成功した component_sweep — 鮮度のウォーターマークであり、sweep 完了後に最後に更新される
		config_url	string						プロジェクトごとの取り込み config.json の S3 キー（WF／DESIGN 領域パターン、memo マーカー）。ホーム {org}/{proj}/wf2des/config.json。assemble フェーズはそこから DESIGN 領域の矩形を解決する
		sweep_error	string			◯			最新の component_sweep の失敗。なければ null
		style_captures	object						{ <token>: string } — ファイルレベルのローカルテキストスタイル ＋ カラー変数。figma_file_key ごとに 1 つ。各 token は Figma のスタイル／変数 id に写像される。派生スペックの style_bindings マップはこれから生成される
		sweep_marker	object			◯			{ token: string, acquired_at: datetime, expires_at: datetime } — component_sweep の single-flight ロック（クラッシュ耐性あり、失効ロックの回復付き。expires_at を過ぎたロックは再取得可能）。sweep が実行中でないときは NULL
		index_schema_version	number						ドキュメントスキーマのバージョン（スキーマガバナンスの同等性）
		created_at	datetime						作成タイムスタンプ
		updated_at	datetime						最終更新タイムスタンプ

リレーション

• organization_id → organization.id
• project_id → project.id
• figma_file_key — Figma ファイルキー。このファイルから sweep されたコンポーネントの design（type=component）行および design_component ドキュメントに結合する。
• DocumentDB 内ではリレーションは強制されない。論理リレーションであり、アプリケーションコードで検証する。

インデックス

• PRIMARY KEY (_id)
• UNIQUE (organization_id, project_id, figma_file_key) — プロジェクトファイルごとに 1 件の帳簿ドキュメント
• role 上のセカンダリインデックス (organization_id, project_id, role) — component_sweep は走査をプロジェクトの登録済みファイル（working ＋ library の役割）にスコープする

Type Codes

role

• 0: working（生成出力ファイル）
• 1: library（コンポーネント／ルールの出所）

注記

• 互いに素な 2 つの書き込み者、競合なし。プラグインのファイル登録は wf2des-api を通じて role／config_url を書き込み、component_sweep は components_synced_at、sweep_error、style_captures、sweep_marker を直接書き込む。書き込みはフィールド単位で、決して重ならない。
• sweep_marker は component_sweep の single-flight ガードである — sweep の開始時に取得され、終了時に解放／失効する。expires_at を過ぎたマーカーは再取得可能（クラッシュ耐性のある失効ロック回復）。
• components_synced_at は sweep 完了後にのみ最後に更新されるため、他に台帳を持たない内部実行に対する実行鮮度シグナルも兼ねる。
• style_captures は assemble フェーズ中に生成される派生スペック style_bindings マップの唯一の出所である。figma_file_key ごとに捕捉セットがちょうど 1 つになるよう、design_component からここへ移設された。
• config_url はプロジェクトごとの config.json を指す。assemble ワーカーはこれを読み取って design_generation_result.placement.design_area を解決する（プラグインはプロジェクト設定を直接読み取らない）。
• 監査カラムは created_at／updated_at のみ — 論理削除はなし（deleted_at なし）。コンポーネントの削除はここではなくプラットフォームの design 行のステータスに記録される。
• このコレクションは他の 5 つの wf2des コレクションが持つ共通の lineage エンベロープを意図的に省く: 互いに素な 2 つの書き込み者を持ち、単一の生成元実行がないため、出所は実行スコープのエンベロープではなくフィールド単位（components_synced_at／sweep_error）＋ index_schema_version となる。