# 機能設計書 356-Test-DbaDbLogShipStatus

## 概要

本ドキュメントは、ログシッピング監視インスタンスからログシッピングの稼働状況と健全性情報を取得する `Test-DbaDbLogShipStatus` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、ログシッピング監視システムに接続し、プライマリおよびセカンダリインスタンスのバックアップ、コピー、リストア各操作の状態を確認する。閾値を超過した遅延や失敗を検出し、ステータスレポートを出力する。

**業務上の目的・背景**：ログシッピング環境の継続的な監視は、RPO/RTO目標の達成に不可欠である。バックアップの遅延、ファイルコピーの失敗、リストアの停滞などを早期に検出することで、災害時のデータ損失を最小化できる。本機能により、監視インスタンスから一括でステータスを取得し、問題のあるデータベースを特定できる。

**機能の利用シーン**：
- 定期的なログシッピング健全性チェック
- 障害発生時のステータス確認
- ダッシュボード向けステータスデータ取得
- 監視システムとの連携

**主要な処理内容**：
1. 監視インスタンスへの接続
2. sp_help_log_shipping_monitor ストアドプロシージャの実行
3. 結果を一時テーブルに格納
4. Database/ExcludeDatabase フィルタの適用
5. Primary/Secondary フィルタの適用
6. 閾値超過の判定とステータスメッセージ生成
7. 結果オブジェクトの出力

**関連システム・外部連携**：ログシッピング監視インスタンス、sys.sp_help_log_shipping_monitor

**権限による制御**：sysadmin権限が必要。Express Editionは非対応。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

ステータス監視 / 健全性チェック

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 監視インスタンス | - |
| SqlCredential | PSCredential | No | 認証情報 | - |
| Database | String[] | No | 対象データベース名 | - |
| ExcludeDatabase | String[] | No | 除外データベース名 | - |
| Simple | Switch | No | 簡易出力モード | - |
| Primary | Switch | No | プライマリのみ表示 | - |
| Secondary | Switch | No | セカンダリのみ表示 | - |
| EnableException | Switch | No | 例外制御 | - |

### 入力データソース

- sys.sp_help_log_shipping_monitor ストアドプロシージャ

## 出力仕様

### 出力データ

#### 標準出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| InstanceName | String | インスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| Database | String | データベース名 |
| InstanceType | String | Primary Instance / Secondary Instance |
| TimeSinceLastBackup | DateTime | 最終バックアップからの経過時間 |
| LastBackupFile | String | 最終バックアップファイル名 |
| BackupThreshold | Int | バックアップ閾値（分） |
| IsBackupAlertEnabled | Boolean | バックアップアラート有効 |
| TimeSinceLastCopy | DateTime | 最終コピーからの経過時間 |
| LastCopiedFile | String | 最終コピーファイル名 |
| TimeSinceLastRestore | DateTime | 最終リストアからの経過時間 |
| LastRestoredFile | String | 最終リストアファイル名 |
| LastRestoredLatency | Int | リストアレイテンシ（秒） |
| RestoreThreshold | Int | リストア閾値（分） |
| IsRestoreAlertEnabled | Boolean | リストアアラート有効 |
| Status | String | ステータスメッセージ |

#### Simple出力（-Simple指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | String | 完全なインスタンス名 |
| Database | String | データベース名 |
| InstanceType | String | Primary Instance / Secondary Instance |
| Status | String | ステータスメッセージ |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. クエリ構築（beginブロック）
   ├─ 一時テーブル #logshippingstatus 作成
   ├─ sp_help_log_shipping_monitor 実行結果を挿入
   └─ Database/ExcludeDatabase フィルタ用WHERE句構築

2. インスタンス接続（processブロック）
   └─ Connect-DbaInstance（MinimumVersion 9）

3. Express Editionチェック
   └─ 非対応の場合は警告出力してスキップ

4. Primary/Secondary 同時指定チェック
   └─ 両方指定はエラー

5. クエリ実行
   └─ 一時テーブル取得クエリ実行

6. Primary/Secondary フィルタ適用

7. 各結果の処理
   ├─ ステータス判定（閾値超過チェック）
   ├─ 時間計算（現在時刻 - 分数）
   └─ PSCustomObject生成

8. 出力
   ├─ -Simple: 4項目のみ出力
   └─ 通常: 全項目出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[クエリ構築]
    B --> C[インスタンスループ開始]
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[エラー、次へ]
    E -->|Yes| G{Express Edition?}
    G -->|Yes| H[警告、スキップ]
    G -->|No| I{Primary AND Secondary?}
    I -->|Yes| J[エラー: 排他パラメータ]
    I -->|No| K[クエリ実行]
    K --> L{結果あり?}
    L -->|No| M[エラー: データなし]
    L -->|Yes| N[Primary/Secondaryフィルタ]
    N --> O[結果ループ開始]
    O --> P{Status判定}
    P -->|問題あり| Q[ステータスメッセージ生成]
    P -->|問題なし| R[All OK設定]
    Q --> S[時間計算]
    R --> S
    S --> T[PSCustomObject生成]
    T --> U{-Simple?}
    U -->|Yes| V[4項目出力]
    U -->|No| W[全項目出力]
    V --> X{次の結果?}
    W --> X
    X -->|Yes| O
    X -->|No| Y{次のインスタンス?}
    F --> Y
    H --> Y
    J --> Y
    M --> Y
    Y -->|Yes| C
    Y -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL Server 2005以上必須 | MinimumVersion 9 | 常時 |
| BR-002 | Express Edition非対応 | 警告出力してスキップ | Express Edition時 |
| BR-003 | Primary/Secondary排他 | 両方同時指定はエラー | パラメータ検証時 |
| BR-004 | 閾値超過判定 | TimeSince >= Threshold で警告 | ステータス判定時 |

### 計算ロジック

- TimeSinceLastBackup = 現在時刻 - TimeSinceLastBackup（分）
- TimeSinceLastCopy = 現在時刻 - TimeSinceLastCopy（分）
- TimeSinceLastRestore = 現在時刻 - TimeSinceLastRestore（分）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ステータス取得 | sys.sp_help_log_shipping_monitor | EXEC | 監視データ取得 |
| 一時テーブル | #logshippingstatus | CREATE/INSERT/SELECT/DROP | 結果格納 |

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

#### #logshippingstatus（一時テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE | Status, IsPrimary, Server, DatabaseName, TimeSinceLastBackup等 | sp_help_log_shipping_monitorから取得 | 16カラム |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Stop-Function、continue |
| ExpressEdition | 機能非対応 | Express Edition | 警告、continue |
| InvalidParameter | パラメータエラー | Primary AND Secondary | Stop-Function、continue |
| NoData | データなし | ログシッピング未構成 | Stop-Function、continue |

### リトライ仕様

リトライ処理なし。

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

読み取り専用。一時テーブルはセッション内で完結。

## パフォーマンス要件

- sp_help_log_shipping_monitor の実行時間に依存

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

- sysadmin権限が必要

## 備考

- 監視インスタンスに接続する必要がある（プライマリ/セカンダリとは別の場合あり）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDbLogShipStatus.ps1 | `public/Test-DbaDbLogShipStatus.ps1` | 一時テーブル構造（145-162行目） |

**読解のコツ**: sp_help_log_shipping_monitor の出力形式を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDbLogShipStatus.ps1 | `public/Test-DbaDbLogShipStatus.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **124-135行目**: パラメータ定義
2. **137-199行目**: beginブロック（クエリ構築）
3. **202-227行目**: インスタンス接続とバリデーション
4. **239-289行目**: ステータス判定ロジック
5. **291-316行目**: PSCustomObject生成と出力

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

```
Test-DbaDbLogShipStatus
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │
    ├─ $server.Query($sql)
    │      ├─ CREATE TABLE #logshippingstatus
    │      ├─ INSERT INTO (sp_help_log_shipping_monitor)
    │      ├─ SELECT FROM #logshippingstatus
    │      └─ DROP TABLE #logshippingstatus
    │
    └─ Select-DefaultView (-Simple時)
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance
                         │
                         ▼
              sp_help_log_shipping_monitor実行
                         │
                         ▼
              フィルタ適用
              (Database/Primary/Secondary)
                         │
                         ▼
              ステータス判定
              (閾値超過チェック)
                         │
                         ▼
              時間計算 ───▶ PSCustomObject
              (現在時刻-分数)     │
                                 ├─ Standard: 17項目
                                 └─ Simple: 4項目
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDbLogShipStatus.ps1 | `public/Test-DbaDbLogShipStatus.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
