# 機能設計書 245-Test-DbaDbDataMaskingConfig

## 概要

本ドキュメントは、データマスキング構成JSONファイルを構造的および論理的エラーについて検証する機能 `Test-DbaDbDataMaskingConfig` の設計仕様を記載する。

### 本機能の処理概要

この機能は、データマスキング構成JSONファイルを検証し、カラムプロパティ、データ型、マスキングタイプ、およびアクション構成をdbatools要件に対してチェックする。検証に失敗したテーブルとカラムの詳細なエラー情報を返し、データマスキング操作実行前に構成問題を特定するのに役立つ。

**業務上の目的・背景**：データマスキングは個人情報保護やセキュリティコンプライアンスのために重要な機能である。構成ファイルの事前検証により、実行時エラーを防止し、マスキング処理の成功率を向上させる。複雑なマスキング構成のトラブルシューティングには、詳細なエラー情報が不可欠である。

**機能の利用シーン**：
- データマスキング構成ファイルの事前検証
- 構成ファイル修正後のバリデーション
- 日付・数値アクションの設定検証
- CI/CDパイプラインでの自動検証

**主要な処理内容**：
1. JSON構成ファイルの読み込みとパース
2. 構成ファイルのタイプ（DataMaskingConfiguration）確認
3. 各テーブル・カラムの必須/許可プロパティ存在確認
4. カラムタイプのサポート状況確認
5. マスキングタイプ・サブタイプの有効性確認
6. 日付型の検証（MinValue、MaxValueの日付形式）
7. アクション設定の検証（datetime、number、columnカテゴリ）
8. エラー情報の出力

**関連システム・外部連携**：Bogusランダム化ライブラリ（Get-DbaRandomizedType経由）。

**権限による制御**：ファイルシステムへの読み取りアクセスが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 58 | データマスキング | 補助機能 | マスキング設定のテスト |

## 機能種別

バリデーション処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FilePath | string | Yes | 検証するJSON構成ファイルへのパス | ファイルが存在すること |
| EnableException | switch | No | 例外のスロー有効化 | - |

### 入力データソース

- JSON構成ファイル（New-DbaDbMaskingConfigで生成）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Table | string | エラーが見つかった構成内のテーブル名 |
| Column | string | エラーが見つかったテーブル内のカラム名 |
| Value | string | 問題のある値またはプロパティ名のカンマ区切りリスト |
| Error | string | 検出されたバリデーションエラーの説明 |

### 出力先

- PowerShellパイプライン出力（PSCustomObject）
- 構成ファイルが有効でエラーがない場合は出力なし

## 処理フロー

### 処理シーケンス

```
1. beginブロックで初期検証
   └─ ファイル存在確認
   └─ JSONパースとタイプ確認
   └─ 各種定義（サポートデータ型、許可プロパティ、アクション設定など）
2. processブロックで各テーブル・カラムをループ
   └─ 必須/許可プロパティの存在確認
   └─ カラムタイプの検証
   └─ マスキングタイプ/サブタイプの検証
   └─ 日付型の特別検証
   └─ アクション設定の検証
3. エラー情報をPSCustomObjectで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ファイル存在?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D[JSONパース]
    D --> E{パース成功?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G{Type確認}
    G -->|不正| H[Stop-Function]
    G -->|正常| I{各テーブルをループ}
    I --> J{各カラムをループ}
    J --> K[必須プロパティチェック]
    K --> L[許可プロパティチェック]
    L --> M[カラムタイプチェック]
    M --> N[マスキングタイプチェック]
    N --> O[サブタイプチェック]
    O --> P{日付型?}
    P -->|Yes| Q[日付検証]
    P -->|No| R{アクション有り?}
    Q --> R
    R -->|Yes| S[アクション検証]
    R -->|No| J
    S --> J
    J -->|完了| I
    I -->|完了| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-245-1 | タイプ確認 | Type = "DataMaskingConfiguration" であること | 常時 |
| BR-245-2 | 必須プロパティ | 13個の必須プロパティが存在すること | 各カラムに対して |
| BR-245-3 | 許可プロパティ | 許可された15個のプロパティのみ使用可能 | 各カラムに対して |
| BR-245-4 | 日付型検証 | date型では MaskingType=Date、MinValue/MaxValueが有効な日付 | ColumnType=date の場合 |
| BR-245-5 | アクションカテゴリ | datetime、number、columnのみ許可 | アクション指定時 |
| BR-245-6 | アクションタイプ | Add、Divide、Multiply、Nullify、Set、Subtractのみ許可 | アクション指定時 |

### 必須カラムプロパティ

```
Action, CharacterString, ColumnType, Composite, Deterministic, Format,
MaskingType, MaxValue, MinValue, Name, Nullable, KeepNull, SubType
```

### 許可カラムプロパティ

```
Action, CharacterString, ColumnType, Composite, Deterministic, Format,
MaskingType, MaxValue, MinValue, Name, Nullable, KeepNull, Separator,
SubType, StaticValue
```

### サポートされるデータ型

```
bigint, bit, bool, char, date, datetime, datetime2, decimal, float, int,
money, nchar, ntext, nvarchar, smalldatetime, smallint, text, time,
tinyint, uniqueidentifier, userdefineddatatype, varchar
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FileNotFound | ファイルエラー | 構成ファイルが見つからない | Stop-Functionで処理終了 |
| ParseError | パースエラー | JSONパース失敗 | Stop-Functionで処理終了 |
| TypeMissing | タイプエラー | Typeプロパティがない | Stop-Functionで処理終了 |
| InvalidType | タイプエラー | TypeがDataMaskingConfigurationでない | Stop-Functionで処理終了 |
| MissingProperty | プロパティエラー | 必須プロパティがない | エラー情報を出力 |
| ExtraProperty | プロパティエラー | 許可されていないプロパティがある | エラー情報を出力 |
| InvalidColumnType | データ型エラー | サポートされないカラムタイプ | エラー情報を出力 |
| InvalidMaskingType | マスキングエラー | 無効なマスキングタイプ | エラー情報を出力 |
| InvalidSubType | サブタイプエラー | 無効なサブタイプ | エラー情報を出力 |
| InvalidDateValue | 日付エラー | MinValue/MaxValueが無効な日付 | エラー情報を出力 |
| InvalidActionCategory | アクションエラー | 許可されないアクションカテゴリ | エラー情報を出力 |
| InvalidActionType | アクションエラー | 許可されないアクションタイプ | エラー情報を出力 |

### リトライ仕様

リトライ処理なし。ファイル読み込みエラーは即座に終了。

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

ファイルシステム操作のみのため、トランザクション管理は不要。

## パフォーマンス要件

- JSON構成ファイルのサイズに応じて処理時間が変動
- Get-DbaRandomizedTypeの呼び出しが1回のみ（beginブロック）

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

- ファイルシステムへの読み取りアクセス権限が必要
- データマスキング構成ファイルには機密情報を含めないこと推奨

## 備考

- sysadminアクセス権限がSQL Server操作時に必要（ドキュメントより）
- 構成ファイルはNew-DbaDbMaskingConfigで生成されることを前提
- Test-DbaDbDataGeneratorConfigと類似構造だが、アクション検証が追加

---

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

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

### 推奨読解順序

#### Step 1: コマンド構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDbDataMaskingConfig.ps1 | `public/Test-DbaDbDataMaskingConfig.ps1` | パラメータ定義、コメントベースヘルプ |

**読解のコツ**: beginブロックで定義される各種検証用定数に注目。

#### Step 2: beginブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDbDataMaskingConfig.ps1 | `public/Test-DbaDbDataMaskingConfig.ps1` | 検証用定数の定義 |

**主要処理フロー**:
1. **73-78行目**: ファイル存在確認
2. **80-84行目**: JSONパース
3. **86-94行目**: 構成タイプの検証
4. **96行目**: サポートデータ型の定義
5. **98行目**: ランダム化タイプの取得
6. **100-101行目**: 必須/許可カラムプロパティの定義
7. **103-108行目**: アクション関連定数の定義
8. **110-111行目**: datetime/numberアクション必須プロパティの定義

#### Step 3: processブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaDbDataMaskingConfig.ps1 | `public/Test-DbaDbDataMaskingConfig.ps1` | 各種検証ロジック |

**主要処理フロー**:
1. **121-146行目**: 必須/許可プロパティの検証
2. **148-156行目**: カラムタイプの検証
3. **158-166行目**: マスキングタイプの検証
4. **168-176行目**: サブタイプの検証
5. **178-228行目**: 日付型の特別検証
6. **230-330行目**: アクション設定の検証

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

```
Test-DbaDbDataMaskingConfig
    │
    ├─ Test-Path
    │      └─ ファイル存在確認
    │
    ├─ Get-Content | ConvertFrom-Json
    │      └─ JSON読み込みとパース
    │
    ├─ Get-DbaRandomizedType
    │      └─ 有効なマスキングタイプ一覧取得
    │
    ├─ Compare-Object
    │      └─ プロパティ比較
    │
    ├─ [datetime]::TryParse
    │      └─ 日付形式検証
    │
    └─ PSCustomObject出力
           └─ エラー情報
```

### データフロー図

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

FilePath       ───▶ Test-Path ───▶ 存在確認
                           │
                           ▼
                    Get-Content ───▶ JSONテキスト
                           │
                           ▼
                    ConvertFrom-Json ───▶ $json
                           │
                           ▼
                    タイプ検証 ───▶ 検証結果
                           │
                           ▼
                    カラム検証 ───▶ プロパティ・タイプ検証
                           │
                           ▼
                    日付検証 ───▶ MinValue/MaxValue検証
                           │
                           ▼
                    アクション検証 ───▶ PSCustomObject（エラー情報）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDbDataMaskingConfig.ps1 | `public/Test-DbaDbDataMaskingConfig.ps1` | ソース | メイン機能実装 |
| Get-DbaRandomizedType.ps1 | `public/Get-DbaRandomizedType.ps1` | ソース | マスキングタイプ一覧取得 |
| New-DbaDbMaskingConfig.ps1 | `public/New-DbaDbMaskingConfig.ps1` | ソース | 構成ファイル生成（関連） |
| Invoke-DbaDbDataMasking.ps1 | `public/Invoke-DbaDbDataMasking.ps1` | ソース | マスキング実行（関連） |
