ユーザー一覧

メソッド

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

HTTP メソッド

GET: ページネーションと任意の組織フィルタ付きユーザー一覧

命名規則

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

リクエストとレスポンス

ヘッダー

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

リクエストヘッダー

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

レスポンスヘッダー

Content-Type: application/json

ユーザー一覧

URI

/api/v1/users

クエリパラメータ

名前	型	デフォルト	説明
page	integer	1	ページ番号
limit	integer	10	1 ページあたりの件数（最大 100）
sort	string	`updated_at:desc`	ソート項目と向き（形式: `field:asc` または `field:desc`）
organization_id	integer	—	組織 ID でフィルタ

レスポンス（200 OK）

レスポンスは JSON です。

{
  "currentPage": 1,
  "totalCount": 10,
  "list": [
    {
      "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
サーバ内部エラー	500	Internal Server Error

処理フロー

シーケンス図

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

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

    alt Token Valid
        Middleware-->>API: Auth info
        API->>Service: list({ page, limit, sort, organizationId })
        Service->>DB: findAllPaginated with filters
        DB-->>Service: Paginated user records
        Service-->>API: { currentPage, total, users }
        API-->>Client: 200 OK { currentPage, totalCount, list }
    else Token Invalid
        Middleware-->>Client: 401 Unauthorized
    end

Routes 層

ルーティングはここで行います。protectedRoute ミドルウェアが JWT を検証します。ハンドラはページネーション用クエリと任意の組織フィルタを取り出し、ユーザーサービスに委譲します。

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

Services 層

ビジネスロジックの説明です。page / limit からオフセットを算出し、任意の組織 ID フィルタ付きでリポジトリにページ分割取得を委譲します。

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

Repositories 層

データベースへのアクセスです。動的ソートと任意の組織 ID フィルタ付きページ分割クエリを扱います。

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

セキュリティ

ハンドラ実行前に protectedRoute ミドルウェアがトークンを検証します
ページネーションの limit は最大 100 に制限され、過剰取得を防ぎます