# 开发 (Development)

## 项目概述

**Abyssal Codex** 是一款基于 Python 的 Roguelike 卡牌游戏，受《杀戮尖塔》启发，融合克苏鲁神话与深渊探索主题。

## 技术栈

| 技术 | 用途 |
|------|------|
| Python 3.10+ | 主要编程语言 |
| pytest | 单元测试框架 |
| Git | 版本控制 |
| GitHub | 代码托管 |

## 项目结构

```
Abyssal-Codex/
├── abyssal/                    # 核心游戏模块
│   ├── __init__.py
│   ├── game.py                 # 游戏主控制器
│   ├── entities/               # 游戏实体
│   │   ├── hero.py             # 英雄系统
│   │   ├── enemy.py            # 敌人系统
│   │   ├── boss.py             # Boss 系统
│   │   └── npc.py              # NPC 系统
│   ├── cards/                  # 卡牌系统
│   │   ├── card.py             # 卡牌基类
│   │   ├── attacks.py          # 攻击牌
│   │   ├── skills.py           # 技能牌
│   │   ├── powers.py           # 能力牌
│   │   └── curses.py           # 诅咒牌
│   ├── relics/                 # 遗物系统
│   │   ├── relic.py            # 遗物基类
│   │   └── relics.py           # 遗物实现
│   ├── events/                 # 事件系统
│   │   ├── event.py            # 事件基类
│   │   ├── event_runner.py     # 事件执行器
│   │   └── events.py           # 事件实现
│   ├── floors/                 # 楼层系统
│   │   ├── floor.py            # 楼层基类
│   │   └── floors.py           # 楼层实现
│   ├── dialogue/               # 对话系统
│   │   ├── engine.py           # 对话引擎
│   │   ├── node.py             # 对话节点
│   │   └── npcs.py             # NPC 实现
│   ├── endings/                # 结局系统
│   │   ├── ending.py           # 结局基类
│   │   └── endings.py          # 结局实现
│   └── utils/                  # 工具函数
│       ├── constants.py        # 游戏常量
│       └── helpers.py          # 辅助函数
├── data/                       # 游戏数据文件
│   ├── hero_data.json          # 英雄数据
│   ├── card_data.json          # 卡牌数据
│   ├── enemy_data.json         # 敌人数据
│   ├── relic_data.json         # 遗物数据
│   └── event_data.json         # 事件数据
├── saves/                      # 存档目录
├── tests/                      # 测试目录
│   ├── test_hero.py
│   ├── test_cards.py
│   ├── test_enemies.py
│   ├── test_events.py
│   ├── test_relics.py
│   ├── test_npc.py
│   └── test_endings.py
├── requirements.txt            # Python 依赖
├── README.md                   # 项目说明
└── .gitignore                  # Git 忽略文件
```

## 开发流程

### 环境搭建
```bash
# 克隆仓库
git clone https://github.com/Linrane/Abyssal-Codex.git
cd Abyssal-Codex

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/macOS

# 安装依赖
pip install -r requirements.txt
```

### 运行游戏
```bash
python -m abyssal.game
```

### 运行测试
```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_hero.py

# 带覆盖率报告
pytest --cov=abyssal tests/
```

## 代码规范

### 命名约定
- **类名**：PascalCase（如 `Hero`, `CardBase`, `EventRunner`）
- **函数/方法**：snake_case（如 `get_health`, `apply_effect`, `trigger_event`）
- **常量**：UPPER_SNAKE_CASE（如 `MAX_HP`, `DEFAULT_ENERGY`）
- **私有方法**：前缀下划线（如 `_internal_logic`）

### 文档字符串
所有公共类和方法必须包含 docstring：
```python
class Hero:
    """英雄基类，定义英雄的核心属性和行为。

    Attributes:
        name (str): 英雄名称
        current_hp (int): 当前生命值
        max_hp (int): 最大生命值
        energy (int): 当前能量
    """

    def take_damage(self, amount: int) -> None:
        """受到伤害。

        Args:
            amount: 伤害数值
        """
```

### 类型注解
所有函数和方法使用类型注解：
```python
def calculate_damage(base: int, strength: int, vulnerable: bool) -> int:
    pass
```

## 贡献指南

### 提交规范
- **feat**: 新功能
- **fix**: 修复 bug
- **docs**: 文档更新
- **refactor**: 代码重构
- **test**: 测试相关
- **chore**: 其他维护

示例：`feat: 添加 NPC 对话引擎`

### Pull Request 流程
1. Fork 仓库
2. 创建功能分支
3. 编写代码和测试
4. 确保所有测试通过
5. 提交 Pull Request

## 版本发布流程

1. 更新版本号
2. 运行完整测试套件
3. 更新 CHANGELOG
4. 创建 annotated tag
5. 推送到 GitHub
6. 更新 Wiki

## 已知问题

### 当前版本 (v0.9.0)
- 暂无已知严重问题

### 计划改进
- 游戏 UI 完善
- 存档系统增强
- 多人模式探索
- Steam Deck 适配

## 联系方式

- **GitHub**: [https://github.com/Linrane/Abyssal-Codex](https://github.com/Linrane/Abyssal-Codex)
- **Issues**: [https://github.com/Linrane/Abyssal-Codex/issues](https://github.com/Linrane/Abyssal-Codex/issues)
- **Wiki**: [https://github.com/Linrane/Abyssal-Codex/wiki](https://github.com/Linrane/Abyssal-Codex/wiki)