# 機能設計書 67-通貨CRUD

## 概要

本ドキュメントは、Medusaコマースプラットフォームにおける通貨管理機能の設計を記述する。システムで利用可能な通貨の取得と管理を提供する。

### 本機能の処理概要

**業務上の目的・背景**：グローバルECサイト運営では、複数の通貨をサポートする必要がある。通貨CRUD機能は、システムで利用可能な通貨情報（通貨コード、シンボル、小数点以下桁数等）を管理し、地域設定や価格設定で使用する通貨の参照を提供する。通貨データは主にマスターデータとして参照されることが多く、シード処理で事前に投入される。

**機能の利用シーン**：
- 地域作成時の通貨コード選択のための通貨一覧取得
- 価格設定時の通貨情報参照
- ストア設定でのサポート通貨選択
- 通貨詳細情報（シンボル、小数桁数等）の確認

**主要な処理内容**：
1. 通貨一覧取得（フィルタ・ページネーション対応）
2. 通貨詳細取得（通貨コード指定）
3. 通貨コードの正規化（小文字変換）

**関連システム・外部連携**：
- 地域モジュール（地域の通貨コード設定）
- 価格設定モジュール（価格の通貨指定）
- ストアモジュール（サポート通貨設定）

**権限による制御**：通貨の取得は認証済みユーザーがアクセス可能。通貨データの追加・変更は通常マイグレーションまたはシード処理で行う。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 110 | 通貨追加画面 | 主画面 | ストアに通貨を追加 |

## 機能種別

参照（取得）操作

## 入力仕様

### 入力パラメータ

#### 通貨一覧取得

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| code | string[] | No | 通貨コードフィルタ | 小文字に正規化 |
| q | string | No | 検索クエリ | - |
| limit | number | No | 取得件数 | 1以上 |
| offset | number | No | オフセット | 0以上 |

#### 通貨詳細取得

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| code | string | Yes | 通貨コード | 小文字に正規化 |

### 入力データソース

- Admin API HTTPリクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string | 通貨コード（ISO 4217準拠、例: usd） |
| symbol | string | 通貨シンボル（例: $） |
| symbol_native | string | ネイティブシンボル |
| name | string | 通貨名（例: US Dollar） |
| decimal_digits | number | 小数点以下桁数 |
| rounding | number | 丸め設定 |

### 出力先

- Admin API HTTPレスポンス

## 処理フロー

### 処理シーケンス

```
1. 通貨一覧取得
   ├─ フィルタパラメータの正規化（code小文字化）
   ├─ remoteQueryでcurrencyテーブル検索
   └─ ページネーション付きで結果返却

2. 通貨詳細取得
   ├─ codeパラメータの正規化（小文字化）
   ├─ remoteQueryでcode指定検索
   └─ 単一通貨情報返却
```

### フローチャート

```mermaid
flowchart TD
    A[API リクエスト] --> B{操作種別}
    B -->|GET /currencies| C[通貨一覧取得]
    B -->|GET /currencies/:code| D[通貨詳細取得]

    C --> E[フィルタ正規化]
    E --> F[normalizeFilters実行]
    F --> G[remoteQuery実行]
    G --> H[結果返却]

    D --> I[code正規化]
    I --> J[remoteQuery実行]
    J --> K{通貨存在?}
    K -->|No| L[NOT_FOUNDエラー]
    K -->|Yes| M[通貨情報返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | 通貨コード正規化 | 通貨コードは小文字に正規化して検索 | 一覧取得・詳細取得時 |
| BR-67-02 | ISO 4217準拠 | 通貨コードはISO 4217規格に準拠 | 全通貨データ |
| BR-67-03 | マスターデータ | 通貨データは主にシード処理で投入 | システム初期化時 |

### 計算ロジック

**フィルタ正規化**:
```typescript
if (fieldName === "code" && !!value) {
  return value.toLowerCase()
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 一覧取得 | currency | SELECT | フィルタ・ページネーション付き |
| 詳細取得 | currency | SELECT | code指定で単一取得 |

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

#### currency

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | code | 主キー、WHERE code = ? | 詳細取得時 |
| SELECT | code, symbol, symbol_native, name, decimal_digits, rounding | 取得対象 | 全フィールド取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NOT_FOUND | MedusaError | 指定codeの通貨が存在しない | 404レスポンス |

### リトライ仕様

参照操作のためリトライ不要。

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

参照操作のみのためトランザクション管理不要。

## パフォーマンス要件

- code（主キー）による高速検索
- code, nameカラムはsearchableで全文検索対応

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

- 認証必須エンドポイント
- 読み取り専用操作で安全

## 備考

- 通貨コードは主キーとして設定（自動生成IDなし）
- 通貨データはシード処理で主要通貨が事前投入される
- rounding値はbigNumber型で高精度計算対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | currency.ts | `packages/modules/currency/src/models/currency.ts` | Currencyモデルの構造（code, symbol, name, decimal_digits, rounding） |

**読解のコツ**: codeが主キー（model.id()ではなくmodel.text().primaryKey()）。searchable()はcode, nameに設定。

#### Step 2: APIエントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | route.ts | `packages/medusa/src/api/admin/currencies/route.ts` | GET - 通貨一覧取得 |
| 2-2 | [code]/route.ts | `packages/medusa/src/api/admin/currencies/[code]/route.ts` | GET - 通貨詳細取得 |

**主要処理フロー**:
1. **route.ts 8-31行目**: 一覧取得、remoteQuery使用、ページネーション対応
2. **[code]/route.ts 9-32行目**: 詳細取得、NOT_FOUNDエラー処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | currency-module-service.ts | `packages/modules/currency/src/services/currency-module-service.ts` | CurrencyModuleServiceの実装 |

**主要処理フロー**:
- **43-53行目**: retrieveCurrency - codeの正規化とsuper.retrieveCurrency呼び出し
- **56-66行目**: listCurrencies - フィルタ正規化とsuper.listCurrencies呼び出し
- **81-94行目**: normalizeFilters - codeフィールドの小文字変換

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

```
Admin API Route
    │
    ├─ GET /currencies
    │      └─ remoteQuery
    │             └─ currencyService.listCurrencies
    │                    └─ normalizeFilters (code小文字化)
    │
    └─ GET /currencies/:code
           └─ remoteQuery
                  └─ currencyService.retrieveCurrency
                         └─ normalizeFilters (code小文字化)
```

### データフロー図

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

通貨一覧取得
  filters (code, q等) ───▶ normalizeFilters ───▶ 正規化されたフィルタ
                                │
                                ▼
                         remoteQuery実行
                                │
                                ▼
                         currencyテーブル
                                │
                                ▼
                         CurrencyDTO[]

通貨詳細取得
  code ──────────────────▶ normalizeFilters ───▶ 小文字化されたcode
                                │
                                ▼
                         remoteQuery実行
                                │
                         ┌──────┴──────┐
                         ▼             ▼
                     存在する       存在しない
                         │             │
                         ▼             ▼
                   CurrencyDTO    NOT_FOUNDエラー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| currency.ts | `packages/modules/currency/src/models/currency.ts` | ソース | Currencyモデル定義 |
| currency-module-service.ts | `packages/modules/currency/src/services/currency-module-service.ts` | ソース | CurrencyModuleService |
| route.ts | `packages/medusa/src/api/admin/currencies/route.ts` | ソース | 通貨一覧API |
| [code]/route.ts | `packages/medusa/src/api/admin/currencies/[code]/route.ts` | ソース | 通貨詳細API |
| validators.ts | `packages/medusa/src/api/admin/currencies/validators.ts` | ソース | 入力バリデーション |
