Metadata-Version: 2.5
Name: py-tiehu-sdk
Version: 0.2.2
Summary: 铁虎道闸平台 Python SDK - 同步接口调用（官方文档: https://www.showdoc.com.cn/1735808258920310/9467753400037587）
Project-URL: Homepage, https://gitee.com/guolei19850528/py_tiehu_sdk
Project-URL: Repository, https://gitee.com/guolei19850528/py_tiehu_sdk.git
Project-URL: Issues, https://gitee.com/guolei19850528/py_tiehu_sdk/issues
Author-email: guolei <174000902@qq.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# py_tiehu_sdk

> TieHuo 铁虎道闸平台 Python SDK — 35 个完整下行接口

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Toolchain](https://img.shields.io/badge/uv-ruff-mypyt-4B8BBE?logo=python&logoColor=FFD43B)](https://docs.astral.sh/uv/)

## 📖 项目简介

`py_tiehu_sdk` 是 [铁虎道闸平台](https://www.showdoc.com.cn/1735808258920310/9467753400037587) 的 Python SDK 封装，提供**自动签名**、**HTTP 请求发送**、**响应数据验证**、**异常统一处理**等开箱即用的能力。

### 核心特性

- 🔐 **自动签名** — 按道闸平台 6 步签名规则自动计算 sign，无需手动处理 MD5 拼接
- 🚀 **类型安全** — 完整的 Pydantic v2 数据模型 + mypy strict 类型检查
- 📦 **零样板** — 只需提供 `base_url` / `app_key` / `parking_id`，即可调用所有接口
- 🌐 **httpx 驱动** — 支持 HTTP/2、连接池复用、代理配置、自定义超时
- 🛠 **国际主流工具链** — uv 管理依赖、ruff 格式化/Lint、mypy 类型检查

---

## 🧱 项目结构

```
py_tiehu_sdk/
├── pyproject.toml                 # uv + hatchling 配置，版本动态读取 _version.py
├── uv.lock                        # 依赖锁文件
├── src/
│   └── py_tiehu_sdk/
│       ├── __init__.py            # ✅ 对外统一入口（Provider + Config + 异常 + 响应模型）
│       ├── _version.py            # 版本号（pyproject.toml 动态读取）
│       ├── provider.py            # ✅ PklotAPIProvider — 对外统一访问入口
│       └── core/
│           └── pklot/
│               ├── __init__.py
│               ├── base/
│               │   ├── __init__.py           # ✅ 统一对外导出（Config / 异常 / 模型 / API 基类）
│               │   ├── _config.py            #    PklotAPIConfig（SDK 全局配置，Pydantic）
│               │   ├── _exceptions.py        #    SDK 异常体系（PklotError 基类 + 5 种子类）
│               │   ├── _models.py            #    PklotBaseResponse + PklotCommonResponse
│               │   ├── _signature.py         #    🔒 签名算法（内部，不对外暴露）
│               │   └── _api.py               #    PklotBaseAPI + PklotAPI（请求处理器）
│               └── downstream/
│                   ├── __init__.py           # ✅ DownstreamAPI 导出
│                   └── _api.py                #    DownstreamAPI（32 个下行业务接口）
├── tests/
│   ├── conftest.py                # pytest 配置 + .env 加载 + --integration 开关
│   ├── test_signature.py          # 签名算法单元测试
│   ├── test_models.py             # 响应模型单元测试
│   ├── test_provider.py           # Provider 构造 + 签名注入测试
│   └── test_integration.py        # 🔗 真实网络集成测试（需 --integration）
├── scripts/
│   ├── quick_test.py              # 快速验证脚本（执行查询类接口并打印返回）
│   └── debug_request.py           # Debug 脚本（打印签名计算细节）
├── .env.example                   # 测试环境配置模板
└── LICENSE                        # MIT License
```

### 目录分层设计

```
┌──────────────────────────────────────────────────────────────┐
│  py_tiehu_sdk/__init__.py   ← 对外唯一入口                    │
│  py_tiehu_sdk/provider.py   ← Provider 统一入口               │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  core/pklot/base/            🔧 基础能力层                    │
│    ├─ _config.py             SDK 全局配置                     │
│    ├─ _signature.py          🔒 签名算法（内部）               │
│    ├─ _exceptions.py         异常定义                          │
│    ├─ _models.py             Pydantic 响应模型                  │
│    └─ _api.py                请求处理器（签名 + HTTP + 解析）   │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  core/pklot/downstream/      📥 下行业务层                    │
│    └─ _api.py                DownstreamAPI — 32 个完整接口     │
└──────────────────────────────────────────────────────────────┘
```

### 调用链路示意

```python
provider = PklotAPIProvider(config)
resp = provider.downstream_api.query_pklot()
```

```
PklotAPIProvider(config)
  │
  ├─ .base_api = PklotAPI(config)
  │     └─ 持有 httpx.Client，负责签名 + 请求 + 响应解析
  │
  └─ .downstream_api = DownstreamAPI(base_api)
        └─ .query_pklot()
              │
              ▼
        base_api._post_json("queryPklot", {})
              │
              ├─ _build_signed_payload()  自动注入 parkingId / timestamp / sign
              ├─ httpx.Client.post()       发送 JSON POST
              └─ PklotCommonResponse       返回完整响应（调用方通过 resp.ok 判断业务状态）
```

---

## 📦 已实现的下行接口（32 个）

### 车位查询（3）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `query_pklot()` | queryPklot | 1.0 | 获取车场车位信息 |
| `get_parkinfo()` | getParkinfo | 2.1 | 获取车场详情 |
| `get_park_device_state()` | getParkDeviceState | 3.3 | 获取设备在线状态 |

### 临停缴费（4）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `calculating_temp_cost(application_id, plate_number)` | calculatingTempCost | 1.1 | 获取临停应缴金额 |
| `pay_temp_cost(plate_number, order_no, pay_fee, pay_type, order_id)` | payTempCost | 1.2 | 支付成功通知道闸 |
| `get_vehicle_information(plate_number)` | getVehicleInformation | 4.4 | 查询车辆在场信息 |
| `simulate_cla_fee(during_time)` | simulateClaFee | 4.3 | 模拟计算费用（duringTime 单位：分钟） |

### 车类 / 车型（2）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `get_park_car_type()` | getParkCarType | 1.3 | 获取车类列表 |
| `get_park_car_model()` | getParkCarModel | 1.4 | 获取车型列表 |

### 闸机控制（3）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `open_gate(gate_id, status)` | openGate | 2.5 | 远程开关闸（0关/1开/2常开/3常闭） |
| `get_park_gate()` | getParkGate | 2.4 | 获取通道列表 |
| `no_plate_qrcode(lane_no, open_id)` | noPlateQRcode | 1.6 | 无牌车扫码进出 |

### 月卡管理（6）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `pay_monthly(plate_number, amount, start_time, end_time, pay_type)` | payMonthly | 1.5 | 月卡续期 |
| `save_monthly_rent(emp_name, emp_mobile, plate_number, ...)` | saveMonthlyRent | 2.6 | 增加 / 修改月租 |
| `del_monthly_rent(plate_number)` | delMonthlyRent | 2.7 | 删除月租 |
| `get_monthly_rent(plate_number)` | getMonthlyRent | 2.8 | 车牌查月卡详情 |
| `get_monthly_rent_list(page_index, page_size, plate_number, rent_type)` | getMonthlyRentList | 2.9 | 月卡列表分页 |
| `del_monthly_rent_list(plate_numbers)` | delMonthlyRentList | 3.0 | 批量删除月租 |

### 储值充值（1）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `recharge_stored_value(plate_number, pay_fee)` | rechargeStoredValue | 4.1 | 储值车充值 |

### 访客（2）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `add_visit(plate_number, visitor_name, begin_time, end_time, visitor_count, car_model_id)` | addVisit | 1.7 | 添加访客 |
| `delete_visit(plate_number)` | deleteVisit | 4.0 | 取消访客（入场前可调用） |

### 锁车控制（1）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `lock_car(plate_number)` | lockCar | 2.0 | 锁车 / 解锁（连续调用切换状态） |

### 黑名单（3）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `add_park_black(plate_number, start_time, end_time, status)` | addParkBlack | 2.2 | 增加黑名单 |
| `del_park_blacklist(plate_number)` | delParkBlacklist | 2.3 | 删除黑名单 |
| `get_park_black_list(plate_number, page_index, page_size)` | getParkBlackList | 3.5 | 黑名单列表分页 |

### 商家打折（2）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `discount_rules(seller_no, pwd)` | discountRules | 1.8 | 获取商家打折规则 |
| `discount_pay(plate_number, seller_no, derate_id, derate_value, seller_id)` | discountPay | 1.9 | 消费打折 |

### 商家管理（3）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `seller_charge(seller_id, money)` | sellerCharge | 3.7 | 商家充值 |
| `seller_charge_list(seller_id, parking_nume)` | sellerChargeList | 3.8 | 商家优免记录 |
| `get_park_seller_list(page_index, page_size)` | getParkSellerList | 3.9 | 车场商家列表分页 |

### 其他辅助（2）

| 方法名 | 接口路径 | 文档编号 | 说明 |
|:---|:---|:---|:---|
| `upate_plate_info(old_plate_number, new_plate_number, gate_id, record_id)` | upatePlateInfo | 3.4 | 修改车牌号（平台接口名拼写有误，保持原样） |
| `parking_invoice(order_id, open_id, title_type, buyer_title)` | parkingInvoice | 4.5 | 车场开票 |

---

## 🚀 快速开始

### 前置要求

- Python **3.10 或更高**
- [uv](https://docs.astral.sh/uv/) 包管理器（推荐）或 pip

### 安装

```bash
# 方式一：通过 uv 安装（推荐）
uv add py-tiehu-sdk

# 方式二：通过 pip 安装
pip install py-tiehu-sdk

# 开发模式（本地开发）
git clone <repo-url> py_tiehu_sdk
cd py_tiehu_sdk
uv sync --dev
```

### 配置环境变量

复制 `.env.example` 为 `.env`，填入你的道闸平台测试参数：

```bash
cp .env.example .env
# 然后编辑 .env 填入真实值
```

`.env` 内容示例：

```ini
# API 基础 URL（去掉 /interface 后缀）
PKLOT_BASE_URL=http://ykt.test.cxyun.net.cn:7303/cxzn

# 道闸平台分配的 appKey（明文，SDK 内部自动 MD5）
PKLOT_APP_KEY=b620f6be42328effc32b982a2b9

# 默认车场 ID
PKLOT_PARKING_ID=5607116888606308222

# HTTP 请求超时（秒）
PKLOT_TIMEOUT=30.0
```

### 基本使用

```python
from py_tiehu_sdk import PklotAPIProvider, PklotAPIConfig

# 1. 创建配置（从 .env 读取，或直接硬编码）
config = PklotAPIConfig(
    base_url="http://ykt.test.cxyun.net.cn:7303/cxzn",
    app_key="your_app_key_here",
    parking_id="your_parking_id_here",
)

# 2. 创建 Provider（SDK 统一入口）
provider = PklotAPIProvider(config)

# 3. 调用下行接口
resp = provider.downstream_api.query_pklot()

# 4. 检查结果
if resp.ok:
    print("✅ 成功！")
    print(f"  总车位   : {resp.Data.get('totalLot')}")
    print(f"  空闲车位 : {resp.Data.get('emptyLot')}")
else:
    print(f"❌ 失败: {resp.message}")
```

### 更多接口调用示例

```python
# 车场详情
resp = provider.downstream_api.get_parkinfo()

# 远程开闸（gate_id 从 get_park_gate 获取）
resp = provider.downstream_api.open_gate(gate_id="G001", status=1)

# 根据车牌查询月卡
resp = provider.downstream_api.get_monthly_rent(plate_number="湘A12345")

# 分页获取月卡列表（支持车牌模糊搜索 + 月卡类型过滤）
resp = provider.downstream_api.get_monthly_rent_list(
    page_index=1,
    page_size=20,
    plate_number="湘A",   # 可选
    rent_type=1,          # 可选（不传默认月租车）
)

# 根据停车时长（分钟）模拟计算费用
resp = provider.downstream_api.simulate_cla_fee(during_time=60)

# 添加访客车
resp = provider.downstream_api.add_visit(
    plate_number="湘A12345",
    visitor_name="张三",
    begin_time="2026-11-18 09:00:00",
    end_time="2026-11-18 18:00:00",
    visitor_count=-1,          # -1 表示不限次数
    car_model_id="model_01",
    gate_id="G001",             # 可选
)

# 增加黑名单
resp = provider.downstream_api.add_park_black(
    plate_number="湘A99999",
    start_time="2026-11-18 00:00:00",
    end_time="2026-12-31 23:59:59",
    status=1,                   # 1=不可进出, 2=可进不可出, 3=可进可出, 4=可出不可进
    remark="欠费车辆",           # 可选
)

# 月卡续期
resp = provider.downstream_api.pay_monthly(
    plate_number="湘A12345",
    amount="100",
    start_time="2026-11-01 00:00:00",
    end_time="2027-10-31 23:59:59",
    pay_type=2,                 # 1=现金, 2=微信, 3=支付宝
)

# 商家打折
resp = provider.downstream_api.discount_pay(
    plate_number="湘A12345",
    seller_no="store_001",
    derate_id="rule_05",
    derate_value="5",           # 根据规则类型：减金额填元数，减时间填分钟
    seller_id="seller_001",
)
```

### 复用外部 httpx.Client（连接池复用）

```python
import httpx
from py_tiehu_sdk import PklotAPIProvider, PklotAPIConfig

# 手动管理 httpx.Client，适用于多 SDK 实例共享连接池
with httpx.Client(
    proxies={"http://": "http://127.0.0.1:7890"},  # 代理
    headers={"User-Agent": "my-app/1.0"},
) as client:
    config = PklotAPIConfig(
        base_url="http://x.cxyun.net.cn:7303/cxzn",
        app_key="xxx",
        parking_id="yyy",
    )
    provider = PklotAPIProvider(config, client=client)
    resp = provider.downstream_api.query_pklot()
```

---

## 🔑 签名算法

SDK 内部自动处理签名，调用方无需关心。签名规则（6 步）：

```
原始 params
    │ ① sort_params  过滤空值 + 按参数名 ASCII 升序
    ▼
排序后 params
    │ ② 拼接 "key1=value1&key2=value2" → stringA
    ▼
stringA
    │ ③ md5(appKey) → 大写 32 位 md5_app_key
    ▼
md5_app_key
    │ ④ stringA + md5_app_key → stringSignTemp
    ▼
stringSignTemp
    │ ⑤ md5 → 大写 32 位 → sign
    ▼
sign（最终结果）
```

### 自动注入的请求字段

每次 `_post_json` 调用会自动注入以下三个字段，**调用方不需要手动传入**：

| 字段 | 来源 | 值 |
|:---|:---|:---|
| `parkingId` | `config.parking_id` | 车场 ID |
| `timestamp` | `int(time.time() * 1000)` | 13 位毫秒时间戳（2 分钟内有效） |
| `sign` | `generate_sign()` 计算 | 大写 32 位签名 |

---

## 🧪 测试

### 运行单元测试（默认，不发真实网络请求）

```bash
uv run pytest -v
```

输出示例：

```
tests/test_signature.py::TestMd5Uppercase::test_basic PASSED
tests/test_models.py::TestPklotBaseResponse::test_ok_true_with_int PASSED
tests/test_provider.py::TestProvider::test_provider_creation PASSED
...
======================== 20 passed, 6 skipped in 0.08s =========================
```

### 运行集成测试（真实网络请求）

**前置**：
1. 复制 `.env.example` 为 `.env` 并填入真实值
2. 当前出口 IP 必须已在道闸平台白名单内（否则平台返回 `status=0, msg=不是白名单`）

```bash
uv run pytest --integration -v
```

### 快速验证脚本

```bash
# 执行查询类接口并打印完整返回
uv run python scripts/quick_test.py

# Debug 脚本 — 打印签名计算细节，用于排查签名不匹配问题
uv run python scripts/debug_request.py
```

### 代码质量检查

```bash
# Ruff 格式化 + Lint
uv run ruff check src tests --fix

# Mypy 类型检查（strict 模式）
uv run mypy src

# 构建发布包（自动从 _version.py 读取版本号）
uv build
```

---

## 📚 异常处理

### 业务状态 vs SDK 异常

SDK **不会自动**因 `status != 1` 抛出异常。道闸平台的 `status` 有多种语义：

| status | 含义 | 处理方式 |
|:---|:---|:---|
| `1` | 成功 | 正常读取 `resp.Data` |
| `2` | 正常业务状态（如车辆不在场、不是月卡车） | 按业务逻辑处理，不算异常 |
| `0` | 失败（参数错误、网络问题等） | 通过 `resp.message` 排查 |

因此推荐的调用模式是**先检查 `resp.ok`，再按需主动抛异常**：

```python
resp = provider.downstream_api.get_vehicle_information(plate_number="测试00001")

if resp.ok:
    # status=1，车辆在场
    print(f"车辆入场时间: {resp.Data.get('startTime')}")
elif resp.status == 2:
    # 正常业务状态：车辆不在场
    print("车辆不在车场")
else:
    # status=0，需要排查
    print(f"查询失败: {resp.message}")
```

### PklotAPIError 主动抛异常

如果你希望 `status != 1` 时自动中断流程，可以**主动调用** `resp.raise_for_status()`：

```python
resp = provider.downstream_api.query_pklot()
resp.raise_for_status()  # status != 1 时抛 PklotAPIError

# 或者这样写（显式声明"这里必须成功"）
provider.downstream_api.query_pklot().raise_for_status()
```

### SDK 异常体系

SDK 在以下场景自动抛异常（不需要业务层判断）：

| 异常 | 触发时机 |
|:---|:---|
| `PklotAPIError` | HTTP 非 200 错误、DNS 解析失败 |
| `PklotValidationError` | 响应非 JSON、Pydantic 验证失败 |
| `PklotTimeoutError` | 请求超时（可通过 `PklotAPIConfig(timeout=60)` 调整） |

```python
from py_tiehu_sdk import (
    PklotError,              # 所有 SDK 异常基类（可以统一捕获）
    PklotAPIError,           # HTTP 错误 / 主动 raise_for_status()
    PklotSignatureError,     # 签名生成失败（内部使用）
    PklotTimeoutError,       # 请求超时
    PklotValidationError,    # 响应 JSON 解析 / Pydantic 验证失败
)

try:
    resp = provider.downstream_api.query_pklot()
except PklotTimeoutError:
    print("请求超时，可通过 PklotAPIConfig(timeout=60) 增加超时时间")
except PklotValidationError as e:
    print(f"响应格式异常: {e}")
except PklotError as e:
    print(f"SDK 通用错误: {e}")
```

---

## 🧰 工具链

| 工具 | 版本 | 用途 |
|:---|:---|:---|
| **uv** | ≥ 0.5 | 依赖管理 + 虚拟环境 + 构建 |
| **ruff** | ≥ 0.5 | 格式化（替代 black）+ Lint（替代 flake8 + isort）|
| **mypy** | ≥ 1.10 | strict 模式类型检查 |
| **hatchling** | — | 构建后端（支持动态版本）|
| **pytest** | ≥ 8 | 单元测试 + 集成测试 |
| **pydantic** | ≥ 2.7 | 数据验证 + 序列化 |
| **httpx** | ≥ 0.27 | HTTP 客户端（支持 HTTP/2）|
| **python-dotenv** | ≥ 1.2 | 加载 `.env` 配置（dev 依赖）|

---

## 🔐 安全说明

- **appKey 明文存储** — SDK 内部会自动 MD5 转大写后参与签名，调用方无需任何加密处理
- **HTTPS** — 建议使用 `https://` 开头的 API 地址，避免 appKey 在明文传输中被劫持
- **IP 白名单** — 道闸平台默认校验请求来源 IP，需要在平台管理后台配置白名单
- **签名有效期** — timestamp 对应的毫秒时间戳与道闸服务器时间差不能超过 2 分钟
- **不暴露签名工具** — `generate_sign`、`md5_uppercase`、`sort_params` 为内部方法，不通过 `__init__.py` 对外暴露

---

## 📄 版本管理

版本号统一在 `src/py_tiehu_sdk/_version.py` 中维护：

```python
__version__ = "0.2.1"
```

`pyproject.toml` 通过 hatchling 动态读取，**无需**两处重复修改：

```toml
[project]
dynamic = ["version"]

[tool.hatch.version]
path = "src/py_tiehu_sdk/_version.py"
expression = "__version__"
```

---

## 📜 License

本项目基于 [MIT License](LICENSE) 开源。
