# 機能設計書 384-Update-DbaBuildReference

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるUpdate-DbaBuildReference機能の設計仕様を記載する。本機能は、パッチコンプライアンスとバージョン追跡に使用されるSQL Serverビルドリファレンスデータベースを最新版にダウンロード・更新する。

### 本機能の処理概要

本機能は、Get-DbaBuildおよびTest-DbaBuild関数で使用される包括的なSQL Serverビルドリファレンスデータベースを最新のパッチ情報で更新する。このデータベースには、すべてのSQL Serverバージョンについて、ビルド番号、サービスパック、累積更新プログラム、KB記事、リリース日、サポートライフサイクル日の詳細なマッピングが含まれている。

**業務上の目的・背景**：データベース管理者は、正確なパッチコンプライアンスレポートを維持し、更新が必要な古いインストールを特定するために、最新のSQL Serverビルド情報が必要である。dbatoolsモジュールのリリース間でも新しいパッチがリリースされるため、本機能により最新のパッチデータを取得できる。

**機能の利用シーン**：
- 新しいSQL Server累積更新プログラムのリリース後
- パッチコンプライアンス監査の前
- dbatools最新リリースとの間で新パッチがリリースされた場合
- エアギャップ環境でのローカルファイル指定による更新

**主要な処理内容**：
1. モジュールディレクトリと書き込み可能ディレクトリのビルドリファレンスファイル確認
2. 既存ファイルのLastUpdated日時を取得
3. オンライン（またはローカルファイル）から新しいリファレンスデータを取得
4. 新データが新しい場合のみファイルを更新

**関連システム・外部連携**：dbatoolsプロジェクトリポジトリからHTTPS経由でダウンロード。エアギャップ環境では-LocalFileパラメータでローカルファイルを指定可能。

**権限による制御**：dbatoolsデータディレクトリへの書き込み権限が必要。

## 関連画面

本機能はCLIベースのPowerShellコマンドレットであり、GUI画面との直接的な関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行と更新結果確認 |

## 機能種別

ファイル更新 / データ同期

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| LocalFile | string | No | インターネットの代わりに使用するローカルJSONファイルのパス | 有効なファイルパス |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- オンライン：assets.sqlbuildreferenceで設定されたURL
- ローカルファイル：-LocalFileで指定されたJSONファイル
- 既存データ：モジュールディレクトリおよびdbatoolsデータディレクトリのdbatools-buildref-index.json

## 出力仕様

### 出力データ

本機能はパイプラインオブジェクトを返さない。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | 更新成功時はWrite-Messageで情報メッセージを出力 |

### 出力先

- ファイル：dbatools-buildref-index.jsonを更新
- コンソール：Write-MessageでOutput/Verbose/Warningレベルのメッセージ

## 処理フロー

### 処理シーケンス

```
1. モジュールディレクトリのリファレンスファイル確認
   └─ $script:PSModuleRoot/bin/dbatools-buildref-index.json
2. 書き込み可能ディレクトリの確認
   └─ Path.DbatoolsDataの設定値を取得
   └─ writable_idxfile = $DbatoolsData/dbatools-buildref-index.json
3. ファイル存在チェックと初期化
   └─ 書き込み可能コピーが存在しない場合、モジュールファイルをコピー
   └─ 両方存在する場合、新しい方を使用
4. 新データの取得
   └─ LocalFile指定時: ファイルから読み込み
   └─ それ以外: オンラインからダウンロード
5. LastUpdated日時の比較
   └─ 新データがオフラインデータより新しい場合のみ更新
6. ファイル更新
   └─ UTF-8エンコーディングで書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[モジュールディレクトリのidxfile確認]
    B --> C{orig_idxfile存在?}
    C -->|No| D[警告: モジュール整合性を確認]
    C -->|Yes| E[DbatoolsDataパス取得]
    D --> E
    E --> F{writable_idxfile存在?}
    F -->|No| G[orig_idxfileをコピー]
    F -->|Yes| H{orig_idxfileも存在?}
    G --> I[offline_time設定]
    H -->|Yes| J[LastUpdated比較]
    H -->|No| I
    J --> K{module_time > data_time?}
    K -->|Yes| L[orig_idxfileをコピー]
    K -->|No| M[data_timeをoffline_timeに設定]
    L --> I
    M --> I
    I --> N{LocalFile指定?}
    N -->|Yes| O[ローカルファイル読み込み]
    N -->|No| P[オンラインダウンロード]
    O --> Q{読み込み成功?}
    P --> Q
    Q -->|No| R[警告/エラー]
    Q -->|Yes| S[new_time取得]
    R --> T[終了]
    S --> U{new_time > offline_time?}
    U -->|Yes| V[ファイル更新]
    U -->|No| T
    V --> W[更新完了メッセージ]
    W --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 新しい場合のみ更新 | LastUpdatedが新しい場合のみファイルを更新 | 常時 |
| BR-002 | モジュールファイル優先 | モジュールファイルが書き込み可能ファイルより新しい場合は上書き | 両方存在時 |
| BR-003 | プロキシ自動検出 | 直接接続失敗時はデフォルトネットワーク認証情報でプロキシ使用 | オンラインダウンロード時 |
| BR-004 | UTF-8エンコーディング | 更新ファイルはUTF-8で書き込み | ファイル更新時 |

### 計算ロジック

日時比較ロジック:
```powershell
$new_time = Get-Date ($newContent | ConvertFrom-Json).LastUpdated
if ($new_time -gt $offline_time) {
    # 更新実行
}
```

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

本機能はデータベースを操作しない。

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | ファイルシステム操作のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル読み込みエラー | LocalFileが読み込めない | Stop-Functionでエラー出力 |
| - | ダウンロードエラー | オンライン接続失敗 | プロキシ経由で再試行、失敗時は警告 |
| - | ファイル書き込みエラー | 書き込み権限なし | エラー詳細を確認 |
| - | ファイル不在エラー | orig_idxfileもwritable_idxfileも存在しない | 例外スロー |

### リトライ仕様

オンラインダウンロードは自動的にプロキシ経由で1回再試行する。

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

ファイル操作のため、トランザクション管理は実装されていない。

## パフォーマンス要件

- オンラインダウンロードはネットワーク速度に依存
- ローカルファイル読み込みは高速
- ファイル比較・書き込みは軽量な操作

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

- オンラインダウンロードはHTTPS経由（Invoke-TlsWebRequest使用）
- ローカルファイル使用時は信頼できるソースからのファイルを使用

## 備考

- 現在のダウンロードURLはGet-DbatoolsConfigValue -Name 'assets.sqlbuildreference'で確認可能
- エアギャップ環境では-LocalFileパラメータを使用
- SuppressMessageAttribute: PSUseShouldProcessForStateChangingFunctions（ファイル更新のため）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dbatools-buildref-index.json | `bin/dbatools-buildref-index.json` | ビルドリファレンスデータ形式 |

**読解のコツ**: JSONファイルにはLastUpdatedプロパティとDataプロパティ（ビルド情報配列）が含まれる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | パラメータ定義（58-63行目） |
| 2-2 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | beginブロック（65-87行目） |

**主要処理フロー**:
1. **58-63行目**: パラメータ定義。LocalFileとEnableExceptionのみ
2. **66-86行目**: Get-DbaBuildReferenceIndexOnline内部関数

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | ファイルパス設定（89-93行目） |
| 3-2 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | ファイル存在チェック（95-123行目） |
| 3-3 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | 新データ取得・更新（125-143行目） |

**主要処理フロー**:
- **90-93行目**: モジュールディレクトリとデータディレクトリのパス設定
- **95-107行目**: 書き込み可能ファイルが存在しない場合の初期化
- **110-123行目**: 両ファイル存在時のLastUpdated比較
- **126-134行目**: LocalFileまたはオンラインから新データ取得
- **137-142行目**: 新データが新しい場合のみファイル更新

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

```
Update-DbaBuildReference
    │
    ├─ Get-DbaBuildReferenceIndexOnline (内部関数)
    │      ├─ Invoke-TlsWebRequest
    │      └─ プロキシ経由での再試行
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ assets.sqlbuildreference URL取得
    │      └─ Path.DbatoolsData パス取得
    │
    ├─ Copy-Item
    │      └─ モジュールファイルをデータディレクトリにコピー
    │
    └─ Out-File
           └─ 更新データをUTF-8で書き込み
```

### データフロー図

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

オンラインURL ─────┐
                   │
LocalFile ─────────┼──▶ LastUpdated比較 ──▶ dbatools-buildref-index.json
                   │                         (更新)
既存JSONファイル ──┘
(モジュール/データ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | ソース | メイン機能実装 |
| Update-DbaBuildReference.Tests.ps1 | `tests/Update-DbaBuildReference.Tests.ps1` | テスト | 単体テスト |
| dbatools-buildref-index.json | `bin/dbatools-buildref-index.json` | データ | モジュール同梱リファレンス |
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | 依存 | リファレンスデータ使用先 |
| Test-DbaBuild.ps1 | `public/Test-DbaBuild.ps1` | 依存 | リファレンスデータ使用先 |
