# アプリケーション共通処理方式

本章では、アプリケーション全体で共通的に使用する処理方式を定義します。
各機能実装時は本方式に従うことで、品質の統一と保守性の向上を図ります。

---

## ログ出力仕様

### ログレベル定義

| レベル | 用途 | 出力タイミング |
|--------|------|--------------|
| ERROR | エラー情報 | システムエラー、業務エラー発生時 |
| WARN | 警告情報 | 想定外だが処理継続可能な事象 |
| INFO | 情報ログ | 主要な処理の開始・終了、状態変化 |
| DEBUG | デバッグ情報 | 開発時のデバッグ用詳細情報 |

### ログ出力形式

**JSON形式での構造化ログ:**
```json
{
  "timestamp": "2025-11-20T15:30:00.123Z",
  "level": "INFO",
  "logger": "com.example.service.OrderService",
  "message": "注文処理開始",
  "trace_id": "trace_abc123",
  "span_id": "span_xyz789",
  "user_id": "user_12345",
  "request_id": "req_abc123",
  "context": {
    "order_id": "order_98765",
    "amount": 15000
  }
}
```

### ログ出力項目

**必須項目:**
- タイムスタンプ
- ログレベル
- ロガー名（クラス名）
- メッセージ
- トレースID（分散トレーシング用）

**任意項目:**
- ユーザーID
- リクエストID
- 業務キー（注文ID等）
- コンテキスト情報

### 個人情報のマスキング

**マスキング対象:**
- パスワード: 完全マスキング（`***`）
- メールアドレス: 部分マスキング（`ya***@example.com`）
- クレジットカード番号: 下4桁以外マスキング（`************1234`）
- 電話番号: 中間部マスキング（`090-****-5678`）

### ログローテーション

**設定:**
- ファイルサイズ: 100MB
- 世代管理: 30世代
- 圧縮: gzip圧縮
- 保存期間: 3ヶ月

---

## 例外・エラー処理仕様

### 例外階層構造

```mermaid
graph TD
    A[Exception] --> B[ApplicationException<br/>アプリケーション例外]
    A --> C[SystemException<br/>システム例外]
    B --> D[BusinessException<br/>業務エラー]
    B --> E[ValidationException<br/>検証エラー]
    C --> F[DatabaseException<br/>DB例外]
    C --> G[ExternalApiException<br/>外部API例外]
```

### エラーコード体系

**フォーマット:** `{カテゴリ}{連番}`

| カテゴリ | コード範囲 | 説明 |
|---------|-----------|------|
| AUTH | AUTH-001～099 | 認証・認可エラー |
| VAL | VAL-001～099 | 入力検証エラー |
| BIZ | BIZ-001～099 | 業務エラー |
| DB | DB-001～099 | データベースエラー |
| EXT | EXT-001～099 | 外部連携エラー |
| SYS | SYS-001～099 | システムエラー |

### エラーレスポンス形式

```json
{
  "error_code": "VAL-001",
  "message": "入力値が不正です",
  "details": [
    {
      "field": "email",
      "message": "メールアドレスの形式が正しくありません"
    }
  ],
  "timestamp": "2025-11-20T15:30:00Z",
  "request_id": "req_abc123"
}
```

### 例外ハンドリングフロー

```mermaid
graph TD
    A[処理実行] --> B{例外発生?}
    B -->|No| C[正常終了]
    B -->|Yes| D{例外種別判定}
    D -->|業務エラー| E[エラーログ出力<br/>WARN]
    D -->|システムエラー| F[エラーログ出力<br/>ERROR]
    E --> G[ユーザーへ<br/>エラーメッセージ表示]
    F --> H[管理者へ<br/>アラート通知]
    G --> I[エラー画面/<br/>エラーレスポンス]
    H --> I
```

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

**業務エラー:**
- ユーザーに分かりやすいメッセージを表示
- リトライ可能な場合はその旨を通知
- ログレベル: WARN

**システムエラー:**
- 一般的なエラーメッセージを表示（詳細は隠蔽）
- 管理者に即座に通知
- ログレベル: ERROR

---

## セッション管理方式

### セッション実装方式

**採用技術:**
- サーバーサイド: Redisベースのセッションストア
- クライアント: Cookieベースのセッション管理

### セッション設定

**Cookie属性:**
```
Set-Cookie: session_id=abc123xyz789; 
  Path=/; 
  HttpOnly; 
  Secure; 
  SameSite=Strict; 
  Max-Age=3600
```

**タイムアウト設定:**
- セッションタイムアウト: 30分（無操作時）
- 絶対タイムアウト: 8時間（ログインからの経過時間）
- タイムアウト前警告: 5分前に通知

### セッション格納データ

**格納項目:**
- ユーザーID
- ロール・権限情報
- 最終アクセス時刻
- ログイン時刻
- CSRF トークン
- 言語設定

**格納禁止項目:**
- パスワード
- クレジットカード情報
- 個人番号
- 機密性の高い個人情報

### セッション同期

**マルチサーバー環境:**
- Redis Clusterによるセッション共有
- スティッキーセッションは使用しない
- セッションデータの一貫性保証

---

## DBアクセス処理方式

### データアクセス層構成

```mermaid
graph LR
    A[Controller<br/>制御層] --> B[Service<br/>業務層]
    B --> C[Repository<br/>データアクセス層]
    C --> D[Entity<br/>エンティティ]
    C --> E[Database<br/>データベース]
```

### アクセス方針

**基本方針:**
- レイヤー間の責務分離を徹底
- SQLインジェクション対策（プリペアドステートメント使用）
- N+1問題の回避（適切なJOIN、バッチ処理）
- インデックスの適切な使用

### ORM使用方針

**使用方針:**
- 基本的にORMのクエリビルダーを使用
- 複雑なクエリ・パフォーマンスが重要な処理はネイティブSQL許可
- 動的クエリは専用のビルダーパターンを使用

### コネクションプール設定

**推奨設定:**
- 最小アイドル接続数: 10
- 最大接続数: 50
- コネクションタイムアウト: 30秒
- アイドルタイムアウト: 10分
- 最大ライフタイム: 30分

### クエリパフォーマンス管理

**監視項目:**
- スロークエリの検知（閾値: 1秒以上）
- クエリ実行回数
- コネクションプール使用率

---

## トランザクション管理・スコープ管理仕様

### トランザクション境界

**基本方針:**
- Serviceレイヤーでトランザクション境界を定義
- 1つのユースケース（ユーザー操作）= 1トランザクション
- トランザクションは可能な限り短く保つ

### トランザクション制御フロー

```mermaid
graph TD
    A[処理開始] --> B[トランザクション開始]
    B --> C{業務処理}
    C -->|成功| D[コミット]
    C -->|失敗| E[ロールバック]
    D --> F[処理完了]
    E --> G[エラー処理]
    G --> H[ログ記録]
```

### 分離レベル

| レベル | 用途 | 備考 |
|--------|------|------|
| READ_COMMITTED | 通常の参照・更新処理 | デフォルト |
| REPEATABLE_READ | 複数回読み取りで一貫性が必要 | ファントムリード注意 |
| SERIALIZABLE | 厳密な一貫性が必要な処理 | 決済等、パフォーマンス低下注意 |

### トランザクション伝播

| 伝播タイプ | 説明 |
|----------|------|
| REQUIRED | トランザクションがあれば参加、なければ新規作成（デフォルト） |
| REQUIRES_NEW | 常に新しいトランザクションを作成 |
| NESTED | ネストしたトランザクションを作成 |
| SUPPORTS | トランザクションがあれば参加、なくても実行 |

---

## 同時実行制御方式

### 楽観的ロック

**実装方式:**
- バージョン番号による制御
- 更新時にバージョン番号をチェック
- 競合検知時は適切なエラーメッセージを表示

**制御フロー:**
```mermaid
sequenceDiagram
    participant User1
    participant User2
    participant DB
    
    User1->>DB: データ取得(version=1)
    User2->>DB: データ取得(version=1)
    User1->>DB: 更新(version=1→2)
    DB-->>User1: 成功
    User2->>DB: 更新(version=1→2)
    DB-->>User2: 失敗(version不一致)
    User2->>DB: 最新データ再取得
```

**適用対象:**
- 競合発生頻度が低い処理
- ユーザーによるデータ編集
- マスタデータの更新

### 悲観的ロック

**使用場面:**
- 在庫管理等、確実にロックが必要な処理
- 複数レコードの整合性を保証する処理
- 競合発生頻度が高い処理

**ロック範囲:**
- 必要最小限のレコードのみロック
- ロック時間を最短化
- デッドロック回避のためロック順序を統一

### 二重サブミット防止

**トークン方式:**
1. 画面表示時にワンタイムトークンを発行
2. サブミット時にトークンを検証
3. 使用済みトークンは即座に破棄

**実装フロー:**
```mermaid
sequenceDiagram
    participant Browser
    participant Server
    participant TokenStore
    
    Browser->>Server: 画面表示要求
    Server->>TokenStore: トークン生成
    TokenStore-->>Server: token_abc123
    Server-->>Browser: 画面+トークン
    Browser->>Server: サブミット(token_abc123)
    Server->>TokenStore: トークン検証
    alt トークン有効
        TokenStore-->>Server: OK
        Server->>TokenStore: トークン削除
        Server-->>Browser: 処理成功
    else トークン無効
        TokenStore-->>Server: NG
        Server-->>Browser: エラー(二重サブミット)
    end
```

**トークン管理:**
- 有効期間: 1時間
- 保存先: Redis
- トークン形式: UUID v4

---

## バリデーション方式

### バリデーション実施箇所

**多層防御アプローチ:**
```mermaid
graph LR
    A[クライアント側<br/>バリデーション] --> B[サーバー側<br/>バリデーション]
    B --> C[データベース<br/>制約]
```

1. **クライアント側バリデーション**
   - 目的: UX向上、即座のフィードバック
   - 信頼性: 低（バイパス可能）

2. **サーバー側バリデーション**（必須）
   - 目的: セキュリティ、データ整合性
   - 信頼性: 高

3. **データベース制約**
   - 目的: 最後の砦、データ整合性保証
   - 信頼性: 最高

### バリデーションルール

**共通ルール:**

| 項目 | ルール | チェック内容 |
|------|--------|------------|
| 必須チェック | Required | 未入力不可 |
| 型チェック | Type | データ型の妥当性 |
| 桁数チェック | Length | 最小・最大桁数 |
| 形式チェック | Format | 正規表現による形式検証 |
| 範囲チェック | Range | 数値・日付の範囲 |
| 相関チェック | Cross-field | 項目間の整合性 |

**具体的なバリデーション例:**

| 項目 | ルール |
|------|--------|
| メールアドレス | RFC 5322準拠の形式 |
| 電話番号 | 国内形式: `0X0-XXXX-XXXX` |
| 郵便番号 | `XXX-XXXX` 形式 |
| URL | RFC 3986準拠 |
| 日付 | ISO 8601形式 |

### エラーメッセージ

**メッセージ方針:**
- ユーザーにとって分かりやすい表現
- 具体的な修正方法を提示
- セキュリティ情報は漏洩させない

**メッセージ例:**
- ❌ 悪い例: "Validation error in field 'email'"
- ✅ 良い例: "メールアドレスの形式が正しくありません。例: user@example.com"

---

## 通知方式

### 通知チャネル

| チャネル | 用途 | 優先度 | 到達時間 |
|---------|------|--------|---------|
| メール | 重要通知、定期レポート | 高 | 数分以内 |
| SMS | 緊急通知、2要素認証 | 最高 | 即時 |
| プッシュ通知 | リアルタイム情報 | 中 | 即時 |
| Slack/Teams | システムアラート | 高 | 即時 |
| アプリ内通知 | 一般的なお知らせ | 低 | 次回ログイン時 |

### 通知フロー

```mermaid
graph LR
    A[通知要求] --> B[メッセージキュー]
    B --> C[通知ワーカー]
    C --> D{チャネル振り分け}
    D --> E[メール送信]
    D --> F[SMS送信]
    D --> G[プッシュ通知]
    E --> H[送信履歴記録]
    F --> H
    G --> H
```

### 通知テンプレート管理

**テンプレート構成:**
- テンプレートID
- 件名テンプレート
- 本文テンプレート
- プレースホルダー定義
- 多言語対応

### 送信制御

**レート制限:**
- 同一ユーザーへの送信: 10通/時間
- システム全体: 1000通/分

**リトライ制御:**
- 最大リトライ回数: 3回
- リトライ間隔: 指数バックオフ（1分、5分、15分）
- 恒久的エラーはリトライしない（例: 宛先不正）

**送信履歴:**
- 送信日時
- 送信先
- 送信結果（成功/失敗）
- エラー詳細

---

## その他共通処理方式

### ページネーション

**実装方式:**

| 方式 | 用途 | 特徴 |
|------|------|------|
| オフセットベース | 小規模データ、ページ番号指定 | 実装シンプル、大規模データで性能劣化 |
| カーソルベース | 大規模データ、無限スクロール | 高速、ページ番号指定不可 |

**レスポンス形式:**
```json
{
  "data": [...],
  "pagination": {
    "total": 1000,
    "page": 1,
    "per_page": 20,
    "total_pages": 50,
    "has_next": true,
    "has_prev": false
  }
}
```

### ソート機能

**ソート指定:**
- フィールド名とソート順を指定
- 複数フィールドのソート対応
- デフォルトソート順の定義

### フィルタリング

**フィルタ条件:**
- 等価条件（equals）
- 範囲条件（between、greater than、less than）
- 部分一致（like、contains）
- IN条件（複数値指定）

### キャッシュ制御

**キャッシュ戦略:**

```mermaid
graph TD
    A[リクエスト] --> B{キャッシュ<br/>存在?}
    B -->|Yes| C[キャッシュ返却]
    B -->|No| D[DBアクセス]
    D --> E[キャッシュ保存]
    E --> F[レスポンス返却]
```

**キャッシュ階層:**
1. ブラウザキャッシュ
2. CDNキャッシュ
3. アプリケーションキャッシュ（Redis）
4. DBキャッシュ

**キャッシュキー設計:**
```
{namespace}:{entity}:{id}:{version}
例: app:user:12345:v1
```

**TTL（Time To Live）設定:**
- マスタデータ: 1時間
- ユーザーデータ: 10分
- 一時データ: 5分

### 一括処理

**バッチ処理方針:**
- データ量に応じたチャンク分割
- トランザクションサイズの適切な管理
- 処理状況の可視化
- エラー発生時の部分ロールバック

### 国際化(i18n)・地域化(l10n)対応

**対応項目:**
- 言語切替（日本語、英語等）
- 日時フォーマット
- 数値フォーマット（桁区切り、小数点）
- 通貨表示

**言語判定優先順位:**
1. ユーザー設定
2. Accept-Languageヘッダー
3. デフォルト言語（日本語）

**メッセージ管理:**
- 言語ごとにリソースファイルを用意
- キー: `{カテゴリ}.{項目}`
- プレースホルダーによる動的置換

### ファイルアップロード・ダウンロード

**アップロード制限:**
- 最大ファイルサイズ: 10MB
- 許可ファイル形式: PDF、画像（JPEG、PNG）、Excel等
- ウイルススキャン実施

**ダウンロード制御:**
- ストリーミング方式（大容量ファイル対応）
- Content-Dispositionヘッダーによるファイル名指定
- レート制限

---