AI Page Import — I/O 定義

SQS input

{
  "page_import_id": "019ffa75-01c0-75a2-8123-456789abcdf0",
  "attempt": 1,
  "nonce": "transport-fence",
  "organization_id": 1,
  "project_id": 7,
  "source_url": "https://example.com/",
  "viewport": { "width": 1440, "height": 900, "device_scale_factor": 1 },
  "ready_selector": null
}

Unknown field は拒否します。Tenant ID は正数、attempt は 1、source URL は HTTP(S)、viewport は width／height 240..7680、device scale factor 0.5..4、ready_selector は null または最大 512 文字です。Backend は nonce を保存し、row と一致する callback のみを受理します。

アップロード済みページは source_kind: "codebase_route"、source_manifest_url、source_manifest_hash を指定します。URL はローカル描画ページの識別用で、ワーカーは取得しません。static のみ対応します。公開 URL は source_kind: "public_url" とし、マニフェスト項目を省略します。

スクリプトはバックエンドが認可した PUT URL で S3 に直接アップロードし、その後 Page Import を作成します。キューは参照のみを保持します。マニフェストは s3://{result_bucket}/{organization_id}/{project_id}/page-import/{page_import_id}/source/manifest.json に配置し、SHA-256、組織・プロジェクト・ジョブ ID、URL、viewport がキューと一致する必要があります。

マニフェストは source_bundle_version: "1.0"、captured_at、source、viewport、evidence、screenshot、assets を含みます。オブジェクト参照は key、hash、content_type、byte_length を持ち、画像には source_url も必要です。キーは source/objects/{sha256}.{ext} とし、実バイト長とハッシュを検証します。

evidence は application/vnd.guinness.page-evidence+json、evidence_version: "1.0" とし、document、nodes、font_faces、warnings、切り詰めフラグを含みます。スクリーンショットは PNG です。マニフェストは最大 2 MB、evidence とスクリーンショットは各 20 MB、画像は各 3 MB（設定値がより小さい場合はその値）です。画像数と合計バイト数にも設定上限を適用します。動画は受け付けず、公開 URL 取得でも動画と超過画像をスキップします。

Capture output

Worker は次の prefix に保存します。

{organization_id}/{project_id}/page-import/{page_import_id}/

Key	Content
`screenshot.png`	Full-page PNG
`assets/{sha256}.{ext}`	Immutable image／SVG-derived asset
`capture.json`	source/final URL、viewport、document bounds、ordered node、asset、screenshot、warning
`result.json`	Capture／screenshot を指す success summary
`manifest.json`	成功した backend row effect
`failed.json` / `failed-manifest.json`	安全な terminal failure artifact／effect

JSON は sorted key と compact separator で serialize します。Immutable write は同じ bytes の既存 object を許可し、異なる bytes の競合を拒否します。capture_hash は capture.json の正確な bytes の SHA-256 です。

Captured node evidence

Node は stable ID／parent ID、kind／tag／name／role／text、安全な attribute、document-relative bounds、選択した computed style、任意の asset hash／inline SVG、paint order を持ちます。Collector は hidden／zero-size node を除外し、node limit を超えると node_limit_reached warning を出します。

Image は S3 に copy します。Figma が正しく import できない SVG は browser 内で rasterize し、対応可能な inline SVG は vector evidence として維持します。CSS image saturation／grayscale は native Figma image filter 用に正規化します。

Terminal webhook

Webhook は type: "page_import"、job ID、attempt、nonce、succeeded／failed、manifest URL、schema version を送ります。Manifest の row_effects.page_import は成功時 status "1" と capture pointer、失敗時 status "2" と failure pointer を持ちます。

Backend は bucket、tenant/job prefix、job ID、attempt、nonce、row effect を検証します。PostgreSQL compare-and-set は一度だけ成功し、duplicate callback は idempotent です。この callback は Code2Des を作成も dispatch もしません。

Database boundary

Worker は PostgreSQL／DocumentDB credential を持ちません。PostgreSQL は lifecycle と capture pointer、S3 は詳細 capture を保存し、database write は backend のみが行います。