py-chanjet-toolkit 1.0.0__py3-none-any.whl

py_chajet_toolkit/__init__.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_chajet 包入口模块
+
+该包是畅捷通 T+ 系列产品的 Python 客户端库，提供与畅捷通 T+ 系统的 API 交互能力。
+
+包结构：
+- py_chajet/
+  - tplus/           # T+ 系列产品模块
+    - zkhb/         # 智慧社区业务模块
+      - __init__.py # 智慧社区服务客户端类
+      - utils.py    # 工具函数集合
+
+主要功能：
+- 提供畅捷通 T+ 智慧社区 WebService 接口的同步和异步调用
+- 封装 SOAP 请求的构建和响应解析
+- 提供数据校验、日期处理、SQL 生成等辅助工具函数
+
+使用示例：
+    from py_chajet.tplus.zkhb import ForcelandEstateService
+    
+    service = ForcelandEstateService(base_url="http://your-server/estate")
+    response = service.get_data_set()
+    data = convert_to_get_data_set_results(response)
+"""

py_chajet_toolkit/tplus/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_chajet.tplus 模块
+
+该模块包含畅捷通 T+ 系列产品的客户端实现，目前主要包含智慧社区（zkhb）业务模块。
+
+子模块：
+- zkhb: 智慧社区业务模块，提供与智慧社区系统的 WebService 接口交互能力
+
+未来扩展计划：
+- 添加更多 T+ 产品线的客户端支持
+- 提供统一的 API 调用接口
+- 增加数据模型和类型定义
+"""

py_chajet_toolkit/tplus/zkhb/__init__.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from typing import Optional
+
+import httpx
+from py_httpx_toolkit import Httpx
+
+
+class ForcelandEstateService(Httpx):
+    """
+    畅捷通T+智慧社区服务客户端
+
+    该类封装了与畅捷通T+智慧社区系统的WebService接口交互，提供同步和异步两种调用方式。
+    通过SOAP协议与服务端通信，主要用于获取数据集信息。
+
+    核心功能：
+    - 支持同步和异步HTTP客户端
+    - 封装GetDataSet接口调用
+    - 自动处理请求头和参数配置
+    - 支持自定义客户端配置
+
+    典型应用场景：
+    - 查询物业收费数据
+    - 获取小区信息
+    - 查询房间详情
+    - 获取收费项目列表
+
+    Attributes:
+        base_url: 服务端基础URL
+        client_kwargs: HTTP客户端配置参数
+    """
+
+    def __init__(
+            self,
+            base_url: Optional[str] = None,
+            client_kwargs: Optional[dict] = None,
+    ):
+        """
+        初始化智慧社区服务客户端
+
+        Args:
+            base_url: WebService服务基础URL，如 "http://example.com/estate"
+            client_kwargs: 额外的HTTP客户端配置参数，如headers、timeout等
+
+        Note:
+            - base_url末尾的斜杠会被自动去除
+            - 默认超时时间为60秒
+            - 默认关闭SSL证书验证
+        """
+        # 处理base_url，去除末尾斜杠（如果存在）
+        self.base_url = base_url or ""
+        self.base_url = self.base_url[:-1] if self.base_url.endswith("/") else self.base_url
+
+        # 合并默认配置与用户配置
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            "base_url": self.base_url,
+            "timeout": 60,  # 默认超时时间60秒
+            "verify": False,  # 默认关闭SSL验证（适用于内部服务）
+            **self.client_kwargs,
+        }
+
+    def get_data_set(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ):
+        """
+        同步调用GetDataSet接口
+
+        通过SOAP协议请求智慧社区服务端的GetDataSet方法，获取数据集信息。
+
+        Args:
+            client: 可选的HTTP客户端实例，如果提供则使用该客户端；否则创建新客户端
+            client_kwargs: 可选的HTTP客户端配置参数，如headers、timeout等
+            **kwargs: 额外的请求参数，会覆盖默认配置
+
+        Returns:
+            httpx.Response: HTTP响应对象，包含XML格式的SOAP响应
+
+        Note:
+            - 默认Content-Type为text/xml; charset=utf-8
+            - 默认请求路径为 /estate/webService/ForcelandEstateService.asmx
+            - 默认HTTP方法为POST
+        """
+        # 合并默认参数与用户参数，用户参数优先级更高
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+        kwargs = {
+            "url": "/estate/webService/ForcelandEstateService.asmx",  # WebService接口路径
+            "method": "POST",  # SOAP请求使用POST方法
+            "params": {
+                "op": "GetDataSet",  # 操作名称
+            },
+            "headers": {
+                "Content-Type": "text/xml; charset=utf-8",  # SOAP请求必须的Content-Type
+            },
+            **kwargs,
+        }
+
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_get_data_set(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ):
+        """
+        异步调用GetDataSet接口
+
+        通过SOAP协议异步请求智慧社区服务端的GetDataSet方法，获取数据集信息。
+
+        Args:
+            client: 可选的异步HTTP客户端实例，如果提供则使用该客户端；否则创建新客户端
+            client_kwargs: 可选的异步HTTP客户端配置参数，如headers、timeout等
+            **kwargs: 额外的请求参数，会覆盖默认配置
+
+        Returns:
+            httpx.Response: HTTP响应对象，包含XML格式的SOAP响应
+
+        Note:
+            - 默认Content-Type为text/xml; charset=utf-8
+            - 默认请求路径为 /estate/webService/ForcelandEstateService.asmx
+            - 默认HTTP方法为POST
+        """
+        # 合并默认参数与用户参数，用户参数优先级更高
+        client = client or None
+        client_kwargs = client_kwargs or {}
+        kwargs = kwargs or {}
+        kwargs = {
+            "url": "/estate/webService/ForcelandEstateService.asmx",  # WebService接口路径
+            "method": "POST",  # SOAP请求使用POST方法
+            "params": {
+                "op": "GetDataSet",  # 操作名称
+            },
+            "headers": {
+                "Content-Type": "text/xml; charset=utf-8",  # SOAP请求必须的Content-Type
+            },
+            **kwargs,
+        }
+
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)

py_chajet_toolkit/tplus/zkhb/responses.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from datetime import datetime
+
+from pydantic import BaseModel, Field, AwareDatetime
+
+
+class ActualPaymentItem(BaseModel):
+    ChargeMListID: int = Field(..., title="收费项目列表ID", description="收费项目列表ID")
+    ChargeMListNo: str = Field(..., title="收费项目列表编号", description="收费项目列表编号")
+    ChargeTime: datetime = Field(..., title="收费时间", description="收费时间")
+    PayerName: str = Field(..., title="缴费人姓名", description="缴费人姓名")
+    ChargePersonName: str = Field(..., title="收费人姓名", description="收费人姓名")
+    ActualPayMoney: float = Field(..., title="实际支付金额", description="实际支付金额")
+    ActualAmount: float = Field(..., title="实际支付金额", description="实际支付金额")
+    EstateID: int = Field(..., title="小区ID", description="小区ID")
+    EstateName: str = Field(..., title="小区名称", description="小区名称")
+    ItemName: str = Field(..., title="收费项目名称", description="收费项目名称")
+    ItemNames: str = Field(..., title="收费项目名称列表", description="收费项目名称列表")
+    ChargeFeeItemID: int = Field(..., title="收费项目ID", description="收费项目ID")
+    SDate: AwareDatetime = Field(..., title="开始日期", description="开始日期")
+    EDate: AwareDatetime = Field(..., title="结束日期", description="结束日期")
+    RmId: int = Field(..., title="房间ID", description="房间ID")
+    RmNo: str = Field(..., title="房间编号", description="房间编号")
+    IsPayFull: bool = Field(..., title="是否全付", description="是否全付")
+    PayDays: int = Field(..., title="支付天数", description="支付天数")
+    CreateTime: AwareDatetime = Field(..., title="开始日期", description="开始日期")
+    LastUpdateTime: AwareDatetime = Field(..., title="结束日期", description="结束日期")
+
+    model_config = {
+        "extra": "allow"  # 允许额外动态字段，适配 API 响应的灵活性
+    }

py_chajet_toolkit/tplus/zkhb/utils.py

@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from collections import Counter, defaultdict
+from datetime import tzinfo
+from typing import Any, Optional, Union
+
+import arrow
+import httpx
+from jsonpath_ng import parse
+from jsonschema.validators import Draft202012Validator
+import xmltodict
+
+
+def json_find_first(expression: str, data: Any) -> Any:
+    """
+    使用 JSONPath 表达式从嵌套的 JSON 数据中查找第一个匹配项
+
+    JSONPath 是一种用于查询 JSON 结构的表达式语言，类似于 XPath 之于 XML。
+    该函数通过解析表达式并在数据中执行查询，返回第一个匹配的值。
+
+    典型应用场景：
+    - 从复杂的 API 响应中提取特定字段
+    - 在嵌套结构中快速定位目标数据
+    - 动态提取不确定位置的数据
+
+    Args:
+        expression: JSONPath 表达式字符串，用于指定数据查询路径
+                    示例表达式：
+                    - "$.name" - 获取根节点下的 name 字段
+                    - "$.users[0].id" - 获取 users 数组第一个元素的 id
+                    - "$..id" - 获取所有层级下的 id 字段
+        data: 待查询的 JSON 数据，可以是字典、列表或任意嵌套结构
+
+    Returns:
+        Any: 第一个匹配到的值，如果表达式无效或没有找到匹配项则返回 None
+
+    Examples:
+        >>> data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+        >>> json_find_first("$.users[0].name", data)
+        'Alice'
+        >>> json_find_first("$..id", data)
+        1
+    """
+    # 使用 jsonpath_ng 库解析表达式并执行查询
+    # parse() 将表达式字符串转换为可执行的 JSONPath 对象
+    # find() 在数据中查找所有匹配项，返回 Match 对象列表
+    # 列表推导式提取每个匹配项的 value 属性
+    results = [i.value for i in parse(expression).find(data)]
+
+    # 检查查询结果是否为非空列表
+    # 如果有匹配项，返回第一个；否则返回 None
+    if isinstance(results, list) and len(results) > 0:
+        return results[0]
+    return None
+
+
+def json_is_valid(schema: Optional[dict], data: Any) -> bool:
+    """
+    校验 JSON 数据是否符合指定的 JSON Schema 规范
+
+    使用 JSON Schema Draft 2020-12 版本进行校验，确保数据结构和类型符合预期。
+    该函数常用于 API 响应数据的完整性校验，防止因数据格式异常导致的程序错误。
+
+    典型应用场景：
+    - 验证登录响应是否包含必要的用户信息字段
+    - 校验 API 返回的数据结构是否符合预期
+    - 在数据处理前进行格式检查，提高代码健壮性
+
+    Args:
+        schema: JSON Schema 字典，定义了数据应遵循的结构规范
+                Schema 应符合 JSON Schema Draft 2020-12 规范
+                可以包含 type、properties、required、minLength 等关键字
+        data: 待校验的 JSON 数据，可以是任意类型
+
+    Returns:
+        bool: 校验结果，True 表示数据符合 Schema，False 表示不符合
+
+    Examples:
+        >>> schema = {
+        ...     "type": "object",
+        ...     "properties": {"id": {"type": "string"}},
+        ...     "required": ["id"]
+        ... }
+        >>> json_is_valid(schema, {"id": "123"})
+        True
+        >>> json_is_valid(schema, {"name": "Alice"})
+        False
+    """
+    # 使用 Draft202012Validator 创建校验器实例
+    # is_valid() 方法执行完整校验并返回布尔结果
+    return Draft202012Validator(schema).is_valid(data)
+
+
+def build_get_data_set_post_xml(data: Optional[dict] = None) -> str:
+    """
+    将请求数据转换为 SOAP GetDataSet 接口所需的 XML 格式
+
+    该函数用于构建符合畅捷通 T+ 智慧社区 WebService 规范的 SOAP 请求体。
+    将用户提供的查询参数（如 sql、url）封装到标准的 SOAP Envelope 结构中。
+
+    Args:
+        data: 可选的请求参数字典，可包含 sql、url 等字段
+
+    Returns:
+        str: 完整的 SOAP XML 请求体字符串
+
+    Note:
+        - 默认添加 sql 和 url 字段，值为空字符串
+        - 用户传入的数据会覆盖默认值
+        - 返回的 XML 包含标准的 SOAP 命名空间声明
+
+    Examples:
+        >>> build_get_data_set_post_data({"sql": "SELECT * FROM EstateDetail"})
+        '<?xml version="1.0" encoding="utf-8"?><soap:Envelope ...><GetDataSet><sql>SELECT * FROM EstateDetail</sql><url/></GetDataSet></soap:Envelope>'
+    """
+    # 处理默认参数，确保 data 不为 None
+    data = data or {}
+
+    # 合并默认字段与用户字段，用户字段优先级更高
+    data = {
+        "sql": "",  # 默认空SQL语句
+        "url": "",  # 默认空URL
+        **data,  # 用户传入的数据覆盖默认值
+    }
+
+    # 使用 xmltodict 将字典转换为 XML 字符串
+    return xmltodict.unparse(
+        {
+            "soap:Envelope": {
+                # SOAP 标准命名空间声明
+                "@xmlns:soap": "http://schemas.xmlsoap.org/soap/envelope/",
+                # XML Schema 实例命名空间
+                "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
+                # XML Schema 命名空间
+                "@xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
+                "soap:Body": {
+                    "GetDataSet": {
+                        # 畅捷通智慧社区 WebService 命名空间
+                        "@xmlns": "http://zkhb.com.cn/",
+                        **data,  # 展开用户提供的请求数据
+                    }
+                },
+            }
+        }
+    )
+
+
+def build_get_data_set_results(response: Optional[Any] = None) -> list:
+    """
+    从 GetDataSet 接口响应中提取实际数据列表
+
+    该函数用于解析畅捷通 T+ 智慧社区 API 返回的 SOAP 响应，提取嵌套在复杂 XML 结构中的实际业务数据。
+    支持直接传入 httpx.Response 对象或已解析的 XML 字典。
+
+    数据提取路径说明：
+    SOAP响应 -> Envelope -> Body -> GetDataSetResponse -> GetDataSetResult -> diffgram -> NewDataSet -> Table
+
+    Args:
+        response: 从畅捷通 tplus API 返回的响应数据
+                  可以是 httpx.Response 对象，也可以是已解析的 XML 字典
+
+    Returns:
+        list: 包含实际业务数据的列表，每个元素是一个字典
+
+    Note:
+        - 如果提取结果是单个字典（单行数据），自动包装为列表
+        - 如果未找到匹配数据，返回空列表
+
+    Examples:
+        >>> # 假设 response 是包含单行数据的响应
+        >>> build_get_data_set_results(response)
+        [{'ChargeMListID': '1', 'ChargeMListNo': 'CF20240101'}]
+    """
+    results = []
+
+    # 根据响应类型选择不同的解析方式
+    if isinstance(response, httpx.Response):
+        # 如果是 httpx.Response 对象，先解析 XML 为字典
+        results = json_find_first(
+            "$.'soap:Envelope'.'soap:Body'.GetDataSetResponse.GetDataSetResult.'diffgr:diffgram'.NewDataSet.Table",
+            xmltodict.parse(response.text)
+        )
+    else:
+        # 如果是已解析的字典，直接查询
+        results = json_find_first(
+            "$.'soap:Envelope'.'soap:Body'.GetDataSetResponse.GetDataSetResult.'diffgr:diffgram'.NewDataSet.Table",
+            response
+        )
+
+    # 如果查询结果是单个字典（单行数据），转换为列表形式
+    if isinstance(results, dict):
+        return [results]
+
+    # 返回结果（可能是列表或 None）
+    return results
+
+
+def build_actual_payment_items_query_sql(
+        columns: str = "",
+        conditions: str = "",
+        order_by: str = "order by cfi.ChargeFeeItemID"
+) -> str:
+    """
+    生成查询实际支付项目的 SQL 语句
+
+    该函数用于构建查询物业收费相关数据的 SQL 语句，支持自定义查询列、条件和排序方式。
+    默认查询包含收费主列表、小区详情、收费项目、房间详情等多表关联数据。
+
+    表关联关系说明：
+    - chargeMasterList (cml): 收费主列表（主表）
+    - EstateDetail (ed): 小区详情（通过 EstateID 关联）
+    - ChargeFeeItem (cfi): 收费项目（通过 ChargeMListID 关联）
+    - RoomDetail (rd): 房间详情（通过 RmId 关联）
+    - ChargeBillItem (cbi): 收费账单项目（通过 CBillItemID 关联）
+
+    Args:
+        columns: 额外的查询列（默认空字符串），会添加到默认列前面
+        conditions: 查询条件（默认空字符串），会拼接到 WHERE 子句后
+        order_by: 排序方式（默认 "order by cfi.ChargeFeeItemID"）
+
+    Returns:
+        str: 完整的 SQL 查询语句
+
+    Note:
+        - 使用 LEFT JOIN 确保即使关联表无数据也能返回结果
+        - WHERE 子句使用 "1=1" 便于追加额外条件
+
+    Examples:
+        >>> build_actual_payment_items_query_sql(conditions="and cml.EstateID='E001'")
+        'select  cml.ChargeMListID,cml.ChargeMListNo,... from chargeMasterList as cml ... where 1=1 and cml.EstateID='E001' order by cfi.ChargeFeeItemID;'
+    """
+    # 定义默认查询列集合，包含收费相关的主要字段
+    default_columns = [
+        "cml.ChargeMListID",  # 收费主列表ID
+        "cml.ChargeMListNo",  # 收费单号
+        "cml.ChargeTime",  # 收费时间
+        "cml.PayerName",  # 付款人姓名
+        "cml.ChargePersonName",  # 收费人姓名
+        "cml.ActualPayMoney",  # 实际支付金额
+        "cml.EstateID",  # 小区ID
+        "cml.ItemNames",  # 项目名称
+        "ed.Caption as EstateName",  # 小区名称（别名）
+        "cfi.ChargeFeeItemID",  # 收费项目ID
+        "cfi.ActualAmount",  # 实际金额
+        "cfi.SDate",  # 开始日期
+        "cfi.EDate",  # 结束日期
+        "cfi.RmId",  # 房间ID
+        "rd.RmNo",  # 房间号
+        "cml.CreateTime",  # 创建时间
+        "cml.LastUpdateTime",  # 最后更新时间
+        "cbi.ItemName",  # 项目名称
+        "cbi.IsPayFull",  # 是否已全额支付
+        "ABS(DATEDIFF(dd,cfi.EDate, cfi.SDate)) as PayDays",  # 支付天数（计算字段）
+    ]
+
+    # 定义默认表连接关系，使用 LEFT JOIN 确保即使关联表无数据也能返回结果
+    table_joins = "".join([
+        " from chargeMasterList as cml",  # 主表：收费主列表
+        " left join EstateDetail as ed on cml.EstateID=ed.EstateID",  # 左联：小区详情
+        " left join ChargeFeeItem as cfi on cml.ChargeMListID=cfi.ChargeMListID",  # 左联：收费项目
+        " left join RoomDetail as rd on cfi.RmId=rd.RmId",  # 左联：房间详情
+        " left join ChargeBillItem as cbi on cfi.CBillItemID=cbi.CBillItemID",  # 左联：收费账单项目
+    ])
+
+    # 构建并返回完整的 SQL 语句
+    # 使用 1=1 便于无条件时仍保持语法正确
+    return f"select {columns} {','.join(default_columns)} {table_joins} where 1=1 {conditions} {order_by};"
+
+
+def payment_date_range_is_valid(
+        daily_fee: Union[int, float] = 0,
+        total_amount: Union[int, float] = 0,
+        start: str = "",
+        start_tz: Union[str, tzinfo] = "Asia/Shanghai",
+        end: str = "",
+        end_tz: Union[str, tzinfo] = "Asia/Shanghai",
+):
+    """
+    验证支付金额与日期范围是否匹配
+
+    根据每日费用、总金额和日期范围，验证总金额是否足够支付指定日期范围内的费用。
+    主要用于校验物业费、租金等按日计费场景的金额是否合理。
+
+    计算逻辑：
+    1. 将每日费用和总金额转换为浮点数
+    2. 如果总金额小于等于0，直接返回 False
+    3. 使用 arrow 库解析开始日期和结束日期
+    4. 计算日期范围内的总天数（包含起止两天）
+    5. 验证总金额是否 >= 每日费用 × 总天数
+
+    Args:
+        daily_fee: 每日费用金额
+        total_amount: 实际支付的总金额
+        start: 计费开始日期字符串（支持多种格式）
+        start_tz: 开始日期的时区，默认为 "Asia/Shanghai"
+        end: 计费结束日期字符串（支持多种格式）
+        end_tz: 结束日期的时区，默认为 "Asia/Shanghai"
+
+    Returns:
+        bool: 如果总金额大于等于每日费用乘以天数则返回 True，否则返回 False
+
+    Note:
+        - 日期范围包含开始日期和结束日期两天
+        - 总金额小于等于0时直接返回 False
+        - 使用 arrow 库处理时区转换，避免时区问题导致的天数计算错误
+
+    Examples:
+        >>> payment_date_range_is_valid(daily_fee=10, total_amount=300, start="2024-01-01", end="2024-01-31")
+        True
+        >>> payment_date_range_is_valid(daily_fee=10, total_amount=290, start="2024-01-01", end="2024-01-31")
+        False
+    """
+    # 将输入转换为浮点数，确保数值计算准确性
+    daily_fee = float(daily_fee)
+    total_amount = float(total_amount)
+
+    # 总金额小于等于0时直接返回 False（无效金额）
+    if float(total_amount) <= 0:
+        return False
+
+    # 使用 arrow 库解析日期，支持多种日期格式和时区
+    start_arrow: arrow.Arrow = arrow.get(start, tzinfo=start_tz)
+    end_arrow: arrow.Arrow = arrow.get(end, tzinfo=end_tz)
+
+    # 计算日期范围内的总天数（包含起止两天）
+    # 使用 interval 方法生成每天的时间点，然后统计数量
+    total_days = sum(1 for _ in start_arrow.interval(
+        frame="days",
+        start=start_arrow.datetime,
+        end=end_arrow.datetime
+    ))
+
+    # 验证总金额是否足够支付指定天数的费用
+    return total_amount >= daily_fee * total_days
+
+
+def filter_actual_payment_items(actual_payment_items: Optional[list[dict]] = None) -> list[dict]:
+    """
+    过滤实际支付记录，移除配对记录
+
+    Args:
+        actual_payment_items: 每条记录包含 ChargeMListID, ActualAmount, SDate, EDate
+
+    Returns:
+        移除配对记录后的列表
+    """
+    # 1. 按 (start_date, end_date, abs(amount)) 分组
+    actual_payment_items_groups = defaultdict(list)
+    for item in actual_payment_items:
+        sdate = item.get("SDate", "")
+        edate = item.get("EDate", "")
+        actual_amount = float(item.get("ActualAmount", 0))
+        group_key = (sdate, edate, abs(float(actual_amount)))
+        actual_payment_items_groups[group_key].append(item)
+    # return actual_payment_items_groups
+
+    # 2. 找出需要移除的 id
+    remove_ids = set()
+
+    for group_value in actual_payment_items_groups.values():
+        # 分离正金额（充值）和负金额（退款）
+        positives = [r for r in group_value if float(r.get("ActualAmount", 0)) > 0]
+        negatives = [r for r in group_value if float(r.get("ActualAmount", 0)) < 0]
+
+        # 按 id 排序（也可以按其他字段，比如 created_at）
+        positives.sort(key=lambda x: x['ChargeMListID'])
+        negatives.sort(key=lambda x: x['ChargeMListID'])
+
+        # 一一配对移除
+        paired_count = min(len(positives), len(negatives))
+        for i in range(paired_count):
+            remove_ids.add(positives[i]['ChargeMListID'])
+            remove_ids.add(negatives[i]['ChargeMListID'])
+
+    # 3. 返回未移除的记录
+    return [item for item in actual_payment_items if item['ChargeMListID'] not in remove_ids]

py_chanjet_toolkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: py-chanjet-toolkit
+Version: 1.0.0
+Summary: 畅捷通 T+ Python 客户端库，提供与畅捷通 T+ 智慧社区系统的 WebService 接口交互能力，支持同步和异步调用。
+Author-email: Guolei <174000902@qq.com>
+License: MIT License
+        
+        Copyright (c) 2026 郭磊
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://gitee.com/guolei19850528/py_chanjet_toolkit
+Project-URL: Repository, https://gitee.com/guolei19850528/py_chanjet_toolkit.git
+Project-URL: Issues, https://gitee.com/guolei19850528/py_chanjet_toolkit/issues
+Project-URL: Documentation, https://gitee.com/guolei19850528/py_chanjet_toolkit/wikis
+Keywords: chanjet,tplus,畅捷通,智慧社区,webservice,soap,api,client,async
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jsonpath-ng>=1.5.3
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: xmltodict>=1.0.4
+Requires-Dist: arrow>=1.4.0
+Requires-Dist: py-httpx-toolkit>=1.0.1
+Dynamic: license-file
+
+# py-chajet-toolkit
+
+畅捷通 T+ 系列产品的 Python 客户端库，提供与畅捷通 T+ 系统的 API 交互能力。
+
+## 功能特性
+
+- 提供畅捷通 T+ 智慧社区 WebService 接口的同步和异步调用
+- 封装 SOAP 请求的构建和响应解析
+- 提供数据校验、日期处理、SQL 生成等辅助工具函数
+- 支持 JSONPath 查询和 JSON Schema 校验
+
+## 安装方式
+
+### 使用 pip 安装
+
+```bash
+pip install py-chajet-toolkit
+```
+
+### 使用 uv 安装
+
+```bash
+uv add py-chajet-toolkit
+```
+
+## 快速开始
+
+### 基础使用示例
+
+```python
+from py_chajet_toolkit.tplus.zkhb import ForcelandEstateService
+from py_chajet_toolkit.tplus.zkhb.utils import (
+    build_get_data_set_post_xml,
+    build_get_data_set_results,
+    build_actual_payment_items_query_sql
+)
+
+# 初始化服务客户端
+service = ForcelandEstateService(base_url="http://your-server/estate")
+
+# 构建 SOAP 请求体
+xml_data = build_get_data_set_post_xml({"sql": "SELECT * FROM EstateDetail"})
+
+# 同步调用接口
+response = service.get_data_set(content=xml_data)
+
+# 解析响应数据
+results = build_get_data_set_results(response)
+print(results)
+```
+
+### 异步调用示例
+
+```python
+import asyncio
+from py_chajet_toolkit.tplus.zkhb import ForcelandEstateService
+from py_chajet_toolkit.tplus.zkhb.utils import build_get_data_set_post_xml, build_get_data_set_results
+
+async def main():
+    service = ForcelandEstateService(base_url="http://your-server/estate")
+    xml_data = build_get_data_set_post_xml({"sql": "SELECT * FROM ChargeMasterList"})
+    
+    # 异步调用接口
+    response = await service.async_get_data_set(content=xml_data)
+    results = build_get_data_set_results(response)
+    print(results)
+
+asyncio.run(main())
+```
+
+## API 说明
+
+### ForcelandEstateService
+
+畅捷通T+智慧社区服务客户端类，封装了与畅捷通T+智慧社区系统的WebService接口交互。
+
+#### 初始化
+
+```python
+service = ForcelandEstateService(
+    base_url="http://your-server/estate",
+    client_kwargs={"timeout": 120}
+)
+```
+
+#### 同步方法
+
+- `get_data_set(client=None, client_kwargs=None, **kwargs)` - 调用 GetDataSet 接口
+
+#### 异步方法
+
+- `async_get_data_set(client=None, client_kwargs=None, **kwargs)` - 异步调用 GetDataSet 接口
+
+## Utils 工具函数
+
+### json_find_first
+
+使用 JSONPath 表达式从嵌套的 JSON 数据中查找第一个匹配项。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import json_find_first
+
+data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}
+result = json_find_first("$.users[0].name", data)
+# 返回: 'Alice'
+```
+
+### json_is_valid
+
+校验 JSON 数据是否符合指定的 JSON Schema 规范。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import json_is_valid
+
+schema = {
+    "type": "object",
+    "properties": {"id": {"type": "string"}},
+    "required": ["id"]
+}
+is_valid = json_is_valid(schema, {"id": "123"})
+# 返回: True
+```
+
+### build_get_data_set_post_xml
+
+将请求数据转换为 SOAP GetDataSet 接口所需的 XML 格式。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import build_get_data_set_post_xml
+
+xml = build_get_data_set_post_xml({"sql": "SELECT * FROM EstateDetail"})
+```
+
+### build_get_data_set_results
+
+从 GetDataSet 接口响应中提取实际数据列表。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import build_get_data_set_results
+
+results = build_get_data_set_results(response)
+```
+
+### build_actual_payment_items_query_sql
+
+生成查询实际支付项目的 SQL 语句。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import build_actual_payment_items_query_sql
+
+sql = build_actual_payment_items_query_sql(
+    conditions="and cml.EstateID='E001'",
+    order_by="order by cml.CreateTime desc"
+)
+```
+
+### payment_date_range_is_valid
+
+验证支付金额与日期范围是否匹配。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import payment_date_range_is_valid
+
+is_valid = payment_date_range_is_valid(
+    daily_fee=10,
+    total_amount=300,
+    start="2024-01-01",
+    end="2024-01-31"
+)
+# 返回: True
+```
+
+### filter_actual_payment_items
+
+过滤实际支付记录，移除配对的充值和退款记录。
+
+```python
+from py_chajet_toolkit.tplus.zkhb.utils import filter_actual_payment_items
+
+filtered_items = filter_actual_payment_items(actual_payment_items)
+```
+
+## 项目结构
+
+```
+py_chajet_toolkit/
+├── tplus/
+│   ├── zkhb/
+│   │   ├── __init__.py    # 智慧社区服务客户端类
+│   │   ├── utils.py       # 工具函数集合
+│   │   └── responses.py   # 响应处理模块
+│   └── __init__.py
+└── __init__.py
+```
+
+## 依赖
+
+- arrow - 日期时间处理
+- httpx - HTTP 客户端
+- jsonpath_ng - JSONPath 查询
+- jsonschema - JSON Schema 校验
+- xmltodict - XML 与字典转换
+- py_httpx_toolkit - HTTP 工具封装
+
+## 项目主页
+
+[https://gitee.com/guolei19850528/py_chanjet_toolkit](https://gitee.com/guolei19850528/py_chanjet_toolkit)
+
+## 作者
+
+**Author**: Lei Guo  
+**Email**: guolei@example.com
+
+## 许可证
+
+MIT License

py_chanjet_toolkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+py_chajet_toolkit/__init__.py,sha256=xKia_U8WeX_VlXAZQd5ucHvKF82oSeBadiDTvN-wRyg,862
+py_chajet_toolkit/tplus/__init__.py,sha256=9cHhA80MfeXYcf-Z_2F2qpNpAuXDqPl8rDYgkl9gDOg,445
+py_chajet_toolkit/tplus/zkhb/__init__.py,sha256=n2dhiCurjJQtSPyKKV24_1uO7LMG29ASEkI93BWwP4c,5166
+py_chajet_toolkit/tplus/zkhb/responses.py,sha256=oWlTUbGZHZHdXPwADq5g_QuW0NpFzaXNmskmXnPDils,2087
+py_chajet_toolkit/tplus/zkhb/utils.py,sha256=Tq8rCF5wxOwktIQlMO5zyFRRcajcdMJEps7FQyjdbW0,15314
+py_chanjet_toolkit-1.0.0.dist-info/licenses/LICENSE,sha256=HazFJNaQP3rbY1dvg3hAmO-FZ6v7DwM0YHwXvWsGG3A,1063
+py_chanjet_toolkit-1.0.0.dist-info/METADATA,sha256=q3vChqme-EgRNsFFTKfXyOMIx-KYvVHN2uZFkgAFFL4,8011
+py_chanjet_toolkit-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+py_chanjet_toolkit-1.0.0.dist-info/top_level.txt,sha256=OxwP24CYWVpzRu4AqrlD4dSVE-ocT3IBVlCm37ukAoI,18
+py_chanjet_toolkit-1.0.0.dist-info/RECORD,,

py_chanjet_toolkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_chanjet_toolkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 郭磊
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_chanjet_toolkit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+py_chajet_toolkit