py-easy-chanjet 2.0.0
一个简化畅捷通 T+ 系统 WebService SOAP API 使用的 Python 工具包，提供便捷的 API 调用和数据处理功能。
Requires Python: >=3.6

# py-easy-chanjet

一个简化畅捷通 T+ 系统 WebService SOAP API 使用的 Python 工具包，提供便捷的 API 调用和数据处理功能。

## 功能特性

- **WebService调用**：支持与畅捷通 T+ 系统的 WebService SOAP API 交互
- **同步与异步**：同时支持同步和异步操作
- **响应处理**：统一的响应处理机制，自动验证和解析响应结果
- **SQL格式化**：提供SQL语句格式化工具，方便构建查询
- **日期处理**：使用arrow库进行精确的日期计算和验证
- **类型提示**：完整的类型注解，提供良好的IDE支持

## 安装

### 使用pip安装

```bash
pip install py-easy-chanjet
```

### 从源码安装

```bash
git clone https://gitee.com/guolei19850528/py_easy_chanjet.git
cd py_easy_chanjet
pip install -e .
```

## 依赖

- httpx
- xmltodict
- arrow
- jsonschema
- jsonpath-ng

## 快速开始

### WebService使用

```python
from py_easy_chanjet.tplus.zkhb import WebService, query_actual_payment_items_sql_formatter

# 初始化WebService实例
web_service = WebService(base_url="http://your-tplus-server:port/")

# 构建SQL查询
sql = query_actual_payment_items_sql_formatter(
    columns="top 10",  # 限制返回记录数
    conditions="where cml.ActualPayMoney > 0",  # 添加查询条件
    order_by="order by cml.ChargeTime desc"  # 排序方式
)

# 调用GetDataSet方法执行查询
response = web_service.get_data_set(
    data={"sql": sql}
)

print(f"查询结果: {response.validated}")
if response.validated:
    print(f"返回数据: {response.value}")
```

### 异步WebService使用

```python
import asyncio
from py_easy_chanjet.tplus.zkhb import WebService, query_actual_payment_items_sql_formatter

async def main():
    web_service = WebService(base_url="http://your-tplus-server:port/")
    
    # 构建SQL查询
    sql = query_actual_payment_items_sql_formatter(
        columns="top 10"
    )
    
    # 异步调用GetDataSet方法
    response = await web_service.async_get_data_set(
        data={"sql": sql}
    )
    
    print(f"查询结果: {response.validated}")
    if response.validated:
        print(f"返回数据: {response.value}")

asyncio.run(main())
```

### 支付日期范围验证

```python
from py_easy_chanjet.tplus.zkhb import payment_date_range_validator

# 验证支付金额是否足够
is_valid = payment_date_range_validator(
    payment_daily_fee=100,  # 每日费用
    payment_total_amount=1000,  # 实际支付总金额
    payment_date_start="2024-01-01",  # 开始日期
    payment_date_end="2024-01-10"  # 结束日期
)

print(f"支付金额验证结果: {is_valid}")
```

## API文档

### WebService类

#### 初始化参数
- `base_url`：WebService接口的基础URL
- `client_kwargs`：传递给httpx.Client的额外参数

#### 方法
- `client(**kwargs)`：创建同步客户端实例
- `async_client(**kwargs)`：创建异步客户端实例
- `request(client=None, **kwargs)`：同步请求方法
- `async_request(client=None, **kwargs)`：异步请求方法
- `get_data_set(client=None, **kwargs)`：同步调用GetDataSet方法
- `async_get_data_set(client=None, **kwargs)`：异步调用GetDataSet方法

### 工具函数

#### query_actual_payment_items_sql_formatter

```python
def query_actual_payment_items_sql_formatter(
        columns: str = "",
        conditions: str = "",
        order_by: str = "order by cfi.ChargeFeeItemID desc"
) -> str:
    """
    格式化查询实际支付项目的SQL语句

    Args:
        columns: 额外的查询列
        conditions: 查询条件
        order_by: 排序方式

    Returns:
        str: 完整的SQL查询语句
    """
```

#### payment_date_range_validator

```python
def payment_date_range_validator(
        payment_daily_fee: Union[int, float] = 0,
        payment_total_amount: Union[int, float] = 0,
        payment_date_start: str = "",
        payment_date_start_tz: Union[str, tzinfo] = "Asia/Shanghai",
        payment_date_end: str = "",
        payment_date_end_tz: Union[str, tzinfo] = "Asia/Shanghai",
) -> bool:
    """
    验证支付金额是否足够覆盖指定日期范围内的费用

    Args:
        payment_daily_fee: 每日费用金额
        payment_total_amount: 实际支付的总金额
        payment_date_start: 开始日期字符串
        payment_date_start_tz: 开始日期的时区
        payment_date_end: 结束日期字符串
        payment_date_end_tz: 结束日期的时区

    Returns:
        bool: 如果支付金额足够返回True，否则返回False
    """
```

### 响应处理

所有API调用都会返回`RequestResponse`对象，包含以下属性：
- `validated`：响应是否有效
- `value`：从响应中提取的值
- `text`：响应的文本内容
- `json`：响应的JSON数据（解析后的XML）
- `response`：原始的httpx.Response对象

## 测试

运行测试用例：

```bash
python -m unittest test_tplus_zkhb.py
```

## 项目结构

```
py-easy-chanjet/
├── py_easy_chanjet/
│   ├── __init__.py        # 模块初始化
│   └── tplus/
│       ├── __init__.py    # T+模块初始化
│       └── zkhb.py        # 中科华博财务处理模块
├── test_tplus_zkhb.py     # 测试文件
├── setup.py               # 安装配置
├── requirements.txt       # 依赖声明
├── LICENSE                # 许可证
└── README.md              # 项目文档
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

- 作者：guolei
- 邮箱：174000902@qq.com
- 项目地址：https://gitee.com/guolei19850528/py_easy_chanjet