first commi

checker/README.md

@@ -0,0 +1,161 @@
+# Checker - Credit Card Validation Tool
+
+一个功能强大的信用卡检测工具，支持 Stripe 支付网关验证。
+
+## ✨ 特性
+
+- 🚀 **多线程检测** - 支持并发检测，提高效率
+- 🔄 **代理支持** - 支持代理轮换，避免IP限制
+- 📱 **Telegram通知** - 实时推送检测结果
+- 🎨 **美观界面** - 彩色终端输出，清晰易读
+- 🔍 **BIN查询** - 自动查询卡片BIN信息
+- 📦 **模块化设计** - 清晰的代码结构，易于维护和扩展
+
+## 📦 安装
+
+### 使用 uv（推荐）
+
+```bash
+# 克隆仓库
+git clone https://github.com/yourusername/checker.git
+cd checker
+
+# 安装依赖
+uv pip install -e .
+
+# 或安装开发依赖
+uv pip install -e ".[dev]"
+```
+
+### 使用 pip
+
+```bash
+pip install -e .
+```
+
+## 🚀 使用
+
+### 命令行使用
+
+```bash
+# 直接运行
+checker
+
+# 或使用 Python 模块方式
+python -m checker
+```
+
+### 配置文件
+
+复制 `.env.example` 为 `.env` 并配置：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env` 文件：
+
+```env
+# Telegram 通知（可选）
+TELEGRAM_TOKEN=your_bot_token
+TELEGRAM_CHAT_ID=your_chat_id
+
+# 线程配置
+MAX_THREADS=3
+DEFAULT_THREADS=1
+
+# 超时配置
+TIMEOUT=15
+```
+
+### 作为库使用
+
+```python
+from checker import Card, StripeChecker
+import requests
+
+# 创建检测器
+checker = StripeChecker(
+    timeout=15,
+    max_retries=5,
+    telegram_token="your_token",  # 可选
+    telegram_chat_id="your_chat_id"  # 可选
+)
+
+# 解析卡片
+card = Card.parse("4111111111111111|12|2025|123")
+
+# 执行检测
+session = requests.Session()
+result = checker.check(card, session)
+
+print(f"状态: {result.status}")
+print(f"消息: {result.message}")
+print(f"BIN信息: {result.bin_info}")
+```
+
+## 📂 项目结构
+
+```
+checker/
+├── src/checker/          # 源代码
+│   ├── cli/             # 命令行界面
+│   ├── core/            # 核心配置
+│   ├── models/          # 数据模型
+│   ├── cards/           # 卡片处理
+│   ├── checkers/        # 检测器实现
+│   ├── integrations/    # 外部服务集成
+│   └── utils/           # 工具函数
+├── tests/               # 测试文件
+├── data/                # 数据文件
+├── scripts/             # 辅助脚本
+└── pyproject.toml       # 项目配置
+```
+
+## 🧪 测试
+
+```bash
+# 运行所有测试
+pytest
+
+# 运行测试并显示覆盖率
+pytest --cov=checker
+
+# 运行特定测试
+pytest tests/test_cards/test_parser.py
+```
+
+## 🛠️ 开发
+
+### 代码格式化
+
+```bash
+# 使用 black 格式化代码
+black src/checker tests
+
+# 使用 ruff 检查代码
+ruff check src/checker tests
+```
+
+### 类型检查
+
+```bash
+mypy src/checker
+```
+
+## 📝 许可证
+
+MIT License
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## ⚠️ 免责声明
+
+本工具仅供学习和研究使用，请勿用于非法用途。使用本工具产生的一切后果由使用者自行承担。
+
+## 📞 联系方式
+
+- GitHub: [github.com/KianSantang777](https://github.com/KianSantang777)
+- Telegram: [t.me/xqndrs](https://t.me/xqndrs)