# 帳票設計書 3-ConvertTo-DbaTimeline

## 概要

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

### 本帳票の処理概要

ConvertTo-DbaTimelineは、Get-DbaAgentJobHistoryやGet-DbaDbBackupHistoryからパイプで渡されたデータをGoogle Chartsタイムラインライブラリを使用したインタラクティブなHTMLファイルに変換するコマンドレットです。生成されるHTMLは自己完結型で、ブラウザで直接表示できます。

**業務上の目的・背景**：SQL Serverの運用において、ジョブ実行スケジュールの分析、バックアップウィンドウの確認、重複操作のトラブルシューティング、管理レポートの視覚的な作成が必要です。タイムラインビューにより、複数インスタンスの実行時間やタイミングの関係を直感的に把握できます。

**帳票の利用シーン**：
1. SQLエージェントジョブのスケジュール分析と最適化
2. バックアップウィンドウの可視化と計画
3. 重複実行やリソース競合のトラブルシューティング
4. 管理者・ステークホルダーへの視覚的レポート提供
5. 過去の操作履歴のアーカイブと分析

**主要な出力内容**：
1. HTMLファイル（Google Charts使用のインタラクティブタイムライン）
2. 実行時間を示す水平バー
3. ステータスに応じた色分け表示
4. ホバーツールチップ（開始時刻、終了時刻、実行時間等）

**帳票の出力タイミング**：Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの結果をパイプラインで受け取り、ConvertTo-DbaTimelineを実行し、Out-Fileでファイル保存した時点でHTML帳票が生成されます。

**帳票の利用者**：データベース管理者（DBA）、システム管理者、運用チーム、管理者

## 帳票種別

タイムライン可視化レポート（HTML）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | ConvertTo-DbaTimeline \| Out-File |
| N/A | Webブラウザ | file:///{出力パス} | HTMLファイル表示 |
| N/A | メール | N/A | BodyAsHtmlでメール送信 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | HTML |
| 用紙サイズ | N/A（Web表示） |
| 向き | N/A（レスポンシブ） |
| ファイル名 | Out-Fileパラメータで指定 |
| 出力方法 | パイプライン出力 → Out-File |
| 文字コード | ASCII（推奨） |

### HTML構成

| 項目 | 内容 |
|-----|------|
| 外部依存 | jQuery 3.3.1, Bootstrap 3.3.7, Google Charts |
| チャートライブラリ | Google Charts Timeline |
| スタイリング | Bootstrap CSS + カスタムCSS |
| 対話機能 | ホバーツールチップ、レスポンシブサイズ |

## 帳票レイアウト

### レイアウト概要

HTMLファイルはタイムラインチャートを中心としたレイアウトで構成されます。

```
┌─────────────────────────────────────┐
│            ヘッダー部                │
│  (コマンド名, インスタンス名, ロゴ)   │
├─────────────────────────────────────┤
│                                     │
│         タイムラインチャート          │
│                                     │
│  [インスタンス] ジョブ名  ████████   │
│  [インスタンス] ジョブ名  ██████     │
│  [インスタンス] DB名     ████       │
│                                     │
├─────────────────────────────────────┤
│            フッター部                │
│    (dbatools.io リンク, クレジット)   │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | コマンド名 | 元データを生成したコマンド名 | CallerName変数 | コードスタイル |
| 2 | インスタンス名 | 対象SQL Serverインスタンス | servers配列 | コードスタイル |
| 3 | ロゴ | dbatoolsロゴ画像 | dbatools.io URL | 画像 |

### 明細部（タイムラインチャート）

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | 行ラベル | [インスタンス名] ジョブ/DB名 | vLabel | 文字列 | 自動 |
| 2 | 水平ラベル | ステータス/タイプ | hLabel | 文字列 | N/A |
| 3 | タイムラインバー | 実行期間を示す水平バー | StartDate, EndDate | 色付きバー | 時間比例 |
| 4 | ツールチップ | 詳細情報 | 各項目から生成 | HTML | ホバー表示 |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | サイトリンク | dbatools.io へのリンク | 固定値 | ハイパーリンク |
| 2 | Twitterリンク | @psdbatools | 固定値 | ハイパーリンク |
| 3 | 作者クレジット | @marcingminski | 固定値 | ハイパーリンク |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| InputObject | Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの結果 | Yes |
| ExcludeRowLabel | 行ラベル非表示フラグ | No |

### 対応入力タイプ

| 入力タイプ | 検出方法 | 対応コマンド |
|-----------|---------|------------|
| AgentJobHistory | TypeName == 'AgentJobHistory' | Get-DbaAgentJobHistory |
| BackupHistory | [Dataplat.Dbatools.Database.BackupHistory]型 | Get-DbaDbBackupHistory |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 入力順序に依存 | N/A |

### 改ページ条件

HTMLのためページ分割はありません。チャートは自動的にコンテンツに合わせてサイズ調整されます。

## データベース参照仕様

### 参照テーブル一覧

本コマンドは直接データベースを参照しません。Get-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryの結果オブジェクトを入力として処理します。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | パイプライン入力 | N/A |

### 入力オブジェクト構造（AgentJobHistory）

| プロパティ | 説明 | 用途 |
|-----------|------|------|
| SqlInstance | SQL Serverインスタンス名 | サーバー識別、ラベル |
| InstanceName | インスタンス名 | データ変換 |
| Job | ジョブ名 | 行ラベル |
| Status | 実行ステータス | 水平ラベル、色分け |
| StartDate | 開始日時 | タイムライン開始点 |
| EndDate | 終了日時 | タイムライン終了点 |

### 入力オブジェクト構造（BackupHistory）

| プロパティ | 説明 | 用途 |
|-----------|------|------|
| SqlInstance | SQL Serverインスタンス名 | サーバー識別、ラベル |
| InstanceName | インスタンス名 | データ変換 |
| Database | データベース名 | 行ラベル |
| Type | バックアップタイプ | 水平ラベル |
| Start | 開始日時 | タイムライン開始点 |
| End | 終了日時 | タイムライン終了点 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| Duration | EndDate - StartDate | 秒単位 | JavaScriptで計算 |
| Hours | duration / 3600 % 24 | 整数 | parseInt |
| Minutes | duration / 60 % 60 | 整数 | parseInt |
| Seconds | duration % 60 | 整数 | 剰余 |
| vLabel | "[" + SqlInstance + "] " + Job/Database | N/A | バックスラッシュエスケープ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[ConvertTo-DbaTimeline実行] --> B{入力タイプ判定}
    B -->|AgentJobHistory| C[ジョブ履歴データ変換]
    B -->|BackupHistory| D[バックアップ履歴データ変換]
    B -->|その他| E[エラー: Unsupported input data]
    C --> F[データ行生成]
    D --> F
    F --> G[サーバーリスト更新]
    G --> H{単一インスタンス?}
    H -->|Yes| I[ラベルからインスタンス名除去]
    H -->|No| J[そのまま]
    I --> K[HTML生成]
    J --> K
    K --> L[パイプライン出力]
    L --> M[Out-Fileでファイル保存]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| サポート外入力 | AgentJobHistory/BackupHistory以外の入力 | "Unsupported input data. To request support for additional commands, please file an issue at dbatools.io/issues and we'll take a look" | 対応コマンドの出力を使用 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数百〜数千件（ブラウザ描画能力に依存） |
| 目標出力時間 | 数秒（データ件数に依存） |
| 同時出力数上限 | 1セッション1ファイル |

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

- 生成されるHTMLは外部CDN（jQuery、Bootstrap、Google Charts）に依存
- インターネット接続がない環境では正常に表示されない
- ジョブ名やデータベース名が公開される可能性があるため、機密性に注意
- HTMLメール送信時はメールクライアントの互換性を確認

## 備考

- Google Charts Timeline（バージョン43）を使用
- Bootstrap 3.3.7とjQuery 3.3.1に依存
- 単一インスタンスの場合、ラベルからインスタンス名が自動除去される
- ステータスの色分けはConvert-DbaTimelineStatusColor関数で実行
- 日時変換はConvertTo-JsDate関数で実行

---

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

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

### 推奨読解順序

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

入力オブジェクトはGet-DbaAgentJobHistoryまたはGet-DbaDbBackupHistoryからの結果です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | AgentJobHistory出力構造 |
| 1-2 | Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | BackupHistory出力構造 |

**読解のコツ**: TypeName、SqlInstance、StartDate/EndDate等のプロパティに注目

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | パラメータ定義と全体構造 |

**主要処理フロー**:
1. **行86-149**: beginブロック - HTML Header生成（$begin変数）
2. **行151-173**: processブロック - データ変換と行生成
3. **行174-239**: endブロック - HTML Footer生成と出力

#### Step 3: HTML構造生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | Here-Stringによる HTML生成 |

**主要処理フロー**:
- **行88-149**: HTMLヘッダー、CSS、JavaScript関数定義（$begin）
- **行180-237**: JavaScriptチャート描画コード、HTMLフッター（$end）

#### Step 4: データ変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | Select-Objectによるデータ変換 |

**主要処理フロー**:
- **行161-163**: AgentJobHistory用のデータ変換
- **行164-166**: BackupHistory用のデータ変換
- **行172**: データ行のJavaScript配列への変換

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

```
ConvertTo-DbaTimeline (PowerShell)
    │
    ├─ ConvertTo-JsDate (dbatools内部関数)
    │      └─ PowerShell DateTime → JavaScript Date変換
    │
    ├─ Convert-DbaTimelineStatusColor (dbatools内部関数)
    │      └─ ステータス → カラーコード変換
    │
    └─ 出力（3つの文字列配列）
           ├─ $begin (HTMLヘッダー/JavaScript)
           ├─ $body (データ行)
           └─ $end (HTMLフッター/JavaScript)
```

### データフロー図

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

Get-DbaAgentJobHistory       ┌──────────────────┐
     └─ JobHistory ─────────▶│  入力タイプ判定  │
                             │                  │
Get-DbaDbBackupHistory       │                  │
     └─ BackupHistory ──────▶│                  │
                             └────────┬─────────┘
                                      │
                                      ▼
                             ┌──────────────────┐
                             │  データ変換      │
                             │ (Select-Object)  │
                             │  vLabel, hLabel  │
                             │  StartDate等     │
                             └────────┬─────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    │                 │                 │
                    ▼                 ▼                 ▼
              ┌──────────┐     ┌──────────┐     ┌──────────┐
              │ $begin   │     │  $body   │     │  $end    │
              │ (Header) │     │  (Data)  │     │ (Footer) │
              └────┬─────┘     └────┬─────┘     └────┬─────┘
                   │                 │                 │
                   └─────────────────┼─────────────────┘
                                     │
                                     ▼
                              ┌─────────────┐
                              │  Out-File   │
                              │  HTMLファイル │
                              └─────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ConvertTo-DbaTimeline.ps1 | `public/ConvertTo-DbaTimeline.ps1` | ソース | メインコマンドレット実装 |
| ConvertTo-JsDate.ps1 | `private/functions/ConvertTo-JsDate.ps1`（推定） | ソース | JavaScript日時変換関数 |
| Convert-DbaTimelineStatusColor.ps1 | `private/functions/Convert-DbaTimelineStatusColor.ps1`（推定） | ソース | ステータス色変換関数 |
| Get-DbaAgentJobHistory.ps1 | `public/Get-DbaAgentJobHistory.ps1` | ソース | ジョブ履歴取得 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
