# 非機能要件定義書

## 概要

本ドキュメントは、InvenTreeプロジェクトの非機能要件を定義するものです。InvenTreeはオープンソースの在庫管理システムであり、Djangoフレームワークをベースに構築されています。本書では、性能、可用性、セキュリティ、拡張性、保守性、運用・監視に関する要件を、実装コードから抽出・分析した結果に基づいて記載します。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| API応答（通常） | 2秒以内 | データベース接続タイムアウト: 2秒（PostgreSQL設定） |
| バックグラウンドタスク | 90秒以内 | `Q_CLUSTER['timeout']`で設定（デフォルト90秒） |
| キャッシュ接続 | 5秒以内 | Redis `SOCKET_CONNECT_TIMEOUT`: 5秒 |
| キャッシュ操作 | 3秒以内 | Redis `SOCKET_TIMEOUT`: 3秒 |
| メール送信 | 60秒以内 | `EMAIL_TIMEOUT`: 60秒 |
| マジックリンクログイン | 300秒以内 | `SESAME_MAX_AGE`: 300秒（有効期限） |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| Gunicornワーカー数 | CPU数 x 2 + 1 | `multiprocessing.cpu_count() * 2 + 1` |
| ワーカースレッド数 | 4スレッド/ワーカー | `gunicorn.conf.py`の`threads = 4` |
| バックグラウンドワーカー数 | 4（デフォルト） | `INVENTREE_BACKGROUND_WORKERS`で設定可能 |
| 最大リクエスト数/ワーカー | 1000リクエスト | `max_requests = 1000`（ワーカー再起動閾値） |
| 同時接続数（キュー） | 50 | `Q_CLUSTER['queue_limit']`: 50 |
| バルク処理数 | 10 | `Q_CLUSTER['bulk']`: 10 |
| データアップロード最大フィールド数 | 10,000 | `DATA_UPLOAD_MAX_NUMBER_FIELDS` |

### データベース性能設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| 接続タイムアウト（PostgreSQL） | 2秒 | `connect_timeout`（最小値: libpqの制限） |
| TCPキープアライブ | 有効 | `keepalives = 1` |
| キープアライブ間隔 | 1秒 | `keepalives_idle`, `keepalives_interval` |
| キープアライブ失敗カウント | 5回 | `keepalives_count` |
| トランザクション分離レベル | READ COMMITTED | デフォルト設定、SERIALIZABLE設定可能 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 稼働率 | 設定による | Docker構成では`restart: unless-stopped`で自動復旧 |
| 計画停止時間 | 設定による | メンテナンスモード対応（`maintenance_mode`） |
| 障害復旧時間（RTO） | 設定による | 自動バックアップ機能対応 |
| 目標復旧時点（RPO） | 1日（デフォルト） | `INVENTREE_BACKUP_DAYS`で設定可能 |
| メンテナンスモードリトライ | 10秒 | `MAINTENANCE_MODE_RETRY_AFTER` |

### 冗長構成

| コンポーネント | 冗長化方式 | 備考 |
| --- | --- | --- |
| Webサーバー | Gunicorn複数ワーカー | CPU数に応じた自動スケール |
| バックグラウンドワーカー | 複数ワーカー対応 | グローバルキャッシュ有効時のみ複数ワーカー許可 |
| データベース | PostgreSQL推奨 | TCPキープアライブによる接続監視 |
| キャッシュ | Redis（オプション） | TCPキープアライブ設定対応 |
| リバースプロキシ | Caddy（Docker構成） | 自動再起動: `restart: always` |

### バックアップ

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| 自動バックアップ | 設定可能 | `INVENTREE_BACKUP_ENABLE` |
| バックアップ間隔 | 1日（デフォルト） | `INVENTREE_BACKUP_DAYS` |
| バックアップストレージ | FileSystemStorage（デフォルト） | S3等外部ストレージ設定可能 |
| GPG暗号化 | 対応 | `DBBACKUP_GPG_RECIPIENT` |
| バックアップ失敗通知 | メール対応 | `INVENTREE_BACKUP_SEND_EMAIL` |

## セキュリティ要件

### 認証・認可

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| 認証方式 | 多要素対応 | Basic認証、セッション認証、OAuth2、APIトークン、LDAP、SSO |
| 多要素認証（MFA） | TOTP、WebAuthn、リカバリーコード | `MFA_SUPPORTED_TYPES`で設定 |
| MFA強制 | 設定可能 | `LOGIN_ENFORCE_MFA` |
| ログイン試行制限 | 5回/分（デフォルト） | `ACCOUNT_RATE_LIMITS['login_failed']` |
| パスワード検証 | Django標準4種 | 類似性、最小長、一般的パスワード、数字のみ禁止 |
| セッション管理 | DBセッション | `allauth.usersessions`によるセッション追跡 |
| APIトークン | 独自実装 | `users.models.ApiToken` |

### 通信セキュリティ

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| HTTPS | 推奨 | 本番環境では必須 |
| CSRF保護 | 有効 | `CSRF_COOKIE_NAME = 'csrftoken'` |
| Cookieセキュリティ | SameSite設定可能 | Lax/Strict/None選択可能 |
| セキュアCookie | 本番環境で有効 | DEBUGモード無効時に自動有効化 |
| X-Forwarded-Proto | 対応 | `SECURE_PROXY_SSL_HEADER`設定可能 |
| クリックジャッキング保護 | 有効 | `XFrameOptionsMiddleware` |

### CORS設定

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| CORS有効化 | 設定可能 | `CORS_ALLOW_ALL_ORIGINS` |
| 認証情報許可 | 有効（デフォルト） | `CORS_ALLOW_CREDENTIALS` |
| 許可URL正規表現 | `/api/`, `/auth/`, `/media/`, `/plugin/`, `/static/` | `CORS_URLS_REGEX` |
| オリジンホワイトリスト | 設定可能 | `CORS_ALLOWED_ORIGINS` |

### エラーレポーティング

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| Sentry統合 | 対応（オプション） | `SENTRY_ENABLED` |
| サンプルレート | 0.1（デフォルト） | `SENTRY_SAMPLE_RATE` |
| PII送信 | 有効 | `send_default_pii=True` |
| 除外エラー | Http404、ValidationError等 | セキュリティ関連エラーは除外 |

## 拡張性要件

### プラグインシステム

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| プラグイン有効化 | 設定可能 | `INVENTREE_PLUGINS_ENABLED` |
| 必須プラグイン | 設定可能 | `INVENTREE_PLUGINS_MANDATORY` |
| プラグインリトライ | 3回（デフォルト） | `PLUGIN_RETRY` |
| プラグインインストール無効化 | 設定可能 | `INVENTREE_PLUGIN_NOINSTALL` |

### ストレージ拡張

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| ローカルストレージ | 対応 | デフォルト |
| S3互換ストレージ | 対応 | `django-storages`統合 |
| SFTP | 対応 | Paramiko経由 |
| 署名付きURL有効期限 | 600秒 | `PRESIGNED_URL_EXPIRATION` |

### 国際化

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| 多言語対応 | 70+言語 | `LOCALES`で定義 |
| 通貨対応 | 多通貨 | `djmoney`統合 |
| タイムゾーン | 設定可能 | `INVENTREE_TIMEZONE` |
| 言語Cookie有効期間 | 30日 | `LANGUAGE_COOKIE_AGE` |

## 保守性要件

### ログ管理

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| ログレベル | WARNING（デフォルト） | DEBUG/INFO/WARNING/ERROR/CRITICAL |
| 構造化ログ | 対応 | `structlog`使用 |
| JSONログ出力 | 設定可能 | `INVENTREE_JSON_LOG` |
| ファイルログ | 設定可能 | `INVENTREE_WRITE_LOG` |
| コンソールログ | 有効（デフォルト） | `INVENTREE_CONSOLE_LOG` |
| データベースログ | 設定可能 | `INVENTREE_DB_LOGGING` |

### データ保持

| 項目 | 保持期間 | 備考 |
| --- | --- | --- |
| バックグラウンドタスク結果 | 30日（デフォルト） | `INVENTREE_DELETE_TASKS_DAYS` |
| エラーログ | 30日（デフォルト） | `INVENTREE_DELETE_ERRORS_DAYS` |
| 通知 | 30日（デフォルト） | `INVENTREE_DELETE_NOTIFICATIONS_DAYS` |
| メールログ | 30日（デフォルト） | `INVENTREE_DELETE_EMAIL_DAYS` |
| メールログ保護 | 設定可能 | `INVENTREE_PROTECT_EMAIL_LOG` |

### 設定管理

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| 環境変数 | 対応 | 優先度: 環境変数 > config.yaml |
| 設定ファイル | YAML形式 | `config.yaml` |
| グローバル設定オーバーライド | 対応 | `INVENTREE_GLOBAL_SETTINGS` |
| 再起動通知 | 対応 | `SERVER_RESTART_REQUIRED` |

## 運用・監視要件

### OpenTelemetry統合

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| トレーシング | 対応 | `INVENTREE_TRACING_ENABLED` |
| メトリクス | 対応 | OTLPエクスポーター |
| ログ転送 | 対応 | OTLPログエクスポーター |
| HTTP/gRPC | 両対応 | `tracing.is_http`で選択 |
| コンソール出力 | 設定可能 | デバッグ用 |

### 自動インストゥルメンテーション

| 対象 | 対応 | 備考 |
| --- | --- | --- |
| Django | 対応 | `DjangoInstrumentor` |
| Redis | 対応 | `RedisInstrumentor` |
| HTTP Requests | 対応 | `RequestsInstrumentor` |
| システムメトリクス | 対応 | `SystemMetricsInstrumentor` |
| PostgreSQL | 対応 | `PsycopgInstrumentor` |
| MySQL | 対応 | `PyMySQLInstrumentor` |
| SQLite | 対応 | `SQLite3Instrumentor` |

### キャッシュ管理

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| グローバルキャッシュ | Redis（オプション） | `INVENTREE_CACHE_HOST` |
| ローカルキャッシュ | LocMemCache | デフォルト |
| リクエストキャッシュ | スレッドローカル | `InvenTreeRequestCacheMiddleware` |
| キャッシュポート | 6379（デフォルト） | `INVENTREE_CACHE_PORT` |
| キャッシュTCPキープアライブ | 対応 | `TCP_KEEPCNT`, `TCP_KEEPIDLE`等 |

### バックグラウンドタスク（django-q）

| 項目 | 設定 | 備考 |
| --- | --- | --- |
| タスク名 | InvenTree | `Q_CLUSTER['name']` |
| タイムアウト | 90秒（デフォルト） | `Q_CLUSTER['timeout']` |
| リトライ | 120秒または timeout+30秒 | `Q_CLUSTER['retry']` |
| 最大試行回数 | 5回（デフォルト） | `Q_CLUSTER['max_attempts']` |
| ポーリング間隔 | 1.5秒 | `Q_CLUSTER['poll']` |
| キャッチアップ | 無効 | `Q_CLUSTER['catch_up'] = False` |

### Docker運用

| コンテナ | 再起動ポリシー | 備考 |
| --- | --- | --- |
| inventree-db (PostgreSQL) | unless-stopped | データベースサーバー |
| inventree-cache (Redis) | always | キャッシュサーバー |
| inventree-server (Gunicorn) | unless-stopped | Webアプリケーションサーバー |
| inventree-worker | unless-stopped | バックグラウンドワーカー |
| inventree-proxy (Caddy) | always | リバースプロキシ |

## 備考

### デバッグ・開発支援

| 機能 | 設定 | 備考 |
| --- | --- | --- |
| Django Silk | DEBUGモードで有効化可能 | プロファイリングツール |
| QueryCount | DEBUGモードで有効化可能 | クエリ数監視 |
| クエリ閾値（中） | 50クエリ | `QUERYCOUNT['THRESHOLDS']['MEDIUM']` |
| クエリ閾値（高） | 200クエリ | `QUERYCOUNT['THRESHOLDS']['HIGH']` |

### バージョン管理

| 項目 | 対応 | 備考 |
| --- | --- | --- |
| 更新チェック | 7日間隔（デフォルト） | `INVENTREE_UPDATE_CHECK_INTERVAL` |
| 自動更新 | 設定可能 | `INVENTREE_AUTO_UPDATE` |
| コミットハッシュ追跡 | 対応 | Sentry/OpenTelemetryタグ |
