# 機能設計書 54-ヘルスチェック

## 概要

本ドキュメントは、Actual Budget同期サーバーにおけるヘルスチェック機能の設計を記述する。この機能は、サーバーの稼働状態を確認するためのエンドポイントを提供し、監視システムやロードバランサーからの死活監視に対応する。

### 本機能の処理概要

Actual Budget同期サーバーが正常に稼働しているかを確認するためのHTTPエンドポイントを提供する機能である。シンプルなJSON形式のレスポンスを返すことで、外部の監視システムやKubernetesなどのコンテナオーケストレーションツールからの死活監視を可能にする。

**業務上の目的・背景**：サーバーの可用性を維持するためには、サーバーの稼働状態を常に監視し、問題発生時に迅速に対応する必要がある。ヘルスチェックエンドポイントを提供することで、自動化された監視・復旧システムとの連携が可能になる。

**機能の利用シーン**：
- Kubernetesのliveness/readinessプローブ
- ロードバランサーからの死活監視
- 監視ツール（Prometheus、Datadog等）からのヘルスチェック
- デスクトップアプリからのサーバー接続確認

**主要な処理内容**：
1. GET /health エンドポイントへのリクエスト受信
2. ステータス情報のJSON形式での返却
3. GET /info エンドポイントによるサーバー情報提供
4. GET /metrics エンドポイントによるメトリクス提供

**関連システム・外部連携**：監視システム、ロードバランサー、コンテナオーケストレーションツール

**権限による制御**：ヘルスチェックエンドポイントは認証不要（パブリックアクセス可能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ブートストラップ画面 | 補助機能 | サーバー接続状態の確認処理 |
| 6 | サーバー設定画面 | 補助機能 | 設定変更後のサーバー接続確認 |

## 機能種別

サーバー機能 / 監視・運用

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータ不要 | - |

### 入力データソース

HTTPリクエスト（GETメソッド）

## 出力仕様

### 出力データ（/health）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| status | string | サーバー状態（"UP"） |

### 出力データ（/info）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| build.name | string | パッケージ名 |
| build.description | string | パッケージ説明 |
| build.version | string | バージョン番号 |

### 出力データ（/metrics）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| mem | object | メモリ使用状況 |
| uptime | number | サーバー起動時間（秒） |

### 出力先

HTTPレスポンス（JSON形式）

## 処理フロー

### 処理シーケンス

```
1. ヘルスチェックリクエスト受信
   └─ GET /health, /info, または /metrics

2. レスポンス生成
   ├─ /health: 固定のステータスオブジェクト
   ├─ /info: package.jsonからの情報取得
   └─ /metrics: process.memoryUsage() と process.uptime()

3. JSONレスポンス送信
   └─ HTTP 200 OK
```

### フローチャート

```mermaid
flowchart TD
    A[GET /health] --> B[status: UP を返却]
    B --> C[HTTP 200 OK]

    D[GET /info] --> E[package.json検索]
    E --> F{見つかった?}
    F -->|Yes| G[build情報を返却]
    F -->|No| H[null値を返却]
    G --> C
    H --> C

    I[GET /metrics] --> J[メモリ使用量取得]
    J --> K[起動時間取得]
    K --> L[メトリクス返却]
    L --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-1 | 認証不要 | ヘルスチェックエンドポイントは認証なしでアクセス可能 | 常時 |
| BR-54-2 | 常にUP | /healthは正常時常に"UP"を返す | サーバー稼働時 |
| BR-54-3 | package.json検索 | /infoはディレクトリを遡ってpackage.jsonを検索 | /info アクセス時 |

### 計算ロジック

特になし

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

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

この機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続不可 | サーバーダウン時 | 監視システムでアラート発報 |

### リトライ仕様

この機能自体にリトライロジックはない。クライアント側で必要に応じてリトライを実装。

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

トランザクション処理なし

## パフォーマンス要件

- レスポンス時間：10ms以内
- 同時接続数：制限なし（レート制限の対象外）

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

- 認証不要のため、機密情報は含まない
- /metricsは詳細情報を含むため、必要に応じてアクセス制限を検討

## 備考

- Kubernetesのliveness probeとして使用可能
- 監視システムからの頻繁なアクセスを想定した軽量実装

---

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

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

### 推奨読解順序

#### Step 1: エンドポイント定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | app.ts | `packages/sync-server/src/app.ts` | 各ヘルスチェックエンドポイントの定義 |

**読解のコツ**: Express.jsのルーティング定義パターンを理解しておくと、エンドポイントの構造が把握しやすい。

**主要処理フロー**:
- **71-73行目**: GET /mode エンドポイント
- **75-114行目**: GET /info エンドポイント
- **116-118行目**: GET /health エンドポイント
- **120-125行目**: GET /metrics エンドポイント

#### Step 2: /health エンドポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | app.ts | `packages/sync-server/src/app.ts` | 116-118行目：/health実装 |

**主要処理フロー**:
- **116行目**: GET /health ルート定義
- **117行目**: HTTP 200ステータス設定
- **117行目**: { status: 'UP' } をJSONで返却

#### Step 3: /info エンドポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | app.ts | `packages/sync-server/src/app.ts` | 75-114行目：/info実装 |

**主要処理フロー**:
- **76-102行目**: findPackageJson関数（親ディレクトリを遡って検索）
- **104-105行目**: 現在のディレクトリから検索開始
- **107-113行目**: build情報を返却

#### Step 4: /metrics エンドポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | app.ts | `packages/sync-server/src/app.ts` | 120-125行目：/metrics実装 |

**主要処理フロー**:
- **121行目**: process.memoryUsage()でメモリ情報取得
- **122行目**: process.uptime()で起動時間取得

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

```
app.ts (Express Server)
    │
    ├─ GET /health
    │      └─ res.json({ status: 'UP' })
    │
    ├─ GET /info
    │      │
    │      ├─ findPackageJson()
    │      │      └─ fs.existsSync() / readFileSync()
    │      │
    │      └─ res.json({ build: {...} })
    │
    └─ GET /metrics
           │
           ├─ process.memoryUsage()
           ├─ process.uptime()
           │
           └─ res.json({ mem, uptime })
```

### データフロー図

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

監視システム ───▶ GET /health ───▶ { status: 'UP' }
                      │
                      ▼
                 HTTP 200 OK
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| app.ts | `packages/sync-server/src/app.ts` | ソース | ヘルスチェックエンドポイント定義 |
| package.json | `packages/sync-server/package.json` | 設定 | /infoで参照するパッケージ情報 |
