# Poker Hand Evaluation Program

一个用Python实现的扑克牌手牌评估程序，能够从7张牌中找出最佳的5张牌组合并返回手牌排名。

## 功能特性

- **完整的数据结构**：实现了Card、Deck、HandRanking等核心类
- **字符串解析**：支持从字符串格式解析扑克牌（如 "AsKs AhAdAc6s7s"）
- **手牌评估**：支持所有标准扑克手牌类型的识别和排名
- **最佳组合选择**：从7张牌中自动选择最佳的5张牌组合
- **全面测试**：包含完整的单元测试套件

## 支持的手牌类型

1. **皇家同花顺** (Royal Flush) - A♠K♠Q♠J♠T♠
2. **同花顺** (Straight Flush) - 连续的五张同花色牌
3. **四条** (Four of a Kind) - 四张相同点数的牌
4. **满堂红** (Full House) - 三条加一对
5. **同花** (Flush) - 五张同花色的牌
6. **顺子** (Straight) - 五张连续点数的牌（包括A-2-3-4-5轮子）
7. **三条** (Three of a Kind) - 三张相同点数的牌
8. **两对** (Two Pair) - 两个对子
9. **一对** (One Pair) - 一个对子
10. **高牌** (High Card) - 没有组合的单张高牌

## 安装和使用

### 环境要求
- Python 3.13+
- uv 包管理器

### 运行程序

```bash
# 基本用法
python main.py "AsKs AhAdAc6s7s"
# 输出: Quad(A)

# 其他示例
python main.py "AhKhQhJhTh2c3c"
# 输出: Royal Flush

python main.py "2h3h4h5h6h7s8s"
# 输出: Straight Flush(6 high)

python main.py "JsJhJdQcQs2h3d"
# 输出: Full House(J over Q)
```

### 输入格式

输入字符串应包含恰好7张牌，每张牌用2个字符表示：
- 第一个字符是点数：`2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `T`, `J`, `Q`, `K`, `A`
- 第二个字符是花色：`s`(黑桃), `h`(红桃), `d`(方块), `c`(梅花)

牌之间可以用空格分隔，也可以连续书写。

### 运行测试

```bash
# 运行自定义测试套件
python run_tests.py

# 如果安装了pytest，也可以运行：
pytest tests/ -v
```

## 项目结构

```
poker_emd_task/
├── poker/                 # 核心模块
│   ├── __init__.py       # 模块初始化
│   ├── card.py           # Card、Rank、Suit类
│   ├── deck.py           # Deck类
│   ├── hand_ranking.py   # HandRanking、HandType类
│   └── hand_evaluator.py # HandEvaluator类（核心算法）
├── tests/                # 测试文件
│   ├── test_card.py
│   ├── test_deck.py
│   ├── test_hand_ranking.py
│   ├── test_hand_evaluator.py
│   └── test_integration.py
├── main.py               # 主程序入口
├── run_tests.py          # 简化的测试运行器
├── pyproject.toml        # 项目配置
└── README.md             # 项目说明
```

## 设计特点

### 核心数据结构

- **Card类**：表示单张扑克牌，包含点数和花色
- **Rank枚举**：定义牌的点数，支持比较操作
- **Suit枚举**：定义牌的花色
- **HandType枚举**：定义所有手牌类型及其强度
- **HandRanking类**：表示手牌评估结果，包含类型和关键牌
- **Deck类**：表示一副标准52张牌
- **HandEvaluator类**：核心算法，评估手牌并选择最佳组合

### 算法实现

1. **穷举法**：从7张牌中穷举所有可能的5张牌组合（21种）
2. **模式识别**：对每个5张牌组合识别手牌类型
3. **排名比较**：选择强度最高的手牌组合
4. **特殊处理**：正确处理A-2-3-4-5轮子顺子等特殊情况

### 错误处理

- 输入验证：检查牌数是否为7张
- 格式验证：验证每张牌的格式是否正确
- 范围验证：确保点数和花色在有效范围内
- 友好错误信息：提供清晰的错误提示

## 示例用法

```python
from poker.hand_evaluator import HandEvaluator
from poker.card import Card, Rank, Suit

# 方式1：从字符串评估
ranking = HandEvaluator.evaluate_from_input("AsKs AhAdAc6s7s")
print(ranking)  # Quad(A)

# 方式2：从Card对象评估
cards = [
    Card(Rank.ACE, Suit.SPADES),
    Card(Rank.KING, Suit.SPADES),
    # ... 更多牌
]
ranking = HandEvaluator.evaluate_hand(cards)
print(ranking)
```

## 测试覆盖

项目包含全面的测试套件，覆盖：
- 所有核心类的功能测试
- 各种手牌类型的识别测试
- 边界条件和错误情况测试
- 集成测试和端到端测试

运行测试确保所有功能正常工作：

```bash
python run_tests.py
```

预期输出：
```
Running poker hand evaluation tests...

Testing Card functionality...
✓ Card tests passed
Testing hand parsing...
✓ Hand parsing tests passed
Testing hand evaluation...
✓ Hand evaluation tests passed
Testing wheel straight...
✓ Wheel straight test passed
Testing deck functionality...
✓ Deck tests passed
Testing error handling...
✓ Error handling tests passed

Test Results: 6 passed, 0 failed
All tests passed! 🎉
```

## 技术栈

- **语言**：Python 3.13
- **包管理**：uv / poetry
- **测试**：自定义测试框架（也支持pytest）
- **开发环境**：VS Code