# 通知設計書 11-rows_delete余分な列無視

## 概要

本ドキュメントは、dplyrパッケージの`rows_delete()`関数において、削除対象データフレーム`y`にキー列以外の余分な列が含まれている場合に表示される情報通知の設計を記載する。

### 本通知の処理概要

`rows_delete()`関数は、データフレーム`x`から`y`に含まれるキー値に一致する行を削除する機能を提供する。この際、`y`にはキー列のみが必要であり、それ以外の列は削除処理には使用されない。

**業務上の目的・背景**：データ操作において、ユーザーが`y`に余分な列を含めてしまうケースがある。この通知により、余分な列が無視されることを明示的に伝え、ユーザーが意図しない動作を防ぐ。また、削除処理が正しく行われることを保証しつつ、データの整合性に関する注意喚起を行う。

**通知の送信タイミング**：`rows_delete()`関数の実行時、`y`データフレームにキー列以外の列が存在することが検出された時点で通知が発生する。具体的には、`rows_delete.data.frame()`メソッド内で`y_key`が生成された後、`extra <- setdiff(names(y), names(y_key))`で余分な列を検出し、その結果が空でない場合に通知される。

**通知の受信者**：R言語のコンソールを使用している開発者・データアナリスト。通知はコンソールに直接出力される。

**通知内容の概要**：「Ignoring extra `y` columns: {列名のリスト}」という形式で、無視される列名が表示される。複数列がある場合はカンマ区切りで列挙される。

**期待されるアクション**：ユーザーは通知を確認し、余分な列が意図的なものか確認する。不要な列を事前に除外することで、コードの明確性を向上させることが推奨される。

## 通知種別

コンソール情報メッセージ（`inform()`による`message`条件）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行中に即座に表示） |
| 優先度 | 低（情報通知） |
| リトライ | 無し |

### 送信先決定ロジック

R言語の標準メッセージハンドラを通じてコンソールに出力される。`suppressMessages()`で抑制可能。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| メッセージクラス | `dplyr_message_delete_extra_cols`, `dplyr_message` |
| 形式 | テキスト |

### 本文テンプレート

```
Ignoring extra `y` columns: {列名1}, {列名2}, ...
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| extra | 無視される余分な列名のベクトル | `setdiff(names(y), names(y_key))` | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `rows_delete()`の実行 | `y`にキー列以外の列が存在する | キー列との差分を検出して通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `y`がキー列のみで構成される場合 | 余分な列がないため通知不要 |
| `suppressMessages()`でラップされている場合 | ユーザーが明示的にメッセージを抑制 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[rows_delete実行] --> B[by引数のチェック]
    B --> C[y_keyの生成]
    C --> D{yにキー列以外の列があるか}
    D -->|Yes| E[extra列を特定]
    E --> F[inform関数で通知]
    F --> G[削除処理を継続]
    D -->|No| G
    G --> H[結果を返す]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| 該当なし | - | インメモリデータフレーム操作 |

### テーブル別参照項目詳細

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | この通知自体はエラーではなく情報提供 |

### リトライ仕様

該当なし

## 配信設定

### レート制限

該当なし（即座に1回表示）

### 配信時間帯

該当なし（関数実行時に即座に表示）

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

列名情報がコンソールに出力されるため、機密性の高い列名が含まれる場合は注意が必要。

## 備考

- この通知は`dplyr_message_delete_extra_cols`クラスを持ち、特定の条件でのみ捕捉・処理することが可能
- `rows_insert()`, `rows_update()`, `rows_patch()`, `rows_upsert()`では、`y`の列は`x`の列のサブセットである必要があり、余分な列はエラーとなる。`rows_delete()`のみが余分な列を無視する

---

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

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

### 推奨読解順序

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

rows_*関数群は2つのデータフレーム（x, y）を扱い、キー列（by）で結合・操作を行う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | rows.R | `R/rows.R` | 1-118行目のドキュメントでrows_*関数群の全体像を理解 |

**読解のコツ**: SQL的な操作（INSERT, UPDATE, DELETE）との対応を意識すると理解しやすい。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | rows.R | `R/rows.R` | 409-419行目の`rows_delete()`ジェネリック関数 |

**主要処理フロー**:
1. **409行目**: `rows_delete`ジェネリック関数の定義
2. **418行目**: `UseMethod("rows_delete", x)`でディスパッチ

#### Step 3: 通知ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | rows.R | `R/rows.R` | 422-472行目の`rows_delete.data.frame()`メソッド |

**主要処理フロー**:
- **436行目**: `rows_check_by()`でby引数をチェック
- **441-442行目**: x_key, y_keyの生成
- **454行目**: `extra <- setdiff(names(y), names(y_key))`で余分な列を検出
- **455-464行目**: 余分な列がある場合の通知処理
- **456-459行目**: `glue()`でメッセージを構築
- **460-463行目**: `inform()`で通知を発行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | rows.R | `R/rows.R` | 476-503行目の`rows_check_by()`関数 |

**主要処理フロー**:
- **479-490行目**: byがNULLの場合、yの最初の列をキーとして使用し、通知を表示

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

```
rows_delete(x, y, by, ...)
    │
    ├─ rows_delete.data.frame()
    │      │
    │      ├─ rows_check_by()              # by引数の検証
    │      │      └─ inform()               # by自動検出時の通知(No.10)
    │      │
    │      ├─ rows_check_contains_by()     # by列の存在確認
    │      │
    │      ├─ rows_check_y_unmatched()     # 未マッチキーの処理
    │      │
    │      └─ inform()                      # 余分な列の通知(本通知)
    │             └─ glue()
    │             └─ commas()
    │             └─ tick_if_needed()
```

### データフロー図

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

x (data.frame) ───┐
                  │
y (data.frame) ───┼──▶ rows_delete.data.frame() ──▶ 結果(data.frame)
                  │           │
by (character) ───┘           │
                              ▼
                    extra列検出
                              │
                              ▼
                    [コンソール通知]
                    "Ignoring extra `y` columns: ..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rows.R | `R/rows.R` | ソース | rows_*関数群の実装 |
| utils-format.R | `R/utils-format.R` | ソース | tick_if_needed(), commas()等のユーティリティ |
