# 画面設計書 261-ランダムデータ

## 概要

本ドキュメントは、dbatoolsのランダムデータ生成機能に関する画面設計書です。データマスキングやテストデータ生成のためのランダム値・データセット・テンプレート・タイプの取得機能を提供するPowerShellコマンド群を定義します。

### 本画面の処理概要

本機能は、SQL Serverのデータマスキングおよびテストデータ生成のためのランダムデータを生成する4つのPowerShellコマンドを提供します。

**業務上の目的・背景**：本番環境のデータを非本番環境（開発・テスト・トレーニング）で使用する際、個人情報や機密データを現実的な偽データに置き換える必要があります。単純なランダム文字列ではなく、名前・住所・電話番号などの意味のあるパターンを持つデータを生成することで、アプリケーションの動作検証やデモンストレーションに適したデータを作成できます。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
- `Get-DbaRandomizedValue` - 個別のランダム値を生成
- `Get-DbaRandomizedDataset` - テンプレートに基づくデータセットを生成
- `Get-DbaRandomizedDatasetTemplate` - 利用可能なテンプレートを取得
- `Get-DbaRandomizedType` - 利用可能なランダムタイプを取得

**主要な操作・処理内容**：
1. SQL Serverデータ型に適合したランダム値の生成（bigint, varchar, datetime等）
2. Bogusライブラリを使用した現実的な偽データの生成（名前、住所、電話番号等）
3. JSONテンプレートに基づく構造化されたデータセットの生成
4. 利用可能なランダマイザータイプとサブタイプの検索・取得
5. カスタムロケール対応による地域固有データの生成

**画面遷移**：
- 本コマンドは独立して実行可能
- `Get-DbaRandomizedDatasetTemplate`の出力を`Get-DbaRandomizedDataset`にパイプライン入力可能
- `Invoke-DbaDbDataMasking`や`New-DbaDbMaskingConfig`と連携してデータマスキングワークフローを構成

**権限による表示制御**：
- 特別な権限は不要（ローカルPowerShell実行権限のみ）
- テンプレートファイルへの読み取りアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 144 | Get-DbaRandomizedValue | 主機能 | ランダム値の取得 |
| 141 | Get-DbaRandomizedDataset | 補助機能 | ランダムデータセットの取得 |
| 142 | Get-DbaRandomizedDatasetTemplate | 補助機能 | データセットテンプレートの取得 |
| 143 | Get-DbaRandomizedType | 補助機能 | ランダムタイプの取得 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaRandomizedValue`
- `Get-DbaRandomizedDataset`
- `Get-DbaRandomizedDatasetTemplate`
- `Get-DbaRandomizedType`

## 入出力項目

### Get-DbaRandomizedValue パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| DataType | string | 条件付き | SQL Serverデータ型（bigint, varchar, datetime等） |
| RandomizerType | string | 条件付き | Bogusライブラリのカテゴリ（Address, Person, Finance等） |
| RandomizerSubType | string | 条件付き | カテゴリ内の具体的なタイプ（FirstName, ZipCode等） |
| Min | object | No | 最小値または最小長 |
| Max | object | No | 最大値または最大長（デフォルト: 255） |
| Precision | int | No | 小数点以下の桁数（デフォルト: 2） |
| CharacterString | string | No | 文字列生成に使用する文字セット |
| Format | string | No | 出力フォーマットパターン |
| Symbol | string | No | 通貨記号等のプレフィックス |
| Separator | string | No | MACアドレス等の区切り文字 |
| Value | string | No | Shuffle用の入力値 |
| Locale | string | No | ロケール（デフォルト: en） |
| EnableException | switch | No | 例外を有効化 |

### Get-DbaRandomizedDataset パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Template | string[] | 条件付き | 使用するテンプレート名 |
| TemplateFile | string[] | 条件付き | カスタムテンプレートファイルのパス |
| Rows | int | No | 生成する行数（デフォルト: 100） |
| Locale | string | No | ロケール（デフォルト: en） |
| InputObject | object[] | No | パイプライン入力（テンプレートオブジェクト） |
| EnableException | switch | No | 例外を有効化 |

### Get-DbaRandomizedDatasetTemplate パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Template | string[] | No | フィルタするテンプレート名 |
| Path | string[] | No | カスタムテンプレートディレクトリのパス |
| ExcludeDefault | switch | No | デフォルトテンプレートを除外 |
| EnableException | switch | No | 例外を有効化 |

### Get-DbaRandomizedType パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| RandomizedType | string[] | No | フィルタするメインタイプ |
| RandomizedSubType | string[] | No | フィルタするサブタイプ |
| Pattern | string | No | パターンマッチング用の文字列 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaRandomizedValue 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (スカラー値) | varies | DataTypeまたはRandomizerTypeに応じた型の値 |

### Get-DbaRandomizedDataset 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (テンプレート定義による) | varies | テンプレートのColumns配列で定義された各プロパティ |

### Get-DbaRandomizedDatasetTemplate 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BaseName | string | テンプレート名（.json拡張子なし） |
| FullName | string | テンプレートファイルのフルパス |

### Get-DbaRandomizedType 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Type | string | メインデータカテゴリ |
| SubType | string | カテゴリ内の具体的なデータパターン |

## イベント仕様

### 1-Get-DbaRandomizedValue実行

1. パラメータ検証（DataType、RandomizerType、RandomizerSubTypeのいずれかが必須）
2. Bogus Fakerオブジェクトの初期化（ロケール指定）
3. ランダマイザータイプCSVファイルの読み込み
4. DataType指定時: SQL Serverデータ型に応じたランダム値生成
5. RandomizerType指定時: Bogusライブラリを使用した現実的データ生成
6. 生成値の出力

### 2-Get-DbaRandomizedDataset実行

1. テンプレート指定の検証（Template、TemplateFile、InputObjectのいずれか）
2. テンプレートファイルの読み込みとJSON解析
3. 指定行数分のループ処理
4. 各カラムに対してGet-DbaRandomizedValueを呼び出し
5. PSCustomObjectとして行データを出力

### 3-Get-DbaRandomizedDatasetTemplate実行

1. デフォルトテンプレートディレクトリからJSONファイル取得
2. カスタムPath指定時は追加ディレクトリからも取得
3. Template指定時はBaseNameでフィルタリング
4. BaseName、FullNameを含むオブジェクト出力

### 4-Get-DbaRandomizedType実行

1. en.randomizertypes.csvファイルの読み込み
2. Pattern指定時はType、SubTypeでマッチング
3. RandomizedType、RandomizedSubType指定時はフィルタリング
4. Type、SubTypeの一意な組み合わせをソートして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 全コマンド | なし | なし | データベースへの直接的な影響なし（値生成のみ） |

本コマンド群はランダム値の生成のみを行い、データベースへの直接的な操作は行いません。生成された値は他のコマンド（Invoke-DbaDbDataMasking等）で使用されます。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | エラー | Please use one of the variables i.e. -DataType, -RandomizerType or -RandomizerSubType | 必須パラメータ未指定 |
| MSG002 | エラー | You cannot use -DataType with -RandomizerType or -RandomizerSubType | DataTypeと他パラメータの同時指定 |
| MSG003 | エラー | Please enter a sub type | RandomizerType指定時にSubType未指定 |
| MSG004 | エラー | Unsupported sql data type | サポートされていないDataType指定 |
| MSG005 | エラー | Invalid randomizer type | 無効なRandomizerType指定 |
| MSG006 | エラー | Invalid randomizer sub type | 無効なRandomizerSubType指定 |
| MSG007 | エラー | Value cannot be empty when using sub type 'Shuffle' | Shuffle使用時にValue未指定 |
| MSG008 | エラー | Please enter a template or assign a template file | テンプレート未指定 |
| MSG009 | エラー | Could not find any templates | テンプレートが見つからない |
| MSG010 | エラー | Could not parse template file | テンプレートファイルの解析エラー |
| MSG011 | 情報 | Min value for data type is empty or too small. Reset to X | 最小値の自動調整 |
| MSG012 | 情報 | Max value for data type is empty or too big. Reset to X | 最大値の自動調整 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パラメータ検証エラー | Stop-Functionでエラーメッセージを表示し処理中断 |
| テンプレートファイル読み込みエラー | Stop-Functionでエラーレコードと共に処理中断 |
| ランダム値生成エラー | Stop-FunctionでContinueし次の処理へ |
| CSVファイル読み込みエラー | Stop-Functionで処理中断 |
| EnableException指定時 | try/catchで例外をスローし呼び出し元で処理可能 |

## 備考

- Bogusライブラリを使用してリアルなフェイクデータを生成
- サポートされるSQL Serverデータ型: bigint, bit, bool, char, date, datetime, datetime2, decimal, int, float, guid, money, numeric, nchar, ntext, nvarchar, real, smalldatetime, smallint, text, time, tinyint, uniqueidentifier, userdefineddatatype, varchar
- サポートされるRandomizerType: Address, Commerce, Company, Database, Date, Finance, Hacker, Hashids, Image, Internet, Lorem, Name, Person, Phone, Random, Rant, System
- 日付型のフォーマット: date=yyyy-MM-dd, datetime=yyyy-MM-dd HH:mm:ss.fff, datetime2=yyyy-MM-dd HH:mm:ss.fffffff
- ロケールによる地域固有データ対応（デフォルト: en）

---

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

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

### 推奨読解順序

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

ランダムデータ生成に使用される外部データファイルの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | en.randomizertypes.csv | `bin/randomizer/en.randomizertypes.csv` | Type, SubTypeの組み合わせ定義を確認 |
| 1-2 | テンプレートJSON | `bin/randomizer/templates/*.json` | Columns配列のName, Type, SubType構造を確認 |

**読解のコツ**: CSVファイルはBogusライブラリのタイプマッピングを定義しており、JSONテンプレートはデータセット生成のスキーマを定義しています。

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

各コマンドのパラメータ検証と初期化処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | beginブロックでのFaker初期化、パラメータ検証ロジック |
| 2-2 | Get-DbaRandomizedDataset.ps1 | `public/Get-DbaRandomizedDataset.ps1` | テンプレート取得と行生成ループ |
| 2-3 | Get-DbaRandomizedDatasetTemplate.ps1 | `public/Get-DbaRandomizedDatasetTemplate.ps1` | テンプレートファイル検索ロジック |
| 2-4 | Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | CSVインポートとフィルタリング |

**主要処理フロー（Get-DbaRandomizedValue）**:
1. **185-206行**: Bogus Fakerオブジェクトの初期化とCSVインポート
2. **211-241行**: パラメータ検証（DataType/RandomizerType/RandomizerSubTypeの排他制御）
3. **262-376行**: DataType指定時のswitch処理でSQL Server型に応じた値生成
4. **382-635行**: RandomizerType指定時のswitch処理でBogusライブラリ呼び出し

#### Step 3: 値生成ロジックを理解する

DataTypeとRandomizerTypeに応じた値生成の詳細を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | processブロックのswitch文による値生成 |

**主要処理フロー**:
- **263-275行**: bigint型の範囲制限と値生成
- **277-283行**: bit/bool型のブール値生成
- **284-327行**: 日付型のフォーマット処理
- **305-307行**: decimal/float/money型の精度指定生成
- **372-374行**: varchar/char型の文字列生成
- **383-396行**: Address RandomizerTypeの処理
- **484-491行**: Finance RandomizerTypeの処理

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

```
Get-DbaRandomizedValue
    |
    +-- Bogus.Faker (外部ライブラリ)
    |       +-- faker.Address.*
    |       +-- faker.Commerce.*
    |       +-- faker.Company.*
    |       +-- faker.Database.*
    |       +-- faker.Date.*
    |       +-- faker.Finance.*
    |       +-- faker.Internet.*
    |       +-- faker.Lorem.*
    |       +-- faker.Name.*
    |       +-- faker.Person.*
    |       +-- faker.Phone.*
    |       +-- faker.Random.*
    |       +-- faker.System.*
    |
    +-- Import-Csv (en.randomizertypes.csv)

Get-DbaRandomizedDataset
    |
    +-- Get-DbaRandomizedDatasetTemplate
    |       +-- Get-ChildItem (テンプレートファイル検索)
    |
    +-- Get-Content (テンプレートJSON読み込み)
    +-- ConvertFrom-Json
    +-- Get-DbaRandomizedValue (各カラムの値生成)

Get-DbaRandomizedDatasetTemplate
    |
    +-- Get-ChildItem (bin/randomizer/templates/*.json)
    +-- Get-ChildItem (カスタムPath/*.json)

Get-DbaRandomizedType
    |
    +-- Import-Csv (en.randomizertypes.csv)
    +-- Where-Object (フィルタリング)
    +-- Select-Object (Type, SubType)
```

### データフロー図

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

パラメータ
  DataType/          +-----------------+
  RandomizerType  -->| Get-DbaRandom   |---> スカラー値
  Min/Max/Format     | izedValue       |     (int/string/datetime等)
                     +-----------------+
                            |
                            v
                     Bogus.Faker
                     (外部ライブラリ)

Template/            +-----------------+
TemplateFile     -->| Get-DbaRandom   |---> PSCustomObject[]
Rows/Locale         | izedDataset     |     (テンプレート定義の行)
                     +-----------------+
                            |
                            +-- Get-DbaRandomizedDatasetTemplate
                            +-- Get-DbaRandomizedValue

Template/Path        +-----------------+
ExcludeDefault   -->| Get-DbaRandom   |---> PSCustomObject[]
                     | izedDataset     |     (BaseName, FullName)
                     | Template        |
                     +-----------------+

RandomizedType/      +-----------------+
RandomizedSubType -->| Get-DbaRandom   |---> PSCustomObject[]
Pattern              | izedType        |     (Type, SubType)
                     +-----------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | 個別ランダム値生成の主要ロジック |
| Get-DbaRandomizedDataset.ps1 | `public/Get-DbaRandomizedDataset.ps1` | ソース | テンプレートベースのデータセット生成 |
| Get-DbaRandomizedDatasetTemplate.ps1 | `public/Get-DbaRandomizedDatasetTemplate.ps1` | ソース | テンプレートファイルの検索・取得 |
| Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | ソース | 利用可能なタイプ・サブタイプの取得 |
| en.randomizertypes.csv | `bin/randomizer/en.randomizertypes.csv` | データ | ランダマイザータイプの定義 |
| *.json | `bin/randomizer/templates/*.json` | テンプレート | データセットテンプレート定義 |
| Bogus | 外部ライブラリ | 依存 | フェイクデータ生成エンジン |
