マッチドコード取得

メソッド

RESTメソッドを採用しています。

HTTPメソッド

GET: コードDes2Code結果取得

命名規則

クエリパラメータとノードの命名を統一し、可読性を向上させるため、リクエスト時のURIとJSON内のノードにはsnake_caseを使用します。

リクエストとレスポンス

ヘッダー

メタ情報はレスポンスボディではなく、HTTPヘッダーに設定されます。

リクエストヘッダー

Authorization (一時Bearerトークン)
Content-Type
Accept
Accept-language

レスポンスヘッダー

Content-Type

コードDes2Code結果取得

URI

GET /v1/des2code/{design_id}

パスパラメータ

名前	型	必須	説明
design_id	string	必須	デザインID（形式: `{project_id}_{file_id}_{node_id}`）

レスポンス

レスポンスはJSONです。

{
  "designId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "matchedCodeCount": 2,
  "matchedCodes": [
    {
      "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
      "name": "Button Primary",
      "semanticValue": ["button", "primary", "cta"],
      "similarity": 0.92,
      "visualSimilarity": 0.95,
      "semanticSimilarity": 0.89,
      "sourceCode": "export function ButtonPrimary() { ... }",
      "cssCode": ".buttonPrimary { ... }"
    },
    {
      "codeId": "1192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6c",
      "name": "Primary Button",
      "semanticValue": ["button", "submit"],
      "similarity": 0.87,
      "visualSimilarity": 0.82,
      "semanticSimilarity": 0.91,
      "sourceCode": "export function PrimaryButton() { ... }",
      "cssCode": ".primaryButton { ... }"
    }
  ],
  "artifact": {
    "bucket": "dev-guinness-backend",
    "key": "1/42/des2code/42_hDDA9BNori9OTXSClduXqR_40002029%3A37033-20260628T000000000000Z-result.json",
    "contentType": "application/json",
    "expiresAt": "2026-07-28T00:00:00Z"
  },
  "status": "success",
  "processedAt": 1234567890000
}

マッチステータス

ステータス	説明
pending	Des2Codeリクエストはキューに入っているがまだ処理されていません
processing	Des2Code処理中
success	Des2Codeが正常に完了
failed	Des2Codeが失敗（エラーメッセージを確認）

レスポンスフィールド

名前	型	説明
designId	string	デザインID
matchedCodeCount	number	matched code 件数
matchedCodes	array	マッチしたコードの配列
matchedCodes[].codeId	string	マッチしたコードID
matchedCodes[].name	string	マッチしたコード名
matchedCodes[].semanticValue	string[]	matched code semantic words
matchedCodes[].similarity	number	weighted raw score
matchedCodes[].visualSimilarity	number \| null	raw visual similarity score
matchedCodes[].semanticSimilarity	number \| null	raw semantic similarity score
matchedCodes[].sourceCode	string \| null	assistant context 用の matched code source code
matchedCodes[].cssCode	string \| null	assistant context 用の matched code CSS
artifact	object \| null	latest S3 result artifact reference
status	string	Des2Codeステータス
processedAt	number	処理タイムスタンプ（エポックミリ秒）

認証

このエンドポイントは一時Bearerトークンを使用します（標準JWTではありません）。

Authorization: Bearer <temporary_token>

例外処理

例外処理のステータスコードは以下の通りです。

説明	ステータスコード	ステータス名
一時トークンがないか無効	401	Unauthorized
デザインが見つからないかDes2Code結果が利用できません	404	Not Found
内部サーバーエラー	500	Internal Server Error

処理フロー

パスパラメータからデザインIDを抽出
AI status webhook が書き込んだ PostgreSQL の latest Des2Code result/status と artifact reference を取得
similarity score と latest S3 artifact reference を含む Des2Code 結果を返却

詳細フローチャート

flowchart TD
    Start([GET リクエスト]) --> Auth[認証・パラメータ取得]
    Auth --> Service[Service Layer]
    Service --> AccessCheck[権限チェック]
    AccessCheck --> HasAccess{Read権限?}
    HasAccess -->|なし| Err404[404 Not Found]
    HasAccess -->|あり| QueryDB[Repository Layer]
    QueryDB --> FindRecord[latest Des2Code result + artifact ref を取得<br/>WHERE deletedAt IS NULL]
    FindRecord --> Exists{存在?}
    Exists -->|なし| Err404
    Exists -->|あり| Format[レスポンス整形]
    Format --> Success[200 OK]

Similarity score の扱い

match には weighted score と raw similarity score が含まれます。

フィールド	説明
`similarity`	ranking に使う weighted raw score
`visualSimilarity`	raw visual score。`0.0` から `1.0`、または visual search disabled 時は `null`
`semanticSimilarity`	raw semantic score。`0.0` から `1.0`、または semantic search disabled 時は `null`

ポーリング推奨

クライアントは定期的にこのエンドポイントをポーリングして、Des2Code処理の完了を確認できます。完了は guinness-ai-v2/apps/des2code が S3 artifact を書き込み、POST /v1/webhooks/ai-status に送信し、backend が PostgreSQL を更新することで反映されます。pending または processing の間はエクスポネンシャルバックオフの使用を推奨します。