# 通知設計書 37-ログインメソッド取得失敗

## 概要

本ドキュメントは、Actual Budget アプリケーションにおける「ログインメソッド取得失敗」通知の設計仕様を記述する。この通知は、サーバーから利用可能なログインメソッド（パスワード、OpenID など）の一覧を取得する際にエラーが発生した場合に表示される。

### 本通知の処理概要

**業務上の目的・背景**：Actual Budget はマルチユーザー環境をサポートしており、サーバー側で複数の認証方法（パスワード認証、OpenID 認証など）を設定できる。アプリ起動時やサーバー接続時に利用可能なログインメソッドを取得する必要があるが、この取得に失敗した場合、ユーザーは適切な認証方法を選択できなくなる。この通知により、問題の発生をユーザーに知らせ、サーバー接続の確認やサポートへの連絡を促す。

**通知の送信タイミング**：`ServerContext` で `refreshLoginMethods` が呼び出され、サーバーから `subscribe-get-login-methods` の応答にエラーが含まれている場合に表示される。

**通知の受信者**：サーバーに接続しようとしているユーザー。

**通知内容の概要**：ログインメソッドの取得に失敗したことを示すエラータイトルと、サーバーから返されたエラーメッセージ（または "Unknown"）が表示される。

**期待されるアクション**：ユーザーはエラー内容を確認し、サーバーの状態を確認するか、管理者に連絡する。

## 通知種別

アプリ内通知（トースト通知 - エラータイプ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（API レスポンス受信時） |
| 優先度 | 高 |
| リトライ | 無（通知自体のリトライはなし） |

### 送信先決定ロジック

- `subscribe-get-login-methods` API の応答に `error` プロパティが含まれる場合に表示
- サーバー URL が設定されている場合のみリクエストが発行される

## 通知テンプレート

### アプリ内通知の場合

| 項目 | 内容 |
|-----|------|
| 通知タイプ | `error` |
| 表示位置 | 画面右下（固定位置） |
| タイムアウト | デフォルト（6500ms） |

### 本文テンプレート

```
Title: Failed to refresh login methods
Message: {data.error || 'Unknown'}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| type | 通知タイプ | 固定値 `error` | Yes |
| title | 通知タイトル | 固定値（i18n対応） | Yes |
| message | エラーメッセージ | `data.error` または `Unknown` | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API レスポンス | subscribe-get-login-methods | 応答に error が含まれる | ServerContext.tsx で検知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `serverURL` が空 | サーバー URL が設定されていない場合はリクエスト自体が発行されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[refreshLoginMethods 呼び出し] --> B{serverURL が設定済み?}
    B -->|No| C[何もしない]
    B -->|Yes| D[subscribe-get-login-methods API 呼び出し]
    D --> E{応答に error が含まれる?}
    E -->|No| F[availableLoginMethods を更新]
    E -->|Yes| G[addNotification dispatch]
    G --> H[availableLoginMethods を空にする]
    H --> I[Notifications コンポーネントで表示]
    C --> J[終了]
    F --> J
    I --> J
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| - | - | 通知表示自体ではDB参照なし |

### 状態更新

エラー発生時は `availableLoginMethods` が空配列にリセットされる。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| サーバー接続エラー | サーバーに到達できない | 通知でエラーを表示、ログインメソッドを空にリセット |
| API エラー | サーバー側でエラー発生 | 通知でエラーメッセージを表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（API エラー発生時に即時表示）

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

- エラーメッセージはサーバーから受信したものをそのまま表示するため、センシティブな情報が含まれないよう、サーバー側での適切なエラーメッセージ設計が必要
- ログインメソッドが取得できない場合、デフォルトで `password` 認証にフォールバックする

## 備考

- この通知は `ServerContext` コンポーネント内で発行される
- `useRefreshLoginMethods` フックを通じて外部から `refreshLoginMethods` を呼び出すことも可能
- マルチユーザー機能が有効な環境でのみ関連性がある

---

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

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

### 推奨読解順序

#### Step 1: ServerContext の構造を理解する

サーバー接続とログインメソッド管理のコンテキストを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ServerContext.tsx | `packages/desktop-client/src/components/ServerContext.tsx` | ServerContextValue 型定義（24-36行目） |

**読解のコツ**: `availableLoginMethods`, `refreshLoginMethods` の役割を理解する。

#### Step 2: refreshLoginMethods の実装を理解する

ログインメソッド取得処理と通知発行処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ServerContext.tsx | `packages/desktop-client/src/components/ServerContext.tsx` | refreshLoginMethods 関数（113-134行目） |

**主要処理フロー**:
1. **113行目**: `useCallback` で `refreshLoginMethods` を定義
2. **114行目**: `serverURL` が存在する場合のみ処理
3. **115-116行目**: `subscribe-get-login-methods` API を呼び出し
4. **117行目**: 応答に `error` が含まれるかチェック
5. **118-126行目**: エラーの場合、`addNotification` で通知を dispatch
6. **127行目**: エラー時は `availableLoginMethods` を空にリセット
7. **128-130行目**: 成功時は `data.methods` で更新

#### Step 3: LoginMethod の利用を理解する

取得したログインメソッドがどのように使用されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ServerContext.tsx | `packages/desktop-client/src/components/ServerContext.tsx` | useLoginMethod フック（63-71行目） |

**読解のコツ**: ログインメソッドが取得できない場合は `password` がデフォルトとして返される。

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

```
ServerContext.tsx
    │
    ├─ ServerProvider コンポーネント
    │      │
    │      ├─ refreshLoginMethods (useCallback)
    │      │      │
    │      │      └─ send('subscribe-get-login-methods')
    │      │             │
    │      │             ├─ (成功) → setAvailableLoginMethods(data.methods)
    │      │             │
    │      │             └─ (エラー) → addNotification dispatch
    │      │                    │
    │      │                    └─ setAvailableLoginMethods([])
    │      │
    │      └─ useEffect (serverURL 変更時)
    │             │
    │             └─ subscribe-needs-bootstrap
    │                    │
    │                    └─ setAvailableLoginMethods(data.availableLoginMethods)
    │
Notifications.tsx
    │
    └─ エラー通知表示
```

### データフロー図

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

サーバー URL ─────────────────▶ refreshLoginMethods() ─────────▶ API 呼び出し
                                       │
                                       ├─▶ (成功)
                                       │      └─▶ availableLoginMethods 更新
                                       │
                                       └─▶ (エラー)
                                              ├─▶ addNotification dispatch
                                              │      └─▶ 通知表示
                                              │
                                              └─▶ availableLoginMethods = []
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ServerContext.tsx | `packages/desktop-client/src/components/ServerContext.tsx` | ソース | サーバー接続・ログインメソッド管理 |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の Redux slice 定義 |
| Notifications.tsx | `packages/desktop-client/src/components/Notifications.tsx` | ソース | 通知表示コンポーネント |
| Login.tsx | `packages/desktop-client/src/components/manager/subscribe/Login.tsx` | ソース | ログイン画面（ログインメソッドを使用） |
