# mahjong-py · 麻将胡了（回合池生成器）

规则唯一事实来源是 `docs/麻将胡了设计方案.md`；本目录是它的 Python 实现（母本风格照 `D:\changzhou_app\changzhou_backend\olympus-py`，但**引擎是重写的**：麻将从盘面自己判定，母本只记账）。

## 现在有什么 / 还没有什么

| 状态 | 内容 |
|---|---|
| ✅ 已实现 | `mahjong/config.py`（规则参数唯一来源）、`models.py`、`engine.py`（前缀链 / 金色就地转百搭 / 列内重力+补位 / 阶梯 / FS / 500x 封顶）、`tests/test_engine.py`（11 项）、`mahjong_simulator.py`（自然盘面仿真） |
| ⛔ 还没有 | `generate_rounds.py`（按桶配额主动摆盘面 + bias 反解 + 落库）、`_recalc_boxes.py`（配比）、`schema.sql`、`mahjong_db.py`、`_make_templates.py`、`simulate_cycle.py`、`_regen.py` |

## 跑起来

```bash
cd mahjong-py
set PYTHONIOENCODING=utf-8          # Windows：中文输出
python tests/test_engine.py          # 11 项规则单测（无需 pytest）
python mahjong_simulator.py --rounds 200000 --seed 2026   # 自然盘面仿真（不含偏置构造）
```

## 引擎的 6 条铁律（写代码时别绕开）

1. **前缀链**：从第 1 轴起 1→2→3→4→5 连续，断链整笔作废；`ways` 只乘链内轴。
2. **金色格只当它自己的自然符号**（不做别的符号的替代）；"顶替别人"只有 `W` 会做。
3. **金色中奖格就地变 `W`**：不清空、不补牌；几个金格中奖就留几个 `W`（无上限）。金色只镀在第 2/3/4 轴的普通符号上 ⇒ **`W` 永远不落在第 1/5 轴**。
4. **`W` 要满足消除链才被消除**；没参与成奖就留到下一波。同一个 `W` 可以同时被多个符号借用。
5. **金色标记跟着符号下落**（不是跟着格号）——否则会"传染"给新补的牌。
6. **阶梯每旋重置**：基础 `1/2/3/5`、FS `2/4/6/10`；**一屏最多 5 个胡**；FS 上限 36 旋且"发不满就不发"。

## 与设计文档的已知偏差（文档已同步勘误）

- §15 第 4 波原本只算两笔奖，漏了"同一个 `W` 也能当白板"→ 白板 3 连。修正后本波 ¥1200、本旋总账 **¥2380**（原 ¥2180）。
- §3.9 是新加的空转率结论（65%），依据就是本目录 20 万局的自然仿真数据。

## ponytail 备注

- 生成端（配额/偏置）**故意还没写**：它的形状取决于 §3.9 的空转率口径与桶配比，先把引擎钉死再往上堆，避免拿未验证的数学去凑池子。
- 仿真只做自然盘面，没有引入任何"目标倍率反解"；`play_spin` 已经支持外部传盘面，构造器接上去即可。