# 画面設計書 218-タイムライン変換

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「タイムライン変換」機能（ConvertTo-DbaTimeline）の画面設計書です。SQL Server Agent ジョブ履歴やバックアップ履歴をインタラクティブなHTML形式のタイムライン可視化に変換する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者やDBAは、ジョブの実行スケジュール、バックアップウィンドウ、重複する操作などを視覚的に分析する必要があります。ConvertTo-DbaTimelineは、Get-DbaAgentJobHistoryやGet-DbaDbBackupHistoryの出力をGoogle Chartsを使用したインタラクティブなタイムラインHTMLに変換し、ブラウザで確認できるレポートを生成します。

**画面へのアクセス方法**：PowerShellコンソールからGet-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの出力を `ConvertTo-DbaTimeline` にパイプで渡して実行します。

**主要な操作・処理内容**：
1. Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの出力を受け取る
2. 入力データタイプを判定（AgentJobHistory/BackupHistory）
3. データをGoogle Chartsタイムライン形式に変換
4. 完全なHTMLドキュメントを生成（jQuery、Bootstrap、Google Charts含む）
5. 文字列として出力（Out-Fileでファイル保存可能）

**画面遷移**：CLIコマンドのため画面遷移はありません。生成されたHTMLをブラウザで開くことで可視化を確認できます。

**権限による表示制御**：特別な権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 150 | ConvertTo-DbaTimeline | 主機能 | タイムライン可視化変換 |
| 233 | Get-DbaAgentJobHistory | 入力元 | ジョブ実行履歴取得 |
| 228 | Get-DbaDbBackupHistory | 入力元 | バックアップ履歴取得 |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# ジョブ履歴のタイムライン
Get-DbaAgentJobHistory -SqlInstance sql-1 -StartDate '2018-08-13 00:00' -EndDate '2018-08-13 23:59' -ExcludeJobSteps | ConvertTo-DbaTimeline | Out-File C:\temp\jobs.html -Encoding ASCII

# バックアップ履歴のタイムライン
Get-DbaDbBackupHistory -SqlInstance sql2017, sql2016 -Since '2018-08-13 00:00' | ConvertTo-DbaTimeline | Out-File C:\temp\backups.html -Encoding ASCII
```

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| InputObject | object[] | Yes | - | Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの出力 |
| ExcludeRowLabel | switch | No | $false | 行ラベルを非表示にする |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| - | string[] | HTMLコード（3つの文字列要素：ヘッダー、ボディ、フッター） |

### 生成されるタイムラインの要素

| 要素 | 説明 |
|------|------|
| 水平バー | 実行時間の長さを示す |
| ステータス色 | 成功/失敗などのステータスを色分け |
| ホバーツールチップ | アイテム名、ステータス、開始/終了時刻、所要時間を表示 |
| 行ラベル | [インスタンス名] ジョブ名/データベース名 |

## イベント仕様

### 1-コマンド実行時

1. beginブロック:
   - HTMLヘッダー（jQuery、Bootstrap、Google Charts、CSS）を生成
   - Google Chartsタイムライン初期化コードを生成
2. processブロック:
   - サーバーリストを作成（複数インスタンス対応）
   - 入力データタイプを判定:
     - TypeName == 'AgentJobHistory': ジョブ履歴として処理
     - BackupHistory型: バックアップ履歴として処理
     - その他: エラーメッセージ
   - データをタイムライン形式に変換
   - ConvertTo-JsDateで日時をJavaScript形式に変換
   - Convert-DbaTimelineStatusColorでステータスを色に変換
3. endブロック:
   - 単一インスタンスの場合、インスタンス名ラベルを削除
   - HTMLフッター（チャート描画コード）を生成
   - begin, body, endの3要素を出力

## データベース更新仕様

このコマンドはデータベースを更新しません。データ変換のみを行います。

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| エラー | Unsupported input data. To request support for additional commands... | サポートされていない入力タイプの場合 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| 未サポートの入力データタイプ | Stop-Functionでエラーを報告 |

## 備考

- サポートされる入力: Get-DbaAgentJobHistory、Get-DbaDbBackupHistoryの出力のみ
- 出力はOut-File -Encoding ASCIIで保存することを推奨
- 生成されたHTMLはインターネット接続が必要（jQuery、Bootstrap、Google Charts CDN）
- 複数インスタンスからのデータを統合可能
- ExcludeRowLabelでチャートスペースを最大化可能
- メールでの送信は一部のメールクライアントでサポートされない場合あり

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | 出力構造（行238：begin, body, end） |

**読解のコツ**: 出力は3つの文字列要素（begin, body, end）で構成され、これらを結合すると完全なHTMLドキュメントになります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | パラメータ定義（行80-85）と3つのブロック構造 |

**主要処理フロー**:
1. **行86-149**: beginブロックでHTMLヘッダーとGoogle Charts初期化コードを生成
2. **行151-173**: processブロックで入力データを判定・変換
3. **行161-163**: AgentJobHistory処理（Convert-DbaTimelineStatusColor使用）
4. **行164-166**: BackupHistory処理
5. **行174-239**: endブロックでHTMLフッターとチャート描画コードを生成

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

```
ConvertTo-DbaTimeline
    |
    +-- beginブロック
    |      +-- HTMLヘッダー生成（jQuery, Bootstrap, Google Charts）
    |      +-- CSS定義
    |      +-- Google Chartsタイムライン初期化
    |
    +-- processブロック
    |      +-- 入力タイプ判定（AgentJobHistory / BackupHistory）
    |      +-- ConvertTo-JsDate（日時変換）
    |      +-- Convert-DbaTimelineStatusColor（ステータス色変換）
    |      +-- データ行生成
    |
    +-- endブロック
           +-- 単一インスタンス時のラベル調整
           +-- HTMLフッター生成
           +-- チャート描画コード
           +-- 出力（begin, body, end）
```

### データフロー図

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

Get-DbaAgentJobHistory ──▶ TypeName判定 ──────────────▶ ジョブ履歴処理
      |
      v
                    vLabel（行ラベル）生成 ────────▶ [Instance] JobName
                    hLabel（ステータス）生成 ──────▶ Success/Failed
                    Style（色）生成 ────────────────▶ Convert-DbaTimelineStatusColor
                    日時変換 ──────────────────────▶ ConvertTo-JsDate
      |
      v
Get-DbaDbBackupHistory ──▶ 型判定 ───────────────────▶ バックアップ履歴処理
      |
      v
                    vLabel（行ラベル）生成 ────────▶ [Instance] Database
                    hLabel（タイプ）生成 ──────────▶ Full/Diff/Log
      |
      v
                    HTML生成 ──────────────────────▶ 完全なHTMLドキュメント
                           |
                           +── begin（ヘッダー/スクリプト）
                           +── body（データ行）
                           +── end（フッター/描画コード）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | ソース | メインコマンド実装 |
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | 入力元 | ジョブ履歴取得 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | 入力元 | バックアップ履歴取得 |

### 生成されるHTML構造

```html
<html>
<head>
    <!-- jQuery、Bootstrap、Google Charts CDN -->
    <style>/* カスタムCSS */</style>
    <script>
        google.charts.load('43', {'packages':['timeline']});
        google.charts.setOnLoadCallback(drawChart);
        function drawChart() {
            // DataTable作成
            dataTable.addRows([
                // タイムラインデータ行
            ]);
            // チャート描画
        }
    </script>
</head>
<body>
    <div class="container-fluid">
        <h3>タイトル</h3>
        <div id="Chart"></div>
        <p>フッター</p>
    </div>
</body>
</html>
```
