# 機能設計書 32-ユーザーアカウント管理

## 概要

本ドキュメントは、InvenTreeシステムにおけるユーザーアカウント管理機能の設計を定義する。ユーザーの作成・編集・削除およびプロファイル情報の管理を行う機能を提供する。

### 本機能の処理概要

ユーザーアカウント管理機能は、InvenTreeシステムを利用するユーザーのアカウント情報を一元管理する。Django標準のUserモデルを拡張し、UserProfileモデルで追加のプロファイル情報を管理する。

**業務上の目的・背景**：在庫管理システムでは、複数のユーザーが同時に作業を行うため、各ユーザーを一意に識別し、適切な権限を付与する必要がある。また、ユーザーごとの設定やプロファイル情報を管理することで、個人に最適化された操作環境を提供する。

**機能の利用シーン**：
- 新しい従業員がシステムを利用開始する際のアカウント作成
- 従業員の役職変更に伴う権限やグループの変更
- ユーザーの表示名や連絡先情報の更新
- 退職者のアカウント無効化
- LDAPとの連携によるユーザー自動作成

**主要な処理内容**：
1. ユーザーアカウントの作成（ローカル/LDAP）
2. ユーザー情報の更新（名前、メール、パスワード）
3. ユーザープロファイルの管理（言語、テーマ、表示名等）
4. ユーザーの有効化・無効化
5. グループへの所属管理
6. Ownerモデルによるオーナーシップ管理

**関連システム・外部連携**：
- Django allauth（ソーシャル認証、メール確認）
- LDAP認証（django-auth-ldap）
- OAuth2認証

**権限による制御**：
- ユーザー作成・編集・削除はスタッフ権限かつadminロールが必要
- 自身のプロファイル編集は認証済みユーザーであれば可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 31 | システム概要画面 | 主画面 | ユーザー一覧の表示 |
| 32 | ユーザー詳細画面 | 主画面 | ユーザー詳細情報の表示・編集 |
| 33 | グループ詳細画面 | 参照画面 | グループメンバーの表示 |
| 34 | 管理センター画面 | 参照画面 | ユーザー/アクセス管理パネル |

## 機能種別

CRUD操作 / マスタ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| username | str | Yes | ユーザー名 | 一意性チェック、150文字以内 |
| email | str | Yes | メールアドレス | メール形式チェック |
| password | str | Yes (作成時) | パスワード | Django標準バリデーション |
| first_name | str | No | 名 | 150文字以内 |
| last_name | str | No | 姓 | 150文字以内 |
| is_active | bool | No | アカウント有効状態 | true/false |
| is_staff | bool | No | スタッフ権限 | true/false |
| is_superuser | bool | No | スーパーユーザー権限 | true/false |
| groups | list[int] | No | 所属グループID一覧 | 有効なグループIDであること |

### UserProfile入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| language | str | No | 優先言語 | 10文字以内 |
| theme | json | No | UIテーマ設定 | JSON形式 |
| widgets | json | No | ダッシュボードウィジェット設定 | JSON形式 |
| displayname | str | No | 表示名 | 255文字以内 |
| position | str | No | 役職 | 255文字以内 |
| status | str | No | ステータスメッセージ | 2000文字以内 |
| location | str | No | 所在地 | 2000文字以内 |
| active | bool | No | アクティブ状態 | true/false |
| contact | str | No | 連絡先 | 255文字以内 |
| type | str | No | ユーザータイプ | bot/internal/external/guest |
| organisation | str | No | 組織 | 255文字以内 |
| primary_group | int | No | プライマリグループID | ユーザーが所属するグループであること |

### 入力データソース

- 管理画面からのフォーム入力
- REST API経由のJSON入力
- LDAPサーバーからの自動取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | int | ユーザーID |
| username | str | ユーザー名 |
| email | str | メールアドレス |
| first_name | str | 名 |
| last_name | str | 姓 |
| is_active | bool | アカウント有効状態 |
| is_staff | bool | スタッフ権限 |
| is_superuser | bool | スーパーユーザー権限 |
| groups | list | 所属グループ一覧 |
| profile | object | ユーザープロファイル |

### 出力先

- REST APIレスポンス（JSON）
- 管理画面への表示
- データベース（auth_user, users_userprofile, users_owner）

## 処理フロー

### 処理シーケンス

```
1. ユーザー作成リクエスト受信
   └─ UserCreateSerializerでバリデーション
2. ユーザーデータの保存
   └─ Userモデルへの保存
3. UserProfile自動作成
   └─ post_saveシグナルによる自動生成
4. Owner自動作成
   └─ post_saveシグナルによる自動生成
5. レスポンス返却
   └─ 作成されたユーザー情報の返却
```

### フローチャート

```mermaid
flowchart TD
    A[ユーザー作成リクエスト] --> B{権限チェック}
    B -->|OK| C[バリデーション]
    B -->|NG| D[403エラー]
    C -->|OK| E[Userモデル保存]
    C -->|NG| F[400エラー]
    E --> G[post_saveシグナル発火]
    G --> H[UserProfile自動作成]
    G --> I[Owner自動作成]
    H --> J[レスポンス返却]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-01 | ユーザー名一意性 | ユーザー名はシステム全体で一意であること | ユーザー作成・更新時 |
| BR-32-02 | プロファイル自動生成 | ユーザー作成時にUserProfileが自動生成される | ユーザー作成時 |
| BR-32-03 | プライマリグループ制約 | プライマリグループはユーザーが所属するグループから選択 | プロファイル更新時 |
| BR-32-04 | LDAP連携 | LDAP認証時にメールアドレスからEmailAddressが自動作成される | LDAPログイン時 |
| BR-32-05 | 表示名設定 | DISPLAY_FULL_NAMES設定により表示名形式が変わる | ユーザー表示時 |

### 計算ロジック

ユーザー表示名の決定:
```python
if DISPLAY_FULL_NAMES and (first_name or last_name):
    display_name = f'{first_name} {last_name}'
else:
    display_name = username
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ユーザー作成 | auth_user | INSERT | ユーザーレコード作成 |
| ユーザー作成 | users_userprofile | INSERT | プロファイル自動作成 |
| ユーザー作成 | users_owner | INSERT | オーナー自動作成 |
| ユーザー更新 | auth_user | UPDATE | ユーザー情報更新 |
| プロファイル更新 | users_userprofile | UPDATE | プロファイル情報更新 |
| ユーザー削除 | auth_user | DELETE | ユーザーレコード削除（カスケード） |
| グループ所属 | auth_user_groups | INSERT/DELETE | グループ所属関係の管理 |

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

#### auth_user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | username, email, password等 | 入力値 | パスワードはハッシュ化 |
| UPDATE | first_name, last_name, is_active等 | 入力値 | |
| DELETE | id | 削除対象ID | セッション削除後に実行 |

#### users_userprofile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | user_id | 作成されたユーザーID | シグナルで自動作成 |
| UPDATE | language, theme, displayname等 | 入力値 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | 入力データが不正 | エラー内容を確認して修正 |
| 403 | PermissionDenied | 権限不足 | スタッフ権限とadminロールを確認 |
| 404 | NotFound | 指定ユーザーが存在しない | ユーザーIDを確認 |
| 409 | IntegrityError | ユーザー名重複 | 別のユーザー名を使用 |

### リトライ仕様

一般的なCRUD操作のため、特別なリトライ仕様は不要。データベース接続エラーの場合はDjangoの標準エラーハンドリングに従う。

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

- ユーザー作成時はUser, UserProfile, Ownerの作成が単一トランザクションで処理される
- グループ所属の変更はatomicトランザクションで処理
- ユーザー削除前にセッションを削除（UserSession）

## パフォーマンス要件

- ユーザー一覧取得：ページネーション対応（デフォルト25件/ページ）
- ユーザー検索：first_name, last_name, usernameフィールドで全文検索対応
- プロファイル取得：1リクエスト50ms以内

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

- パスワードはDjango標準のハッシュ化（PBKDF2_SHA256）で保存
- パスワード変更時はpassword_changed()で検証
- スーパーユーザー以外はパスワード設定にバリデーションチェックが必須
- ユーザー削除時は全セッションを無効化

## 備考

UserProfile.UserTypeの定義:
- bot: 自動化用ボットアカウント
- internal: 内部ユーザー
- external: 外部ユーザー
- guest: ゲストユーザー

---

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

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

### 推奨読解順序

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

ユーザー管理に関連するモデル定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/users/models.py` | UserProfile（489-597行目）とApiToken（83-199行目）の定義 |
| 1-2 | models.py | `src/backend/InvenTree/users/models.py` | Owner（296-458行目）とRuleSet（201-294行目）の定義 |

**読解のコツ**: Django標準のUserモデルを拡張しており、OneToOneFieldでUserProfileと関連付けられている。

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

REST APIエンドポイントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.py | `src/backend/InvenTree/users/api.py` | UserListとUserDetail（175-194行目、251-279行目） |
| 2-2 | api.py | `src/backend/InvenTree/users/api.py` | MeUserDetail（226-249行目）で自身の情報を取得・更新 |

**主要処理フロー**:
1. **251-279行目**: UserListでユーザー一覧取得・作成
2. **175-194行目**: UserDetailで個別ユーザーの取得・更新・削除
3. **226-249行目**: MeUserDetailで現在のユーザー情報を取得・更新

#### Step 3: シグナル処理を理解する

ユーザー作成時の自動処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | models.py | `src/backend/InvenTree/users/models.py` | create_or_update_user_profile（600-605行目） |
| 3-2 | models.py | `src/backend/InvenTree/users/models.py` | create_owner（461-467行目） |

**主要処理フロー**:
- **600-605行目**: post_saveシグナルでUserProfileを自動作成
- **461-467行目**: post_saveシグナルでOwnerを自動作成

#### Step 4: 認証・権限を理解する

権限チェックの仕組みを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | api.py | `src/backend/InvenTree/users/api.py` | StaffRolePermissionOrReadOnly権限クラスの適用 |
| 4-2 | permissions.py | `src/backend/InvenTree/users/permissions.py` | 権限クラスの定義 |

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

```
UserList / UserDetail API
    │
    ├─ UserCreateSerializer
    │      └─ User.save()
    │
    ├─ post_save シグナル
    │      ├─ create_or_update_user_profile()
    │      │      └─ UserProfile.objects.create()
    │      │
    │      └─ create_owner()
    │             └─ Owner.create()
    │
    └─ ExtendedUserSerializer
           └─ レスポンス生成
```

### データフロー図

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

APIリクエスト ───▶ UserCreateSerializer ───▶ User作成
        │                                         │
        │                                         ▼
        │                              post_saveシグナル
        │                                    │
        │                     ┌──────────────┼──────────────┐
        │                     ▼              ▼              ▼
        │              UserProfile作成  Owner作成   グループ設定
        │                     │              │              │
        │                     └──────────────┴──────────────┘
        │                                    │
        │                                    ▼
        └─────────────────────────── APIレスポンス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/users/models.py` | ソース | ユーザー関連モデル定義 |
| api.py | `src/backend/InvenTree/users/api.py` | ソース | ユーザーAPIエンドポイント |
| serializers.py | `src/backend/InvenTree/users/serializers.py` | ソース | ユーザーシリアライザ |
| permissions.py | `src/backend/InvenTree/users/permissions.py` | ソース | 権限クラス定義 |
| authentication.py | `src/backend/InvenTree/users/authentication.py` | ソース | 認証バックエンド |
| admin.py | `src/backend/InvenTree/users/admin.py` | ソース | Django管理画面設定 |
| ruleset.py | `src/backend/InvenTree/users/ruleset.py` | ソース | ルールセット定義 |
| tasks.py | `src/backend/InvenTree/users/tasks.py` | ソース | バックグラウンドタスク |
