api-admin 概要

apps/admin は 4D 運用スタッフ向けの REST API です。Hono + Bun で実装され、PostgreSQL をデータストアとして使用します。管理者アカウント・組織・プロジェクト・ユーザーの CRUD と、AWS Cognito を使ったセッション管理を提供します。

アーキテクチャ

Routes → Services → Repositories → Database の 4 層構成です。

クライアントリクエスト
    ↓
Middlewares（認証・ログ・エラーハンドリング）
    ↓
Routes（リクエストバリデーション・レスポンス整形）
    ↓
Services（ビジネスロジック）
    ↓
Repositories（データアクセス）
    ↓
PostgreSQL / AWS Cognito

api-user との主な違いは以下の 2 点です。

項目	api-admin	api-user
データベース	PostgreSQL	PostgreSQL
セッション管理	PostgreSQL session テーブルでトークンハッシュを管理	Cognito JWT のみ

エンドポイント一覧

すべてのエンドポイントは /v1 プレフィックスでバージョン管理されています。

パス	担当ファイル	内容
`/v1/auth/*`	`routes/v1/auth.ts`	ログイン・ログアウト・セッションクリーンアップ
`/v1/admins/*`	`routes/v1/admin.ts`	管理者アカウント CRUD
`/v1/organizations/*`	`routes/v1/organization.ts`	組織 CRUD
`/v1/projects/*`	`routes/v1/project.ts`	プロジェクト管理
`/v1/users/*`	`routes/v1/user.ts`	アプリユーザー管理
`/v1/projects/{project_id}/users/*`	`routes/v1/user-project.ts`	プロジェクトのユーザーアクセス割り当て
`/v1/ping`	`routes/v1/ping.ts`	ヘルスチェック

ミドルウェアパイプライン

ミドルウェア	ファイル	役割
`requestId()`	`hono/request-id`	トレース用の一意なリクエスト ID を付与
`winstonLogger()`	`middlewares/winston-logger.ts`	リクエスト / レスポンスの構造化ログ（所要時間含む）
`cors()`	`hono/cors`	クロスオリジンリソース共有
`compress()`	`hono/compress`	Gzip レスポンス圧縮
`protectedRoute`	`middlewares/protected-route.ts`	JWT 検証・Cognito sub 抽出
`errorHandler`	`middlewares/error-handler.ts`	集中エラーハンドリング・統一フォーマット返却

認証・セッションフロー

sequenceDiagram
    participant Admin as 管理者
    participant API as API Gateway
    participant Lambda as Lambda (api-admin)
    participant Cognito as AWS Cognito
    participant DB as PostgreSQL

    Admin->>API: POST /v1/auth/login
    API->>Lambda: リクエスト転送
    Lambda->>Cognito: initiateAuth()
    Cognito-->>Lambda: JWT アクセストークン
    Lambda->>DB: セッション作成（token_hash, IP, User-Agent）
    Lambda-->>Admin: 200 { token, admin }

    Admin->>API: 保護されたエンドポイント呼び出し
    API->>Lambda: Authorization: Bearer <token>
    Lambda->>Cognito: JWT 検証
    Lambda->>DB: token_hash でセッション検索
    DB-->>Lambda: セッション有効
    Lambda-->>Admin: レスポンス

    Admin->>API: POST /v1/auth/logout
    API->>Lambda: リクエスト転送
    Lambda->>Cognito: globalSignOut()
    Lambda->>DB: セッション失効（revoked_at をセット）
    Lambda-->>Admin: 200

セッションライフサイクル

stateDiagram-v2
    [*] --> Created: 管理者ログイン
    Created --> Active: セッションを DB に保存
    Active --> Expired: expires_at 超過
    Active --> Revoked: 管理者ログアウト
    Active --> Revoked: パスワードリセット
    Active --> Revoked: グローバルサインアウト
    Expired --> CleanedUp: スケジュール済みクリーンアップ
    Revoked --> CleanedUp: スケジュール済みクリーンアップ
    CleanedUp --> [*]: ソフト削除（deleted_at をセット）

セッションは期限切れ後も SESSION_RETENTION_DAYS（デフォルト: 90 日）の間保持されてからソフト削除されます。

エラーハンドリング

すべてのエラーは以下の JSON 形式で返却されます。

{
  "error": {
    "message": "エラーの説明",
    "code": "ERROR_CODE",
    "details": {}
  }
}

ステータス	用途
`400 Bad Request`	無効な入力データ
`401 Unauthorized`	認証がないか無効
`403 Forbidden`	権限不足
`404 Not Found`	リソースが見つからない
`409 Conflict`	リソースの競合（重複など）
`500 Internal Server Error`	予期しないサーバーエラー

主要環境変数

変数	必須	説明
`ADMIN_COGNITO_USER_POOL_ID`	Yes	AWS Cognito User Pool ID
`ADMIN_COGNITO_CLIENT_ID`	Yes	AWS Cognito App Client ID
`ADMIN_COGNITO_REGION`	No	AWS リージョン（デフォルト: `ap-northeast-1`）
`DATABASE_NAME`	Yes	PostgreSQL データベース名
`DATABASE_USER`	Yes	PostgreSQL ユーザー
`DATABASE_PASSWORD`	Yes	PostgreSQL パスワード
`DATABASE_HOST`	No	PostgreSQL ホスト（デフォルト: `localhost`）
`DATABASE_PORT`	No	PostgreSQL ポート（デフォルト: `5432`）
`SESSION_CLEANUP_API_KEY`	Yes	セッションクリーンアップ API キー
`SESSION_RETENTION_DAYS`	No	期限切れセッションの保持日数（デフォルト: `90`）
`ALLOWED_ORIGINS`	No	カンマ区切り CORS オリジン
`PORT`	No	サーバーポート（デフォルト: `8081`）