henan-backend/mahjong-py

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

跑起来

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 已经支持外部传盘面，构造器接上去即可。