1

src/engine/actions.py

@@ -1,13 +1,40 @@
 def draw_tile(state):
+    """
+    当前玩家摸牌的动作逻辑。
+
+    参数:
+    - state: ChengduMahjongState 实例，表示当前游戏状态。
+
+    返回:
+    - tile: 当前玩家摸到的牌的索引。
+
+    异常:
+    - ValueError: 如果牌堆已经空了（流局条件）。
+    """
     if state.remaining_tiles == 0:
-        raise ValueError("牌堆已空")
-    tile = state.deck.pop(0)
-    state.remaining_tiles -= 1
-    state.hands[state.current_player][tile] += 1
+        raise ValueError("牌堆已空")  # 牌堆为空时不能摸牌
+    tile = state.deck.pop(0)  # 从牌堆顶取出一张牌
+    state.remaining_tiles -= 1  # 更新牌堆剩余数量
+    state.hands[state.current_player][tile] += 1  # 将摸到的牌添加到当前玩家的手牌中
     return tile
 
+
 def discard_tile(state, tile):
+    """
+    当前玩家打出一张牌的动作逻辑。
+
+    参数:
+    - state: ChengduMahjongState 实例，表示当前游戏状态。
+    - tile: 玩家想要打出的牌的索引。
+
+    操作:
+    - 从当前玩家手牌中移除指定的牌。
+    - 将指定牌添加到当前玩家的牌河中。
+
+    异常:
+    - ValueError: 如果当前玩家的手牌中没有这张牌。
+    """
     if state.hands[state.current_player][tile] == 0:
-        raise ValueError("玩家没有这张牌")
-    state.hands[state.current_player][tile] -= 1
-    state.discards[state.current_player].append(tile)
+        raise ValueError("玩家没有这张牌")  # 防止打出不存在的牌
+    state.hands[state.current_player][tile] -= 1  # 从手牌中移除该牌
+    state.discards[state.current_player].append(tile)  # 将牌添加到牌河

src/engine/chengdu_mahjong_engine.py

@@ -1,5 +1,4 @@
 from .game_state import ChengduMahjongState
-from .utils import get_suit
 
 
 class ChengduMahjongEngine:

src/engine/game_state.py

@@ -1,3 +1,5 @@
+from utils import get_suit
+
 class ChengduMahjongState:
     def __init__(self):
         # 每个玩家的手牌
@@ -14,3 +16,34 @@ class ChengduMahjongState:
         self.remaining_tiles = 108
         # 胜利玩家列表
         self.winners = []
+
+    def set_missing_suit(player, missing_suit):
+        # 确定玩家的缺门
+        valid_suits = ["条", "筒", "万"]
+        if missing_suit not in valid_suits:
+            raise ValueError("缺门设置无效")
+        player.missing_suit = missing_suit
+
+    def can_win(hand):
+        # 判断是否满足胡牌条件（四组+一对）
+        from collections import Counter
+
+        # 判断缺一门
+        suits = [get_suit(tile) for tile, count in enumerate(hand) if count > 0]
+        if len(set(suits)) > 2:
+            return False  # 不满足缺一门
+
+        # 判断是否满足四组+一对
+        def is_valid_group(tiles):
+            # 判断是否为顺子、刻子或对子
+            return len(tiles) == 3 and (tiles[0] == tiles[1] == tiles[2] or
+                                        tiles[0] + 1 == tiles[1] and tiles[1] + 1 == tiles[2])
+
+        counter = Counter(hand)
+        pairs = [tile for tile, count in counter.items() if count >= 2]
+        for pair in pairs:
+            temp_hand = hand[:]
+            temp_hand[pair] -= 2
+            if is_valid_group(temp_hand):
+                return True
+        return False

src/engine/scoring.py

@@ -1,13 +1,21 @@
-def can_win(hand):
-    # 判断是否满足胡牌条件
-    ...
-
+# 计算番数逻辑
 def calculate_fan(hand, melds, is_self_draw, is_cleared):
+    """
+    根据胡牌手牌、碰杠、是否自摸等情况计算番数。
+    参数：
+    - hand: 当前胡牌的手牌
+    - melds: 碰杠等明牌列表
+    - is_self_draw: 是否自摸
+    - is_cleared: 是否清一色
+
+    返回：
+    - fan: 计算出的番数
+    """
     fan = 1  # 基本胡
     if is_cleared:
-        fan += 2  # 清一色
+        fan += 2  # 清一色加番
     if len(melds) >= 2:
-        fan += len(melds)
+        fan += len(melds)  # 每次碰杠额外加番
     if is_self_draw:
-        fan += 1
+        fan += 1  # 自摸加番
     return fan