# 非機能要件定義書

## 概要

本ドキュメントは、Rパッケージ「dplyr」（バージョン 1.2.0.9000）の非機能要件を定義する。dplyrはデータフレーム操作のための文法を提供するRパッケージであり、メモリ内およびメモリ外（データベース等）のデータフレーム操作を高速かつ一貫した方法で実現する。本パッケージはtidyverseエコシステムの中核コンポーネントとして位置づけられ、広範なユーザーベースを持つ。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 基本的なデータフレーム操作（filter, select, mutate等） | サブ秒レベル（一般的なデータサイズ） | C++実装による高速化（src/filter.cpp, src/mutate.cpp等） |
| グループ操作（group_by + summarise） | データサイズに比例した線形スケール | vec_order_radix による最適化されたソートアルゴリズム |
| 結合操作（join系関数） | データサイズとキー数に応じた準線形時間 | vctrs パッケージとの連携による効率的な実装 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 同時セッション数 | R セッション単位（シングルスレッド） | R言語の特性によりセッション単位での処理 |
| データフレーム行数 | 数百万行まで対応 | メモリ内処理の場合、使用可能メモリに依存 |
| データベース連携時 | データベースサーバーの性能に依存 | dbplyrパッケージによるSQLへの変換 |

### 性能最適化の実装

コード解析により以下の性能最適化が確認された：

1. **C/C++実装による高速化**: 主要な演算処理（filter, mutate, summarise, group_by等）はC++で実装されている（src/ディレクトリ）
2. **遅延評価（Lazy Evaluation）**: `dplyr_lazy_vec_chop_impl`によるチャンク単位の遅延処理
3. **メモリ効率**: `dplyr_new_tibble`関数は`tibble::new_tibble()`より約9倍高速な内部実装
4. **参照による変更**: グループIDとサイズはC言語レベルで参照により更新（data-mask.R）

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | N/A（クライアントサイドパッケージ） | ユーザーのR環境で実行されるため、システム稼働率は適用外 |
| 計画停止時間 | N/A | パッケージ更新時にユーザー判断で実施 |
| 障害復旧時間（RTO） | N/A | ローカル実行のため適用外 |
| 目標復旧時点（RPO） | N/A | ローカル実行のため適用外 |

### パッケージ可用性

- **CRAN**: Comprehensive R Archive Networkを通じた配布
- **GitHub**: https://github.com/tidyverse/dplyr での開発版公開
- **マルチプラットフォーム対応**:
  - macOS (macos-latest)
  - Windows (windows-latest, oldrel-4)
  - Linux/Ubuntu (ubuntu-latest, devel, release, oldrel-1〜4)

## セキュリティ要件

### ライセンス

- **MITライセンス**: オープンソースライセンスとして配布
- **著作権**: dplyr authors (2026)

### 入力バリデーション

コード解析により以下のバリデーション機構が確認された：

1. **引数チェック関数群**:
   - `check_dots_empty0()`: 余分な引数の検出
   - `check_by()`, `check_by_typo()`: by引数のバリデーション
   - `check_bool()`, `check_string()`: 型チェック
   - `check_size()`, `check_frac()`: サイズ・割合の妥当性検証
   - `check_keep()`, `check_na_matches()`: オプション引数の検証

2. **データフレームバリデーション**:
   - NULL名、NA名、空文字名の検出（data-mask.R:17-37）
   - 重複列名の検出
   - `validate_grouped_df()`: グループ化データフレームの整合性検証

3. **エラーハンドリング**:
   - `dplyr_error_handler()`: 統一的なエラー処理
   - 警告のスタッシュと遅延表示（`last_dplyr_warnings()`）

### 依存パッケージの信頼性

主要な依存パッケージはいずれもtidyverseチームまたは信頼できる開発者により保守されている：
- rlang (>= 1.1.7)
- vctrs (>= 0.7.1)
- tibble (>= 3.2.0)
- tidyselect (>= 1.2.0)
- pillar (>= 1.9.0)
- cli (>= 3.6.2)
- lifecycle (>= 1.0.5)

## 拡張性要件

### ジェネリック関数設計

dplyrの主要関数はS3ジェネリック関数として実装されており、ユーザーやパッケージ開発者が新しいデータ型に対応するメソッドを追加可能：

- `filter()`, `select()`, `mutate()`, `summarise()`
- `inner_join()`, `left_join()`, `right_join()`, `full_join()`
- `semi_join()`, `anti_join()`, `nest_join()`
- `group_by()`, `ungroup()`, `rowwise()`

### データベースバックエンド拡張

- **dbplyrとの連携**: データベース固有の実装を外部パッケージに委譲
- `src`, `tbl`, `compute`, `collect`, `explain`等のジェネリック関数

### ライフサイクル管理

- `lifecycle`パッケージによる関数の段階的な非推奨化
  - experimental -> stable
  - stable -> deprecated -> defunct
- 後方互換性を維持しながらの機能進化

## 保守性要件

### コード品質

1. **テストカバレッジ**:
   - testthatフレームワークによる包括的なユニットテスト
   - 80以上のテストファイル（tests/testthat/ディレクトリ）
   - GitHub Actionsによる継続的テスト実行
   - codecovによるカバレッジ測定

2. **コーディング規約**:
   - roxygen2によるドキュメント生成
   - tidyverseスタイルガイドに準拠

3. **ドキュメント**:
   - 包括的なRdドキュメント（man/ディレクトリ）
   - 10本のビネット（vignettes/ディレクトリ）
   - pkgdownによるウェブサイト生成

### CI/CDパイプライン

GitHub Actionsによる自動化：
- **R-CMD-check.yaml**: 複数のOS/Rバージョンでのビルドとチェック
- **test-coverage.yaml**: テストカバレッジの測定と報告
- **pkgdown.yaml**: ドキュメントサイトの自動生成
- **format-suggest.yaml**: コードフォーマットの提案
- **pr-commands.yaml**: PRコマンドの自動処理

### 依存関係管理

- **最小Rバージョン**: R (>= 4.1.0)
- **testthat edition**: 3
- **ビルド時のコンパイルデータベース**: 有効

## 運用・監視要件

### 警告・エラー管理

1. **警告のバッファリング**:
   - グループ化/行単位処理での警告の集約
   - `last_dplyr_warnings()`による警告の確認機能
   - 警告トレースの保持（最大5件）

2. **プログレス表示**:
   - `progress_estimated()`（deprecated）による処理進捗表示
   - `dplyr.show_progress`オプションによる制御
   - knitrドキュメント内での自動抑制

### デバッグ支援

1. **SQLクエリの説明**: `explain()`関数によるデータベースクエリプランの表示
2. **エラーコンテキスト**: 詳細なエラーメッセージとグループ情報の提供
3. **ローカルエラーコール**: `dplyr_local_error_call()`による呼び出し元の追跡

### パッケージロード時の処理

- `.onLoad()`: Cライブラリの初期化、vctrs関数のインポート
- `.onAttach()`: plyrパッケージとの競合警告の設定
- `.onDetach()`: フックのクリーンアップ

## 備考

### 対象Rバージョンサポート

GitHub Actions設定により、以下のバージョンでの動作が保証される：
- R devel（開発版）
- R release（最新安定版）
- R oldrel-1〜4（過去4バージョン）

### パフォーマンスに関する設計判断

1. **case_when(), if_else(), coalesce()**: vctrs経由のC言語実装により大幅な高速化とメモリ使用量削減（NEWS.md記載）
2. **内部tibble作成**: 専用の高速実装（`dplyr_new_tibble()`）
3. **ラベリングの最適化**: `with_no_rlang_infix_labeling()`による中置演算子ラベリングの遅延回避

### 既知の制限事項

1. **シングルスレッド処理**: R言語の特性により、並列処理は外部パッケージに依存
2. **メモリ内処理**: 大規模データにはデータベースバックエンド（dbplyr）の使用を推奨
3. **progress_estimated()の非推奨化**: progressパッケージの使用を推奨
