# 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`: 依存パッケージ