Metadata-Version: 2.1
Name: xzstudio-code
Version: 1.0.1
Summary: XZStudio校验码发送工具库 - 支持GUI界面与批量操作
Home-page: https://github.com/xzteam/xzstudio
Author: XZ Team
Author-email: XZ Team <xzteam@example.com>
License: MIT
Project-URL: Homepage, https://github.com/xzteam/xzstudio
Project-URL: Documentation, https://github.com/xzteam/xzstudio#readme
Project-URL: Repository, https://github.com/xzteam/xzstudio
Project-URL: Issues, https://github.com/xzteam/xzstudio/issues
Keywords: verification-code,api-client,gui,batch-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: openpyxl>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: build>=0.7.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# XZStudio - 综合调用平台

> **相关内容含AI生成**
> **相关第三方库系XZ团队内部开发，不建议外部人员使用**

## 简介

XZStudio 是一个功能完善的API综合调用平台，支持通过API发送校验码，并提供直观的GUI界面和批量操作功能。支持自定义Payload模板和密文配置。

## 特性

- **双模式操作**：支持单用户发送和批量发送两种模式
- **校验码类型**：支持临时校验码（需指定有效期）和永久校验码
- **GUI界面**：基于tkinter的直观图形界面，无需额外依赖
- **批量处理**：支持Excel文件导入导出，一键批量发送
- **自定义模板**：支持自定义Payload参数，可保存为模板重复使用
- **密文支持**：支持XZKey_格式的密文配置，保护敏感信息
- **错误处理**：完善的异常处理机制和用户反馈
- **配置持久化**：API Token等配置自动保存

## 安装

```bash
pip install xzstudio-code
```

或从源码安装：

```bash
# 克隆项目
git clone <repository-url>
cd xzstudio-code

# 安装依赖
pip install -e .
```

## 快速开始

### 命令行启动GUI

```bash
xzstudio-code
```

### 代码中使用

```python
from xzstudio import APIClient

# 创建客户端（需配置API Token和URL）
client = APIClient(api_token="your_api_token")

# 发送临时校验码
result = client.send_verification_code(
    username="张三",
    code_type="temp",
    email="zhangsan@example.com",
    date="2026-12-31"
)

# 发送永久校验码
result = client.send_verification_code(
    username="李四",
    code_type="permanent",
    email="lisi@example.com"
)

print(result)
```

### 使用密文配置

```python
from xzstudio import APIClient, EncryptionManager

# 创建密文（工具函数）
plain_url = "https://example.com/api"
cipher_url = EncryptionManager.create_xz_key(plain_url)
print(f"密文: {cipher_url}")

# 使用密文配置（系统会自动解密）
client = APIClient()
client.api_url = "XZKey_..."  # 直接使用密文
```

### 自定义Payload参数

```python
from xzstudio import APIClient

client = APIClient(api_token="your_token")

# 发送时添加自定义参数
result = client.send_verification_code(
    username="张三",
    code_type="temp",
    email="zhangsan@example.com",
    date="2026-12-31",
    extra_params={
        "custom_field1": "value1",
        "custom_field2": 123
    }
)
```

### 使用模板管理

```python
from xzstudio import APIClient, Config

config = Config()

# 保存模板
config.add_payload_template("默认模板", {
    "username": "默认用户",
    "code_type": "temp",
    "email": "default@example.com",
    "date": "2026-12-31",
    "custom_field": "default_value"
})

# 使用模板发送
client = APIClient(api_token="your_token", config=config)
result = client.send_with_template("默认模板", {
    "username": "张三",  # 覆盖模板中的用户名
    "email": "zhangsan@example.com"  # 覆盖模板中的邮箱
})
```

## GUI使用说明

### 1. 设置页面（首次使用必填）

- **API Token**：填写您的API认证Token
- **API URL**：填写API服务地址
  - 支持明文：`https://example.com/api`
  - 支持密文：`XZKey_base64编码内容`
- **超时时间**：设置请求超时秒数（默认30秒）

### 2. 单用户发送

填写以下信息：
- 用户名
- 校验码类型（临时/永久）
- 邮箱
- 有效期（仅临时校验码需要）
- 自定义参数（可选，JSON格式）

点击"发送校验码"即可发送

### 3. 批量发送

**Excel模板格式：**

| 用户名 | 类型 | 邮箱 | 日期 |
|--------|------|------|------|
| 张三 | temp | zhangsan@example.com | 2026-12-31 |
| 李四 | permanent | lisi@example.com | |
| 王五 | temp | wangwu@example.com | 2026-06-30 |

**操作流程：**
1. 点击"生成模板文件"获取Excel模板
2. 填写用户信息后点击"导入Excel文件"
3. 预览数据确认无误后点击"批量发送校验码"
4. 完成后点击"导出结果"查看发送状态和校验码

### 4. 模板管理

支持以下操作：
- **新建模板**：创建自定义Payload模板
- **编辑模板**：修改已有模板
- **删除模板**：删除不需要的模板
- **导入模板**：从JSON文件导入模板
- **导出模板**：导出模板为JSON文件

## 密文配置说明

XZStudio支持`XZKey_`格式的密文配置，用于保护API Token和URL等敏感信息。

### 加密工具使用

```python
from xzstudio import EncryptionManager

# 加密
cipher = EncryptionManager.create_xz_key("your_sensitive_data")
print(f"密文: {cipher}")

# 解密
plain = EncryptionManager.parse_xz_key(cipher)
print(f"明文: {plain}")
```

### 在配置文件中使用

配置文件`~/.xzstudio/config.json`中可以直接保存密文：

```json
{
  "api_token": "XZKey_YWRtaW4tdG9rZW4=",  
  "api_url": "XZKey_aHR0cHM6Ly9leGFtcGxlLmNvbS9hcGk="
}
```

系统会自动识别并解密`XZKey_`开头的配置。

## API参考

### APIClient类

| 方法 | 说明 | 参数 |
|------|------|------|
| `send_verification_code()` | 发送校验码 | username, code_type, email, date(可选), extra_params(可选) |
| `send_with_template()` | 使用模板发送 | template_name, params |
| `test_connection()` | 测试API连接 | 无 |
| `add_extra_param()` | 添加额外参数 | key, value |

### EncryptionManager类

| 方法 | 说明 | 参数 |
|------|------|------|
| `create_xz_key()` | 创建密文 | plain_text |
| `parse_xz_key()` | 解析密文 | cipher_text |
| `is_xz_key()` | 判断是否为密文 | value |

### Config类

| 方法 | 说明 |
|------|------|
| `add_payload_template()` | 添加Payload模板 |
| `remove_payload_template()` | 删除Payload模板 |
| `payload_templates` | 获取所有模板 |

## 异常处理

```python
from xzstudio import APIClient
from xzstudio.exceptions import (
    AuthenticationError,
    NetworkError,
    APIError,
    ValidationError
)

client = APIClient(api_token="your_api_token")

try:
    result = client.send_verification_code(
        username="张三",
        code_type="temp",
        email="invalid-email"
    )
except ValidationError as e:
    print(f"参数错误: {e.message}")
except AuthenticationError as e:
    print(f"认证失败: {e.message}")
except NetworkError as e:
    print(f"网络错误: {e.message}")
except APIError as e:
    print(f"API错误: {e.message}")
```

## 依赖

- Python >= 3.7
- requests >= 2.25.0
- openpyxl >= 3.0.0

## 注意事项

1. **API配置**：首次使用必须配置API Token和URL，无默认配置
2. **密文使用**：敏感信息建议使用XZKey_格式的密文
3. **数据安全**：Excel文件可能包含敏感用户信息，请妥善保管
4. **版本要求**：Python版本需>=3.7

## 许可证

MIT License

## 联系方式

- 邮箱：frasht@qq.com

---

**XZStudio 综合调用平台 v1.0.1**  
**最后更新：2026年4月**
