# 非機能要件定義書

## 概要

本ドキュメントは、Medusaオープンソースコマースプラットフォームの非機能要件を定義するものです。MedusaはTypeScriptで構築されたモジュラーアーキテクチャを採用したモノレポプロジェクトであり、30以上のコマースパッケージを含みます。本ドキュメントでは、コードベースから抽出された性能、可用性、セキュリティ、拡張性、保守性、運用監視に関する要件を記載します。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| API応答（標準） | 設定可能 | HTTP圧縮オプションにより応答サイズを最適化可能 |
| ワークフローステップタイムアウト | 設定可能（デフォルト30秒TTL） | TransactionOrchestratorのDEFAULT_TTLとして定義 |
| ロック取得タイムアウト | デフォルト5秒 | RedisLockingProviderのwaitLockingTimeoutとして設定可能 |
| セッションクッキー有効期限 | 10時間（36,000,000ms） | sessionOptions.ttlで変更可能 |
| JWT有効期限 | 1日（24h） | http.jwtExpiresInで設定可能 |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| データベース接続プール（最小） | 2接続 | poolMinのデフォルト値 |
| データベース接続プール（最大） | 設定可能 | poolMaxとして環境に応じて設定 |
| バッチ処理サイズ | 100件 | MikroORMのbatchSizeとして設定 |
| ジョブバッチサイズ | 1000件 | projectConfig.jobsBatchSizeのデフォルト値 |
| イベントバスリトライ | 1回 | BullMQのデフォルト試行回数 |

### キャッシュ設定

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| Redis キャッシュTTL | 3600秒（1時間） | RedisCachingProviderのdefaultTTL |
| 圧縮閾値 | 2048バイト（2KB） | compressionThreshold: データサイズがこれを超えるとgzip圧縮 |
| グループイベントTTL | 600秒 | groupedEventsTTLのデフォルト値 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| データベース接続リトライ | 最大5回 | __MEDUSA_DB_CONNECTION_MAX_RETRIESで変更可能 |
| リトライ遅延 | 1000ms | __MEDUSA_DB_CONNECTION_RETRY_DELAYで変更可能 |
| ワークフロー自動リトライ | デフォルト0回 | TransactionOrchestrator.DEFAULT_RETRIES |
| ロック取得リトライ間隔 | 5ms（初期）〜200ms（最大） | defaultRetryInterval / maximumRetryInterval |
| ワーカーモード | shared/worker/server | 分離デプロイによる高可用性構成をサポート |

### フォールトトレランス機能

- **トランザクション補償（Saga）パターン**: ワークフローSDKによる分散トランザクション管理とロールバック機能
- **ステップ永続化**: TransactionOrchestratorによるチェックポイント保存機能
- **接続エラーハンドリング**: Redis接続エラー時のグレースフルデグレード（キャッシュミス時はオリジナルデータソースにフォールバック）
- **イベント再配信**: BullMQによるイベント再処理機能

## セキュリティ要件

### 認証・認可

| 項目 | 実装 | 備考 |
| --- | --- | --- |
| セッション認証 | express-session | Redis/DynamoDBストア対応 |
| Bearer認証 | JWT | jsonwebtokenライブラリ使用 |
| APIキー認証 | Basic認証形式 | sk_プレフィックス付きシークレットキー |
| 非対称暗号化 | RSA/ES対応 | jwtPublicKey, jwtVerifyOptionsで設定可能 |

### CORS設定

| エンドポイント | 設定項目 | 備考 |
| --- | --- | --- |
| 認証API（/auth） | http.authCors | 正規表現パターン対応 |
| ストアAPI | http.storeCors | 正規表現パターン対応 |
| 管理API | http.adminCors | 正規表現パターン対応 |

### セッション・クッキーセキュリティ

| 項目 | 本番環境設定 | 開発環境設定 |
| --- | --- | --- |
| secure | true | false |
| sameSite | none | false |
| trust proxy | 1 | 1 |

### 秘密情報管理

- **JWT Secret**: http.jwtSecretまたはJWT_SECRET環境変数（本番環境では必須）
- **Cookie Secret**: http.cookieSecretまたはCOOKIE_SECRET環境変数（本番環境では必須）
- **開発環境デフォルト**: supersecret（本番環境では警告/エラー）

### アクセス制御

- **アクターベース認証**: actorType（user/customer等）とauthType（session/bearer/api-key）の組み合わせ
- **認証メソッド制限**: authMethodsPerActorによるアクター別認証プロバイダー制限
- **フィールド制限**: restrictedFieldsによるAPI応答フィールド制限

## 拡張性要件

### モジュラーアーキテクチャ

| 項目 | 説明 |
| --- | --- |
| モジュール構成 | 30以上の独立したコマースモジュール（product, order, cart, payment等） |
| プラグインシステム | NPMパッケージとしてのプラグイン追加対応 |
| プロバイダーパターン | 決済、配送、キャッシュ、ロック等の抽象プロバイダーインターフェース |
| ワークフローSDK | createWorkflow/createStepによる拡張可能なワークフロー定義 |

### 水平スケーリング対応

| 項目 | 実装 |
| --- | --- |
| ワーカー分離 | workerMode: server/workerによるプロセス分離 |
| イベントバス | Redis Pub/Sub（BullMQ）による分散イベント処理 |
| セッションストア | Redis/DynamoDBによる外部セッション管理 |
| キャッシュ | Redis Clusterサポート |
| 分散ロック | Redisベースの分散ロック機構 |

## 保守性要件

### コード品質

| 項目 | 基準 |
| --- | --- |
| 言語 | TypeScript（ES2021ターゲット） |
| 型安全性 | strictNullChecks有効 |
| コードフォーマット | Prettier（セミコロンなし、ダブルクォート、2スペースインデント） |
| テストフレームワーク | Jest 29.7.0（バックエンド）、Vitest 3.0.5（フロントエンド） |

### 命名規則

| 対象 | 規則 |
| --- | --- |
| ファイル名 | kebab-case (例: define-config.ts) |
| 型/インターフェース/クラス | PascalCase |
| 関数/変数 | camelCase |
| 定数 | SCREAMING_SNAKE_CASE |
| データベースフィールド | snake_case |

### エラーハンドリング

| エラータイプ | HTTPステータス |
| --- | --- |
| NOT_FOUND | 404 |
| UNAUTHORIZED | 401 |
| FORBIDDEN | 403 |
| INVALID_DATA / NOT_ALLOWED | 400 |
| DUPLICATE_ERROR / PAYMENT_AUTHORIZATION_ERROR | 422 |
| CONFLICT | 409 |
| DB_ERROR | 500 |

### データベース管理

| 項目 | 実装 |
| --- | --- |
| ORM | MikroORM |
| マイグレーション | TSMigrationGeneratorベースの自動生成 |
| バッチ処理 | useBatchInserts/useBatchUpdates有効 |
| メタデータキャッシュ | 有効 |

## 運用・監視要件

### ロギング

| 項目 | 実装 |
| --- | --- |
| ロガー | Winston |
| ログレベル | LOG_LEVEL環境変数で設定（デフォルト: http） |
| ログファイル | LOG_FILE環境変数で設定可能 |
| HTTPロギング | Morgan（JSON形式/本番環境） |

### ログフォーマット（本番環境）

```json
{
  "level": "http",
  "client_ip": "xxx",
  "request_id": "xxx",
  "http_version": "1.1",
  "method": "GET",
  "path": "/xxx",
  "status": 200,
  "response_size": 1234,
  "request_size": 0,
  "duration": 123,
  "referrer": "xxx",
  "user_agent": "xxx",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### ヘルスチェック

| 項目 | 実装 |
| --- | --- |
| エンドポイント | /health |
| ログ除外 | ヘルスチェックリクエストはHTTPログから除外 |

### テレメトリ

| 項目 | 実装 |
| --- | --- |
| パッケージ | @medusajs/telemetry |
| パニックトラッキング | PANIC_ERROR_REACHEDイベント |
| レート制限 | APIリクエストに対するレート制限機能 |

### HTTP圧縮

| 項目 | 設定 |
| --- | --- |
| 有効化 | http.compression.enabled |
| 圧縮レベル | http.compression.level（デフォルト: 6） |
| メモリレベル | http.compression.memLevel（デフォルト: 8） |
| 閾値 | http.compression.threshold（デフォルト: 1024バイト） |
| 除外ヘッダー | x-no-compression: true |

## 環境設定

### 主要環境変数

| 変数名 | 用途 | デフォルト |
| --- | --- | --- |
| NODE_ENV | 実行環境 | development |
| LOG_LEVEL | ログレベル | http |
| LOG_FILE | ログファイルパス | - |
| DATABASE_URL | PostgreSQL接続URL | - |
| REDIS_URL | Redis接続URL | - |
| JWT_SECRET | JWT署名シークレット | supersecret（開発のみ） |
| COOKIE_SECRET | Cookieシークレット | supersecret（開発のみ） |
| MEDUSA_WORKER_MODE | ワーカーモード | shared |
| __MEDUSA_DB_CONNECTION_MAX_RETRIES | DB接続リトライ回数 | 5 |
| __MEDUSA_DB_CONNECTION_RETRY_DELAY | DB接続リトライ遅延（ms） | 1000 |

## 備考

- 本ドキュメントの数値はコードベースから抽出したデフォルト値であり、プロジェクト要件に応じて調整が必要です
- 本番環境へのデプロイ時は、セキュリティ関連の設定（JWT_SECRET、COOKIE_SECRET等）を必ず環境固有の値に変更してください
- 高負荷環境では、データベース接続プールサイズ、Redisクラスター構成、ワーカー分離等の設定を適切に調整してください
- ワークフローのタイムアウト設定は、業務要件に応じて個別のステップレベルで設定することを推奨します
