コード作成

メソッド

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

HTTPメソッド

POST: コード作成

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

Authorization
Content-Type: multipart/form-data
Accept
Accept-language

レスポンスヘッダー

Content-Type

コード作成

URI

POST /v1/organizations/{organization_id}/projects/{project_id}/code

パスパラメータ

名前	型	必須	説明
organization_id	number	必須	backend PostgreSQL organization ID
project_id	number	必須	backend PostgreSQL project ID

リクエストボディ

リクエストボディはmultipart/form-dataです。

フォームフィールド

名前	型	必須	説明
id	string	任意	コード UUID。省略時は backend が生成する
name	string	必須	コード名（1-255文字）
source_code	string	必須	コードのソースコード
css_code	string	任意	コードのCSSコード
file	File	必須	プレビュー画像（PNG/JPG/JPEG/GIF、最大5MB）

レスポンス

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

{
  "id": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
  "projectId": 42,
  "name": "Button",
  "s3Key": "code/0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b.png",
  "sourceCode": "const Button = () => { ... }",
  "cssCode": ".button { ... }",
  "status": 2,
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-id",
  "updatedBy": "user-id",
  "deletedBy": null
}

ステータス値

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

認証

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

例外処理

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

説明	ステータスコード	ステータス名
無効なコード UUID または必須フィールド欠落	400	Bad Request
認証情報不足	401	Unauthorized
実行権限不足	403	Forbidden
プロジェクトまたは組織が見つかりません	404	Not Found
ファイルサイズが制限を超えています	413	Payload Too Large
内部サーバーエラー	500	Internal Server Error

処理フロー

フォームデータからすべてのフィールドを抽出
id 省略時はコード UUID を生成し、指定時は UUID として検証
ファイルタイプとサイズを検証
S3に画像をアップロード
PostgreSQL にコードレコードを作成
organization_id、project_id、code_id、source/CSS、preview image URL を含む code-import 処理メッセージを SQS に送信
作成されたコード情報を返却

詳細フローチャート

flowchart TD
    Start([POST Request]) --> Route[Route Handler]
    Route --> Auth[認証情報取得<br/>JWT from Cognito]
    Auth --> Service[Service Layer]

    Service --> AccessCheck[権限チェック]
    AccessCheck --> CheckOrg{組織・プロジェクト<br/>存在確認}
    CheckOrg -->|不在| Err404[404 Not Found]
    CheckOrg -->|存在| CheckPerm{Admin/User<br/>Write権限}
    CheckPerm -->|なし| Err404
    CheckPerm -->|あり| Validate

    Validate[入力バリデーション] --> ValidName{name<br/>1-255文字}
    ValidName -->|NG| Err400[400 Bad Request]
    ValidName -->|OK| ValidCode{sourceCode<br/>必須}
    ValidCode -->|NG| Err400
    ValidCode -->|OK| ValidImg{image<br/>type/size}
    ValidImg -->|NG| Err400
    ValidImg -->|OK| CheckExist

    CheckExist[既存コード確認] --> Exists{既存?}
    Exists -->|Active| Err400
    Exists -->|Deleted| Process[処理実行]
    Exists -->|なし| Process

    Process --> S3Upload[S3画像アップロード]
    S3Upload --> S3OK{成功?}
    S3OK -->|NG| Err400
    S3OK -->|OK| SQSSend[SQSメッセージ送信<br/>Fail-Fast Pattern]

    SQSSend --> SQSOK{成功?}
    SQSOK -->|NG| Err500[500 SQS Unavailable<br/>DB操作中止]
    SQSOK -->|OK| DBOp{既存削除済み?}

    DBOp -->|Yes| Restore[DB復元<br/>deletedAt=NULL]
    DBOp -->|No| Create[DB新規作成]

    Restore --> Success[201 Created]
    Create --> Success

コードID フォーマット

コードIDは backend PostgreSQL のコード UUID です。同じ値を AI v2 へ code_id として送り、DocumentDB では code._id に保存し、code-import Webhook では recordId として echo します。

例: - 有効: 0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b - 無効: not-a-uuid、Button