# 機能設計書 144-Get-DbaRandomizedValue

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Get-DbaRandomizedValue`コマンドレットの機能設計を定義する。本機能は、SQL Serverデータ型に対応したランダム値、またはBogusライブラリを使用した現実的なフェイクデータを生成する。

### 本機能の処理概要

`Get-DbaRandomizedValue`は、データマスキングやテストデータ生成のためのランダム値を生成するコマンドレットである。SQL Serverの全主要データ型（varchar、int、datetime等）に対応した適切な範囲のランダム値を生成するとともに、Bogusライブラリを通じて名前、住所、電話番号、クレジットカード番号などの現実的なフェイクデータも生成できる。

**業務上の目的・背景**：本番データを使用できない開発・テスト環境において、現実的なテストデータの準備は重要な課題である。本機能は単純なランダム文字列ではなく、ビジネスコンテキストに適したフェイクデータを生成することで、より実用的なテスト環境の構築を支援する。また、データマスキング処理において、元データの特性（文字列長、数値範囲、日付形式等）を維持しながら値を置換することが可能。

**機能の利用シーン**：
- データマスキング処理での値置換（Invoke-DbaDbDataMaskingの内部処理）
- テストデータテンプレートからのデータ生成（Get-DbaRandomizedDatasetの内部処理）
- 単独でのテストデータ生成
- データ品質テストのためのダミーデータ作成
- デモ環境向けサンプルデータ準備

**主要な処理内容**：
1. DataType指定時：SQL Serverデータ型に基づくランダム値生成
2. RandomizerType/RandomizerSubType指定時：Bogusライブラリによるセマンティックデータ生成
3. Min/Maxパラメータによる値範囲制御
4. Localeパラメータによる地域対応データ生成
5. Formatパラメータによる出力形式制御

**関連システム・外部連携**：
- Bogusライブラリ（Bogus.Faker）- フェイクデータ生成
- Get-DbaRandomizedDataset（本機能を呼び出すデータセット生成）
- Invoke-DbaDbDataMasking（本機能を呼び出すマスキング機能）
- en.randomizertypes.csv（タイプ定義ファイル）

**権限による制御**：本機能はローカル処理のみを行い、SQL Server接続や特別な権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | ランダム値生成 |

## 機能種別

データ生成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| DataType | string | No* | SQL Serverデータ型 | サポートデータ型リストに含まれること |
| RandomizerType | string | No* | Bogusメインカテゴリ | 有効なタイプ名 |
| RandomizerSubType | string | No* | Bogusサブカテゴリ | 有効なサブタイプ名 |
| Min | object | No | 最小値/最小長 | データ型に応じた有効値 |
| Max | object | No | 最大値/最大長 | データ型に応じた有効値 |
| Precision | int | No | 小数精度（デフォルト2） | 正の整数 |
| CharacterString | string | No | 文字列生成用文字セット | デフォルト: a-zA-Z0-9 |
| Format | string | No | 出力フォーマットパターン | - |
| Symbol | string | No | 数値プレフィックス記号（$等） | - |
| Separator | string | No | 区切り文字（MAC等用） | - |
| Value | string | No | Shuffleサブタイプ用の入力値 | Shuffle使用時必須 |
| Locale | string | No | ロケール（デフォルト'en'） | 有効なロケールコード |
| EnableException | switch | No | 例外を有効化 | - |

*DataType または RandomizerType/RandomizerSubType のいずれかが必須

### 入力データソース

- en.randomizertypes.csv（タイプ定義ファイル）
- Bogus.Fakerオブジェクト（フェイクデータ生成エンジン）

## 出力仕様

### 出力データ

| データ型指定 | 出力型 | 説明 |
|-------------|--------|------|
| bigint | Int64 | -9223372036854775808 〜 9223372036854775807 |
| int | Int32 | -2147483648 〜 2147483647 |
| smallint | Int32 | -32768 〜 32767 |
| tinyint | Int32 | 0 〜 255 |
| bit/bool | Int32 | 0 または 1 |
| decimal/float/money/numeric/real | Decimal | Min〜Max範囲、指定精度 |
| date | String | yyyy-MM-dd形式 |
| datetime | String | yyyy-MM-dd HH:mm:ss.fff形式 |
| datetime2 | String | yyyy-MM-dd HH:mm:ss.fffffff形式 |
| smalldatetime | String | yyyy-MM-dd HH:mm:ss形式 |
| time | String | HH:mm:ss.fffffff形式 |
| uniqueidentifier/guid | String | GUID形式 |
| varchar/char/nvarchar/nchar | String | 指定文字セットからの文字列 |

### 出力先

パイプライン（スカラー値）

## 処理フロー

### 処理シーケンス

```
1. 初期化（begin）
   ├─ Bogus.Fakerオブジェクト作成（未作成の場合）
   ├─ en.randomizertypes.csv読み込み（未読込の場合）
   └─ パラメータバリデーション
2. DataType指定時の処理（process）
   └─ データ型別のswitch文で値生成
3. RandomizerType/SubType指定時の処理
   └─ タイプ別のswitch文でBogusメソッド呼び出し
4. 生成値を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Fakerオブジェクト<br/>存在?}
    B -->|No| C[Bogus.Faker作成]
    B -->|Yes| D[パラメータ検証]
    C --> D
    D --> E{DataType/RandomizerType<br/>どちらか指定?}
    E -->|No| F[Stop-Function:<br/>パラメータ必須]
    E -->|Yes| G{DataTypeと<br/>RandomizerType<br/>両方指定?}
    G -->|Yes| H[Stop-Function:<br/>排他パラメータ]
    G -->|No| I{DataType<br/>指定?}
    I -->|Yes| J[DataType別<br/>switch処理]
    I -->|No| K{RandomizerSubType<br/>のみ指定?}
    K -->|Yes| L[SubTypeからType自動判定]
    K -->|No| M[RandomizerType使用]
    L --> N[RandomizerType別<br/>switch処理]
    M --> N
    J --> O{bigint?}
    O -->|Yes| P[faker.Random.Long]
    O -->|No| Q{bit/bool?}
    Q -->|Yes| R[faker.Random.Bool]
    Q -->|No| S{date系?}
    S -->|Yes| T[faker.Date.Between/Past]
    S -->|No| U{数値系?}
    U -->|Yes| V[faker.Finance.Amount]
    U -->|No| W{文字列系?}
    W -->|Yes| X[faker.Random.String2]
    W -->|No| Y[その他処理]
    N --> Z{Address?}
    Z -->|Yes| AA[faker.Address.*]
    Z -->|No| AB{Person/Name?}
    AB -->|Yes| AC[faker.Name.*/Person.*]
    AB -->|No| AD{Finance?}
    AD -->|Yes| AE[faker.Finance.*]
    AD -->|No| AF[その他タイプ処理]
    P --> AG[値出力]
    R --> AG
    T --> AG
    V --> AG
    X --> AG
    Y --> AG
    AA --> AG
    AC --> AG
    AE --> AG
    AF --> AG
    AG --> AH[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 排他パラメータ | DataTypeとRandomizerType/SubTypeは同時指定不可 | パラメータ検証時 |
| BR-002 | データ型範囲制限 | 各データ型の有効範囲を自動調整 | 数値データ型指定時 |
| BR-003 | デフォルト範囲 | Min/Max未指定時はデフォルト値（1-255）を使用 | 日付以外の型 |
| BR-004 | Locale適用 | 名前、住所等はLocaleに応じた地域データを生成 | Bogusタイプ使用時 |
| BR-005 | Shuffleサブタイプ | Value パラメータが必須 | RandomizerSubType='Shuffle'時 |
| BR-006 | SubType自動判定 | RandomizerSubTypeのみ指定時、適切なTypeを自動判定 | SubTypeのみ指定時 |

### 計算ロジック

- 小数精度: Precisionパラメータで指定（デフォルト2桁）
- 日付範囲: Min/Maxで指定、未指定時は過去日付を生成
- 文字列長: Min〜Max範囲内でランダムに決定

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

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

本機能はデータベースへのアクセスを行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベースアクセスなし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | DataType/RandomizerType/SubType全て未指定 | いずれかを指定 |
| - | 排他パラメータエラー | DataTypeとRandomizerType両方指定 | 一方のみ指定 |
| - | サブタイプ必須エラー | RandomizerTypeのみでSubTypeなし | SubTypeを指定 |
| - | 無効タイプエラー | 存在しないRandomizerType指定 | 有効なタイプを指定 |
| - | 無効サブタイプエラー | 存在しないRandomizerSubType指定 | 有効なサブタイプを指定 |
| - | Value必須エラー | Shuffle使用時にValue未指定 | Valueを指定 |
| - | 日付範囲エラー | Min > Max（日付範囲） | 範囲を修正 |

### リトライ仕様

リトライは実装されていない。

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

データベーストランザクションは使用しない。

## パフォーマンス要件

- Fakerオブジェクトとタイプ定義はスクリプトスコープでキャッシュ
- 単一値生成のため処理は高速

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

- 生成されるデータはフェイクデータであり、実在する個人情報ではない
- 金融情報（クレジットカード番号等）も検証用ではなくフォーマットのみ有効

## 備考

- サポート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, Image, Internet, Lorem, Name, Person, Phone, Random, Rant, System

---

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

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

### 推奨読解順序

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

Fakerオブジェクトとタイプ定義の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | スクリプトスコープ変数の初期化 |

**読解のコツ**:
- **186-189行目**: `$script:faker` - Bogus.Fakerオブジェクトのキャッシュ
- **192-194行目**: `$script:randomizerTypes` - タイプ定義CSVのキャッシュ
- **196-206行目**: ユニークタイプ/サブタイプの抽出

#### Step 2: パラメータバリデーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | 入力検証ロジック |

**主要処理フロー**:
1. **208行目**: サポートデータ型リスト定義
2. **211-219行目**: パラメータ排他チェック
3. **217-218行目**: SubTypeのみ指定時のType自動判定
4. **221-223行目**: DataTypeの有効性チェック
5. **226-241行目**: RandomizerType/SubTypeの有効性チェック
6. **243-253行目**: Min/Maxデフォルト値設定

#### Step 3: DataType処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | データ型別処理 |

**主要処理フロー**:
- **260-376行目**: DataType指定時のswitch文
- **263-275行目**: bigint処理（範囲チェック、faker.Random.Long）
- **277-283行目**: bit/bool処理（faker.Random.Bool）
- **284-304行目**: 日付型処理（date, datetime, datetime2）
- **305-307行目**: 数値型処理（faker.Finance.Amount）
- **308-357行目**: int, smallint, tinyint処理（範囲チェック付き）
- **358-360行目**: GUID処理
- **372-374行目**: 文字列型処理（faker.Random.String2）

#### Step 4: RandomizerType処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | タイプ別処理 |

**主要処理フロー**:
- **378-636行目**: RandomizerType指定時のswitch文
- **383-397行目**: Address処理（Latitude, Longitude, ZipCode等）
- **484-492行目**: Finance処理（Account, Amount等）
- **499-530行目**: Internet処理（Password, MAC等）
- **576-578行目**: Name処理
- **579-589行目**: Person処理
- **597-624行目**: Random処理（Shuffle含む）

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

```
Get-DbaRandomizedValue
    │
    ├─ Bogus.Faker（フェイクデータエンジン）
    │      ├─ faker.Random.*（乱数生成）
    │      ├─ faker.Date.*（日付生成）
    │      ├─ faker.Finance.*（金融データ生成）
    │      ├─ faker.Address.*（住所データ生成）
    │      ├─ faker.Name.*（名前データ生成）
    │      ├─ faker.Person.*（個人情報生成）
    │      ├─ faker.Internet.*（インターネットデータ生成）
    │      ├─ faker.Lorem.*（ダミーテキスト生成）
    │      └─ faker.System.*（システムデータ生成）
    │
    └─ Import-Csv（タイプ定義読み込み）
           └─ bin/randomizer/en.randomizertypes.csv
```

### データフロー図

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

DataType ───────▶  DataType別switch
                        │
                   ┌────┴────┐
                   ▼         ▼
              数値型      文字列型
                │           │
                ▼           ▼
          faker.Random  faker.Random
          .Long/Int     .String2
                │           │
                └─────┬─────┘
                      ▼
                 値を出力 ────────────▶ スカラー値

RandomizerType ─▶  Type別switch
RandomizerSubType      │
                  ┌────┴────┐
                  ▼         ▼
             Address    Finance
                │           │
                ▼           ▼
          faker.Address faker.Finance
             .*メソッド    .*メソッド
                │           │
                └─────┬─────┘
                      ▼
                 値を出力 ────────────▶ スカラー値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | メイン機能 |
| Get-DbaRandomizedDataset.ps1 | `public/Get-DbaRandomizedDataset.ps1` | ソース | 呼び出し元機能 |
| Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | ソース | タイプ一覧取得 |
| en.randomizertypes.csv | `bin/randomizer/en.randomizertypes.csv` | データ | タイプ定義 |
| Bogus.dll | `bin/` | ライブラリ | フェイクデータ生成エンジン |
