# 機能設計書 67-cur_group

## 概要

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

### 本機能の処理概要

`cur_group`関数は、`summarise()`、`mutate()`などのデータマスク動詞内で呼び出され、現在処理中のグループを識別するキーをtibbleとして返す。グループキーは、`group_by()`で指定した列の値を含む1行のデータフレームである。

**業務上の目的・背景**：データ分析において、グループごとの処理を行う際に、現在処理中のグループが何かを知る必要がある場合がある。例えば、グループに応じて異なる処理を行う、グループ情報をログに出力する、グループごとにファイルを出力するなどの場合に使用される。`cur_group()`は、この情報を構造化された形式（tibble）で提供する。

**機能の利用シーン**：
- グループに応じた条件分岐処理を行う場合
- グループ情報をログや出力に含める場合
- グループごとにファイルを出力する場合
- デバッグ時にグループ情報を確認する場合

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | tibble | 現在のグループキー（1行、グループ化変数の列を含む） |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

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

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

3. 結果の返却
   └─ 1行のtibbleを返す
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | コンテキスト制限 | データマスク動詞内でのみ使用可能 | 常時 |
| BR-67-02 | グループキー | グループ化列の値を含む1行のtibbleを返す | グループ化時 |
| BR-67-03 | 非グループ化時 | グループ化されていない場合は空のtibbleを返す | 非グループ化時 |

### 計算ロジック

```
cur_group()の動作:
- グループ化されている場合: グループ化列の現在の値を含む1行のtibble
- グループ化されていない場合: 0行のtibble

例:
  df |> group_by(g) |> summarise(data = list(cur_group()))
  # 各グループのキーがdata列にリストとして格納される
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

グループキーは事前計算されており、現在のグループインデックスでスライスするだけなのでO(1)で取得可能。

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

特になし

## 備考

- data.tableの`.BY`に相当する機能
- `group_keys()`はすべてのグループのキーを返すのに対し、`cur_group()`は現在のグループのキーのみを返す
- 空のグループ化データフレームの場合、特別な処理が行われる

---

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

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

### 推奨読解順序

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

本関数はDataMaskオブジェクトとグループキーの構造に依存している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.R | `R/context.R` | cur_group関数定義（56-58行目） |
| 1-2 | data-mask.R | `R/data-mask.R` | current_keyメソッド（159-170行目） |

**読解のコツ**: `current_key()`は事前計算されたkeysから現在のグループIDでスライスして取得する。

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data-mask.R | `R/data-mask.R` | current_key メソッド（159-170行目） |
| 3-2 | test-context.R | `tests/testthat/test-context.R` | テストケース（1-24行目） |

**主要ポイント**:
- **data-mask.R 159-170行目**: keysからスライスして取得、0グループの場合は特別処理
- **test-context.R 1-13行目**: 基本的な動作のテスト

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

```
cur_group()
    │
    └─ peek_mask()                      [context.R]
           │
           └─ context_peek("mask")      [context.R]
                  │
                  └─ DataMask$current_key()  [data-mask.R]
                         │
                         └─ vec_slice(keys, current_group_id)
```

### データフロー図

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

(コンテキスト) ──▶ peek_mask() ──▶ DataMask ──▶ current_key() ──▶ tibble（1行）
                                      │
                                      ▼
                                   private$keys
                                      │
                                      ▼
                            vec_slice(keys, group_id)
```

### 関連ファイル一覧

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