# 基本設計書（HLD）
| 項目 | 内容 |
|------|------|
| 文書番号 | HLD-ECOM-001 |
| バージョン | 1.0 |
| 作成日 | 2025年12月1日 |
| ステータス | 承認済み |
| 作成者 | 鈴木 一郎（技術部長） |
---
## 1. アーキテクチャ概要
ECサイトプラットフォームは3つの独立デプロイ可能なマイクロサービスで構成され、各サービスが独自のデータベースを保有する（Database-per-Serviceパターン）。
```mermaid
graph TB
FE[フロントエンド管理画面
:5173] --> OS[注文サービス
:8000]
FE --> PS[決済サービス
:8001]
FE --> NS[通知サービス
:8002]
OS --> OS_DB[(注文DB
SQLite)]
PS --> PS_DB[(決済DB
SQLite)]
NS --> NS_DB[(通知DB
SQLite)]
OS -->|POST /api/v1/payments| PS
OS -->|POST /api/v1/notifications/email| NS
PS -->|POST /api/v1/orders/{id}/webhook| OS
```
---
## 2. サービス一覧
| サービス | ポート | 技術スタック | データベース | 責務 |
|---------|--------|------------|------------|------|
| 注文サービス | 8000 | Python 3.12, FastAPI, SQLAlchemy async | SQLite | 注文CRUD、ステータス管理、オーケストレーション |
| 決済サービス | 8001 | Python 3.12, FastAPI, SQLAlchemy async | SQLite | 決済処理、返金、金額バリデーション |
| 通知サービス | 8002 | Python 3.12, FastAPI, SQLAlchemy async | SQLite | メール/SMS通知、テンプレート管理 |
| フロントエンド管理画面 | 5173 | React 19, TypeScript, Vite, Tailwind CSS | なし（ステートレスSPA） | Web管理UI、ダッシュボード、注文管理 |
---
## 3. 通信パターン
サービス間通信は全て**同期REST over HTTP**。メッセージブローカー、イベントバス、非同期通信チャネルは存在しない。
| パターン | 用途 | タイムアウト |
|---------|------|------------|
| 同期REST | 全サービス間呼出し | 30秒（決済）、10秒（通知/Webhook） |
| Webhook（RESTコールバック） | 決済→注文ステータス更新 | 10秒 |
---
## 4. サービス依存関係マトリクス
| 呼出元 | 呼出先 | エンドポイント | メソッド | パターン | 目的 |
|--------|--------|--------------|---------|---------|------|
| 注文サービス | 決済サービス | /api/v1/payments | POST | 同期REST | 注文作成時の決済処理 |
| 注文サービス | 決済サービス | /api/v1/payments/refund | POST | 同期REST | キャンセル時の返金 |
| 注文サービス | 決済サービス | /api/v1/payments/order/{order_id} | GET | 同期REST | 返金用の決済情報取得 |
| 注文サービス | 通知サービス | /api/v1/notifications/email | POST | 同期REST | 確認/発送/キャンセルメール |
| 決済サービス | 注文サービス | /api/v1/orders/{order_id}/webhook | POST | Webhook | 決済ステータス通知 |
| フロントエンド | 注文サービス | /api/v1/orders | GET/POST/DELETE | 同期REST | 注文管理UI |
| フロントエンド | 決済サービス | /api/v1/payments/order/{order_id} | GET | 同期REST | 決済詳細表示 |
| フロントエンド | 通知サービス | /api/v1/notifications/order/{order_id} | GET | 同期REST | 通知ログ表示 |
---
## 5. データフロー図
### 5.1 注文作成フロー
```mermaid
sequenceDiagram
participant C as クライアント
participant OS as 注文サービス
participant PS as 決済サービス
participant NS as 通知サービス
C->>OS: POST /api/v1/orders
Note over OS: 注文データ検証（1件のみ）
Note over OS: 合計金額計算
Note over OS: 注文保存（ステータス: 保留中）
OS->>OS: ステータス→決済処理中
OS->>PS: POST /api/v1/payments
Note over PS: 金額検証（100〜100万円）
Note over PS: 重複チェック
Note over PS: 決済処理実行
PS-->>OS: 201 Created
OS->>OS: ステータス→決済済み
OS->>NS: POST /api/v1/notifications/email
Note over NS: ORDER_CONFIRMATIONテンプレート描画
Note over NS: メール送信
NS-->>OS: 201 Created
OS-->>C: 201 Created（注文詳細）
```
> **注意:** このフローは**1件の注文**を処理する。各ステップはシーケンシャル実行 — 決済完了後に通知を送信。並列処理・バッチ処理の機能はない。
### 5.2 注文キャンセルフロー
```mermaid
sequenceDiagram
participant C as クライアント
participant OS as 注文サービス
participant PS as 決済サービス
participant NS as 通知サービス
C->>OS: DELETE /api/v1/orders/{id}
Note over OS: ステータス→キャンセル済み
OS->>PS: GET /api/v1/payments/order/{order_id}
PS-->>OS: 決済情報
OS->>PS: POST /api/v1/payments/refund
PS-->>OS: 201 返金完了
OS->>NS: POST /api/v1/notifications/email
Note over NS: ORDER_CANCELLEDテンプレート
NS-->>OS: 201 Created
OS-->>C: 200 OK
```
---
## 6. データアーキテクチャ
各サービスが独自のデータベースを排他的に所有。**サービス間の外部キーなし**、**共有データベースなし**。
| サービス | DBファイル | テーブル |
|---------|----------|---------|
| 注文サービス | order_service.db | orders, order_items |
| 決済サービス | payment_service.db | payments, refunds |
| 通知サービス | notification_service.db | notification_templates, notifications |
---
## 7. 既知の制限事項と影響範囲
### 7.1 単一注文処理のみ
全サービス間通信は**1件の注文**を処理する設計。APIコントラクト、DBスキーマ、ビジネスロジックの全てが1件ずつの処理を前提としている。
### 7.2 一括操作追加時の影響
一括注文インポート（CSV、100〜10,000件）の追加には、**全3サービス**の変更が必要：
| サービス | 必要な変更 | 複雑度 |
|---------|----------|--------|
| 注文サービス | 一括作成エンドポイント新設、CSVパーサー、バッチ処理ロジック、進捗追跡、ordersテーブルにbatch_idカラム追加 | 高 |
| 決済サービス | バッチ決済API新設、集約金額計算、取引上限（100万円）の見直し、バッチ決済グループ化 | 高 |
| 通知サービス | 一括通知API新設、レート制限再設計（現在: 10件/秒）、キューベース非同期送信、バッチテンプレート描画 | 中 |
| データベース（全サービス） | スキーマ移行: batch_idカラム追加、インポート履歴テーブル新設 | 高 |
### 7.3 具体的なボトルネック
1. **決済金額上限：** 1回の取引あたり最大100万円。集約バッチ決済は存在しない。
2. **通知レート制限：** 10件/秒。10,000件のインポートでは通知だけで最低1,000秒（約17分）。
3. **シーケンシャル処理：** 現在の注文作成フローは逐次実行。並列・キューベース処理が必要。
4. **バッチエラーハンドリングなし：** バッチ内の1件が失敗した場合、残りの処理を継続する仕組みがない。