# 機能設計書 18-注文クレジットライン管理

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける注文クレジットライン管理機能の設計を記載したものである。注文に対するクレジット（ストアクレジット、ギフトカード等）の適用と管理機能について、処理フロー、データ構造、ビジネスルールを定義する。

### 本機能の処理概要

注文クレジットライン管理機能は、ECサイトにおけるクレジットの注文への適用を管理するための機能である。

**業務上の目的・背景**：ECサイトにおいて、ストアクレジット・ギフトカード・ポイント等を注文に適用することは、顧客満足度向上と再購入促進のために重要である。本機能は、注文に紐づくクレジットライン（割引適用）を管理し、合計金額計算時に適切に反映する。

**機能の利用シーン**：
- 顧客がギフトカードを注文に適用する場面
- ストアクレジットを注文に適用する場面
- ポイントを注文に適用する場面
- クレジットライン適用後の合計金額確認

**主要な処理内容**：
1. クレジットライン（OrderCreditLine）の作成・取得・更新・削除
2. 注文合計金額計算時のクレジット反映
3. クレジット参照情報（ギフトカードID等）の管理
4. バージョン管理によるクレジット履歴追跡

**関連システム・外部連携**：
- 注文モジュール：注文との紐付け
- ギフトカードモジュール：ギフトカード残高管理
- 合計金額計算：クレジット適用後の金額計算

**権限による制御**：
- クレジットラインの追加・削除は認証済みユーザーが実行可能
- 管理者は任意のクレジットラインを追加可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 43 | 注文詳細画面 | 参照画面 | クレジットライン情報の表示 |

## 機能種別

CRUD操作 / 金額計算

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| order_id | string | Yes | 注文ID | 有効な注文IDであること |
| amount | BigNumber | Yes | クレジット金額 | 0以上 |
| reference | string | No | 参照種別（gift_card, store_credit等） | - |
| reference_id | string | No | 参照ID（ギフトカードID等） | - |
| metadata | object | No | メタデータ | JSON形式 |

### 入力データソース

- カート・注文作成時：ギフトカード適用
- 管理画面：ストアクレジット適用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | string | クレジットラインID（prefix: ordcl） |
| order_id | string | 注文ID |
| version | number | 注文バージョン |
| amount | BigNumber | クレジット金額 |
| raw_amount | object | 生の金額データ（JSON） |
| reference | string | 参照種別 |
| reference_id | string | 参照ID |
| metadata | object | メタデータ |

### 出力先

- データベース：order_credit_lineテーブル
- API応答：OrderCreditLineDTO形式
- 合計金額計算：credit_line_total, credit_line_subtotal等

## 処理フロー

### 処理シーケンス

```
1. クレジットライン追加リクエスト受信
   └─ order_id、amount、reference等を含むリクエストを受信

2. 注文存在確認
   └─ 対象注文の存在確認

3. クレジットラインの作成
   └─ OrderCreditLineレコードを作成
   └─ バージョンは注文の現在バージョンを設定

4. 合計金額再計算
   └─ credit_line_totalを更新
   └─ 最終合計金額を再計算

5. 結果返却
   └─ 作成されたクレジットラインをシリアライズして返却
```

### フローチャート

```mermaid
flowchart TD
    A[クレジットライン追加リクエスト] --> B[注文存在確認]
    B --> C{注文が存在?}
    C -->|No| D[エラー返却]
    C -->|Yes| E[OrderCreditLine作成]
    E --> F[合計金額再計算]
    F --> G[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-18-01 | バージョン管理 | クレジットラインは注文のバージョンに紐付く | クレジットライン作成時 |
| BR-18-02 | 合計金額反映 | クレジット金額は合計金額計算時にcredit_line_totalとして集計 | 合計計算時 |
| BR-18-03 | 参照管理 | reference/reference_idでクレジット元（ギフトカード等）を追跡 | - |

### 計算ロジック

```
credit_line_total = SUM(credit_lines.amount)
credit_line_subtotal = credit_line_total - credit_line_tax_total

final_total = item_total + shipping_total - discount_total - credit_line_total
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| クレジットライン作成 | order_credit_line | INSERT | クレジットラインの作成 |
| クレジットライン削除 | order_credit_line | DELETE / soft delete | クレジットラインの削除 |

### テーブル別操作詳細

#### order_credit_line

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成（prefix: ordcl） | 主キー |
| INSERT | order_id | 対象注文ID | 外部キー |
| INSERT | version | 注文の現在バージョン | デフォルト1 |
| INSERT | amount | リクエストのamount | BigNumber |
| INSERT | raw_amount | 金額の生データ | JSON形式 |
| INSERT | reference | リクエストのreference | nullable |
| INSERT | reference_id | リクエストのreference_id | nullable |
| INSERT | metadata | リクエストのmetadata | JSON形式 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定されたorder_idの注文が存在しない | 有効な注文IDを指定 |
| INVALID_DATA | MedusaError | amount未指定または負の値 | 正の金額を指定 |

### リトライ仕様

データベース操作はトランザクション内で実行されるため、失敗時は自動ロールバックされる。

## トランザクション仕様

- 標準のMedusaService CRUD操作を使用
- 注文作成時はクレジットラインも同一トランザクション内で作成

## パフォーマンス要件

- クレジットライン追加：100ms以内
- インデックス：order_id、(order_id, version)にインデックス設定

## セキュリティ考慮事項

- クレジットラインの追加は認証済みユーザーのみ実行可能
- 金額情報は監査ログに記録
- reference_idを通じて元のギフトカード等を追跡可能

## 備考

- クレジットラインは注文のcredit_linesリレーションとして取得可能
- 合計金額計算時にcredit_line_total, credit_line_subtotal, credit_line_tax_totalが算出される
- 複数のクレジットラインを1つの注文に適用可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | credit-line.ts | `packages/modules/order/src/models/credit-line.ts` | OrderCreditLineエンティティ、amount/raw_amount/reference/reference_idプロパティ |

**読解のコツ**:
- **6行目**: IDプレフィックスは"ordcl"
- **7-12行目**: version、reference、reference_id、amount、raw_amount等の主要プロパティ
- **13-15行目**: orderリレーション（belongsTo）

#### Step 2: サービス層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | orderCreditLineService_の使用箇所（115行目、293-295行目）、createOrders_でのcredit_lines処理（803-811行目） |

**読解のコツ**:
- **803-811行目**: 注文作成時のクレジットライン一括作成処理
- **831-836行目**: orderCreditLineService_.createの呼び出し

### プログラム呼び出し階層図

```
OrderModuleService (MedusaService継承)
    ├─ createOrderCreditLines (標準CRUD)
    ├─ updateOrderCreditLines (標準CRUD)
    ├─ deleteOrderCreditLines (標準CRUD)
    ├─ listOrderCreditLines (標準CRUD)
    └─ retrieveOrderCreditLine (標準CRUD)

createOrders_
    └─ orderCreditLineService_.create（注文作成時のクレジットライン作成）
```

### データフロー図

```
[入力]                    [処理]                           [出力]

CreateOrderCreditLineDTO ─▶ orderCreditLineService_.create ─▶ order_credit_line テーブル
       │
       v
 order_id, amount,
 reference, reference_id                                OrderCreditLineDTO

合計計算時:
order.credit_lines ─────▶ decorateCartTotals ──────────▶ credit_line_total
                                                         credit_line_subtotal
                                                         credit_line_tax_total
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| credit-line.ts | `packages/modules/order/src/models/credit-line.ts` | ソース | OrderCreditLineエンティティ定義 |
| order-module-service.ts | `packages/modules/order/src/services/order-module-service.ts` | ソース | サービス層（標準CRUD使用） |
| order.ts | `packages/modules/order/src/models/order.ts` | ソース | Orderエンティティ（credit_linesリレーション） |
