# 機能設計書 68-cur_group_id

## 概要

本ドキュメントは、dplyrパッケージの`cur_group_id`関数の機能設計について記述する。`cur_group_id`は現在のグループの一意な数値IDを取得するコンテキスト関数である。

### 本機能の処理概要

`cur_group_id`関数は、`summarise()`、`mutate()`などのデータマスク動詞内で呼び出され、現在処理中のグループを識別する一意な整数値を返す。このIDは、グループがソートされた順序で1から始まる連番となる。

**業務上の目的・背景**：データ分析において、各グループを一意に識別する数値が必要な場合がある。例えば、グループごとに異なる色を割り当てる、グループIDに基づくシーケンシャルな処理、グループを参照する外部システムとの連携などに使用される。`cur_group_id()`は、このような用途に対応するための簡潔なインターフェースを提供する。

**機能の利用シーン**：
- グループごとに一意なIDを割り当てる場合
- グラフの色分けでグループを識別する場合
- グループを参照する外部データとの連携時
- シーケンシャルなバッチ処理でグループを追跡する場合

**主要な処理内容**：
1. 現在のデータマスクコンテキストを取得（`peek_mask()`）
2. マスクから現在のグループIDを取得（`get_current_group_id()`）
3. グループID（整数）を返す

**関連システム・外部連携**：DataMaskオブジェクトに依存している。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、画面は存在しない |

## 機能種別

コンテキスト関数 / 情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | パラメータなし | - |

### 入力データソース

現在のデータマスクコンテキスト（`peek_mask()`経由で取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | integer | 現在のグループの一意な整数ID（1から始まる） |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. データマスクの取得
   └─ peek_mask(): 現在のコンテキストからDataMaskを取得

2. グループIDの取得
   └─ mask$get_current_group_id(): 現在のグループIDを取得

3. 結果の返却
   └─ 整数値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{データマスク内?}
    B -->|Yes| C[peek_mask]
    B -->|No| D[エラー]
    C --> E[get_current_group_id]
    E --> F[整数値返却]
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-68-01 | コンテキスト制限 | データマスク動詞内でのみ使用可能 | 常時 |
| BR-68-02 | 連番ID | IDは1から始まる連続した整数 | 常時 |
| BR-68-03 | ソート順序 | グループはgroup_by()の列でソートされた順序でIDが付与される | グループ化時 |
| BR-68-04 | 非グループ化時 | グループ化されていない場合もID=1が返される | 非グループ化時 |

### 計算ロジック

```
cur_group_id()の動作:
- グループ化されている場合: 1からnグループまでの整数（ソート順）
- グループ化されていない場合: 常に1
- rowwise()の場合: 各行が1グループなので、行番号と同じ

例:
  df |> group_by(g) |> mutate(id = cur_group_id())
  # 各行のグループに対応するIDがid列に格納される
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンテキストエラー | データマスク動詞外で呼び出された場合 | mutate()やsummarise()内で呼び出す |

### リトライ仕様

該当なし

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

該当なし（本関数はトランザクション処理を行わない）

## パフォーマンス要件

グループIDは参照渡しで更新されており、取得はO(1)で非常に高速。ただし、返却時に`duplicate()`で複製される。

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

特になし

## 備考

- data.tableの`.GRP`に相当する機能
- `cur_group()`がグループキーそのものを返すのに対し、`cur_group_id()`は単一の数値IDを返す
- IDは内部でC言語レベルで参照更新されるため、パフォーマンスが最適化されている

---

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

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

### 推奨読解順序

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

本関数はDataMaskオブジェクトとグループIDの管理方法に依存している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.R | `R/context.R` | cur_group_id関数定義（62-64行目） |
| 1-2 | data-mask.R | `R/data-mask.R` | get_current_group_idメソッド（187-194行目） |

**読解のコツ**: `get_current_group_id()`は`duplicate()`で値を複製して返す。これは、C言語レベルで参照更新される値を安全に返すため。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | context.R | `R/context.R` | `cur_group_id`関数本体（62-64行目） |

**主要処理フロー**:
1. **63行目**: `peek_mask()$get_current_group_id()` - 唯一の処理行

#### Step 3: DataMaskの内部構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data-mask.R | `R/data-mask.R` | get_current_group_id メソッド（187-191行目） |
| 3-2 | data-mask.R | `R/data-mask.R` | env_current_group_info（56-59行目） |
| 3-3 | test-context.R | `tests/testthat/test-context.R` | テストケース（26-38行目） |

**主要ポイント**:
- **data-mask.R 56-59行目**: グループIDを格納する環境の初期化
- **data-mask.R 187-191行目**: `duplicate()`で複製して返す
- **test-context.R 26-38行目**: 基本的な動作のテスト

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

```
cur_group_id()
    │
    └─ peek_mask()                      [context.R]
           │
           └─ context_peek("mask")      [context.R]
                  │
                  └─ DataMask$get_current_group_id()  [data-mask.R]
                         │
                         └─ duplicate(env_current_group_info["dplyr:::current_group_id"])
```

### データフロー図

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

(コンテキスト) ──▶ peek_mask() ──▶ DataMask ──▶ get_current_group_id() ──▶ 整数
                                      │
                                      ▼
                          env_current_group_info
                          ["dplyr:::current_group_id"]
                                      │
                                      ▼
                               duplicate()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| context.R | `R/context.R` | ソース | cur_group_id関数およびその他のコンテキスト関数 |
| data-mask.R | `R/data-mask.R` | ソース | DataMaskクラスの実装 |
| test-context.R | `tests/testthat/test-context.R` | テスト | コンテキスト関数のユニットテスト |
