riichi_engine 0.1.0

data/docs/api_reference.md

@@ -0,0 +1,309 @@
+# API リファレンス
+
+`RiichiEngine::API` は host app や adapter 層から `riichi_engine` を呼ぶための公開入口です。
+
+局進行・和了評価・点数計算はすべてこのモジュールを経由してください。  
+内部 namespace（`Mahjong::Flow::*` 等）を host app から直接呼ぶことは避けてください（詳細は [公開 API ポリシー](public_api_policy.md)）。
+
+牌記法や麻雀用語については [概念・用語集](concepts.md) を参照してください。
+
+---
+
+## 共通の型
+
+### RuleConfig
+
+ゲームルールを保持するオブジェクトです。引数なしでデフォルトルールを使えます。
+
+```ruby
+rule = Mahjong::Config::RuleConfig.new                  # デフォルト
+rule = Mahjong::Config::RuleConfig.new("kuitan" => false)  # 食い断なし
+```
+
+#### RuleConfig の設定項目
+
+| キー | 型 | デフォルト | 説明 |
+|---|---|---|---|
+| `game_type` | String | `"hanchan"` | `"hanchan"`（東南戦）または `"tonpuu"`（東風戦） |
+| `initial_score` | Integer | `25000` | 開始点数 |
+| `oka_origin` | Integer | `30000` | オカの基準点 |
+| `uma` | Array | `[20000, 10000, -10000, -20000]` | ウマ（1位から順） |
+| `aka_dora` | Hash | `{ "m" => 1, "p" => 1, "s" => 1 }` | スートごとの赤ドラ枚数 |
+| `kuitan` | Boolean | `true` | 食い断あり |
+| `atozuke` | Boolean | `true` | 後付けあり |
+| `double_yakuman` | Boolean | `false` | ダブル役満あり |
+| `kazoe_yakuman` | Boolean | `true` | 数え役満あり |
+| `kiriage_mangan` | Boolean | `false` | 切り上げ満貫あり |
+| `triple_ron_draw` | Boolean | `true` | 三家和で流局 |
+| `double_ron` | Boolean | `true` | ダブロンあり |
+| `tobi` | Boolean | `true` | トビあり（点数が0点以下でゲーム終了） |
+| `nishi_iri` | Boolean | `false` | 西入あり |
+| `nishi_iri_threshold` | Integer | `30000` | 西入の基準点 |
+| `renpuu_jantou_fu` | Integer | `2` | 連風牌を雀頭にしたときの符 |
+
+### Snapshots
+
+局の状態を gem へ渡すための値オブジェクトです。ActiveRecord を含まない plain Ruby の構造体です。
+
+```ruby
+Mahjong::Snapshots::GameSetupSnapshot      # 局開始情報
+Mahjong::Snapshots::GameProgressSnapshot   # 局終了後の進行情報
+Mahjong::Snapshots::FinalResultSnapshot    # ゲーム終了時の最終情報
+Mahjong::Snapshots::WinEvaluationSnapshot  # 和了評価用の情報
+```
+
+各フィールドは [使用例](usage_examples.md) のコードを参照してください。
+
+### RoundState
+
+局の進行状態を保持するオブジェクトです。  
+`setup_round` が返し、`apply_round_action` に渡し続けることで局が進行します。  
+JSON へのシリアライズ・デシリアライズが可能なので、キャッシュに保存して復元することもできます。
+
+```ruby
+Mahjong::State::RoundState
+```
+
+---
+
+## メソッド一覧
+
+### `setup_round(game_snapshot:, rule:, seed: nil)`
+
+局の初期状態を構築します。牌山を生成し、配牌を行い、`RoundState` を返します。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `game_snapshot` | `GameSetupSnapshot` | 局番・点棒・親座席などの初期情報 |
+| `rule` | `RuleConfig` | ゲームルール |
+| `seed` | `String \| nil` | 牌山の乱数シード。同じ seed で再現可能。省略するとランダム |
+
+**返り値：** `Mahjong::State::RoundState`
+
+---
+
+### `apply_round_action(state:, action:, rule:)`
+
+局中のアクションを `state` に適用し、結果を返します。  
+`state` は破壊的に更新されます。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `state` | `RoundState` | 現在の局状態 |
+| `action` | `Hash` | 適用するアクション |
+| `rule` | `RuleConfig` | ゲームルール |
+
+**`action` の形式：**
+
+```ruby
+{ type: :tsumo }
+{ type: :dahai,          seat: 0, tile: "5m" }
+{ type: :riichi,         seat: 0, tile: "3z" }
+{ type: :pon,            seat: 1, tiles: %w[5m 5m] }
+{ type: :chi,            seat: 1, tiles: %w[4m 6m] }
+{ type: :ankan,          seat: 0, tile: "5m" }
+{ type: :kakan,          seat: 0, tile: "5m" }
+{ type: :daiminkan,      seat: 1 }
+{ type: :tsumo_agari,    seat: 0 }
+{ type: :ron_agari,      seat: 1 }
+{ type: :skip,           seat: 2 }
+{ type: :kyuushu_kyuuhai, seat: 0 }
+```
+
+アクション種別の詳細は [概念・用語集](concepts.md#アクション種別) を参照してください。
+
+**返り値：** `Mahjong::Results::RoundFlowResult`
+
+| フィールド | 説明 |
+|---|---|
+| `state` | 更新後の `RoundState` |
+| `events` | このアクションで発生したイベントの配列 |
+| `round_end?` | 局が終了したか否か |
+| `round_end_info` | 局終了情報（`RoundEndInfo`）。局中は `nil` |
+
+**例外：**
+
+| 例外 | 発生条件 |
+|---|---|
+| `RiichiEngine::API::InvalidActionError` | 不正なアクション（存在しない打牌・権利のない鳴きなど） |
+| `RiichiEngine::API::EngineError` | エンジン内部エラー |
+
+---
+
+### `available_round_actions(state:, seat:, rule:)`
+
+指定した `seat` が現在選択できるアクションの一覧を返します。  
+`apply_round_action` に渡す `action` の候補を取得するために使います。
+
+**返り値：** `Array<Hash>`
+
+各要素は `{ type: :dahai, tile: "5m" }` のような Hash です。
+
+---
+
+### `resolve_pending_action(pending_actions)`
+
+複数の seat が同時に鳴き・ロンを宣言した場合（鳴き競合）に、優先順位を解決して1つのアクションを選びます。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `pending_actions` | `Hash{Integer => Array<Hash>}` | seat番号 → アクション配列 のマップ |
+
+**返り値：** `Hash | nil`  
+競合を解決したアクション。有効なアクションがない場合は `nil`。
+
+---
+
+### `tenpai_seats(state)`
+
+現在の `RoundState` からテンパイしている座席の一覧を返します。  
+流局時のノーテン罰符計算の前に使います。
+
+**返り値：** `Array<Integer>`（例: `[0, 2]`）
+
+---
+
+### `calculate_tenpai_payments(tenpai_seats)`
+
+流局時のノーテン罰符の支払い点数を計算します。  
+テンパイ者が受け取り、ノーテン者が支払う形で返します。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `tenpai_seats` | `Array<Integer>` | テンパイしている座席番号の配列 |
+
+**返り値：** `Hash{Integer => Integer}`
+
+```ruby
+# 例: seat 0, 2 がテンパイの場合
+# => { 0 => 1500, 1 => -1500, 2 => 1500, 3 => -1500 }
+```
+
+正の値が受け取り、負の値が支払いです。
+
+---
+
+### `judge_next_game_round(progress_snapshot:, round_end_info:, rule:)`
+
+局終了後に次局へ進むかゲームを終了するかを判定します。  
+オーラス・飛び・ゲーム終了条件なども考慮されます。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `progress_snapshot` | `GameProgressSnapshot` | 局終了後の点棒・場況 |
+| `round_end_info` | `RoundEndInfo` | 局終了の詳細情報 |
+| `rule` | `RuleConfig` | ゲームルール |
+
+**返り値：** `Mahjong::Results::GameFlowResult`
+
+`GameFlowResult` の主要フィールド：
+
+| フィールド | 説明 |
+|---|---|
+| `next_round?` | 次局へ進む場合 `true` |
+| `game_end?` | ゲームを終了する場合 `true` |
+| `next_bakaze` | 次局の場風（進行する場合） |
+| `next_kyoku` | 次局の局番号 |
+| `next_honba` | 次局の本場数 |
+
+---
+
+### `calculate_ranked_results(scores:, rule:)`
+
+点棒だけからウマ・オカを含む最終順位と持ち点を計算します。  
+プレイヤー情報（名前・ID 等）が不要な場合に使います。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `scores` | `Hash{Integer => Integer}` | seat番号 → 点棒 のマップ |
+| `rule` | `RuleConfig` | ゲームルール |
+
+**返り値：** `Array<Mahjong::Results::FinalResult>`
+
+---
+
+### `calculate_final_results(final_result_snapshot:, rule:)`
+
+プレイヤー情報（名前・ID）付きの最終結果を計算します。  
+UI 表示用に情報が必要な場合はこちらを使います。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `final_result_snapshot` | `FinalResultSnapshot` | 点棒とプレイヤー情報を含むスナップショット |
+| `rule` | `RuleConfig` | ゲームルール |
+
+**返り値：** `Array<Mahjong::Results::FinalResult>`
+
+---
+
+### `evaluate_win(state:, seat:, agari_type:, agari_tile:, rule:, extra_flags:, snapshot:)`
+
+和了評価を行い、役一覧・翻数・符・点数計算結果を返します。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `state` | `RoundState` | 現在の局状態 |
+| `seat` | `Integer` | 和了者の座席番号 |
+| `agari_type` | `:tsumo \| :ron` | ツモ和了かロン和了か |
+| `agari_tile` | `Tile \| String` | 和了牌（例: `"5m"`） |
+| `rule` | `RuleConfig` | ゲームルール |
+| `extra_flags` | `Hash` | 追加フラグ（チャンカン・リンシャンなど。通常は `{}`） |
+| `snapshot` | `WinEvaluationSnapshot` | 場風・自風などの情報 |
+
+**返り値：** `[winner_info, score_result]`
+
+| 要素 | 型 | 説明 |
+|---|---|---|
+| `winner_info` | `Hash` | 役名・翻数・符を含む情報 |
+| `score_result` | `Mahjong::Scoring::ValueObjects::ScoreResult` | 点数・各プレイヤーへの支払い情報（`.payments` で取得） |
+
+---
+
+### `agari?(tiles_34)`
+
+牌の配列が和了形かどうかを判定します。  
+34形式については [概念・用語集](concepts.md#34形式tiles_34) を参照してください。
+
+**返り値：** `true | false`
+
+---
+
+### `deserialize_round_state(json)`
+
+JSON 文字列から `RoundState` を復元します。  
+Redis やメモリキャッシュに保存した state を復元するときに使います。
+
+**引数：**
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `json` | `String` | `RoundState` をシリアライズした JSON 文字列 |
+
+**返り値：** `Mahjong::State::RoundState`
+
+---
+
+## エラー
+
+```ruby
+RiichiEngine::API::InvalidActionError  # 不正なアクション
+RiichiEngine::API::EngineError         # エンジン内部エラー
+```
+
+adapter 層でこれらを rescue してください。内部エラー（`Mahjong::Errors::*`）を直接 rescue する必要はありません。

data/docs/concepts.md

@@ -0,0 +1,134 @@
+# 概念・用語集
+
+`riichi_engine` で使われる牌記法・麻雀用語・座席番号・アクション種別を解説します。
+
+---
+
+## 牌記法
+
+牌は `"数字 + スート"` の2文字の文字列で表します。
+
+### スート一覧
+
+| 記号 | 種別 | 例 |
+|---|---|---|
+| `m` | 萬子（マンズ） | `"1m"` = 一萬、`"9m"` = 九萬 |
+| `p` | 筒子（ピンズ） | `"1p"` = 一筒、`"9p"` = 九筒 |
+| `s` | 索子（ソーズ） | `"1s"` = 一索、`"9s"` = 九索 |
+| `z` | 字牌（ジハイ） | `"1z"`〜`"7z"` |
+
+### 赤ドラ
+
+数字を `0` にすると赤五（赤ドラ）を表します。
+
+```
+"0m" = 赤五萬
+"0p" = 赤五筒
+"0s" = 赤五索
+```
+
+### 字牌一覧
+
+| 記法 | 牌 | 種別 |
+|---|---|---|
+| `"1z"` | 東 | 風牌（東） |
+| `"2z"` | 南 | 風牌（南） |
+| `"3z"` | 西 | 風牌（西） |
+| `"4z"` | 北 | 風牌（北） |
+| `"5z"` | 白 | 三元牌 |
+| `"6z"` | 發 | 三元牌 |
+| `"7z"` | 中 | 三元牌 |
+
+---
+
+## 座席番号（seat）
+
+座席は `0`〜`3` の整数で表します。局の開始時に `oya_index` で指定した座席が親（東家）となり、以降は時計回りの順です。
+
+| seat | 自風 |
+|---|---|
+| `oya_index` | 東家（親） |
+| `oya_index + 1` | 南家 |
+| `oya_index + 2` | 西家 |
+| `oya_index + 3` | 北家 |
+
+座席番号は `0`〜`3` の範囲でラップします（例：oya が 3 なら南家は 0）。
+
+---
+
+## ゲーム進行の用語
+
+| 用語 | 意味 |
+|---|---|
+| `bakaze` | 場風（東場 = `"ton"`、南場 = `"nan"`） |
+| `kyoku` | 局番号（1〜4）。東1局なら `kyoku: 1` |
+| `honba` | 本場数。連荘・流局のたびに +1 |
+| `kyoutaku` | 供託棒の枚数。リーチ棒が積まれるたびに +1 |
+| `oya_index` | 現在の親の座席番号 |
+| `seed` | 牌山シード。同じ seed を渡すと再現性のある牌山になる |
+
+---
+
+## アクション種別
+
+`apply_round_action` に渡す `action` の `type` 一覧です。
+
+### 自摸・打牌
+
+| type | 意味 | 必須キー |
+|---|---|---|
+| `:tsumo` | 自摸 | なし |
+| `:dahai` | 打牌 | `seat:`, `tile:` |
+| `:riichi` | リーチ宣言（打牌を兼ねる） | `seat:`, `tile:` |
+| `:kyuushu_kyuuhai` | 九種九牌流局 | `seat:` |
+
+### 鳴き・カン
+
+| type | 意味 | 必須キー |
+|---|---|---|
+| `:pon` | ポン | `seat:`, `tiles:` |
+| `:chi` | チー | `seat:`, `tiles:` |
+| `:daiminkan` | 大明槓 | `seat:` |
+| `:ankan` | 暗槓 | `seat:`, `tile:` |
+| `:kakan` | 加槓 | `seat:`, `tile:` |
+
+### 和了・スキップ
+
+| type | 意味 | 必須キー |
+|---|---|---|
+| `:tsumo_agari` | ツモ和了 | `seat:` |
+| `:ron_agari` | ロン和了 | `seat:` |
+| `:skip` | パス（鳴き・ロン権を放棄） | `seat:` |
+
+---
+
+## 局終了の結果種別
+
+`RoundEndInfo#result_type` が取りうる値：
+
+| 値 | 意味 |
+|---|---|
+| `:ron` | ロン和了 |
+| `:tsumo` | ツモ和了 |
+| `:ryuukyoku` | 流局（荒牌） |
+| `:kyuushu` | 九種九牌 |
+| `:suufon_renda` | 四風連打 |
+| `:suucha_riichi` | 四家リーチ |
+| `:sanchahou` | 三家和 |
+| `:suukaikan` | 四槓散了 |
+
+---
+
+## 34形式（tiles_34）
+
+`agari?` メソッドで使う内部形式です。全136枚の牌を34種×4枚で表した長さ34の整数配列です。
+
+```ruby
+# 例: 一萬4枚 + 二萬1枚 の場合
+tiles_34 = [4, 1, 0, 0, 0, 0, 0, 0, 0,  # 萬子 1〜9
+            0, 0, 0, 0, 0, 0, 0, 0, 0,  # 筒子 1〜9
+            0, 0, 0, 0, 0, 0, 0, 0, 0,  # 索子 1〜9
+            0, 0, 0, 0, 0, 0, 0]        # 字牌 1z〜7z
+```
+
+通常は `RoundState` や `Hand` 経由で自動的に扱われるため、直接操作する機会は `agari?` を単体テストする場面くらいです。

data/docs/public_api_policy.md

@@ -0,0 +1,94 @@
+# 公開 API ポリシー
+
+`riichi_engine` では、安定性を保証する公開 API と、内部実装として扱う非公開 API を明確に分けています。
+
+host app が直接呼んでよい範囲を限定することで、gem 内部の自由な整理・リファクタリングを可能にします。
+
+---
+
+## 安定 API（Stable Public Surface）
+
+以下は host app が直接利用してよい、安定性を保証する API です。
+
+### エントリポイント
+
+```ruby
+RiichiEngine::API
+```
+
+局進行・和了評価・点数計算はすべてここを通してください。
+
+### 例外
+
+```ruby
+RiichiEngine::API::InvalidActionError
+RiichiEngine::API::EngineError
+```
+
+### 値オブジェクト・設定
+
+```ruby
+Mahjong::Config::RuleConfig     # ルール設定
+Mahjong::Snapshots::*           # 局情報を gem へ渡すためのスナップショット群
+Mahjong::State::RoundState      # 局状態（API の入出力として使う）
+```
+
+---
+
+## 準公開 API（Conditionally Public Domain Objects）
+
+以下は `RiichiEngine::API` の入出力として現実的に参照することがあるため、事実上 public 扱いとします。  
+ただし、`RiichiEngine::API` の結果として受け取る形でのみ使用し、直接インスタンスを生成しないでください。
+
+```ruby
+Mahjong::Tiles::Tile
+Mahjong::State::Hand
+Mahjong::Results::RoundFlowResult
+Mahjong::Results::GameFlowResult
+Mahjong::Results::FinalResult
+Mahjong::Results::RoundEndInfo
+Mahjong::Scoring::ValueObjects::ScoreResult
+```
+
+この層は大きく壊さない前提ですが、`RiichiEngine::API` ほど強い安定契約はありません。
+
+---
+
+## 内部 API（Internal Surface）
+
+以下は host app から直接参照しないでください。  
+gem の内部責務整理・namespace 再編・最適化のために予告なく変更することがあります。
+
+```ruby
+Mahjong::Flow::*                          # 局・ゲーム進行の内部処理
+Mahjong::Scoring::*                       # 役判定・点数計算の実装詳細
+Mahjong::Cpu::*                           # CPU AI の実装
+Mahjong::Errors::*                        # EngineError / InvalidActionError 以外
+```
+
+---
+
+## host app が守るべきルール
+
+1. 局進行は `RiichiEngine::API` を経由する
+2. 和了評価は `RiichiEngine::API` を経由する
+3. 順位計算は `RiichiEngine::API` を経由する
+4. スナップショット生成・永続化変換は host app の adapter が担う
+5. `Mahjong::Flow::*` や `Mahjong::Scoring::Judges::*` を service/job から直接呼ばない
+
+---
+
+## Breaking Change ポリシー
+
+### Breaking Change とみなすもの（事前告知・メジャーバージョンアップが必要）
+
+- `RiichiEngine::API` のメソッド削除
+- `RiichiEngine::API` の必須引数変更
+- `Mahjong::Snapshots::*` の必須フィールド変更
+- `Mahjong::Config::RuleConfig` の既存キーの意味変更
+
+### Breaking Change とみなさないもの
+
+- 内部 namespace の移動・名前変更
+- `Mahjong::Flow::*` / `Mahjong::Scoring::*` の整理
+- `RiichiEngine::API` を通じた結果が同じである範囲の内部最適化