コンテンツにスキップ

要件作成

メソッド

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

HTTPメソッド

POST: 要件作成（ファイルアップロード）

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

  • Authorization
  • Content-Type (multipart/form-data)
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

要件作成

URI

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

パスパラメータ

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

リクエストボディ

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

名前 型 必須 説明
name string 必須 要件名（プロジェクト内一意）
file file 必須 要件ファイル

レスポンス

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

{
  "id": "requirement-uuid",
  "projectId": 1,
  "name": "My Requirement",
  "s3Key": "1/1/requirement/requirement-uuid",
  "createdAt": 1234567890000,
  "updatedAt": 1234567890000,
  "deletedAt": null,
  "createdBy": "user-cognito-sub",
  "updatedBy": "user-cognito-sub",
  "deletedBy": null
}

レスポンスフィールド

名前 型 説明
id string 要件UUID
projectId number プロジェクトID
name string 要件名
s3Key string | null S3オブジェクトキー
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)を使用して行われます。

例外処理

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

説明 ステータスコード ステータス名
無効なリクエスト（nameが未指定、fileが未添付など） 400 Bad Request
認証情報不足 401 Unauthorized
実行権限不足 403 Forbidden
プロジェクトまたは組織が見つかりません 404 Not Found
プロジェクト内で要件名が重複しています 409 Conflict
内部サーバーエラー 500 Internal Server Error

処理フロー

  1. パスパラメータから組織IDとプロジェクトIDを抽出
  2. リクエストボディからnameとfileを取得
  3. ユーザーがプロジェクトへのWrite権限を持つか検証
  4. プロジェクト内でnameが一意であることを検証
  5. S3の{organization_id}/{project_id}/requirement/プレフィックスにファイルをアップロード
  6. RDSに要件レコード（name, s3_key等）を作成
  7. 作成した要件情報を返却

詳細フローチャート

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 -->|あり| Validate{name・file検証}

    Validate -->|NG| Err400[400 Bad Request]
    Validate -->|OK| UniqueCheck{name一意?}

    UniqueCheck -->|NG| Err409[409 Conflict]
    UniqueCheck -->|OK| UploadS3["S3にファイルをアップロード<br/>{organization_id}/{project_id}/requirement/{requirement_id}"]

    UploadS3 --> S3OK{成功?}
    S3OK -->|NG| Err500[500 Internal Server Error]
    S3OK -->|OK| CreateRDS[RDSにレコード作成<br/>name, s3_key等]

    CreateRDS --> Success[201 Created]