# バッチ設計書 38-schema

## 概要

本ドキュメントは、InvenTreeシステムにおけるAPIスキーマエクスポートバッチ（schema）の設計仕様を定義する。

### 本バッチの処理概要

schemaは、InvenTreeのREST APIスキーマをOpenAPI形式でエクスポートするDjango管理コマンドである。drf-spectacularのschemaコマンドを拡張し、django-allauthの認証エンドポイントを統合する。

**業務上の目的・背景**：InvenTreeは包括的なREST APIを提供しており、外部アプリケーションやフロントエンドクライアントがシステムと連携できる。APIドキュメントの自動生成と、APIクライアント（SDK）の自動生成を可能にするため、OpenAPI（旧Swagger）形式のスキーマが必要である。本バッチは、InvenTree独自のAPIエンドポイントに加え、django-allauthが提供する認証関連エンドポイントも統合したスキーマを生成する。これにより、完全なAPIドキュメントとクライアントSDKの生成が可能になる。

**バッチの実行タイミング**：手動実行（CLIコマンド）。以下の場面で実行される：
- APIドキュメント更新時
- リリースビルド時
- API変更後の検証時
- `invoke schema` コマンド実行時

**主要な処理内容**：
1. django-allauthのOpenAPIスキーマを読み込み
2. allauthのパスとコンポーネントを整形・統合
3. drf-spectacularのスキーマ生成を実行
4. 統合されたOpenAPIスキーマをYAML形式で出力

**前後の処理との関連**：
- 前提：Django環境とDRF（Django REST Framework）が設定されていること
- 後続：APIドキュメント生成、クライアントSDK生成

**影響範囲**：
- 指定された出力ファイル（YAMLファイル）
- APIドキュメンテーション

## バッチ種別

ドキュメント生成 / スキーマエクスポート

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 / invoke schema |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Django環境 | Django環境が正しく設定されていること |
| drf-spectacular | drf-spectacularパッケージがインストールされていること |
| django-allauth | django-allauthパッケージがインストールされていること |
| REST Framework | Django REST Frameworkが設定されていること |

### 実行可否判定

特別な判定ロジックなし。コマンド実行時に常に処理を実行する。

## 入力仕様

### 入力パラメータ

drf-spectacularのschemaコマンドの引数を継承。主要なオプション：

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --file | str | No | stdout | 出力ファイル名 |
| --validate | flag | No | False | スキーマを検証する |
| --color | flag | No | False | カラー出力を有効化 |
| --fail-on-warn | flag | No | False | 警告時に失敗とする |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| DRF ViewSets/APIViews | Pythonクラス | API定義 |
| allauth/headless/spec/doc/openapi.yaml | YAML | allauthのOpenAPIスキーマ |
| SPECTACULAR_SETTINGS | Django設定 | スキーマ生成設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 指定ファイル | YAML | OpenAPI 3.0形式のスキーマ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | --fileで指定（デフォルト: schema.yml） |
| 出力先 | 指定パス |
| 文字コード | UTF-8 |
| フォーマット | YAML（OpenAPI 3.0仕様準拠） |

## 処理フロー

### 処理シーケンス

```
1. allauthスキーマの読み込み
   └─ allauth/headless/spec/doc/openapi.yamlを読み込み
2. パス情報の整形
   └─ 各パスのプレフィックスを調整
   └─ operationIdが無い場合は生成
   └─ パラメータとレスポンスの参照名を調整
   └─ 不要なパラメータを削除
3. コンポーネント情報の整形
   └─ スキーマ、パラメータ、レスポンスの参照名にプレフィックスを追加
   └─ 不要なパラメータを削除
4. Django設定への注入
   └─ SPECTACULAR_SETTINGS['APPEND_PATHS']にパス情報を設定
   └─ SPECTACULAR_SETTINGS['APPEND_COMPONENTS']にコンポーネントを設定
5. 親クラスのhandle()を呼び出し
   └─ drf-spectacularのスキーマ生成を実行
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[allauthスキーマ読み込み]
    B --> C[パス情報のループ処理]
    C --> D[パスプレフィックス調整]
    D --> E[operationId生成]
    E --> F[参照名の調整]
    F --> G[不要パラメータ削除]
    G --> H{全パス完了?}
    H -->|No| C
    H -->|Yes| I[コンポーネント処理]
    I --> J[参照名にプレフィックス追加]
    J --> K[不要パラメータ削除]
    K --> L[SPECTACULAR_SETTINGSに注入]
    L --> M[親クラスhandle()呼び出し]
    M --> N[OpenAPIスキーマ出力]
    N --> O['done'返却]
    O --> P[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | 本バッチはDBを操作しない |

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

本バッチはデータベースへのアクセスは行わない。API定義のイントロスペクションのみを実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileNotFoundError | allauthのスキーマファイルが見つからない | allauthのインストールを確認 |
| - | ValidationError | スキーマ検証エラー（--validate時） | API定義を修正 |
| - | Warning | スキーマ警告（--fail-on-warn時） | 警告内容を確認・修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. エラーメッセージを確認
2. API定義やスキーマ設定を修正
3. 問題解決後に再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル出力のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全APIエンドポイント |
| 目標処理時間 | 数秒〜数十秒 |
| メモリ使用量上限 | 中程度（スキーマ全体をメモリに保持） |

## 排他制御

同時実行の制御は行わない。出力ファイルの競合に注意。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| なし | - | drf-spectacularの標準出力に依存 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | - | - |

## 備考

- 本コマンドは `invoke schema` から呼び出される
- drf-spectacularのspectacular.Command（schemaコマンド）を継承
- django-allauthの認証エンドポイントを統合
- allauth関連の参照名には 'allauth.' プレフィックスが追加される
- 以下のallauthパラメータは削除される（InvenTreeでは使用しない）：
  - allauth.SessionToken
  - allauth.Client
- パスは `/api/auth/v1/` プレフィックスで統一される
- INVENTREE_SITE_URL、INVENTREE_PLUGINS_ENABLED、INVENTREE_CURRENCY_CODES環境変数で出力を安定化できる
- 処理完了時に 'done' を返却
