# 機能設計書 44-バックエンドステータス監視

## 概要

本ドキュメントは、Decap CMSのバックエンドステータス監視機能（`packages/decap-cms-core/src/actions/status.ts`）の設計を記述する。バックエンドAPIの死活状態と認証状態を定期的に確認し、異常時にユーザーへ通知する機能である。

### 本機能の処理概要

**業務上の目的・背景**：CMSの操作中にバックエンドAPI（GitHub、GitLab等）がダウンしたり、認証トークンが期限切れになったりした場合、ユーザーが気づかずに作業を続けてデータ消失するリスクがある。本機能はバックエンドの状態を定期的にポーリングし、問題を早期に検知してユーザーに通知する。

**機能の利用シーン**：CMS使用中にバックグラウンドで定期実行される。APIダウン時やトークン期限切れ時にトースト通知が表示される。APIが復旧した場合は既存のエラー通知が自動消去される。

**主要な処理内容**：
1. 現在のバックエンドの`status()`メソッドを呼び出してAPI状態と認証状態を取得
2. APIがダウンしている場合（`api.status === false`）にエラー通知を表示
3. APIが復旧した場合に既存のバックエンドダウン通知を消去
4. 認証エラーの場合（`auth.status === false`）にログアウト通知を表示
5. 重複通知の防止（同一キーの通知が既に表示されている場合はスキップ）
6. フェッチ中の重複リクエスト防止

**関連システム・外部連携**：各バックエンド実装の`status()`メソッドを呼び出す。GitHub/GitLab/Bitbucket等のAPIステータスページURLも取得可能。

**権限による制御**：特になし。全ユーザーに対して実行される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面共通 | バックグラウンド | バックグラウンドでのステータスポーリングとトースト通知表示 |

## 機能種別

監視・通知

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| state.config | Config | Yes | 現在のCMS設定 | Redux Storeから取得 |
| state.status.isFetching | boolean | Yes | フェッチ中フラグ | - |
| state.notifications.notifications | Notification[] | Yes | 現在の通知一覧 | - |

### 入力データソース

- Redux Store: CMS設定、ステータス状態、通知一覧
- バックエンドAPI: `status()`メソッドのレスポンス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| status.auth.status | boolean | 認証状態（true: 正常、false: 異常） |
| status.api.status | boolean | API状態（true: 正常、false: 異常） |
| status.api.statusPage | string | APIステータスページURL |

### 出力先

- Redux Store: ステータス状態の更新
- 通知システム: トースト通知（エラー）の表示/消去

## 処理フロー

### 処理シーケンス

```
1. checkBackendStatus()呼び出し
   └─ isFetchingチェック（重複防止）
2. statusRequest()ディスパッチ
   └─ isFetching = true
3. backend.status()呼び出し
   └─ バックエンドAPIへのステータス確認
4. APIステータス判定
   └─ api.status === false: エラー通知追加（重複なしの場合）
   └─ api.status === true かつ既存通知あり: 通知消去
5. 認証ステータス判定
   └─ auth.status === false: ログアウト通知追加（重複なしの場合）
6. statusSuccess()ディスパッチ
   └─ ステータスデータをRedux Storeに保存
```

### フローチャート

```mermaid
flowchart TD
    A[checkBackendStatus] --> B{isFetching?}
    B -->|Yes| C[リターン]
    B -->|No| D[statusRequest dispatch]
    D --> E[backend.status 呼び出し]
    E --> F{api.status?}
    F -->|false| G{既存通知あり?}
    G -->|No| H[エラー通知追加]
    G -->|Yes| I[スキップ]
    F -->|true| J{既存ダウン通知あり?}
    J -->|Yes| K[通知消去]
    J -->|No| L[何もしない]
    H --> M{auth.status?}
    I --> M
    K --> M
    L --> M
    M -->|false| N{ログアウト通知あり?}
    N -->|No| O[ログアウト通知追加]
    N -->|Yes| P[スキップ]
    M -->|true| Q[statusSuccess dispatch]
    O --> Q
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-01 | 重複フェッチ防止 | isFetchingがtrueの場合は処理をスキップする | checkBackendStatus呼び出し時 |
| BR-44-02 | 通知重複防止 | 同一キーの通知が既に存在する場合は新規通知を追加しない | APIダウン/認証エラー検出時 |
| BR-44-03 | 復旧時通知消去 | APIが復旧した場合、既存のバックエンドダウン通知を全て消去する | api.status === trueかつ既存通知あり |
| BR-44-04 | 通知キー | APIダウン通知キー: `ui.toast.onBackendDown`、認証エラー通知キー: `ui.toast.onLoggedOut` | 通知作成時 |

### 計算ロジック

特筆すべき計算ロジックなし。

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

本機能はデータベースを操作しない。Redux Storeへの状態更新のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | statusFailure | backend.status()の呼び出しで例外発生 | statusFailureアクションをディスパッチ |

### リトライ仕様

本機能自体にはリトライ機能はない。定期ポーリングにより次回のチェックで再試行される。

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

Redux Storeへの状態更新はReduxの同期メカニズムで制御される。

## パフォーマンス要件

ポーリング間隔は呼び出し元で制御される。バックエンドAPIへのリクエストは軽量なステータスチェックのみ。

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

- 認証トークンの期限切れを検知し、適切にユーザーに通知する
- ステータスチェックはバックエンドの`status()`メソッドに委譲される

## 備考

- アクション定数: `STATUS_REQUEST`、`STATUS_SUCCESS`、`STATUS_FAILURE`
- StatusAction型はこれら3つのアクションのReturnTypeの共用体型

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | status.ts | `packages/decap-cms-core/src/actions/status.ts` | アクション定数（8-10行目）とアクションクリエイター（12-33行目）の戻り値型 |

**読解のコツ**: `as const`を使用したアクションクリエイターパターンに注目。`ReturnType`で型を自動推論し、`StatusAction`共用体型を構成している（97-99行目）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | status.ts | `packages/decap-cms-core/src/actions/status.ts` | checkBackendStatus()関数（35-95行目）が唯一のパブリックなthunkアクション |

**主要処理フロー**:
- **36-41行目**: isFetching重複防止チェック
- **43行目**: statusRequest()ディスパッチ
- **44-45行目**: currentBackendの取得とstatus()呼び出し
- **47-50行目**: 既存のバックエンドダウン通知の検索
- **52-64行目**: APIダウン時の通知処理
- **65-70行目**: API復旧時の通知消去処理
- **72-88行目**: 認証エラー時の通知処理
- **90行目**: statusSuccess()ディスパッチ
- **91-93行目**: エラーキャッチとstatusFailure()ディスパッチ

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

```
checkBackendStatus() [thunk]
    |
    +-- statusRequest()
    |
    +-- currentBackend(state.config)
    |       +-- backend.status()
    |
    +-- [APIダウン時]
    |       +-- addNotification({ key: 'ui.toast.onBackendDown' })
    |
    +-- [API復旧時]
    |       +-- dismissNotification(id) × 既存通知
    |
    +-- [認証エラー時]
    |       +-- addNotification({ key: 'ui.toast.onLoggedOut' })
    |
    +-- statusSuccess(status) / statusFailure(error)
```

### データフロー図

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

Redux State        ──▶  checkBackendStatus()       ──▶  Redux Store
(config, status)         isFetching重複チェック            (status更新)

Backend API        ──▶  backend.status()           ──▶  {auth, api}
(各バックエンド)          ステータス確認                    (状態情報)

ステータス結果     ──▶  通知判定                    ──▶  通知システム
(auth/api)               重複チェック + 復旧チェック       (トースト表示/消去)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| status.ts | `packages/decap-cms-core/src/actions/status.ts` | ソース | ステータス監視アクション |
| notifications.ts | `packages/decap-cms-core/src/actions/notifications.ts` | ソース | 通知追加/消去アクション |
| backend.ts | `packages/decap-cms-core/src/backend.ts` | ソース | currentBackend取得 |
