バックエンドAPI

README.md

@@ -0,0 +1,224 @@
+# Diplomacy Calculation Engine API
+
+ディプロマシー（Diplomacy）ボードゲームの計算エンジンとして機能する、ステートレスなFastAPIアプリケーションです。
+`diplomacy`ライブラリの計算ロジックをウェブAPIとして提供します。フロントエンドアプリケーション等から利用されることを想定しています。
+
+## 主な機能
+
+* **ステートレスな計算**: ゲームの状態（JSON）と命令を送り、次の状態を取得可能。
+* **命令の解決 (Processing)**: フェイズを進行させ、命令を解決します。
+* **命令の検証 (Validation)**: 指定された命令がルール上有効かどうかをチェック。
+* **実行可能な命令の取得**: 現在の盤面で各ユニットができる全命令のリストを取得。
+* **可視化 (Rendering)**: 現在の盤面や入力中の命令を反映したSVG画像を生成。
+
+## 開発環境のセットアップ
+
+```bash
+# 仮想環境の作成と有効化
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+
+# 依存ライブラリのインストール
+pip install -r requirements.txt
+pip install requests  # テスト用
+```
+
+## 起動方法
+
+### 推奨: Pythonコマンド
+
+```bash
+python main.py
+```
+
+### Option: uvicornコマンド
+
+```bash
+# main.pyがルートにあるため main:app と指定します
+uvicorn main:app --host 127.0.0.1 --port 8000
+```
+
+起動後、Swagger UIが [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) で利用可能です。
+
+---
+
+## API エンドポイント仕様
+
+### 1. マップ情報の取得
+
+#### マップ一覧の取得
+
+* **URL**: `/maps`
+* **Method**: `GET`
+* **Description**: 利用可能なマップ名の一覧を返します。
+
+#### マップ詳細の取得
+
+* **URL**: `/maps/{map_name}`
+* **Method**: `GET`
+* **Description**: 指定したマップのトポロジー情報（地域、隣接関係など）を返します。
+* **Example**: `/maps/standard`
+
+### 2. 計算・フェイズ進行
+
+#### ゲームの進行 (Process)
+
+現在の状態と命令を受け取り、判定を行い、次のフェイズの状態を返します。
+
+* **URL**: `/calculate/process`
+* **Method**: `POST`
+* **Request Body**:
+
+    ```json
+    {
+      "game_state": { ... },  // diplomacyライブラリの Game.to_dict() 形式
+      "orders": {
+        "FRANCE": ["A MAR - SPA", "A PAR - BUR"],
+        "ENGLAND": ["F LON - ENG"]
+      }
+    }
+    ```
+
+* **Response**:
+
+    ```json
+    {
+      "game_state": { ... } // 更新された新しいゲーム状態
+    }
+    ```
+
+#### 命令の検証 (Validate)
+
+指定された命令が現在の局面で有効かどうかを検証します（フェイズは進みません）。
+
+* **URL**: `/calculate/validate`
+* **Method**: `POST`
+* **Request Body**: `process` と同様（`game_state` と `orders`）
+* **Response**:
+
+    ```json
+    {
+      "validated_orders": {
+        "FRANCE": ["A MAR - SPA"] // 受け付けられた命令
+      },
+      "errors": [] // エラーがあればここにリストされます
+    }
+    ```
+
+#### 実行可能な命令の取得 (Possible Orders)
+
+現在の局面で実行可能なすべての命令のリストを取得します。
+
+* **URL**: `/calculate/possible-orders`
+* **Method**: `POST`
+* **Query Param**:
+  * `power_name` (Optional) - 特定の国の命令のみ取得する場合に指定。
+  * `by_power` (Optional) - `true`を指定すると、結果を国ごとにグループ化して返します。
+* **Request Body**:
+
+    ```json
+    {
+      "game_state": { ... } // diplomacyライブラリの Game.to_dict() 形式
+    }
+    ```
+
+* **Response**:
+
+    ```json
+    {
+      "possible_orders": {
+        "ADR": [],              // ユニットがいない地域
+        "ANK": [ ... ],         // ユニットがいる地域の命令リスト
+        ...
+      }
+    }
+    ```
+
+    ※ `by_power=true` 指定時は、以下のように国名がキーとなります：
+
+    ```json
+    {
+      "possible_orders": {
+        "FRANCE": {
+          "PAR": [ ... ],
+          "MAR": [ ... ]
+        },
+        "ENGLAND": { ... }
+      }
+    }
+    ```
+
+    ※ `power_name` 指定時は、その国のユニットが存在する地域のみが含まれます。
+
+#### 命令の自動生成 (Auto Orders)
+
+指定した国に対して、ランダムに有効な命令を生成します。
+
+* **URL**: `/calculate/auto-orders`
+* **Method**: `POST`
+* **Query Param**: `power_name` (Required)
+* **Request Body**:
+
+    ```json
+    {
+      "game_state": { ... }
+    }
+    ```
+
+* **Response**:
+
+    ```json
+    {
+      "orders": ["A PAR - BUR", "F BRE H", ...]
+    }
+    ```
+
+#### ゲームの強制終了 (Draw)
+
+ゲームの状態を手動で「引き分け (Draw)」に変更し、フェイズを `COMPLETED` にします。
+
+* **URL**: `/game/draw`
+* **Method**: `POST`
+* **Request Body**:
+
+    ```json
+    {
+      "game_state": { ... },  // Game.to_dict() 形式
+      "winners": ["FRANCE", "GERMANY"] // (Optional) 特定の勝者を指定する場合
+    }
+    ```
+
+* **Response**:
+
+    ```json
+    {
+      "game_state": { ... } // COMPLETED状態のゲーム
+    }
+    ```
+
+### 3. 可視化 (Rendering)
+
+#### マップ画像の生成
+
+現在の状態（および入力中の命令）を反映したSVG画像を生成します。
+
+* **URL**: `/render`
+* **Method**: `POST`
+* **Request Body**:
+
+    ```json
+    {
+      "game_state": { ... },
+      "orders": { ... },     // Optional: 入力中の命令（矢印で描画されます）
+      "incl_orders": true,   // Optional: 命令を描画するか (default: true)
+      "incl_abbrev": true    // Optional: 地名の略称を表示するか (default: true)
+    }
+    ```
+
+* **Response**: `image/svg+xml` (SVG画像データ)
+
+## プロジェクト構造
+
+* `main.py`: APIサーバー実装
+* `test_api.py`: 動作確認用スクリプト
+* `requirements.txt`: 依存パッケージ