# 機能設計書 499-New-DbaAgentJobCategory

## 概要

本ドキュメントは、SQL Server Agent ジョブカテゴリの作成機能 `New-DbaAgentJobCategory` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent のジョブカテゴリを新規作成する機能である。ジョブカテゴリは、関連するジョブをグループ化し、管理・レポート作成を効率化するために使用される。

**業務上の目的・背景**：SQL Server Agent では多数のジョブを管理することがあり、これらを機能別（バックアップ、メンテナンス、ETL等）、部門別、優先度別などで分類管理することが運用効率上重要である。カテゴリを使用することで、SSMS でのジョブ管理が容易になり、レポート作成やメンテナンス作業の効率が向上する。本機能により、PowerShell からカテゴリの一括作成が可能となり、複数インスタンスへの標準化された設定展開ができる。

**機能の利用シーン**：
- 新規 SQL Server インスタンスのセットアップ時
- ジョブ管理の標準化（カテゴリ体系の展開）
- 複数インスタンスへのカテゴリ一括作成
- 自動化スクリプトでのカテゴリ管理

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. カテゴリの重複チェック
3. SMO JobCategory オブジェクトの作成
4. カテゴリタイプの設定
5. カテゴリの保存と結果出力

**関連システム・外部連携**：SQL Server Agent ジョブシステム。

**権限による制御**：SQL Server への sysadmin 権限が必要。SQL Server 2000 以上が対象。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | ジョブカテゴリ管理 | 主画面 | SQLエージェントジョブカテゴリの新規作成 |

## 機能種別

データ作成（INSERT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Category | string[] | Yes | カテゴリ名 | 必須、配列対応、空文字不可 |
| CategoryType | string | No | カテゴリタイプ | LocalJob/MultiServerJob/None、デフォルトLocalJob |
| Force | switch | No | 確認プロンプトをスキップ | - |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- ユーザー指定のパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | カテゴリ名 |
| ID | int | カテゴリID |
| CategoryType | enum | カテゴリタイプ（LocalJob/MultiServerJob/None） |

### 出力先

PowerShell パイプラインへの出力（`Microsoft.SqlServer.Management.Smo.Agent.JobCategory` オブジェクト、Get-DbaAgentJobCategory 経由）

## 処理フロー

### 処理シーケンス

```
1. パラメータ前処理
   └─ Force および CategoryType のデフォルト設定
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. カテゴリ名ループ
   └─ 各 Category 名に対して処理
5. 重複チェック
   └─ 同名カテゴリの存在確認
6. SMO JobCategory オブジェクト作成
   └─ New-Object Microsoft.SqlServer.Management.Smo.Agent.JobCategory
7. カテゴリタイプ設定
   └─ CategoryType プロパティの設定
8. カテゴリ作成
   └─ $jobCategory.Create()
9. JobServer リフレッシュ
   └─ 作成後のコレクション更新
10. 結果出力
    └─ Get-DbaAgentJobCategory で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Force 指定?}
    B -->|Yes| C[ConfirmPreference = none]
    B -->|No| D{CategoryType 指定?}
    C --> D
    D -->|No| E[CategoryType = LocalJob]
    D -->|Yes| F{SqlInstance ループ}
    E --> F
    F --> G[Connect-DbaInstance]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function]
    I --> F
    H -->|Yes| J{Category ループ}
    J --> K{同名カテゴリ存在?}
    K -->|Yes| L[Stop-Function でスキップ]
    L --> J
    K -->|No| M[ShouldProcess 確認]
    M --> N[SMO JobCategory 作成]
    N --> O{AG リスナー経由?}
    O -->|Yes| P[Stop-Function]
    O -->|No| Q[CategoryType 設定]
    Q --> R[jobCategory.Create]
    R --> S[JobServer.Refresh]
    S --> T[Get-DbaAgentJobCategory]
    T --> J
    J -->|終了| F
    F -->|終了| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-499-01 | カテゴリ名一意性 | 同名カテゴリが存在する場合は作成をスキップ | 常時 |
| BR-499-02 | AG リスナー制限 | 可用性グループリスナー経由ではカテゴリ作成不可 | AG リスナー接続時 |
| BR-499-03 | Force でプロンプトスキップ | Force 指定時は確認プロンプトをスキップ | Force 指定時 |
| BR-499-04 | CategoryType デフォルト | 未指定時は LocalJob が適用される | CategoryType 未指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カテゴリ作成 | msdb.dbo.syscategories | INSERT | ジョブカテゴリの作成 |

### テーブル別操作詳細

#### msdb.dbo.syscategories

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | category_id, name, category_class, category_type | SMO JobCategory.Create() 経由 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue |
| CategoryExists | 重複エラー | 同名カテゴリが存在 | Stop-Function で Continue |
| AGListener | AG制限 | AGリスナー経由での接続 | Stop-Function で Continue |

### リトライ仕様

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

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

各カテゴリは個別に作成される。SMO の Create() メソッドで内部的にトランザクション管理。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- カテゴリ作成は軽量な操作

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- sysadmin 権限が必要
- ShouldProcess（WhatIf/Confirm）をサポート

## 備考

- 複数カテゴリを一度に作成可能（Category パラメータは配列対応）
- CategoryType の値:
  - LocalJob: ローカルインスタンスで実行されるジョブ用（デフォルト）
  - MultiServerJob: マルチサーバー環境用
  - None: 汎用カテゴリ

---

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

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

### 推奨読解順序

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

SMO の JobCategory オブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | 51行目の .OUTPUTS セクション |

**読解のコツ**: JobCategory は SMO の軽量オブジェクトで、ID、Name、CategoryType の基本プロパティを持つ。CategoryType は LocalJob/MultiServerJob/None の3値。

#### Step 2: パラメータと前処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | 79-91行目のパラメータ定義、93-100行目の begin ブロック |

**主要処理フロー**:
1. **94行目**: Force による ConfirmPreference 設定
2. **96-99行目**: CategoryType 未指定時のデフォルト設定

#### Step 3: カテゴリ作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | 102-141行目の process ブロック |

**主要処理フロー**:
- **111-112行目**: 既存カテゴリチェック `$cat -in $server.JobServer.JobCategories.Name`
- **115行目**: ShouldProcess 確認
- **117-118行目**: SMO JobCategory オブジェクト作成
- **127行目**: CategoryType 設定
- **129行目**: jobCategory.Create() でカテゴリ作成
- **131行目**: JobServer.Refresh() でコレクション更新
- **137行目**: Get-DbaAgentJobCategory で出力

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

```
New-DbaAgentJobCategory
    │
    ├─ begin ブロック
    │      ├─ Force による ConfirmPreference 設定
    │      └─ CategoryType デフォルト設定
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Stop-Function
    │      └─ エラー処理
    │
    ├─ ShouldProcess
    │      └─ 確認プロンプト
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.Agent.JobCategory
    │      └─ SMO JobCategory オブジェクト作成
    │
    ├─ JobCategory.Create()
    │      └─ カテゴリ作成
    │
    ├─ JobServer.Refresh()
    │      └─ コレクションのリフレッシュ
    │
    └─ Get-DbaAgentJobCategory
           └─ 作成したカテゴリの取得・出力
```

### データフロー図

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

SqlInstance ─────────────┬─► Connect-DbaInstance ──────────────► SMO Server
SqlCredential ───────────┘                                              │
                                                                        ▼
Force ───────────────────────► ConfirmPreference 設定                   │
                                                                        │
CategoryType ────────────────► デフォルト設定（LocalJob）               │
                                                                        │
Category ────────────────────► カテゴリ重複チェック                     │
                                        │                               │
                                   存在する?                            │
                                   │      │                             │
                                 Yes      No                            │
                                   │      │                             │
                             スキップ     ▼                             │
                                    ShouldProcess 確認                  │
                                         │                              │
                                         ▼                              │
                                  New-Object JobCategory                │
                                         │                              │
CategoryType ────────────────────► CategoryType 設定                    │
                                         │                              │
                                         ▼                              │
                                  JobCategory.Create()                  │
                                         │                              │
                                         ▼                              │
                                  JobServer.Refresh()                   │
                                         │                              │
                                         ▼                              │
                              Get-DbaAgentJobCategory ────► JobCategory オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | ソース | メイン機能実装 |
| Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | ソース | カテゴリ取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー処理 |
