# 機能設計書 62-UUID生成

## 概要

本ドキュメントは、NushellにおけるUUID（Universally Unique Identifier）生成機能の設計を記述する。複数のUUIDバージョン（v1, v3, v4, v5, v7）に対応し、用途に応じた一意識別子の生成を提供する。

### 本機能の処理概要

UUID生成機能は、RFC 4122に準拠した様々なバージョンのUUIDを生成する。各バージョンには異なる生成アルゴリズムがあり、用途に応じて選択できる。デフォルトはランダムベースのv4 UUIDである。

**業務上の目的・背景**：分散システムやデータベースにおいて、グローバルに一意な識別子が必要となる場面は多い。UUIDはその標準的なソリューションであり、データベースの主キー、ファイル名、セッションID、トランザクションIDなど幅広い用途に使用される。本機能により、Nushellスクリプト内で標準準拠のUUIDを簡単に生成できる。

**機能の利用シーン**：
- データベースレコードの主キー生成
- 一時ファイルや一意なディレクトリ名の生成
- API のトランザクションID・リクエストID生成
- 分散システムでのイベント識別子生成
- 設定ファイルやリソースの一意識別

**主要な処理内容**：
1. v1 UUID - タイムスタンプ + MACアドレスベース
2. v3 UUID - 名前空間 + 名前のMD5ハッシュベース
3. v4 UUID - 完全ランダムベース（デフォルト）
4. v5 UUID - 名前空間 + 名前のSHA-1ハッシュベース
5. v7 UUID - タイムスタンプ + ランダムベース（ソート可能）

**関連システム・外部連携**：外部システムとの直接連携はない。Rustの`uuid`クレートを内部的に使用する。

**権限による制御**：特別な権限制御はなく、すべてのユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 結果表示画面 | コマンド実行結果としてのUUID文字列表示 |

## 機能種別

計算処理 / データ生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --version, -v | Int | No | UUIDバージョン（1, 3, 4, 5, 7）。デフォルト4 | 1, 3, 4, 5, 7 のいずれか |
| --namespace, -n | String | Conditional | 名前空間（v3, v5で必須）。dns, url, oid, x500, またはUUID文字列 | v3/v5では必須 |
| --name, -s | String | Conditional | 名前文字列（v3, v5で必須） | v3/v5では必須 |
| --mac, -m | String | Conditional | MACアドレス（v1で必須） | XX:XX:XX:XX:XX:XX 形式 |

### 入力データソース

コマンドライン引数およびフラグから入力を受け取る。パイプライン入力は使用しない（Type::Nothing）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| UUID | String | ハイフン区切り形式のUUID（例: 550e8400-e29b-41d4-a716-446655440000） |

### 出力先

パイプラインへの出力（PipelineData）。文字列として他のコマンドとパイプで連結可能。

## 処理フロー

### 処理シーケンス

```
1. コマンドの引数解析
   └─ バージョン、名前空間、名前、MACアドレスを取得

2. バリデーション
   └─ バージョンに応じた必須パラメータのチェック
   └─ バージョンとパラメータの互換性チェック

3. UUID生成
   └─ バージョンに応じた uuid クレートの関数呼び出し
   └─ v1: Uuid::new_v1(timestamp, mac)
   └─ v3: Uuid::new_v3(namespace, name)
   └─ v4: Uuid::new_v4()
   └─ v5: Uuid::new_v5(namespace, name)
   └─ v7: Uuid::new_v7(timestamp)

4. 結果のフォーマット
   └─ hyphenated() でハイフン区切り形式に変換
   └─ Value::string として返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{バージョン取得}
    B --> C{バージョン = 1?}
    C -->|Yes| D[MAC必須チェック]
    D --> E{MAC有効?}
    E -->|No| F[エラー: MAC必須]
    E -->|Yes| G[v1 UUID生成]
    C -->|No| H{バージョン = 3 or 5?}
    H -->|Yes| I[namespace/name必須チェック]
    I --> J{パラメータ有効?}
    J -->|No| K[エラー: パラメータ必須]
    J -->|Yes| L[v3/v5 UUID生成]
    H -->|No| M{バージョン = 4?}
    M -->|Yes| N[v4 UUID生成]
    M -->|No| O{バージョン = 7?}
    O -->|Yes| P[v7 UUID生成]
    O -->|No| Q[エラー: 未サポートバージョン]
    G --> R[ハイフン形式に変換]
    L --> R
    N --> R
    P --> R
    R --> S[Value::string として返却]
    S --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトバージョン | --version 省略時は v4 を使用 | バージョン省略時 |
| BR-002 | v1必須パラメータ | v1 には --mac が必須 | version = 1 |
| BR-003 | v3/v5必須パラメータ | v3, v5 には --namespace と --name が必須 | version = 3 or 5 |
| BR-004 | 名前空間の種類 | dns, url, oid, x500 または任意のUUID文字列 | v3/v5使用時 |
| BR-005 | 非互換パラメータ | v1 に namespace/name を指定するとエラー | version = 1 |
| BR-006 | 非互換パラメータ | v3/v5 に mac を指定するとエラー | version = 3 or 5 |
| BR-007 | 非互換パラメータ | v4/v7 に mac/namespace/name を指定するとエラー | version = 4 or 7 |

### 計算ロジック

- **v1 UUID**: 現在のタイムスタンプとMACアドレス（ノードID）から生成
- **v3 UUID**: 名前空間UUIDと名前のMD5ハッシュから生成（決定論的）
- **v4 UUID**: 128ビットのランダムビットから生成
- **v5 UUID**: 名前空間UUIDと名前のSHA-1ハッシュから生成（決定論的）
- **v7 UUID**: Unixエポックからのミリ秒タイムスタンプとランダムビットから生成

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IncorrectValue | バージョンエラー | サポート外のバージョン指定 | 1, 3, 4, 5, 7 を指定 |
| MissingParameter | パラメータ不足 | v1でMAC未指定、v3/v5でnamespace/name未指定 | 必須パラメータを追加 |
| IncorrectValue | MAC形式エラー | MACアドレスがXX:XX:XX:XX:XX:XX形式でない | 正しい形式で指定 |
| IncorrectValue | namespace形式エラー | namespaceが既知の値でもUUID形式でもない | dns/url/oid/x500 または有効なUUID |
| IncompatibleParametersSingle | 非互換パラメータ | バージョンと不整合なパラメータ指定 | 不要なパラメータを削除 |

### リトライ仕様

リトライは不要。UUID生成は入力が正しければ常に成功する。

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

本機能はトランザクション管理を行わない。

## パフォーマンス要件

- 単一のUUID生成は即座に完了する（マイクロ秒オーダー）
- v4 が最も高速（純粋なランダム生成）
- v1, v7 はタイムスタンプ取得を含むがなお高速
- v3, v5 はハッシュ計算を含むが十分高速

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

- v1 UUID はMACアドレスを含むため、プライバシーに関する考慮が必要
- v4 は暗号学的に安全なランダム生成器を使用（uuid クレートのデフォルト実装）
- v3/v5 は同じ入力から同じUUIDが生成される（決定論的）ため、秘密情報を名前に使用しないこと
- v7 はソート可能だが、生成時刻が推測可能となる点に注意

## 備考

- 出力形式は常にハイフン区切り（8-4-4-4-12）
- 大文字・小文字は小文字で統一

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uuid.rs | `crates/nu-command/src/random/uuid.rs` | random uuid コマンドの全体実装 |

**読解のコツ**: このファイルのみで完結している。Command トレイト実装と uuid() 関数、各種ヘルパー関数を順に読む。

#### Step 2: シグネチャと引数定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uuid.rs | `crates/nu-command/src/random/uuid.rs` | signature() メソッド |

**主要処理フロー**:
- **12-49行目**: シグネチャ定義
- **16-24行目**: --version フラグ（補完候補付き）
- **26-35行目**: --namespace フラグ（補完候補付き）
- **36-41行目**: --name フラグ
- **42-47行目**: --mac フラグ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uuid.rs | `crates/nu-command/src/random/uuid.rs` | uuid() 関数 |

**主要処理フロー**:
- **105-155行目**: `uuid()` 関数本体
- **112-113行目**: バージョン取得（デフォルト4）
- **115行目**: `validate_flags()` でパラメータ互換性チェック
- **117-152行目**: バージョン別のUUID生成ロジック
- **118-123行目**: v1 - タイムスタンプ + MAC
- **124-128行目**: v3 - 名前空間 + 名前（MD5）
- **129-132行目**: v4 - ランダム
- **133-137行目**: v5 - 名前空間 + 名前（SHA-1）
- **138-142行目**: v7 - タイムスタンプ + ランダム

#### Step 4: バリデーションロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | uuid.rs | `crates/nu-command/src/random/uuid.rs` | validate_flags() 関数 |

**主要処理フロー**:
- **157-236行目**: `validate_flags()` 関数
- **164-184行目**: v1 の場合、namespace/name 指定でエラー
- **185-195行目**: v3/v5 の場合、mac 指定でエラー
- **196-234行目**: v4/v7 の場合、mac/namespace/name 指定でエラー

#### Step 5: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | uuid.rs | `crates/nu-command/src/random/uuid.rs` | get_mac_address(), get_namespace_and_name() |

**主要処理フロー**:
- **238-282行目**: `get_mac_address()` - MACアドレスのパースと検証
- **256-263行目**: XX:XX:XX:XX:XX:XX 形式のチェック
- **284-332行目**: `get_namespace_and_name()` - 名前空間と名前の取得
- **313-328行目**: 既知の名前空間（dns, url, oid, x500）またはUUID文字列の解析

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

```
random uuid (uuid.rs)
    │
    ├─ signature()
    │      └─ フラグ定義（version, namespace, name, mac）
    │
    └─ run()
           └─ uuid()
                  │
                  ├─ validate_flags()
                  │      └─ パラメータ互換性チェック
                  │
                  ├─ v1: get_mac_address()
                  │      └─ MACアドレスパース
                  │      └─ Uuid::new_v1(timestamp, mac)
                  │
                  ├─ v3/v5: get_namespace_and_name()
                  │      └─ 名前空間解決（dns/url/oid/x500/UUID）
                  │      └─ Uuid::new_v3/v5(namespace, name)
                  │
                  ├─ v4: Uuid::new_v4()
                  │
                  └─ v7: Uuid::new_v7(timestamp)
```

### データフロー図

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

--version ─────────────────▶ バージョン決定 ──────────────▶ 生成関数選択
                                   │
--mac (v1) ────────────────▶ get_mac_address() ──────────▶ [u8; 6]
                                   │
--namespace (v3/v5) ───────▶ get_namespace_and_name() ──▶ (Uuid, String)
--name (v3/v5) ────────────▶        │
                                   │
                                   ▼
                            Uuid::new_vX()
                                   │
                                   ▼
                            uuid.hyphenated()
                                   │
                                   ▼
                            Value::string ─────────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uuid.rs | `crates/nu-command/src/random/uuid.rs` | ソース | random uuid コマンド実装 |
| mod.rs | `crates/nu-command/src/random/mod.rs` | ソース | モジュール定義、RandomUuid エクスポート |
