# 機能設計書 32-日付取得・生成

## 概要

本ドキュメントは、Nushellにおける日付取得・生成機能（date now, date to-timezone, date humanize）の設計を記述する。これらのコマンドは現在日時の取得、タイムゾーン変換、人間が読みやすい相対日付表示を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
日付・時刻の操作はシェルスクリプトやデータ処理において頻繁に必要となる基本機能である。ファイルのタイムスタンプ確認、ログ分析、スケジュール管理など多様な用途で利用される。Nushellは構造化データを扱うシェルとして、Date型をネイティブサポートし、直感的な日付操作を可能にする。

**機能の利用シーン**：
- スクリプト内での現在日時の取得
- 異なるタイムゾーン間での日付変換（UTCからローカル時間等）
- ログや履歴の相対時間表示（「3時間前」「昨日」等）
- 国際的なチームでの時間調整

**主要な処理内容**：
1. `date now`: 現在のローカル日時を取得する
2. `date to-timezone`: 指定したタイムゾーンに日付を変換する
3. `date humanize`: 日付を現在からの相対時間として人間が読みやすい形式で表示する
4. `date list-timezone`: サポートされているタイムゾーン一覧を表示する

**関連システム・外部連携**：
- chrono クレート（日付・時刻処理）
- chrono-tz クレート（タイムゾーンデータベース）
- nu-protocol クレートのDate型

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 参照画面 | コマンド入力・結果表示 |

## 機能種別

計算処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input (date to-timezone/humanize) | Date/String | Yes | 変換対象の日付 | Date型または日付文字列 |
| timezone (date to-timezone) | String | Yes | 変換先タイムゾーン | 有効なタイムゾーン名 |

### 入力データソース

- `date now`: 引数なし（システム時刻を使用）
- `date to-timezone`: パイプラインからのDate/String入力 + タイムゾーン引数
- `date humanize`: パイプラインからのDate/String入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| date now 出力 | Date | 現在のローカル日時 |
| date to-timezone 出力 | Date | 変換後の日時 |
| date humanize 出力 | String | 相対時間文字列（例：「3 hours ago」） |
| date list-timezone 出力 | Table | タイムゾーン名の一覧テーブル |

### 出力先

パイプライン出力（次のコマンドへ）

## 処理フロー

### 処理シーケンス

```
[date now]
1. システムのローカル時刻を取得
   └─ chrono::Local::now() を呼び出し
2. タイムゾーン情報付きのDate値を生成
   └─ Value::date() でラップして返却

[date to-timezone]
1. 入力値の取得と型判定
   └─ Date型またはString型を受け付け
2. タイムゾーン引数の検証
   └─ chrono-tzで有効性を確認
3. タイムゾーン変換の実行
   └─ datetime_in_timezone() で変換
4. 変換後のDate値を返却

[date humanize]
1. 入力日付の取得と解析
   └─ Date型またはString型を解析
2. 現在時刻との差分を計算
3. 人間が読みやすい形式に変換
   └─ nu_protocol::human_time_from_now() を使用
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{コマンド種別}
    B -->|date now| C[Local::now取得]
    C --> D[Date値生成]
    D --> E[返却]
    B -->|date to-timezone| F{入力型判定}
    F -->|Date| G[タイムゾーン変換]
    F -->|String| H[日付パース]
    H --> G
    G --> I{変換成功?}
    I -->|Yes| J[変換後Date返却]
    I -->|No| K[エラー返却]
    B -->|date humanize| L{入力型判定}
    L -->|Date| M[相対時間計算]
    L -->|String| N[日付パース]
    N --> M
    M --> O[文字列返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-32-1 | タイムゾーン検証 | 無効なタイムゾーン名はエラー | date to-timezone実行時 |
| BR-32-2 | 日付文字列パース | 複数フォーマットをサポート | String入力時 |
| BR-32-3 | localキーワード | "local"でローカルTZを指定可能 | date to-timezone実行時 |
| BR-32-4 | Nothing入力 | Nothing入力時は現在時刻を使用 | date to-timezone/humanize |

### 計算ロジック

- タイムゾーン変換: chrono-tzを使用した標準的な変換
- 相対時間: 現在時刻との差分をhuman_time_from_now()で文字列化

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PipelineEmpty | 入力エラー | パイプライン入力が空 | 入力を提供する |
| TypeMismatch | 型エラー | 無効なタイムゾーン名 | 有効なTZ名を使用 |
| OnlySupportsThisInputType | 型エラー | Date/String以外の入力 | 正しい型を入力 |
| DatetimeParseError | パースエラー | 日付文字列の解析失敗 | 正しいフォーマットを使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- date now: システム時刻取得のため即座に完了
- date to-timezone: タイムゾーン変換は軽量処理
- date humanize: 差分計算と文字列生成は即座に完了

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

- システム時刻へのアクセスのみ
- 外部ネットワークアクセスなし

## 備考

- タイムゾーン名はIANA Time Zone Database形式（例：`Asia/Tokyo`, `US/Hawaii`）
- `+0500`のような固定オフセット形式もサポート
- `date list-timezone`でサポートされているタイムゾーン一覧を確認可能

---

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

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

### 推奨読解順序

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

NushellのDate型とchronoライブラリの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | value.rs | `crates/nu-protocol/src/value/mod.rs` | Value::Date の定義 |

**読解のコツ**: NushellのDate型はchrono::DateTime<FixedOffset>をラップしている。

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

各コマンドのCommand trait実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | now.rs | `crates/nu-command/src/date/now.rs` | DateNowコマンドの実装 |
| 2-2 | to_timezone.rs | `crates/nu-command/src/date/to_timezone.rs` | DateToTimezoneコマンドの実装 |
| 2-3 | humanize.rs | `crates/nu-command/src/date/humanize.rs` | DateHumanizeコマンドの実装 |

**主要処理フロー**:
1. **26-36行目 (now.rs)**: run関数でLocal::now()を呼び出し
2. **52-69行目 (to_timezone.rs)**: run関数で入力をmapして変換
3. **111-150行目 (to_timezone.rs)**: helper関数で型別の処理分岐
4. **139-150行目 (to_timezone.rs)**: _to_timezone関数で実際の変換

#### Step 3: ユーティリティを理解する

日付パースとタイムゾーン処理のヘルパー関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utils.rs | `crates/nu-command/src/date/utils.rs` | parse_date_from_string関数 |
| 3-2 | parser.rs | `crates/nu-command/src/date/parser.rs` | datetime_in_timezone関数 |

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

```
DateToTimezone::run()
    │
    ├─ call.req() [タイムゾーン引数取得]
    │
    └─ input.map(helper)
           │
           ├─ [Value::Date] → _to_timezone()
           │                       │
           │                       └─ datetime_in_timezone()
           │
           ├─ [Value::String] → parse_date_from_string()
           │                       │
           │                       └─ _to_timezone()
           │
           └─ [Value::Nothing] → Local::now() → _to_timezone()
```

### データフロー図

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

Date/String ───▶ DateToTimezone::run() ───▶ Date
    │                  │
    │                  ├─ 入力型判定
    │                  │
    │                  ├─ 日付パース（String時）
    │                  │
    │                  └─ タイムゾーン変換
    │
TZ名 ──────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| now.rs | `crates/nu-command/src/date/now.rs` | ソース | date now コマンド実装 |
| to_timezone.rs | `crates/nu-command/src/date/to_timezone.rs` | ソース | date to-timezone コマンド実装 |
| humanize.rs | `crates/nu-command/src/date/humanize.rs` | ソース | date humanize コマンド実装 |
| list_timezone.rs | `crates/nu-command/src/date/list_timezone.rs` | ソース | date list-timezone コマンド実装 |
| utils.rs | `crates/nu-command/src/date/utils.rs` | ソース | 日付パースユーティリティ |
| parser.rs | `crates/nu-command/src/date/parser.rs` | ソース | タイムゾーン変換ヘルパー |
| mod.rs | `crates/nu-command/src/date/mod.rs` | ソース | dateモジュール定義 |
