# 機能設計書 79-ConvertTo-DbaTimeline

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `ConvertTo-DbaTimeline` コマンドレットに関する機能設計書です。このコマンドは、SQL Serverのジョブ履歴やバックアップ履歴データからインタラクティブなHTMLタイムライン可視化を生成します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのジョブ実行履歴やバックアップ操作を視覚的に分析することで、スケジュールの重複確認、バックアップウィンドウの特定、実行時間の傾向分析が容易になります。本機能は、Google Chartsを使用したインタラクティブなHTMLタイムラインを生成し、DBAやマネージメントへの視覚的なレポートを提供します。

**機能の利用シーン**：
- ジョブスケジュールの可視化と重複確認
- バックアップウィンドウの分析
- パフォーマンス問題のトラブルシューティング
- マネージメント向けの視覚的レポート作成
- 複数インスタンスの処理タイミング比較
- 履歴データのアーカイブと分析

**主要な処理内容**：
1. Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryからのパイプライン入力受け取り
2. 入力データタイプの自動検出
3. Google Charts Timeline用のデータ変換
4. ステータスに基づく色分け
5. 完全なHTMLドキュメントの生成

**関連システム・外部連携**：Google Charts API（クライアント側でロード）、jQuery、Bootstrap

**権限による制御**：入力データの取得に必要な権限（ソースコマンドに依存）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコンソールから実行してHTMLファイルを生成 |

## 機能種別

レポート生成 / 可視化 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| InputObject | object[] | Yes | 入力データ | パイプライン入力のみ |
| ExcludeRowLabel | switch | No | 行ラベルを非表示 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- パイプライン入力のみ
- 対応するコマンド:
  - Get-DbaAgentJobHistory（TypeName = 'AgentJobHistory'）
  - Get-DbaDbBackupHistory（Dataplat.Dbatools.Database.BackupHistory型）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| HTML | string[] | 3つの文字列要素（ヘッダー、ボディ、フッター）として出力 |

### 出力先

- PowerShellパイプライン（string[]）
- 通常はOut-FileでHTMLファイルとして保存
- Send-MailMessageでメール送信も可能

### 生成されるHTMLの構成

1. **ヘッダー部分**: jQuery、Bootstrap、Google Charts、カスタムCSSの読み込み
2. **ボディ部分**: タイムラインデータ行
3. **フッター部分**: チャート描画JavaScript、HTMLの閉じタグ

## 処理フロー

### 処理シーケンス

```
1. beginブロック：HTMLヘッダーの構築
   └─ jQuery、Bootstrap、Google Chartsの参照
   └─ カスタムCSSスタイル
   └─ Chart描画関数の開始
2. processブロック：データ変換
   └─ サーバーリストの構築（複数インスタンス対応）
   └─ 入力タイプの検出（AgentJobHistory or BackupHistory）
   └─ データ行のJavaScript配列形式への変換
3. endブロック：HTML終了部分の構築
   └─ 単一インスタンスの場合はラベルからインスタンス名を削除
   └─ ツールチップ、日付フォーマット、チャートオプション
   └─ オートサイズロジック
   └─ HTML閉じタグ
4. 3つの文字列として出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[beginブロック:HTMLヘッダー構築]
    B --> C[processブロック:データ変換]
    C --> D{入力タイプ?}
    D -->|AgentJobHistory| E[ジョブ履歴データ変換]
    D -->|BackupHistory| F[バックアップ履歴データ変換]
    D -->|その他| G[Stop-Function:サポート外]
    E --> H[サーバーリスト更新]
    F --> H
    H --> I{次のデータ?}
    I -->|Yes| C
    I -->|No| J[endブロック:HTML終了部構築]
    J --> K{サーバー1台?}
    K -->|Yes| L[インスタンス名ラベル削除]
    K -->|No| M[ラベル保持]
    L --> N[HTMLフッター構築]
    M --> N
    N --> O[3文字列出力]
    O --> P[終了]
    G --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-01 | 自動タイプ検出 | 入力データのTypeNameまたは型で処理を分岐 | 常時 |
| BR-79-02 | 単一インスタンス最適化 | サーバー1台の場合はラベルからインスタンス名を削除 | servers.count = 1 |
| BR-79-03 | ステータス色分け | Convert-DbaTimelineStatusColorで色を決定 | AgentJobHistory時 |
| BR-79-04 | 自動サイズ調整 | jQueryでチャート高さを自動調整 | 常時 |

### 計算ロジック

- **期間計算**: 開始日時と終了日時の差分を秒単位で計算し、時分秒に変換
- **日付変換**: ConvertTo-JsDateでPowerShell日時をJavaScript日時に変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | なし | データベース操作は行わない |

### 備考

- 本コマンドはデータ変換のみを行い、データベースには直接アクセスしない
- 入力データは別のコマンド（Get-DbaAgentJobHistory等）から取得

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UnsupportedInput | 入力エラー | サポート外のデータタイプ | Stop-Functionでメッセージ表示 |

### リトライ仕様

- リトライ機能なし

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

- トランザクション不要（データ変換のみ）

## パフォーマンス要件

- 大量のデータではHTML生成に時間がかかる可能性
- ブラウザでの描画パフォーマンスはデータ量に依存

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

- 生成されたHTMLは外部CDN（Google Charts、jQuery、Bootstrap）を参照
- オフライン環境では正しく表示されない可能性

## 備考

- 著者: Marcin Gminski (@marcingminski)
- 依存関数: ConvertTo-JsDate, Convert-DbaTimelineStatusColor
- 外部依存: Google Charts、jQuery 3.3.1、Bootstrap 3.3.7

---

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

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

### 推奨読解順序

#### Step 1: コマンドの全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | begin/process/endの3フェーズ構造、HTMLテンプレート |

**読解のコツ**: Here-String（@"..."@）を多用してHTMLテンプレートを構築している点に注目。

#### Step 2: beginブロック - HTMLヘッダー構築

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | 86-149行目：$begin変数にHTMLヘッダーを格納 |

**主要処理フロー**:
1. **87-88行目**: 変数初期化
2. **88-148行目**: Here-Stringで完全なHTMLヘッダー（CSS、JavaScript含む）を構築

#### Step 3: processブロック - データ変換

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | 151-173行目：入力タイプ検出とデータ変換 |

**主要処理フロー**:
- **152-155行目**: サーバーリストの構築
- **161-163行目**: AgentJobHistory時のデータ変換（ステータス色分け含む）
- **164-166行目**: BackupHistory時のデータ変換
- **167-171行目**: サポート外タイプのエラー処理
- **172行目**: bodyへのデータ行追加

#### Step 4: endブロック - HTMLフッター構築

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | 174-239行目：$end変数にHTMLフッターを格納 |

**主要処理フロー**:
- **175行目**: Test-FunctionInterruptチェック
- **176-179行目**: 単一サーバーの場合のラベル最適化
- **180-237行目**: Here-Stringでチャート描画JavaScript、HTML閉じタグを構築
- **238行目**: 3つの文字列（$begin, $body, $end）を出力

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

```
ConvertTo-DbaTimeline
    │
    ├─ ConvertTo-JsDate (内部関数)
    │      └─ PowerShell日時をJavaScript日時に変換
    │
    ├─ Convert-DbaTimelineStatusColor (内部関数)
    │      └─ ジョブステータスを色コードに変換
    │
    ├─ Test-FunctionInterrupt (内部関数)
    │      └─ 中断フラグチェック
    │
    └─ Stop-Function (dbatools内部関数)
           └─ エラーハンドリング
```

### データフロー図

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

InputObject ───▶ タイプ検出 ──────────────▶ 変換ロジック選択
    │                   │
    ├─ AgentJobHistory ──▶ Select-Object ──────▶ データ行
    │                         │
    │                   Convert-DbaTimelineStatusColor
    │                         │
    └─ BackupHistory ────▶ Select-Object ──────▶ データ行
                              │
                        ConvertTo-JsDate
                              │
                        HTMLテンプレート結合 ───▶ string[] (3要素)
                              │
                              ├─ $begin (ヘッダー)
                              ├─ $body (データ行)
                              └─ $end (フッター)
                                    │
                              Out-File ───────▶ HTMLファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | ソース | メインコマンド実装 |
| ConvertTo-DbaTimeline.Tests.ps1 | `tests/ConvertTo-DbaTimeline.Tests.ps1` | テスト | Pester v5テストファイル |
| ConvertTo-JsDate.ps1 | `private/functions/ConvertTo-JsDate.ps1` | ソース | 日付変換ヘルパー |
| Convert-DbaTimelineStatusColor.ps1 | `private/functions/Convert-DbaTimelineStatusColor.ps1` | ソース | 色変換ヘルパー |
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | ソース | ジョブ履歴取得（入力ソース） |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得（入力ソース） |
