Metadata-Version: 2.4
Name: py_wisharetec_toolkit
Version: 3.0.5
Summary: 浙江慧享科技有限公司 - 善数・慧享云运营平台 Python 扩展包，提供接口调用封装
Author-email: guolei <174000902@qq.com>
License: MIT
Project-URL: Homepage, https://gitee.com/guolei19850528/py_wisharetec_toolkit
Keywords: wisharetec,wisharetec_toolkit,shanshu,saas.wisharetec.com,saas toolkit
Classifier: Programming Language :: Python :: 3
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
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Provides-Extra: cache
Requires-Dist: diskcache>=5.0; extra == "cache"
Requires-Dist: redis>=5.0; extra == "cache"
Dynamic: license-file

# py_wisharetec_toolkit

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

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

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

## 安装

### 推荐使用 uv 安装（推荐）

```bash
uv pip install py_wisharetec_toolkit
```

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

```bash
uv pip install -e .
```

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

```bash
uv pip install py_wisharetec_toolkit[cache]
```

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

```bash
uv pip install -e ".[cache]"
```

### 或者使用 pip 安装

```bash
pip install py_wisharetec_toolkit
```

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

```bash
pip install -e .
```

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

```bash
pip install py_wisharetec_toolkit[cache]
```

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

```bash
pip install -e ".[cache]"
```

## 快速开始

```python
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`。

## 已实现的接口

| 接口 | 方法 | 路径 | 返回模型 |
|------|------|------|----------|
| 登录 | `login` | `/api/user/loginInteractive` | `ShanshuLoginResponse` |
| 园区档案 | `query_community_with_paginator` | `/api/space/community/v2/frontPage` | `ShanshuCommunityPageResponse` |
| 房产档案 | `query_property_with_paginator` | `/api/space/property/propertyPage` | `ShanshuPropertyPageResponse` |
| 车场档案 | `query_yard_archive_with_paginator` | `/api/space/space/yardArchivePage` | `ShanshuYardArchivePageResponse` |
| 楼幢档案 | `query_building_with_paginator` | `/api/space/property/getSpaceBuildingPage` | `ShanshuBuildingPageResponse` |
| 住户档案 | `query_resident_with_paginator` | `/api/user/residentInfo/getResidentPage` | `ShanshuResidentPageResponse` |
| 业主档案 | `query_archive_with_paginator` | `/api/space/archive/examine/page` | `ShanshuArchivePageResponse` |
| 车辆档案 | `query_car_manage_with_paginator` | `/api/space/carManage/pageCarManage` | `ShanshuCarManagePageResponse` |
| 车位档案 | `query_parking_with_paginator` | `/api/space/parking/parkingPage` | `ShanshuParkingPageResponse` |
| 工单档案 | `query_work_order_with_paginator` | `/api/woreport/task/query/page` | `ShanshuWorkOrderPageResponse` |
| 商城订单 | `query_mall_order_with_paginator` | `/api/retailmall/order/pageFront` | `ShanshuMallOrderPageResponse` |
| 服务订单 | `query_service_order_with_paginator` | `/api/houseserve/order/pageFront` | `ShanshuServiceOrderPageResponse` |
| 审批数据 | `query_approval_with_paginator` | `/api/bpm/process/approval` | `ShanshuApprovalPageResponse` |
| 审批详情 | `query_approval_detail` | `/api/bpm/process/progress/{instance_id}/node_433279443693` | `ShanshuApprovalDetailRecord` |
| 业主详情 | `query_owner_detail` | `/api/space/archive/archive/detailSensitive` | `ShanshuOwnerDetailRecord` |

同步客户端 `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`（异步）。

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

```bash
cp examples/shanshu/.env.example examples/shanshu/.env
```

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

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

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

### 示例文件列表

| 同步示例 | 异步示例 | 说明 |
|----------|----------|------|
| `example_login.py` | `example_async_login.py` | 登录接口 |
| `example_community_page.py` | `example_async_community_page.py` | 园区档案列表 |
| `example_property_page.py` | `example_async_property_page.py` | 房产档案列表 |
| `example_yard_archive_page.py` | `example_async_yard_archive_page.py` | 车场档案列表 |
| `example_building_page.py` | `example_async_building_page.py` | 楼幢档案列表 |
| `example_resident_page.py` | `example_async_resident_page.py` | 住户档案列表 |
| `example_archive_page.py` | `example_async_archive_page.py` | 业主档案列表 |
| `example_car_manage_page.py` | `example_async_car_manage_page.py` | 车辆档案列表 |
| `example_parking_page.py` | `example_async_parking_page.py` | 车位档案列表 |
| `example_work_order_page.py` | `example_async_work_order_page.py` | 工单档案列表 |
| `example_mall_order_page.py` | `example_async_mall_order_page.py` | 商城订单列表 |
| `example_service_order_page.py` | `example_async_service_order_page.py` | 服务订单列表 |
| `example_approval_page.py` | `example_async_approval_page.py` | 审批数据列表 |
| `example_approval_detail.py` | `example_async_approval_detail.py` | 审批详情 |
| `example_owner_detail.py` | `example_async_owner_detail.py` | 业主详情 |

## 测试 (`tests/`)

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

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

```bash
cp tests/shanshu/.env.example tests/shanshu/.env
```

安装测试依赖并运行：

```bash
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。

## 目录结构

```text
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` 模型：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| conditions | dict\|None | None | 查询条件 |
| count | bool | True | 是否返回总记录数 |
| last | bool | True | 是否返回 last 标志 |
| order_by | list\|None | None | 排序字段列表 |
| page_num | int | 1 | 页码 |
| page_size | int | 20 | 每页大小 |

## 许可证

MIT License
