# バッチ設計書 5-health-check

## 概要

本ドキュメントは、Actual Budget同期サーバーの稼働状態を確認するヘルスチェックスクリプト「health-check」の設計仕様を記載したものです。

### 本バッチの処理概要

このバッチは、同期サーバーの`/health`エンドポイントにHTTPリクエストを送信し、サーバーが正常に稼働しているかを確認します。レスポンスのステータスが「UP」であることを検証します。

**業務上の目的・背景**：サーバーの監視・運用において、ヘルスチェックは不可欠な機能です。コンテナオーケストレーション（Docker、Kubernetes等）でのLiveness/Readiness Probe、ロードバランサーのヘルスチェック、監視システムからの定期的な死活監視など、様々なユースケースで利用されます。このスクリプトを使用することで、外部ツールからサーバーの稼働状態を確認し、異常時には適切な対応（コンテナ再起動、アラート通知等）を自動化できます。

**バッチの実行タイミング**：手動実行または自動化された監視システムからの定期実行が想定されます。Dockerコンテナ環境ではHEALTHCHECKインストラクションから呼び出されることがあります。

**主要な処理内容**：
1. 設定ファイルからプロトコル（HTTP/HTTPS）を判定
2. 設定ファイルからホスト名とポートを取得
3. `/health`エンドポイントにfetchリクエストを送信
4. レスポンスJSONの`status`フィールドが「UP」かを確認
5. 異常時はエラーメッセージを出力してexit 1

**前後の処理との関連**：サーバーアプリケーションが起動している状態で実行されます。サーバーが起動していない場合や異常がある場合はエラーとなります。

**影響範囲**：サーバーへの読み取り専用リクエストのみで、データの変更は行いません。

## バッチ種別

サーバー管理 / 監視

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 / 定期（監視間隔に依存） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / 監視システム / Docker HEALTHCHECK |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| サーバー起動中 | Actual Budget同期サーバーが稼働していること |
| ビルド完了 | `yarn build`によりTypeScriptがコンパイル済みであること |
| ネットワーク接続 | サーバーへのネットワーク接続が可能であること |

### 実行可否判定

常に実行可能。サーバーが応答しない場合はエラーとして検知されます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | パラメータは設定ファイルから取得 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config.json | JSON | サーバー設定（hostname, port, https設定） |
| 環境変数 | 文字列 | ACTUAL_*形式の設定 |

### 設定項目

| 設定項目 | 説明 | デフォルト値 |
|---------|------|------------|
| hostname | サーバーホスト名 | :: |
| port | サーバーポート | 5006 |
| https.key | HTTPS証明書キー | なし |
| https.cert | HTTPS証明書 | なし |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | エラーメッセージ（異常時のみ） |
| 終了コード | 数値 | 0: 正常、1: 異常 |

### 出力ファイル仕様

該当なし

## 処理フロー

### 処理シーケンス

```
1. プロトコル判定
   └─ https.keyとhttps.certが設定されていればHTTPS、なければHTTP
2. ホスト名取得
   └─ hostname設定を取得（「::」の場合は「localhost」に変換）
3. URLエンドポイント構築
   └─ {protocol}://{hostname}:{port}/health
4. HTTPリクエスト送信
   └─ fetch()でGETリクエスト
5. レスポンス検証
   ├─ JSONパース
   └─ status === 'UP'を確認
6. 結果処理
   ├─ 正常: 正常終了（exit 0）
   └─ 異常: エラー出力してexit 1
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{HTTPS設定あり?}
    B -->|Yes| C[protocol = https]
    B -->|No| D[protocol = http]
    C --> E[hostname取得]
    D --> E
    E --> F{hostname == '::'?}
    F -->|Yes| G[hostname = localhost]
    F -->|No| H[設定値使用]
    G --> I[URL構築]
    H --> I
    I --> J[fetch実行]
    J --> K{リクエスト成功?}
    K -->|No| L[エラー出力]
    L --> M[exit 1]
    K -->|Yes| N[JSONパース]
    N --> O{status == 'UP'?}
    O -->|Yes| P[正常終了 exit 0]
    O -->|No| Q[ステータスエラー出力]
    Q --> M
```

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

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

該当なし。ヘルスチェックはデータベースに対する操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | network-error | サーバーへの接続失敗 | サーバーの起動状態を確認 |
| 1 | status-error | status !== 'UP' | サーバーログを確認 |

### リトライ仕様

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

### 障害時対応

1. ネットワークエラーの場合：サーバープロセスの起動状態を確認
2. ステータスエラーの場合：サーバーアプリケーションログを確認
3. HTTPS接続エラーの場合：証明書設定を確認

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

該当なし。データベース操作を行わないため。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1リクエスト |
| 目標処理時間 | 1秒以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

排他制御なし。読み取り専用の操作のため、同時実行可能です。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | 異常時 | 「Health check failed:」+ エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | 監視システム / Docker HEALTHCHECK |
| 応答時間 | タイムアウト | 監視システム |

## 備考

- 実行コマンド: `yarn health-check`
- `/health`エンドポイントは、サーバーが正常な場合`{ "status": "UP" }`を返す
- hostname設定が「::」（IPv6ワイルドカード）の場合、「localhost」に変換される
- HTTPS設定（https.key, https.cert）が両方設定されている場合のみHTTPSを使用
- Docker環境でのHEALTHCHECKやKubernetesのProbeとして利用可能
