# KARDS Battle System - 系统设计文档

## 🏗️ 架构概述

KARDS战斗系统采用模块化设计，专注于核心战斗机制，为AI训练提供完整的游戏环境。

## 📁 项目结构

```
kards/
├── kards_battle/              # 核心战斗系统包
│   ├── core/                  # 核心引擎和逻辑
│   │   ├── battle_engine.py   # 主战斗引擎（当前使用）
│   │   ├── enums.py          # 枚举定义
│   │   └── unit_combat_rules.py  # 战斗规则
│   ├── battlefield/           # 战场管理
│   │   └── battlefield.py     # 3线战场系统
│   ├── units/                 # 单位系统
│   │   └── unit.py           # 单位基类
│   ├── abilities/             # 能力系统
│   │   ├── abilities.py      # 能力基类
│   │   └── keywords.py       # 关键词效果
│   ├── effects/               # 效果系统
│   │   ├── effects.py        # 游戏效果
│   │   └── target_selectors.py  # 目标选择
│   └── examples/              # 示例单位
│       └── sample_units.py    # 15个示例单位
├── tests/                     # 完整测试套件
│   ├── test_comprehensive_movement.py  # 移动系统测试
│   ├── test_turn_and_resources.py     # 回合资源测试
│   ├── unit/                  # 单元测试
│   ├── integration/           # 集成测试
│   └── examples/              # 示例测试
├── demo/                      # 演示文件
│   ├── demo_new_features.py   # 最新功能演示
│   ├── main.py               # 主程序入口
│   └── DEMOS.md              # 演示说明
├── archive/                   # 已封存的旧版本
└── docs/                      # 项目文档
```

## 🎯 核心模块设计

### 1. BattleEngine（战斗引擎）

**主要职责：**
- 管理游戏状态和回合流程
- 处理单位部署、移动、攻击
- 管理Kredits资源系统
- 提供DEBUG功能

**关键API：**
```python
# 单位操作
deploy_unit_to_support(unit: Unit, player_id: int, position: Optional[int]) -> Dict
move_unit(unit_id: UUID, target_position: tuple, player_id: int) -> Dict
attack_target(attacker_id: UUID, target_id: Union[UUID, str], player_id: int) -> Dict

# 回合管理
end_turn() -> Dict

# 资源管理
get_kredits(player_id: int) -> int
spend_kredits(player_id: int, amount: int) -> bool
```

### 2. Battlefield（战场系统）

**3线布局设计：**
```
Player1_Support  [HQ] [Unit1] [Unit2] ...
Front_Line       [Unit3] [Unit4] ...        (共享前线)
Player2_Support  [HQ] [Unit5] [Unit6] ...
```

**特性：**
- 自动紧凑排列（无空隙）
- 前线控制权动态更新
- HQ作为支援线上的目标
- 每线最多5个目标

### 3. Unit（单位系统）

**组件化设计：**
```python
class Unit:
    stats: UnitStats           # 攻防血量
    keywords: Set[str]         # 关键词集合
    abilities: List[Ability]   # 能力列表
    activation_cost: int       # 激活费用
```

**单位类型：**
- INFANTRY：基础作战单位
- TANK：可同回合移动+攻击
- ARTILLERY：无视距离和守护，不受反击
- FIGHTER：无视距离，保护免受轰炸
- BOMBER：无视距离和守护，不受反击（战斗机除外）

### 4. 资源系统

**双层Kredits设计：**
```python
# Kredits Slot：指挥点容量
kredits_slot: int  # 每回合+1，上限12

# Kredits：当前可用指挥点  
kredits: int       # 每回合重置为slot值，上限24
```

## 🔄 游戏流程

### 回合系统
```
Turn 1: Phase 0 (Player0) → Phase 1 (Player1)
Turn 2: Phase 0 (Player0) → Phase 1 (Player1)
...
```

### 操作流程
```
1. 部署单位到支援线 → deploy_unit_to_support()
2. 移动单位到前线   → move_unit()
3. 攻击敌方目标     → attack_target()
4. 结束回合        → end_turn()
```

## 🎮 玩家系统

**玩家标识：**
- 内部使用整数ID：`0` (Player1), `1` (Player2)
- 显示使用名称：`"Germany"`, `"USA"`
- API统一使用整数ID，避免字符串浪费

**优势：**
- 性能更好（整数比较）
- 代码更简洁
- 减少字符串错误

## 📊 战斗规则系统

### UnitCombatRules
集中管理所有战斗规则：

```python
@staticmethod
def can_attack_target(attacker: Unit, target: Union[Unit, HQ], battlefield: Battlefield) -> bool
def can_counter_attack(defender: Unit, attacker: Unit) -> bool
```

### 攻击距离规则
- 步兵/坦克：只能攻击相邻战线
- 火炮/战斗机/轰炸机：无视攻击距离

### 特殊规则
- 火炮：无视守护，不受反击
- 轰炸机：无视守护，不受反击（战斗机除外）
- 战斗机：可保护同战线免受轰炸机攻击

## 🧪 测试架构

### 测试分层
```
pytest测试套件 (19个测试)
├── 移动系统测试 (10个)
│   ├── 成功场景测试
│   └── 失败场景测试  
└── 回合资源测试 (9个)
    ├── 资源增长测试
    └── 限制验证测试
```

### 测试原则
- 每个核心功能都有对应测试
- 覆盖成功和失败场景
- 验证边界条件和错误处理
- 使用setup_method确保测试独立

## 🔧 可扩展性设计

### 插件化架构
- **关键词系统**：新关键词可独立实现
- **能力系统**：支持部署、触发、静态等多种能力
- **效果系统**：可组合的游戏效果
- **目标选择**：灵活的目标选择逻辑

### 未来扩展方向
- AI对手实现
- 完整的卡牌系统
- 图形用户界面
- 网络对战功能
- 战斗回放系统

## 💡 设计原则

1. **单一职责**：每个模块职责明确
2. **低耦合**：模块间依赖最小化
3. **高内聚**：相关功能集中管理
4. **可测试**：所有核心逻辑都可测试
5. **可扩展**：支持新功能无痛添加

这种设计确保了系统的可维护性、可测试性和可扩展性。