# 機能設計書 62-ユーザーCRUD

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける管理者ユーザーのCRUD（作成・取得・更新・削除）機能の設計を記述する。

### 本機能の処理概要

**業務上の目的・背景**：ECサイトの管理画面を操作するためには、管理者ユーザーアカウントが必要である。ユーザーCRUD機能は、管理者ユーザーの登録、情報取得、プロフィール更新、アカウント削除を提供する。これにより、組織内での権限管理や、スタッフの入退社に伴うアカウント管理が可能となる。RBACモジュールとの連携により、ユーザーごとの権限設定も実現できる。

**機能の利用シーン**：
- 新規管理者スタッフのアカウント作成（招待機能と連携）
- 管理者一覧画面でのユーザー情報表示
- プロフィール編集画面での名前・アバター変更
- 退職者のアカウント削除
- ロール・権限の割り当て

**主要な処理内容**：
1. ユーザー一覧取得（フィルタ・ページネーション対応）
2. 特定ユーザーの詳細情報取得
3. ユーザー作成（招待受諾時のワークフロー内で実行）
4. ユーザー情報更新（名前、アバターURL、メタデータ）
5. ユーザー削除（ソフトデリート）
6. ユーザーへのロール割り当て・解除

**関連システム・外部連携**：
- 認証モジュール（Auth Module）との連携でログイン機能と統合
- RBACモジュールとの連携で権限管理

**権限による制御**：ユーザー削除時、自分自身のアカウントは削除できない制約がある。また、RBACポリシーにより各操作の実行可否が制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 106 | プロフィール詳細画面 | 主画面 | ログインユーザーのプロフィール表示 |
| 107 | プロフィール編集画面 | 主画面 | プロフィール情報の編集 |
| 119 | ユーザー一覧画面 | 主画面 | 管理ユーザー一覧の取得・表示 |
| 121 | ユーザー詳細画面 | 主画面 | ユーザー詳細の表示 |
| 122 | ユーザー編集画面 | 主画面 | ユーザー情報の編集 |
| 123 | ユーザーメタデータ編集画面 | 主画面 | ユーザーメタデータの編集 |

## 機能種別

CRUD操作

## 入力仕様

### 入力パラメータ

#### ユーザー作成

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| email | string | Yes | メールアドレス | 有効なメール形式、一意性 |
| first_name | string | No | 名 | - |
| last_name | string | No | 姓 | - |
| avatar_url | string | No | アバター画像URL | 有効なURL形式 |
| metadata | object | No | メタデータ | - |
| roles | string[] | No | 割り当てるロールID配列 | 有効なロールID |

#### ユーザー更新

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| id | string | Yes | ユーザーID | 存在するユーザー |
| first_name | string | No | 名 | - |
| last_name | string | No | 姓 | - |
| avatar_url | string | No | アバター画像URL | 有効なURL形式 |
| metadata | object | No | メタデータ | - |

#### 一覧取得

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| q | string | No | 検索クエリ | - |
| id | string[] | No | ユーザーIDフィルタ | - |
| email | string[] | No | メールアドレスフィルタ | - |
| limit | number | No | 取得件数 | 1以上 |
| offset | number | No | オフセット | 0以上 |

### 入力データソース

- Admin API HTTPリクエスト
- 招待受諾ワークフロー（acceptInviteWorkflow）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | ユーザーID（user_プレフィックス） |
| email | string | メールアドレス |
| first_name | string | null | 名 |
| last_name | string | null | 姓 |
| avatar_url | string | null | アバター画像URL |
| metadata | object | null | メタデータ |
| created_at | Date | 作成日時 |
| updated_at | Date | 更新日時 |
| deleted_at | Date | null | 削除日時（ソフトデリート） |

### 出力先

- Admin API HTTPレスポンス
- イベント発行（user.created, user.updated, user.deleted）

## 処理フロー

### 処理シーケンス

```
1. ユーザー一覧取得
   └─ remoteQuery でユーザーテーブルを検索、ページネーション適用

2. ユーザー詳細取得
   └─ remoteQuery でIDを指定して単一ユーザー取得

3. ユーザー作成（ワークフロー）
   ├─ ロール存在検証（validateRolesExistStep）
   ├─ ユーザー作成（createUsersStep）
   ├─ ロールリンク作成（createRemoteLinkStep）
   └─ イベント発行（emitEventStep）

4. ユーザー更新（ワークフロー）
   ├─ ユーザー情報更新（updateUsersStep）
   └─ ユーザー再取得（refetchUser）

5. ユーザー削除（ワークフロー）
   ├─ 自己削除チェック
   ├─ 認証アイデンティティ削除
   └─ ユーザーソフトデリート
```

### フローチャート

```mermaid
flowchart TD
    A[API リクエスト] --> B{操作種別}
    B -->|GET /users| C[ユーザー一覧取得]
    B -->|GET /users/:id| D[ユーザー詳細取得]
    B -->|POST /users/:id| E[ユーザー更新]
    B -->|DELETE /users/:id| F[ユーザー削除]

    C --> G[remoteQuery実行]
    D --> G

    E --> H[updateUsersWorkflow実行]
    H --> I[updateUsersStep]
    I --> J[refetchUser]

    F --> K{自己削除?}
    K -->|Yes| L[エラー返却]
    K -->|No| M[removeUserAccountWorkflow実行]
    M --> N[ソフトデリート]

    G --> O[レスポンス返却]
    J --> O
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-62-01 | メール一意性 | 同一メールアドレスで複数ユーザーは作成不可 | ユーザー作成時 |
| BR-62-02 | 自己削除禁止 | ログイン中のユーザーは自分自身を削除できない | ユーザー削除時 |
| BR-62-03 | ソフトデリート | ユーザー削除はdeleted_atの設定で論理削除 | ユーザー削除時 |
| BR-62-04 | ロール検証 | 割り当てるロールは事前に存在確認 | ユーザー作成時 |

### 計算ロジック

特になし

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | user | SELECT | フィルタ・ページネーション付き検索 |
| 詳細取得 | user | SELECT | ID指定で単一取得 |
| 作成 | user | INSERT | 新規ユーザー作成 |
| 更新 | user | UPDATE | ユーザー情報更新 |
| 削除 | user | UPDATE | deleted_atを設定（ソフトデリート） |
| ロール紐付け | user_rbac_role_link | INSERT | ユーザーとロールの紐付け |

### テーブル別操作詳細

#### user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（user_プレフィックス） | generateEntityIdで生成 |
| INSERT | email | 入力値 | ユニーク制約あり |
| INSERT | first_name | 入力値 | nullable |
| INSERT | last_name | 入力値 | nullable |
| INSERT | avatar_url | 入力値 | nullable |
| INSERT | metadata | 入力値 | JSON型、nullable |
| UPDATE | first_name, last_name, avatar_url, metadata | 入力値 | 指定されたフィールドのみ更新 |
| UPDATE | deleted_at | 現在日時 | ソフトデリート時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定IDのユーザーが存在しない | 404レスポンス |
| NOT_ALLOWED | MedusaError | 自分自身を削除しようとした | 400レスポンス |
| INVALID_DATA | MedusaError | メールアドレスが重複 | 400レスポンス |
| INVALID_DATA | MedusaError | 存在しないロールIDを指定 | 400レスポンス |

### リトライ仕様

データベース操作失敗時のリトライはワークフローエンジンで管理。

## トランザクション仕様

- ユーザー作成・更新・削除はワークフロー内でトランザクション管理
- @InjectTransactionManagerデコレータで内部トランザクションを制御
- 失敗時はロールバック

## パフォーマンス要件

- ユーザー一覧取得はページネーション対応
- email, first_name, last_nameカラムはsearchableで全文検索対応
- emailカラムにユニークインデックス設定

## セキュリティ考慮事項

- ユーザー作成は招待ワークフロー経由のみ（直接作成APIなし）
- 認証必須エンドポイント
- RBACによる権限制御
- 自己削除禁止による最低1ユーザー保証

## 備考

- ユーザーIDはuser_プレフィックス付きで自動生成
- メタデータフィールドでカスタム情報を保持可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | user.ts | `packages/modules/user/src/models/user.ts` | Userモデルの構造（id, email, first_name, last_name, avatar_url, metadata） |

**読解のコツ**: `model.define`で定義されたエンティティ。`searchable()`はインデックス対象、`nullable()`はnull許容を示す。

#### Step 2: APIエントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/users/route.ts` | GET - ユーザー一覧取得 |
| 2-2 | [id]/route.ts | `packages/medusa/src/api/admin/users/[id]/route.ts` | GET, POST, DELETE - 個別ユーザー操作 |

**主要処理フロー**:
1. **route.ts 11-33行目**: 一覧取得、remoteQueryでフィルタ・ページネーション
2. **[id]/route.ts 19-41行目**: 詳細取得
3. **[id]/route.ts 44-71行目**: 更新処理、updateUsersWorkflow使用
4. **[id]/route.ts 74-99行目**: 削除処理、自己削除チェック、removeUserAccountWorkflow使用

#### Step 3: サービス層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | user-module.ts | `packages/modules/user/src/services/user-module.ts` | UserModuleServiceの実装 |

**主要処理フロー**:
- **198-224行目**: createUsers - ユーザー作成
- **237-253行目**: updateUsers - ユーザー更新

#### Step 4: ワークフローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | create-users.ts | `packages/core/core-flows/src/user/workflows/create-users.ts` | ユーザー作成ワークフロー |
| 4-2 | update-users.ts | `packages/core/core-flows/src/user/workflows/update-users.ts` | ユーザー更新ワークフロー |
| 4-3 | remove-user-account.ts | `packages/core/core-flows/src/user/workflows/remove-user-account.ts` | ユーザー削除ワークフロー |

**主要処理フロー**:
- **create-users.ts 45-98行目**: ロール検証、ユーザー作成、リンク作成、イベント発行

### プログラム呼び出し階層図

```
Admin API Route
    │
    ├─ GET /users
    │      └─ remoteQuery (user エントリーポイント)
    │
    ├─ GET /users/:id
    │      └─ remoteQuery (user エントリーポイント)
    │
    ├─ POST /users/:id
    │      └─ updateUsersWorkflow
    │             ├─ updateUsersStep
    │             │      └─ userService_.update
    │             └─ refetchUser
    │
    └─ DELETE /users/:id
           └─ removeUserAccountWorkflow
                  ├─ setAuthAppMetadataStep (認証削除)
                  └─ deleteUsersStep
                         └─ userService_.softDelete
```

### データフロー図

```
[入力]                        [処理]                           [出力]

Admin API Request ───▶ Route Handler ───▶ HTTPレスポンス
                            │
                            ▼
                    Workflow Execution
                            │
                            ├─ UserModuleService
                            │        │
                            │        ▼
                            │   user テーブル
                            │
                            └─ Event Emission
                                     │
                                     ▼
                              user.created / updated / deleted
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| user.ts | `packages/modules/user/src/models/user.ts` | ソース | Userモデル定義 |
| user-module.ts | `packages/modules/user/src/services/user-module.ts` | ソース | UserModuleService |
| route.ts | `packages/medusa/src/api/admin/users/route.ts` | ソース | ユーザー一覧API |
| [id]/route.ts | `packages/medusa/src/api/admin/users/[id]/route.ts` | ソース | ユーザー個別API |
| create-users.ts | `packages/core/core-flows/src/user/workflows/create-users.ts` | ソース | 作成ワークフロー |
| update-users.ts | `packages/core/core-flows/src/user/workflows/update-users.ts` | ソース | 更新ワークフロー |
| remove-user-account.ts | `packages/core/core-flows/src/user/workflows/remove-user-account.ts` | ソース | 削除ワークフロー |
| validators.ts | `packages/medusa/src/api/admin/users/validators.ts` | ソース | 入力バリデーション |
