py_wisharetec_toolkit

浙江慧享科技有限公司 - 善数・慧享云运营平台 Python 扩展包。

本包封装了善数・慧享云运营平台 (https://saas.wisharetec.com/) 的各类 API 接口，提供同步客户端 ShanshuClient 和异步客户端 AsyncShanshuClient，供他人调用。

作者：guolei 174000902@qq.com
项目主页：https://gitee.com/guolei19850528/py_wisharetec_toolkit

安装

推荐使用 uv 安装（推荐）

uv pip install py_wisharetec_toolkit

或从本地源码安装（开发模式）：

uv pip install -e .

带缓存依赖安装（diskcache / redis）：

uv pip install py_wisharetec_toolkit[cache]

或从本地源码安装（开发模式，带缓存依赖）：

uv pip install -e ".[cache]"

或者使用 pip 安装

pip install py_wisharetec_toolkit

或从本地源码安装（开发模式）：

pip install -e .

带缓存依赖安装（diskcache / redis）：

pip install py_wisharetec_toolkit[cache]

或从本地源码安装（开发模式，带缓存依赖）：

pip install -e ".[cache]"

快速开始

from py_wisharetec_toolkit.shanshu.client import ShanshuClient
from py_wisharetec_toolkit.shanshu.models import ShanshuPageQueryParams

# 创建同步客户端
client = ShanshuClient(
    base_url="https://saas.wisharetec.com/",
    account="your_account",
    password="your_password",
)

# 登录
resp = client.login("your_account", "your_password")
print(resp.ok)

# 查询园区档案
params = ShanshuPageQueryParams(
    conditions={
        "fields": [
            {"map": {}, "method": 1, "name": "spaceTreeId", "value": "73"},
            {"map": {}, "method": 1, "name": "flag", "value": 0},
        ]
    },
    page_num=1,
    page_size=20,
)
result = client.query_community_with_paginator(params=params)
print(result.ok, result.total, len(result.records or []))

client.close()

注意：账号、密码等敏感信息请通过环境变量（.env 文件）配置，勿硬编码在代码中。测试用例请参考 tests/shanshu/.env.example，示例代码请参考 examples/shanshu/.env.example。

已实现的接口

同步客户端 ShanshuClient 与异步客户端 AsyncShanshuClient 方法名完全一致（异步方法已去掉 async_ 前缀），异步客户端支持 async with 上下文管理器。

所有分页接口均使用 ShanshuPageQueryParams 模型封装查询参数，包含 conditions、count、last、order_by、page_num、page_size 字段。

接口注意事项

• 园区、房产、楼幢、车场、业主、车辆、车位、审批等接口的 conditions 需携带 spaceTreeId 与 flag。
• 住户档案接口需传入空条件：conditions={}；商城订单、服务订单接口需传入 conditions={"fields": []}（不能携带 spaceTreeId、flag，否则后端返回“系统内部报错”）。
• 工单档案接口要求 conditions 中额外携带 appCode=WORK_ORDER。
• 审批详情需先通过审批列表接口获取 procInstId，节点 ID 固定为 node_433279443693；业主详情需先获取 userId / communityId / spaceId，再调用详情接口。

示例代码 (examples/)

完整可运行示例位于 examples/shanshu/，覆盖全部接口的同步与异步调用，文件命名规则为 example_*.py（同步）与 example_async_*.py（异步）。

运行示例前，请复制模板并填写真实账号：

cp examples/shanshu/.env.example examples/shanshu/.env

运行示例（以园区档案为例）：

python examples/shanshu/example_community_page.py
python examples/shanshu/example_async_community_page.py

公共配置与查询条件集中在 examples/shanshu/example_common.py，统一从 examples/shanshu/.env 读取 SHANSHU_* 变量。

示例文件列表

测试 (tests/)

测试用例位于 tests/shanshu/，基于 pytest + pytest-asyncio，统一从 tests/shanshu/.env 读取配置，公共夹具定义在 tests/shanshu/conftest.py。

运行测试前，请复制模板并填写真实账号：

cp tests/shanshu/.env.example tests/shanshu/.env

安装测试依赖并运行：

uv pip install -e ".[dev,cache]"
pytest tests/shanshu -q

未配置 SHANSHU_ACCOUNT / SHANSHU_PASSWORD 时，测试会自动跳过。

测试文件列表

• test_login.py / test_async_login.py：登录接口
• test_community_page.py / test_async_community_page.py：园区档案列表
• test_property_page.py / test_async_property_page.py：房产档案列表
• test_yard_archive_page.py / test_async_yard_archive_page.py：车场档案列表
• test_building_page.py / test_async_building_page.py：楼幢档案列表
• test_resident_page.py / test_async_resident_page.py：住户档案列表
• test_archive_page.py / test_async_archive_page.py：业主档案列表
• test_car_manage_page.py / test_async_car_manage_page.py：车辆档案列表
• test_parking_page.py / test_async_parking_page.py：车位档案列表
• test_work_order_page.py / test_async_work_order_page.py：工单档案列表
• test_mall_order_page.py / test_async_mall_order_page.py：商城订单列表
• test_service_order_page.py / test_async_service_order_page.py：服务订单列表
• test_approval_page.py / test_async_approval_page.py：审批数据列表
• test_approval_detail.py / test_async_approval_detail.py：审批详情
• test_owner_detail.py / test_async_owner_detail.py：业主详情

Token 缓存

客户端支持三种 Token 缓存后端：

• ShanshuMemoryTokenCache：进程内内存缓存（默认，无需额外依赖）
• ShanshuDiskCacheTokenCache：基于 diskcache 的持久化缓存（需安装 [cache] 依赖）
• ShanshuRedisTokenCache：基于 redis 的缓存（需安装 [cache] 依赖）

缓存 key 格式：py_wisharetec_toolkit:shanshu:authorization:{account}，便于缓存不同用户的登录 token。

目录结构

py_wisharetec_toolkit/
├── README.md
├── pyproject.toml
├── uv.lock
├── src/
│   └── py_wisharetec_toolkit/
│       ├── __init__.py          # 顶层包
│       ├── py.typed             # PEP 561 类型标记
│       └── shanshu/             # 子包，供他人调用
│           ├── __init__.py
│           ├── client.py        # 同步客户端 ShanshuClient 与异步客户端 AsyncShanshuClient
│           ├── auth.py          # Token 缓存与认证
│           └── models.py        # pydantic 响应模型
├── tests/
│   └── shanshu/
│       ├── __init__.py
│       ├── conftest.py          # 公共夹具（客户端、登录、查询条件）
│       ├── .env.example         # 测试配置模板
│       └── test_*.py            # 各接口的同步 / 异步测试用例（共 30 个）
└── examples/
    └── shanshu/
        ├── .env.example         # 示例配置模板
        ├── example_common.py    # 示例公共辅助（读取配置、构造客户端、查询条件）
        ├── example_*.py         # 各接口同步示例（共 15 个）
        └── example_async_*.py   # 各接口异步示例（共 15 个）

参数说明

所有分页查询接口均使用 ShanshuPageQueryParams 模型：

许可证

MIT License