権限 API

案件の共有権限を管理するエンドポイント。

認証・レスポンス形式・エラーの扱いは API 定義 を参照。

メソッド

HTTP メソッド

メソッド	URI	概要
GET	/api/surveys/{surveyId}/permissions	権限一覧取得
PUT	/api/surveys/{surveyId}/permissions	権限一括更新

リソース定義

権限の種類

権限	値	できること
閲覧	view	案件の閲覧、プレビュー、版一覧の閲覧、案件・版の複製
編集	edit	view の全操作に加えて、テーマ更新・セクション／設問の編集・保存・出力・権限の変更

管理者（SURVEY_ADMIN_EMAILS に登録されたユーザー）は、権限レコードの有無に関わらずすべての案件を閲覧・編集できます。

権限スキーマ

フィールド	データ型	備考
userId	string	ユーザーの UUID
userName	string	ユーザーの表示名
roleType	enum	view / edit

認証要件

x-user-email / x-user-name ヘッダによるユーザー認証が必要です。

操作	必要な権限
権限一覧取得	view
権限一括更新	edit

権限がない場合は 404 Not Found を返します。

権限一覧取得

概要

案件の共有権限一覧を取得します。

URI

GET /api/surveys/{surveyId}/permissions

パラメータ	データ型	必須	備考
surveyId	string	◯	案件の UUID

レスポンス（200 OK）

{
  "ok": true,
  "data": [
    { "userId": "…", "userName": "設計 太郎", "roleType": "edit" },
    { "userId": "…", "userName": "レビュー 花子", "roleType": "view" }
  ]
}

例外処理

説明	ステータスコード	ステータス名
案件が存在しない、または view 権限がない	404	Not Found

権限一括更新

概要

案件の共有権限を 一括更新 します。リクエストで送った内容が権限一覧そのものになるため、既存の権限を残したい場合も含めてすべて送る必要があります。

URI

PUT /api/surveys/{surveyId}/permissions

リクエストボディ

{
  "permissions": [
    { "userId": "…", "userName": "設計 太郎", "roleType": "edit" },
    { "userId": "…", "userName": "レビュー 花子", "roleType": "view" }
  ]
}

バリデーションルール

フィールド	ルール
permissions	必須。権限の全量を表す配列
permissions[].userId	必須。既存ユーザーの UUID
permissions[].userName	必須。文字列
permissions[].roleType	必須。view / edit のいずれか

加えて、管理者以外は自分自身の edit 権限を配列に含める必要があります。含めずに送るとエラーになります。

レスポンス（200 OK）

更新後の権限一覧を返します。

例外処理

説明	ステータスコード	ステータス名
リクエストボディの形式が不正	400	Bad Request
指定されたユーザーが存在しない	404	Not Found
管理者以外が自分自身の edit 権限を外そうとした	404	Not Found
案件が存在しない、または edit 権限がない	404	Not Found

検証エラーも 404 で返る

検証エラーはハンドラで捕捉され、404 とエラーメッセージとして返されます（「存在しないユーザーを権限に設定することはできません。」「自分自身の編集権限は外せません。」）。ステータスコードではなく error の文言で原因を判別してください。

処理フロー

シーケンス図

sequenceDiagram
    participant Client
    participant API
    participant DB

    Client->>API: PUT /api/surveys/{surveyId}/permissions
    API->>API: edit 権限を確認
    API->>DB: 指定ユーザーの存在を検証
    alt 存在しないユーザーがある
        API-->>Client: 404 (存在しないユーザーを権限に設定することはできません。)
    else 管理者以外で自分の edit 権限が含まれていない
        API-->>Client: 404 (自分自身の編集権限は外せません。)
    else
        API->>DB: トランザクション開始
        API->>DB: 既存の権限を全削除
        API->>DB: 指定された権限を挿入
        API->>DB: コミット
        API-->>Client: 200 OK
    end

自分の編集権限は外せない

一括更新は送られた内容をそのまま反映しますが、管理者以外が自分自身の edit 権限を含めずに送るとエラーになり、更新自体が行われません。誤って自分を締め出すことはできない作りです。管理者はこの制約を受けません。