コンテンツにスキップ

ユーザー作成

メソッド

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

HTTP メソッド

POST: アプリユーザーの新規作成

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

  • Authorization: Bearer <access_token>
  • Content-Type: application/json

レスポンスヘッダー

  • Content-Type: application/json

ユーザー作成

URI

/api/v1/users

リクエストボディ

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

{
  "email": "user@example.com",
  "temporaryPassword": "TempPass123",
  "name": "John Doe",
  "organizationId": 1
}

バリデーションルール

フィールド ルール
email 必須。有効なメール形式。
temporaryPassword 必須。8 文字以上。初回ログイン時に Cognito がパスワード変更を強制します。
name 必須。1〜255 文字。
organizationId 必須。既存組織を参照する正の整数。

レスポンス（201 Created）

レスポンスは JSON です。

{
  "id": 1,
  "cognitoSub": "1111-aaaa-2222-bbbb",
  "organizationId": 1,
  "name": "John Doe",
  "createdAt": 1640995200000,
  "updatedAt": 1640995200000,
  "createdBy": "1111-aaaa-2222-bbbb",
  "updatedBy": "1111-aaaa-2222-bbbb",
  "deletedAt": null,
  "deletedBy": null
}

認証要件

Amazon Cognito が発行する JSON Web Token（JWT）を用いた認証です。Authorization ヘッダーに有効な Bearer トークンが必要です。

例外処理

例外時のステータスコードは次のとおりです。

説明 ステータスコード ステータス名
トークンが欠落または無効 401 Unauthorized
組織が見つからない 404 Not Found
重複ユーザーまたは Cognito 競合 409 Conflict
サーバ内部エラー 500 Internal Server Error

処理フロー

シーケンス図

sequenceDiagram
    participant Client
    participant Middleware as Protected Route Middleware
    participant API as Hono Router
    participant Service as User Service
    participant Cognito as App Cognito Pool
    participant DB as PostgreSQL Database

    Client->>Middleware: POST /api/v1/users
    Middleware->>Middleware: Verify JWT & session

    alt Token Valid
        Middleware-->>API: Auth info (sub)
        API->>Service: create({ email, tempPassword, name, orgId, actorSub })
        Service->>DB: Find organization by ID

        alt Organization Found
            Service->>Cognito: adminCreateUserWithTempPassword
            Cognito-->>Service: User created
            Service->>Cognito: getCognitoSubByEmail
            Cognito-->>Service: cognitoSub

            alt DB Insert Success
                Service->>DB: Create user record
                DB-->>Service: User record
                Service-->>API: User with relations
                API-->>Client: 201 Created
            else DB Insert Failed
                Service->>Cognito: adminDeleteUser (rollback)
                Service-->>API: throw Error
                API-->>Client: 500 Internal Server Error
            end
        else Organization Not Found
            DB-->>Service: null
            Service-->>API: throw NotFoundError
            API-->>Client: 404 Not Found
        end
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes 層

ルーティングはここで行います。protectedRoute ミドルウェアが JWT を検証します。ハンドラは Zod でリクエストボディを検証し、操作者の Cognito sub を取り出してユーザーサービスに委譲します。

ソース: apps/admin/src/routes/v1/user.ts

Services 層

ビジネスロジックの説明です。組織の存在を確認し、アプリ Cognito プールに仮パスワードでユーザーを作成し、cognitoSub を解決してから DB レコードを作成します。DB 挿入に失敗した場合は Cognito ユーザーを削除してロールバックします。

ソース: apps/admin/src/services/user.ts

Repositories 層

データベースおよび外部サービスへのアクセスです。組織参照、Cognito のユーザー作成／sub 解決／削除、ユーザー行の作成を扱います。

ソース: apps/admin/src/repositories/user.ts / apps/admin/src/repositories/cognito-pool.ts

セキュリティ

  • ハンドラ実行前に protectedRoute ミドルウェアがトークンを検証します
  • DB 失敗時の Cognito ロールバックにより、Cognito にだけ残るユーザーを防ぎます
  • 仮パスワードにより初回ログイン時にパスワード変更が強制されます