# Card Game Engine — 棋牌规则引擎

YAML DSL 驱动的棋牌规则引擎。一份 DSL 配置文件 = 一种玩法，
引擎加载后自动运行，不需要写玩法特定代码。

## 项目结构

```
card-game-engine/
├── docs/
│   ├── architecture-plan.md        # 架构设计文档
│   └── demo-implementation-plan.md # Demo 实施计划
├── RuleEngine/                     # C# 规则引擎核心
│   ├── Core/                       # MahjongTile 编码 / Deck 牌堆 / GameState 状态
│   ├── Patterns/                   # MeldsSolver 胡牌判断 + 番型识别
│   ├── Phase/                      # PhaseMachine 回合状态机
│   ├── Scoring/                    # ScoreEngine 计分引擎
│   ├── Dsl/                        # DslLoader YAML 加载 + CapabilityRegistry
│   └── AI/                         # RandomMahjongAI 随机AI（验证用）
├── RuleEngine.Tests/               # 单元测试 (45个)
├── dsl-examples/                   # 玩法 DSL 配置 (YAML)
│   ├── xuezhandaodi.yaml           # 四川麻将血战到底 (108张)
│   ├── guangdong_jipinghu.yaml     # 广东麻将鸡平胡 (136张 + 花牌)
│   ├── guobiao.yaml               # 国标麻将 (144张，81番种)
│   └── wuhan.yaml                 # 武汉麻将 (136张，红中癞子 + 258将)
└── Demo/                           # 控制台 Demo
```

## 核心设计

- **规则引擎 ≠ 游戏引擎**：纯逻辑库（C#），不依赖图形框架。输入状态 → 输出合法操作
- **扑克/麻将引擎分离**：各自精专，共享基础层
- **int 编码**：4 bytes/tile，性能优先
- **加载时能力检查**：DSL 声明 `requires`，引擎 CapabilityRegistry 自动验证

## 已实现能力

### 胡牌判断 (MeldsSolver)
| 能力 | 状态 | 说明 |
|------|------|------|
| 标准胡牌 (4面子+1对) | ✅ | 回溯搜索，含 wildcard 缺口填充 |
| 七对 | ✅ | 纯对子形态，wildcard 配对支持 |
| 十三幺 | ✅ | 13种幺九+1重复 |
| 全不靠 | ✅ | 14牌从16位置模板选，wildcard 补位 |
| 一色双龙会 | ✅ | 同色1-9各至少2张，wildcard 支持 |
| 鬼牌/癞子 | ✅ | 缺口填充式回溯 O(w×2^w) |
| 258将检查 | ✅ | 武汉麻将专用 |

### 番型识别 (IdentifyFans)
自动识别 16 种结构性番型：清一色、混一色、字一色、对对胡、暗七对、带幺九、混幺九、缺一门、平胡、断幺九、全大、全中、全小、大于五、小于五、全双、碰碰和

### 回合控制
| 能力 | 状态 |
|------|------|
| 摸→打→碰杠胡回合 | ✅ |
| 优先级仲裁 (胡>杠>碰>吃) | ✅ |
| 血战到底 (胡后不结束) | ✅ |
| 查叫/查花猪 | ✅ |
| 花牌 (摸到即补) | ✅ |

### DSL 热切换
4 种麻将变体 100% 覆盖率，`--dsl` 参数切换

## Demo 用法

```bash
# 交互模式（逐局展示）
dotnet run --project Demo
dotnet run --project Demo -- --dsl wuhan
dotnet run --project Demo -- --dsl guobiao
dotnet run --project Demo -- --dsl guangdong_jipinghu

# 压测模式
dotnet run --project Demo -- --auto --count 1000

# 运行测试
dotnet test                              # 全部 45 个
```

## 测试覆盖

- **45 个单元测试** 全部通过
- 覆盖：牌编码、牌库构建、标准胡牌、七对、十三幺、全不靠、一色双龙会、
  wildcard 补位、258将检查、番型识别（清一色/混一色/字一色/对对胡/
  带幺九/缺一门/平胡/断幺九/全大/全小/全双）
- 1000 局压测 0 报错

## 开源参考

- q_algorithm (C# 胡牌算法库)
- majiang_algorithm (Java 麻将引擎 + AI)
- MahjongKit (Python 牌谱分析)