コンテンツにスキップ

構造生成

メソッド

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

HTTPメソッド

POST: ストラクチャー生成

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

  • Authorization
  • Content-Type
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

ストラクチャー生成

URI

POST /api/v1/organizations/{organization_id}/projects/{project_id}/structure_generation

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織ID
project_id integer 必須 プロジェクトID

リクエストボディ

リクエストボディはJSONです。

{
  "wireframe_id": "wf-123",
  "detail_design_id": "dd-456",
  "requirement_id": "rq-789"
}

リクエストパラメータ

名前 型 必須 説明
wireframe_id string 必須 関連するワイヤーフレームID
detail_design_id string 任意 関連する詳細設計ID
requirement_id string 任意 関連する要件定義ID

レスポンス

レスポンスはJSONです（HTTPステータス: 201 Created）。

{
  "structureId": "st-789",
  "projectId": 2,
  "wireframeId": "wf-123",
  "detailDesignId": "dd-456",
  "requirementId": "rq-789",
  "json": null,
  "status": 0,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

ステータス値

値 説明
0 処理中
1 完了
2 失敗

レスポンスフィールド

名前 型 説明
structureId string ストラクチャーUUID
projectId number プロジェクトID
wireframeId string ワイヤーフレームID
detailDesignId string | null 詳細設計ID
requirementId string | null 要件定義ID
json object | null 生成されたストラクチャーJSONデータ（処理完了後に設定）
status number 処理ステータス（0-2）
createdAt number 作成日時（エポックミリ秒）
updatedAt number 更新日時（エポックミリ秒）
deletedAt number | null 削除日時（エポックミリ秒）。未削除の場合はnull
createdBy string 作成者のユーザーID
updatedBy string 更新者のユーザーID
deletedBy string | null 削除者のユーザーID。未削除の場合はnull

認証

認証はAmazon Cognitoから発行されるJSON Web Tokens (JWT)を使用して行われます。

例外処理

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

説明 ステータスコード ステータス名
無効なワイヤーフレームIDまたは必須フィールド欠落 400 Bad Request
認証情報不足 401 Unauthorized
実行権限不足 403 Forbidden
プロジェクト、組織、またはワイヤーフレームが見つかりません 404 Not Found
内部サーバーエラー 500 Internal Server Error

処理フロー

  1. パスパラメータから組織IDとプロジェクトIDを抽出
  2. リクエストボディからワイヤーフレームID・詳細設計ID・要件定義IDを抽出
  3. ユーザーがプロジェクトへのWrite権限を持つか検証
  4. ワイヤーフレームの存在確認、および画像URL・JSONスキーマURLを取得
  5. 詳細設計IDが指定された場合は詳細設計の存在確認、およびURLを取得
  6. 要件定義IDが指定された場合は要件定義の存在確認、およびURLを取得
  7. データベースにストラクチャーレコードを作成（json: null、status: 0=処理中）
  8. SQSキューにストラクチャー生成メッセージを送信
  9. 作成されたストラクチャー情報を返却

詳細フローチャート

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[認証・パラメータ取得]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[権限チェック]
    AccessCheck --> HasAccess{Write権限?}
    HasAccess -->|なし| Err404[404 Not Found]
    HasAccess -->|あり| VerifyWireframe[ワイヤーフレーム存在確認]

    VerifyWireframe --> WFExists{存在?}
    WFExists -->|なし| Err404
    WFExists -->|あり| VerifyDetail[詳細設計・要件定義確認<br/>IDが指定された場合]

    VerifyDetail --> DetailExists{存在?}
    DetailExists -->|なし| Err404
    DetailExists -->|あり| CreateDB[DBレコード作成<br/>json=null<br/>status=0 処理中]

    CreateDB --> SendSQS[SQSキューにメッセージ送信]

    SendSQS --> SQSResult{送信成功?}
    SQSResult -->|失敗| Err500[500 Internal Server Error]
    SQSResult -->|成功| Success[201 Created]

非同期処理

ストラクチャーはSQSワーカーによって非同期で生成されます。バックグラウンドワーカーがステータスとjsonフィールドを更新します： - 0 (処理中) → 1 (完了) または 2 (失敗)

完了後はストラクチャー取得APIでjsonデータを取得できます。

SQS ペイロード

SQSキューに送信されるメッセージのペイロードは以下の形式です。

{
  "project_id": "2",
  "structure_id": "st-789",
  "wireframe_id": "wf-123",
  "wireframe_img_url": "s3://4d-gen-ai-swagger/design.png",
  "wireframe_json_url": "s3://bucket-name/path/to/schema.json",
  "detail_design_id": "dd-456",
  "detail_design_url": "s3://bucket-name/path/to/detail-01.pdf",
  "requirement_id": "rq-789",
  "requirement_url": "s3://bucket-name/path/to/requirements-01.md"
}

SQS ペイロードフィールド

名前 型 必須 説明
project_id string 必須 プロジェクトID
structure_id string 必須 生成対象のストラクチャーID
wireframe_id string 必須 ワイヤーフレームID
wireframe_img_url string 必須 S3に保存されたワイヤーフレーム画像のURL
wireframe_json_url string 必須 S3に保存されたワイヤーフレームJSONスキーマのURL
detail_design_id string 任意 詳細設計ID
detail_design_url string 任意 S3に保存された詳細設計ドキュメントのURL
requirement_id string 任意 要件定義ID
requirement_url string 任意 S3に保存された要件定義ドキュメントのURL