# 決済サービス 詳細設計書

| 項目 | 内容 |
|------|------|
| 文書番号 | DD-PAYMENT-001 |
| バージョン | 1.0 |
| 作成日 | 2025年12月1日 |
| ステータス | 承認済み |

---

## 1. サービス概要

決済サービスは個別注文の決済処理を担当する。金額バリデーション、ビジネスルール適用、トランザクション処理、及びWebhookコールバックによる注文サービスへのステータス通知を行う。

---

## 2. APIエンドポイント

### 2.1 POST /api/v1/payments/ — 決済作成

**1件の注文**の決済を処理する。バッチ決済処理はサポートしていない。

**リクエスト:** `{"order_id": 1, "amount": 89800.0, "currency": "JPY"}`

**バリデーション:**
- `amount` >= 100円（最低額）
- `amount` <= 1,000,000円（**1回の取引あたり最大額**）
- `order_id` はユニーク（重複決済不可）

### 2.2 GET /api/v1/payments/{payment_id}

### 2.3 GET /api/v1/payments/order/{order_id}

特定注文の決済情報を返却（1:1関係）。

### 2.4 POST /api/v1/payments/refund

**リクエスト:** `{"payment_id": 1, "reason": "顧客によるキャンセル"}`

---

## 3. データモデル

```mermaid
erDiagram
    payments {
        int id PK
        int order_id UK "UNIQUE - 1注文につき1決済"
        float amount
        string currency "JPY"
        enum status "保留中|処理中|完了|失敗|返金済み"
        string payment_method "credit_card"
        string transaction_id UK
        datetime created_at
        datetime updated_at
    }
    refunds {
        int id PK
        int payment_id FK
        float amount
        string reason
        string status
        datetime created_at
    }
    payments ||--o{ refunds : "返金"
```

> **スキーマ制約:** `order_id` にUNIQUE制約があり、**1注文につき1決済**の関係を強制。複数注文をカバーするバッチ決済は作成できない。`batch_id`、`bulk_payment_group`、`aggregated_amount` カラムは存在しない。

---

## 4. 決済処理フロー

```mermaid
sequenceDiagram
    participant OS as 注文サービス
    participant PS as 決済サービス
    participant DB as 決済DB

    OS->>PS: POST /api/v1/payments
    Note over PS: 金額検証（100〜100万円）
    Note over PS: order_id重複チェック
    PS->>DB: INSERT payment（ステータス: 処理中）
    Note over PS: 決済処理シミュレーション
    PS->>DB: UPDATE payment（ステータス: 完了）
    PS-->>OS: 201 Created
```

---

## 5. ビジネスルール

| ルール | 説明 | 値 |
|--------|------|-----|
| 最低金額 | 1取引あたり最低額 | 100円 |
| 最大金額 | 1取引あたり最大額 | **1,000,000円** |
| 注文関係 | 決済:注文の基数 | **1:1（ユニーク制約）** |
| 重複チェック | 同一order_idは拒否 | エラー400 |
| 返金範囲 | 全額返金のみ | 返金額 = 決済額 |

### 5.1 一括操作への金額バリデーション影響

最大100万円の制限は**1回の取引に適用**される。一括注文インポート機能が追加された場合：
- 100万円未満の個別注文はそれぞれ独立した決済コールが必要
- 複数注文を1トランザクションで処理する集約・バッチ決済エンドポイントは存在しない
- 10,000件の注文処理には10,000回の個別決済APIコールが必要

---

## 6. Webhookメカニズム

決済処理後、注文サービスにステータス更新を通知：

```
POST http://localhost:8000/api/v1/orders/{order_id}/webhook
Body: {"payment_status": "completed", "transaction_id": "uuid"}
```

**1件の注文に対するコールバック**。バッチWebhookやバッチステータス更新は存在しない。

---

## 7. 現在の制限事項

| ID | 制限事項 | 深刻度 |
|----|---------|--------|
| DD-PAY-LIM-001 | **1件ずつの処理のみ。** バッチ決済APIは存在しない。 | 高 |
| DD-PAY-LIM-002 | **集約金額計算なし。** 複数注文の金額を1トランザクションにまとめることは不可。 | 高 |
| DD-PAY-LIM-003 | **1取引あたり最大100万円。** この制限は個別注文に適用。高額注文は拒否される。 | 中 |
| DD-PAY-LIM-004 | **1:1ユニーク制約がバッチ決済グループ化を阻害。** 複数注文をカバーする1件の決済レコードは作成不可。 | 高 |
| DD-PAY-LIM-005 | **単一注文Webhookコールバック。** 複数決済完了のバッチ通知メカニズムなし。 | 中 |
| DD-PAY-LIM-006 | **決済キュー・非同期処理なし。** 全決済はリクエストスレッド内で同期処理。 | 中 |