# 機能設計書 69-cur_group_rows

## 概要

本ドキュメントは、dplyrパッケージの`cur_group_rows`関数の機能設計について記述する。`cur_group_rows`は現在のグループに含まれる行の元データにおけるインデックスを取得するコンテキスト関数である。

### 本機能の処理概要

`cur_group_rows`関数は、`summarise()`、`mutate()`などのデータマスク動詞内で呼び出され、現在処理中のグループに含まれる行が元のデータフレームにおいてどの位置にあったかを示す整数ベクトルを返す。

**業務上の目的・背景**：データ分析において、グループ処理の結果を元のデータに対応付ける必要がある場合がある。例えば、グループごとの計算結果を元データの対応する行に反映させる、グループに属する行を特定してサブセットを作成するなどの用途がある。`cur_group_rows()`は、このような行レベルの対応付けを可能にする。

**機能の利用シーン**：
- 元データの特定の行を参照する必要がある場合
- グループの行インデックスをリストとして保存する場合
- `reframe()`と組み合わせてグループの行を展開する場合
- デバッグ時にどの行がグループに含まれているか確認する場合

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | integer vector | 現在のグループに含まれる行の元データにおけるインデックス |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

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

2. 行インデックスの取得
   └─ mask$current_rows(): 現在のグループの行インデックスを取得

3. 結果の返却
   └─ 整数ベクトルを返す
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-69-01 | コンテキスト制限 | データマスク動詞内でのみ使用可能 | 常時 |
| BR-69-02 | 元データインデックス | 返されるインデックスは元のデータフレームの行番号 | 常時 |
| BR-69-03 | グループ順序 | インデックスはグループ化前のデータの行順 | グループ化時 |
| BR-69-04 | 非グループ化時 | グループ化されていない場合は全行のインデックスを返す | 非グループ化時 |

### 計算ロジック

```
cur_group_rows()の動作:
- グループ化されている場合: 現在のグループに含まれる行の元インデックス
- グループ化されていない場合: 1:nrow(data)と同等
- rowwise()の場合: 現在の行番号のみ

例:
  df <- tibble(x = c("b", "a", "b"), y = 1:3)
  df |> group_by(x) |> summarise(rows = list(cur_group_rows()))
  # x = "a" のグループ: rows = 2L
  # x = "b" のグループ: rows = c(1L, 3L)
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

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

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

特になし

## 備考

- data.tableの`.I`に相当する機能
- `reframe(row = cur_group_rows())`で各グループの行インデックスを展開できる
- `group_data()$.rows`は全グループの行インデックスを返す

---

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

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

### 推奨読解順序

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

本関数はDataMaskオブジェクトと行インデックスの管理方法に依存している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.R | `R/context.R` | cur_group_rows関数定義（68-70行目） |
| 1-2 | data-mask.R | `R/data-mask.R` | current_rowsメソッド（155-157行目） |

**読解のコツ**: `current_rows()`は`private$rows`から現在のグループIDでインデックスを取得する。

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data-mask.R | `R/data-mask.R` | current_rows メソッド（155-157行目） |
| 3-2 | data-mask.R | `R/data-mask.R` | private$rows（335行目） |
| 3-3 | test-context.R | `tests/testthat/test-context.R` | テストケース（40-53行目） |

**主要ポイント**:
- **data-mask.R 155-157行目**: rowsからグループIDでインデックス取得
- **test-context.R 40-53行目**: 基本的な動作のテスト

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

```
cur_group_rows()
    │
    └─ peek_mask()                      [context.R]
           │
           └─ context_peek("mask")      [context.R]
                  │
                  └─ DataMask$current_rows()  [data-mask.R]
                         │
                         └─ private$rows[[current_group_id]]
```

### データフロー図

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

(コンテキスト) ──▶ peek_mask() ──▶ DataMask ──▶ current_rows() ──▶ 整数ベクトル
                                      │
                                      ▼
                               private$rows
                                      │
                                      ▼
                            rows[[current_group_id]]
```

### 関連ファイル一覧

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