CombinationComparator

牌型比较器接口与默认实现。

概述

CombinationComparator 位于 src/combination/CombinationComparator.ts，负责比较两个 CardCombination 的大小关系。该模块只覆盖通用比较语义：

• 牌型不同或卡牌数量不同 → INCOMPARABLE
• 否则取 value ?? rank ?? 0 作为比较值，按数值大小返回 LESS / EQUAL / GREATER

复杂场景（如炸弹压制、特殊牌型链）应在游戏层自行实现 CombinationComparator 接口。

CompareResult 枚举

两个 CardCombination 的比较结果。

enum CompareResult {
  LESS = -1,
  EQUAL = 0,
  GREATER = 1,
  INCOMPARABLE = -2
}

成员	值	说明
LESS	-1	A 小于 B
EQUAL	0	A 与 B 等价
GREATER	1	A 大于 B
INCOMPARABLE	-2	A 与 B 不可比较（不同牌型或不同张数），调用方不应将其当作普通大小关系处理

CombinationComparator 接口

牌型比较器接口。自定义游戏可注入自定义实现以承载特殊比较规则。

interface CombinationComparator {
  compare(a: CardCombination, b: CardCombination): CompareResult
}

compare()

比较两个牌型组合的大小。

compare(a: CardCombination, b: CardCombination): CompareResult

参数

参数	类型	必填	默认值	说明
a	CardCombination	是	—	牌型组合 A
b	CardCombination	是	—	牌型组合 B

返回值

CompareResult：比较结果，参见上表。

DefaultCombinationComparator

默认牌型比较器，实现了 CombinationComparator 接口。

比较规则

1. 若 a.type !== b.type，返回 INCOMPARABLE。
2. 若 a.cards.length !== b.cards.length，返回 INCOMPARABLE。
3. 取 av = a.value ?? a.rank ?? 0 与 bv = b.value ?? b.rank ?? 0：
   • av < bv → LESS
   • av > bv → GREATER
   • 否则 → EQUAL

class DefaultCombinationComparator implements CombinationComparator {
  compare(a: CardCombination, b: CardCombination): CompareResult
}

示例

import { DefaultCombinationComparator, CompareResult } from '../combination/CombinationComparator.js'
import type { CardCombination } from '../combination/CardCombination.js'
import { CombinationType } from '../combination/CombinationType.js'

const cmp = new DefaultCombinationComparator()

const pairOf5: CardCombination = {
  type: CombinationType.PAIR,
  cards: [{ id: 'a' }, { id: 'b' }] as never,
  rank: 5,
  value: 5
}
const pairOf8: CardCombination = {
  type: CombinationType.PAIR,
  cards: [{ id: 'c' }, { id: 'd' }] as never,
  rank: 8,
  value: 8
}

cmp.compare(pairOf5, pairOf8)   // -> CompareResult.LESS
cmp.compare(pairOf8, pairOf5)   // -> CompareResult.GREATER
cmp.compare(pairOf5, pairOf5)   // -> CompareResult.EQUAL

const single: CardCombination = {
  type: CombinationType.SINGLE,
  cards: [{ id: 'e' }] as never,
  rank: 9,
  value: 9
}
cmp.compare(pairOf5, single)    // -> CompareResult.INCOMPARABLE (类型不同)

注意事项

• 该实现仅按数值大小比较，不感知任何游戏专属规则；如需炸弹压制、特殊牌型链等逻辑，请在游戏层实现自定义 CombinationComparator。
• INCOMPARABLE 不应被当作普通大小关系处理（其值为 -2，小于 LESS 的 -1，但语义上意味着"无法比较"）。
• 当 value 与 rank 都缺省时，比较值回退为 0，此时两个同类型同张数的组合将被视为 EQUAL。