Des2Code 作成

メソッド

REST方式とする。

HTTPメソッド

POST: Des2Code request を trigger

命名規則

query parameter と node の naming を統一して readability を高めるため、request の URI/JSON node は snake_case を使用する。

リクエストとレスポンス

ヘッダー

meta information は response body ではなく HTTP header に設定する。

リクエストヘッダー

• Authorization (Bearer session token)
• Content-Type
• Accept
• Accept-language

レスポンスヘッダー

• Content-Type

Des2Code リクエスト

URI

POST /v1/des2code

リクエストボディ

request body は strict JSON です。

{
  "design_id": "42_hDDA9BNori9OTXSClduXqR_40002029:37033"
}

リクエストパラメータ

名前	型	必須	説明
design_id	string	必須	1-500 文字。alphanumeric、_, :, - のみ

project/organization override、model、prompt、index ID、matching bound は 受け付けません。backend は authorized PostgreSQL design row から scope を 解決します。unknown body field は reject します。

レスポンス

response は JSON（HTTP status: 202 Accepted）です。

{
  "message": "Des2Code request queued successfully",
  "designId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "requestId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
}

レスポンスフィールド

名前	型	説明
message	string	queue acknowledgement
designId	string	authorized design ID
requestId	string	UUIDv7 correlation/artifact identity

認証

protected user route で Bearer session token を検証します。authenticated subject は design project への access を持つ必要があります。

Authorization: Bearer <session_token>

例外処理

説明	Status Code	Status Name
invalid design ID/body または required field missing	400	Bad Request
Bearer token missing/invalid	401	Unauthorized
design not found または user から不可視	404	Not Found
design import が completed ではない	409	Conflict (DESIGN_IMPORT_NOT_READY)
AI-v2 current code_index が missing または ready ではない	409	Conflict (CODE_INDEX_NOT_READY)
internal server error	500	Internal Server Error
SQS unavailable	503	Service Unavailable

処理フロー

1. strict design_id request body を validate する。
2. PostgreSQL design と project/organization を読み、user access を enforce する。
3. design status に completed を要求する。
4. organization scope 付き AI-v2 GET /internal/projects/{project_id}/code-index を読み、current DocumentDB index に ready を要求する。
5. UUIDv7 requestId を生成する。
6. design_id, project_id, organization_id, request_id だけを含む flat des2code SQS message を送る。
7. non-empty SQS message ID を要求して 202 Accepted を返す。

詳細フローチャート

flowchart TD
    Start([POST /v1/des2code]) --> Route[Route Handler]
    Route --> ValidateToken[Bearer session 検証]
    ValidateToken --> TokenValid{Valid?}
    TokenValid -->|NG| Err401[401 Unauthorized]
    TokenValid -->|OK| ExtractDesignId[strict design_id validation]
    ExtractDesignId --> ValidateFormat{Format valid?}
    ValidateFormat -->|NG| Err400[400 Bad Request]
    ValidateFormat -->|OK| CheckDesign[design + project scope load]
    CheckDesign --> DesignExists{Exists and authorized?}
    DesignExists -->|No| Err404[404 Not Found]
    DesignExists -->|Yes| DesignReady{Design completed?}
    DesignReady -->|No| Err409Design[409 DESIGN_IMPORT_NOT_READY]
    DesignReady -->|Yes| CheckIndex[AI-v2 current code_index read]
    CheckIndex --> IndexReady{status = ready?}
    IndexReady -->|No| Err409Index[409 CODE_INDEX_NOT_READY]
    IndexReady -->|Yes| GenerateRequestId[UUIDv7 requestId]
    GenerateRequestId --> SQSSend[flat des2code SQS message]
    SQSSend --> SQSOK{MessageId present?}
    SQSOK -->|NG| Err503[503 Service Unavailable]
    SQSOK -->|OK| Success[202 Accepted]

非同期処理

この endpoint は queue への投入だけを行います。worker は success を {organization_id}/{project_id}/des2code/{design_id}/{request_id}.json、failure を同 filename の -failed に保存し、backend AI-status webhook を POST します。 webhook は design scope を validate/log しますが Des2Code PostgreSQL run row は 作成・更新しません。

trigger ごとに新しい request ID を発行し、その trigger の SQS retry は同じ artifact key を再利用します。client は GET を poll し、GET は authorized design prefix の最新 contract-valid request artifact を返します。

SQSエラーハンドリング

SQS send failure または empty MessageId の場合、202 acknowledgement 前に失敗 します。backend は sanitized design ID/request ID を log し、queue unavailable を service error response に map します。