# 非機能要件定義書

## 概要

本ドキュメントは、Shopware eコマースプラットフォームの非機能要件を定義する。プロジェクトコードの解析結果に基づき、性能、可用性、セキュリティ、拡張性、保守性、および運用・監視に関する要件を記載する。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| Elasticsearch検索 | 5秒以内 | `elasticsearch.yaml` の `search.timeout: 5s` による設定 |
| 管理画面Elasticsearch検索 | 5秒以内 | `administration.search.timeout: 5s` による設定 |
| API応答 | - | 明示的な設定値なし（アプリケーション実装に依存） |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| API最大リミット | 500件/リクエスト | `shopware.api.max_limit: 500` |
| Store API最大リミット | 100件/リクエスト | `shopware.api.store.max_limit: 100` |
| Elasticsearch検索最大結果数 | 10,000件 | `index_settings.max_result_window: 10000` |
| 管理画面Elasticsearch最大結果数 | 500,000件 | `administration.index_settings.max_result_window: 500000` |
| Elasticsearchインデックスバッチサイズ | 100件 | `SHOPWARE_ES_INDEXING_BATCH_SIZE` 環境変数 |
| サイトマップバッチサイズ | 100件 | `shopware.sitemap.batchsize: 100` |
| DALバッチサイズ | 125件 | `shopware.dal.batch_size: 125` |
| ファイルシステムバッチ書き込みサイズ | 250件 | `shopware.filesystem.batch_write_size: 250` |

### キャッシュ設定

| キャッシュ種別 | TTL | 備考 |
| --- | --- | --- |
| HTTPキャッシュ（デフォルト） | - | `shopware.http.cache.default_ttl` で設定可能 |
| オブジェクトキャッシュ | 172,800秒（48時間） | `framework.cache.pools.cache.object.default_lifetime` |
| HTTPキャッシュプール | 172,800秒（48時間） | `framework.cache.pools.cache.http.default_lifetime` |
| Store APIキャッシュ（s-maxage） | 1,800秒（30分） | `policies.store_api.cacheable` |
| Store API stale-while-revalidate | 86,400秒（24時間） | キャッシュ更新中の古いコンテンツ提供 |
| Store API stale-if-error | 7,200秒（2時間） | エラー時の古いコンテンツ提供 |
| Storefrontキャッシュ（s-maxage） | 7,200秒（2時間） | `policies.storefront.cacheable` |

### リバースプロキシ設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| リバースプロキシ有効化 | false（デフォルト） | `shopware.http_cache.reverse_proxy.enabled` |
| Varnishホスト | http://varnish | デフォルト設定 |
| 最大並列無効化数 | 2 | `max_parallel_invalidations` |
| BANメソッド | BAN | リバースプロキシ無効化方式 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | - | コード内に明示的な設定なし（インフラ依存） |
| 計画停止時間 | - | メンテナンスモード機能あり |
| 障害復旧時間（RTO） | - | コード内に明示的な設定なし |
| 目標復旧時点（RPO） | - | コード内に明示的な設定なし |
| カートデータ保持期間 | 120日 | `shopware.cart.expire_days: 120` |
| 販売チャネルコンテキスト保持期間 | 120日 | `shopware.sales_channel_context.expire_days: 120` |
| Store APIコンテキスト有効期間 | 1日 | `shopware.api.store.context_lifetime: 'P1D'` |
| DALバージョニング保持期間 | 30日 | `shopware.dal.versioning.expire_days: 30` |

### メッセージキュー設定（冗長性・信頼性）

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| トランスポート | Doctrine（MySQL） | `MESSENGER_TRANSPORT_DSN` |
| 最大リトライ回数 | 3回 | `framework.messenger.transports.async.retry_strategy.max_retries` |
| 初期リトライ遅延 | 1,000ms | `retry_strategy.delay: 1000` |
| リトライ遅延倍率 | 2倍 | `retry_strategy.multiplier: 2` |
| 失敗メッセージキュー | あり | `MESSENGER_TRANSPORT_FAILURE_DSN` |
| スケジュールタスク再キュータイムアウト | 12時間 | `shopware.messenger.scheduled_task.requeue_timeout` |
| メッセージ最大サイズ | 1,024 KiB | `shopware.messenger.message_max_kib_size` |

### データベース設定（Docker環境）

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| InnoDBバッファプールサイズ | 1,024 MB | `innodb_buffer_pool_size` |
| InnoDBログファイルサイズ | 128 MB | `innodb_log_file_size` |
| JOINバッファサイズ | 1,024 MB | `join_buffer_size` |
| Binlogキャッシュサイズ | 16 MB | `binlog_cache_size` |
| 最大Binlogサイズ | 512 MB | `max_binlog_size` |
| Binlog保持期間 | 86,400秒（24時間） | `binlog_expire_logs_seconds` |
| ヘルスチェック間隔 | 5秒 | Docker healthcheck設定 |

## セキュリティ要件

### レートリミッター設定

| 対象 | ポリシー | リセット期間 | 制限内容 |
| --- | --- | --- | --- |
| ログイン | time_backoff | 24時間 | 10秒で10回 → 30秒で15回 → 60秒で20回 |
| ゲストログイン | time_backoff | 24時間 | 10秒で10回 → 30秒で15回 → 60秒で20回 |
| OAuth | time_backoff | 24時間 | 10秒で10回 → 30秒で15回 → 60秒で20回 |
| パスワードリセット | time_backoff | 24時間 | 30秒で3回 → 60秒で5回 → 90秒で10回 |
| ユーザーリカバリー | time_backoff | 24時間 | 30秒で3回 → 60秒で5回 → 90秒で10回 |
| コンタクトフォーム | time_backoff | 24時間 | 30秒で3回 → 60秒で5回 → 90秒で10回 |
| 通知 | time_backoff | 24時間 | 10秒で10回 → 30秒で15回 → 60秒で20回 |
| ニュースレターフォーム | time_backoff | 24時間 | 30秒で3回 → 60秒で5回 → 90秒で10回 |
| カートライン追加 | system_config | 1時間 | 60秒間隔（設定値による） |

### CAPTCHA対応

| CAPTCHAタイプ | 優先度 | 備考 |
| --- | --- | --- |
| HoneypotCaptcha | 400（最高） | バリデーターによる検証 |
| BasicCaptcha | 300 | システム設定による管理 |
| Google reCAPTCHA v2 | 200 | 外部APIクライアント使用 |
| Google reCAPTCHA v3 | 100 | 外部APIクライアント使用 |

### HTMLサニタイザー設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| サニタイザー有効化 | true | `shopware.html_sanitizer.enabled` |
| キャッシュ有効化 | true | `html_sanitizer.cache_enabled` |
| 許可タグセット | HTML5, basic, media, bootstrap, snippet | 用途別に定義 |
| フレームターゲット許可 | _blank, _self, _parent, _top | XSS対策 |
| rel属性許可 | nofollow, print | SEO・セキュリティ対策 |

### セッション設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| セッション名 | session- | `framework.session.name` |
| Cookie Secure | auto | `cookie_secure: 'auto'` |
| Cookie SameSite | lax | CSRF対策 |

### SSL/TLS設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| Elasticsearchサーバー証明書検証 | true | `elasticsearch.ssl.verify_server_cert` |

## 拡張性要件

### Elasticsearchインデックス設定

| 項目 | Storefront | 管理画面 |
| --- | --- | --- |
| シャード数 | null（自動） | 3 |
| レプリカ数 | null（自動） | 3 |
| マッピングフィールド上限 | 50,000 | 50,000 |
| ネストフィールド上限 | 500 | 500 |
| ネストオブジェクト上限 | 1,000,000 | 1,000,000 |

### プラグイン・アプリ拡張

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| 自動更新 | true | `shopware.auto_update.enabled` |
| 機能トグル | true | `shopware.feature_toggle.enable` |
| Blue/Greenデプロイメント | 環境変数による | `BLUE_GREEN_DEPLOYMENT` |
| クラスターセットアップ | false | `shopware.deployment.cluster_setup` |

### ファイルシステム設定

| タイプ | 保存先 | 可視性 |
| --- | --- | --- |
| プライベート | %kernel.project_dir%/files | private |
| パブリック | %kernel.project_dir%/public | public |
| テンポラリ | %kernel.project_dir%/var | - |

### 許可ファイル拡張子

- **パブリック**: jpg, jpeg, png, webp, avif, gif, svg, bmp, tiff, tif, eps, webm, mkv, flv, ogv, ogg, mov, mp4, avi, wmv, pdf, aac, mp3, wav, flac, oga, wma, txt, doc, docx, ico, glb, csv, xls, xlsx, html, vtt, srt, sub, ass, ssa, step, stp
- **プライベート**: 上記に加えて zip, rar, xml

## 保守性要件

### ログ設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| ログローテーション数 | 14ファイル | `shopware.logger.file_rotation_count` |
| 本番環境ログレベル | error | `monolog.handlers.nested.level` |
| ログハンドラタイプ | rotating_file | ファイルローテーション対応 |
| fingers_crossedトリガーレベル | error | アクションレベルでフィルタリング |

### 例外ログレベル設定

コードベースには多数の例外に対するログレベル設定（主に`notice`レベル）が定義されており、ビジネスロジック上想定される例外とシステムエラーを区別している。

### 検索設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| 検索語最大長 | 300文字 | `shopware.search.term_max_length` |
| 保持特殊文字 | -, _, +, ., @ | トークナイズ時に保持 |

## 運用・監視要件

### テレメトリ・メトリクス

| メトリクス名 | タイプ | 説明 |
| --- | --- | --- |
| plugin.install.count | counter | プラグインインストール数 |
| app.install.count | counter | アプリインストール数 |
| cache.invalidate.count | counter | キャッシュ無効化数 |
| messenger.message.size | histogram | メッセージサイズ（バイト） |
| dal.associations.count | histogram | 読み込まれたアソシエーション数 |
| database.locks.count | counter | データベースロック数 |

メトリクス名前空間: `io.opentelemetry.contrib.php.shopware`

### Admin Worker設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| Admin Worker有効化 | true | `shopware.admin_worker.enable_admin_worker` |
| キュー統計ワーカー | true | `enable_queue_stats_worker` |
| 通知ワーカー | true | `enable_notification_worker` |
| ポーリング間隔 | 20秒 | PHPのmax_execution_time未満 |
| 対象トランスポート | async, low_priority | 処理対象キュー |

### スケジュールタスク

- サイトマップ生成: 有効（`shopware.sitemap.scheduled_task.enabled: true`）
- キャッシュ無効化タスク: 定期実行
- Webhookイベントログクリーンアップ: 定期実行

### 使用データ収集

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| データ収集有効化 | true | `shopware.usage_data.collection_enabled` |
| ディスパッチ有効化 | true | `gateway.dispatch_enabled` |
| 送信先 | https://data.shopware.io | Shopwareへの匿名データ送信 |
| バッチサイズ | 50 | 送信単位 |

### ステージング環境設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| メール配信無効化 | true | 本番への誤送信防止 |
| Storefrontバナー表示 | true | ステージング環境識別 |
| 管理画面バナー表示 | true | ステージング環境識別 |
| Elasticsearch存在チェック | true | インデックス確認 |

## 備考

### インフラストラクチャ依存項目

本ドキュメントに記載の多くの非機能要件は、アプリケーション設定として定義されているが、実際の達成にはインフラストラクチャの適切な構成が必要である。

- 稼働率・RTO・RPOはインフラ設計に依存
- スループットはサーバーリソースに依存
- Elasticsearch設定はクラスター構成に依存

### 環境変数による構成

多くの設定は環境変数により上書き可能であり、環境ごとの調整が可能。

- `APP_URL`: アプリケーションURL
- `DATABASE_URL`: データベース接続文字列
- `MESSENGER_TRANSPORT_DSN`: メッセージキュー接続
- `SHOPWARE_ES_*`: Elasticsearch関連設定
- `BLUE_GREEN_DEPLOYMENT`: デプロイ戦略

### バージョン情報

本ドキュメントはShopware 6.7系（開発版）のコードベースを基に作成。
