openhub-fee-sdk 0.1.0__tar.gz

openhub_fee_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# 构建与安装产物（发布由 CI 完成，无需提交）
+__pycache__/
+*.egg-info/
+build/
+dist/

openhub_fee_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: openhub-fee-sdk
+Version: 0.1.0
+Summary: openhub 费用接口 Python 客户端（/api/fee），基于 requests 封装 HMAC-SHA256 签名
+Author: staugur
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+
+# openhub-fee-sdk
+
+openhub 费用接口的 Python 客户端，基于 `requests` 封装 `/api/fee` 的全部接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。鉴权、字段与错误码见仓库
+根目录 `arch/fee.md` 第 5 节。
+
+> 注意：与 pcs 的费用接口不同，openhub **不开放直接入账**（`recharge`），资金只能经
+> 管理员审核进入账本；SDK 因此不提供 `recharge`，转而提供**半自动收款**的订单类接口
+> （建单 / 上传凭证 / 查单 / 取消）。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install openhub-fee-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk/fee
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk/fee 子目录
+pip install "git+https://github.com/staugur/open-hub.git#subdirectory=sdk/fee"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `openhub_fee/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/fee/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/fee/` 目录的改动会触发自动发布；改 `src/`、`arch/`、`README.md`
+> 等其他目录（含 `sdk/` 下的其他项目，如 `sdk/ipamcli`）不会触发，避免无关改动误发版本。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish-sdk.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/fee/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `openhub-fee-sdk`
+> 项目配置 Trusted Publisher（Owner=`staugur`、Repository name=`open-hub`、
+> Workflow name=`publish-sdk.yml`、Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from openhub_fee import FeeClient
+
+client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="sec")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="sec", limit=50)
+client.fee_modules()
+
+# 费用：按量扣费（仅 postpaid；biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")
+
+# 半自动收款：建单 -> 上传凭证 -> 查单 / 取消
+order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
+client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+client.fee_order_get(order["order_no"])
+client.fee_order_cancel(order["order_no"])
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `openhub_fee.FeeApiError`，可读取
+`message` 与 `status_code`：
+
+```python
+from openhub_fee import FeeClient, FeeApiError
+
+try:
+    client.fee_consume(uid="u1", module="sec", amount=999, biz_no="x-1")
+except FeeApiError as e:
+    print(e.status_code, e.message)
+```
+
+> openhub 的业务错误响应目前不含 `code` 字段，故 `FeeApiError.code` 恒为 `None`。
+
+## 复用连接
+
+`FeeClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

openhub_fee_sdk-0.1.0/README.md

@@ -0,0 +1,92 @@
+# openhub-fee-sdk
+
+openhub 费用接口的 Python 客户端，基于 `requests` 封装 `/api/fee` 的全部接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。鉴权、字段与错误码见仓库
+根目录 `arch/fee.md` 第 5 节。
+
+> 注意：与 pcs 的费用接口不同，openhub **不开放直接入账**（`recharge`），资金只能经
+> 管理员审核进入账本；SDK 因此不提供 `recharge`，转而提供**半自动收款**的订单类接口
+> （建单 / 上传凭证 / 查单 / 取消）。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install openhub-fee-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk/fee
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk/fee 子目录
+pip install "git+https://github.com/staugur/open-hub.git#subdirectory=sdk/fee"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `openhub_fee/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/fee/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/fee/` 目录的改动会触发自动发布；改 `src/`、`arch/`、`README.md`
+> 等其他目录（含 `sdk/` 下的其他项目，如 `sdk/ipamcli`）不会触发，避免无关改动误发版本。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish-sdk.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/fee/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `openhub-fee-sdk`
+> 项目配置 Trusted Publisher（Owner=`staugur`、Repository name=`open-hub`、
+> Workflow name=`publish-sdk.yml`、Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from openhub_fee import FeeClient
+
+client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="sec")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="sec", limit=50)
+client.fee_modules()
+
+# 费用：按量扣费（仅 postpaid；biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")
+
+# 半自动收款：建单 -> 上传凭证 -> 查单 / 取消
+order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
+client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+client.fee_order_get(order["order_no"])
+client.fee_order_cancel(order["order_no"])
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `openhub_fee.FeeApiError`，可读取
+`message` 与 `status_code`：
+
+```python
+from openhub_fee import FeeClient, FeeApiError
+
+try:
+    client.fee_consume(uid="u1", module="sec", amount=999, biz_no="x-1")
+except FeeApiError as e:
+    print(e.status_code, e.message)
+```
+
+> openhub 的业务错误响应目前不含 `code` 字段，故 `FeeApiError.code` 恒为 `None`。
+
+## 复用连接
+
+`FeeClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

openhub_fee_sdk-0.1.0/api.md

@@ -0,0 +1,291 @@
+# openhub-fee-sdk API 参考
+
+`openhub-fee-sdk` 是 openhub 费用接口（`/api/fee`）的 Python 客户端，基于
+`requests` 封装，统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。
+鉴权、字段与错误码详见仓库根目录 `arch/fee.md` 第 5 节。
+
+> 与 pcs 的费用接口不同，openhub **不开放直接入账**（`recharge`），资金只能经
+> 管理员审核进入账本；SDK 因此不提供 `recharge`，转而提供**半自动收款**的订单类
+> 接口（建单 / 上传凭证 / 查单 / 取消）。
+
+## 安装
+
+```bash
+pip install openhub-fee-sdk
+```
+
+本地开发：`cd sdk/fee && pip install -e .`
+
+## 客户端
+
+```python
+from openhub_fee import FeeClient
+
+client = FeeClient(
+    base_url="https://openhub.example.com",
+    app_id="<APP_ID>",
+    secret="<SECRET>",
+    timeout=10.0,          # 请求超时（秒）
+    session=None,          # 可复用的 requests.Session；缺省自动创建
+)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `base_url` | str | API 根地址，如 `https://openhub.example.com` |
+| `app_id` | str | 调用方标识（对应 `hub_fee_app.app_id`），随 `X-App-Id` 头传输 |
+| `secret` | str | 调用方密钥（与服务端一致），**仅本地签名用，不随请求传输** |
+| `timeout` | float | 请求超时（秒），默认 `10.0` |
+| `session` | Optional[Session] | 自定义 `requests.Session`（代理 / 证书 / 重试策略），缺省自动创建 |
+
+每次请求自动附加签名头：`X-App-Id`、`X-Timestamp`、`X-Nonce`、`X-Signature`、
+`Accept: application/json`。签名串 = `时间戳 + nonce`，用 `secret` 做 HMAC-SHA256
+得到十六进制签名值，每次请求重新生成时间戳与随机 nonce，防重放。
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `FeeApiError`，可读取以下属性：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `message` | str | 错误描述 |
+| `status_code` | Optional[int] | HTTP 状态码 |
+| `code` | Optional[str] | 业务错误码（openhub 响应目前不含此字段，恒为 `None`） |
+
+```python
+from openhub_fee import FeeClient, FeeApiError
+
+try:
+    client.fee_consume(uid="u1", module="sec", amount=999, biz_no="x-1")
+except FeeApiError as e:
+    print(e.status_code, e.message)
+```
+
+## 接口总览
+
+| 方法 | HTTP | 路径 | 分类 |
+|------|------|------|------|
+| `fee_balance` | GET | `/api/fee/balance` | 查询 |
+| `fee_balances` | GET | `/api/fee/balances` | 查询 |
+| `fee_logs` | GET | `/api/fee/logs` | 查询 |
+| `fee_modules` | GET | `/api/fee/modules` | 查询 |
+| `fee_consume` | POST | `/api/fee/consume` | 扣费 |
+| `fee_order_create` | POST | `/api/fee/order` | 订单 |
+| `fee_order_get` | GET | `/api/fee/order` | 订单 |
+| `fee_order_upload_voucher` | POST | `/api/fee/order/voucher` | 订单 |
+| `fee_order_cancel` | POST | `/api/fee/order/cancel` | 订单 |
+
+所有方法在业务成功时返回响应体中的 `data` 字段；失败抛出 `FeeApiError`。
+
+---
+
+## 查询类
+
+### `fee_balance(uid, module) -> Optional[Dict[str, Any]]`
+
+查询某用户的指定模块费用状态（余额 / 生效 / 到期 / 档位）。
+
+- **HTTP**：`GET /api/fee/balance`
+- **查询参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uid` | str | 是 | 用户唯一标识 |
+| `module` | str | 是 | 付费模块标识 |
+
+- **返回**：费用状态对象（dict）；记录不存在时返回 `None`
+
+```python
+balance = client.fee_balance(uid="u1", module="sec")
+```
+
+### `fee_balances(uid, limit=100, offset=0) -> List[Dict[str, Any]]`
+
+查询用户全部模块的费用状态（仅返回本调用方拥有的模块）。
+
+- **HTTP**：`GET /api/fee/balances`
+- **查询参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uid` | str | 是 | 用户唯一标识 |
+| `limit` | int | 否 | 返回条数上限，默认 `100` |
+| `offset` | int | 否 | 偏移量，配合 `limit` 分页，默认 `0` |
+
+- **返回**：费用状态对象列表
+
+```python
+client.fee_balances(uid="u1")
+client.fee_balances(uid="u1", limit=20, offset=0)
+```
+
+### `fee_logs(uid, module=None, limit=50, offset=0) -> List[Dict[str, Any]]`
+
+查询费用流水（充值 / 消费记录，倒序）。
+
+- **HTTP**：`GET /api/fee/logs`
+- **查询参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uid` | str | 是 | 用户唯一标识 |
+| `module` | str | 否 | 模块过滤，为空返回全部模块 |
+| `limit` | int | 否 | 返回条数上限（封顶 `200`），默认 `50` |
+| `offset` | int | 否 | 偏移量，配合 `limit` 分页，默认 `0` |
+
+- **返回**：流水记录列表
+
+```python
+client.fee_logs(uid="u1", module="sec", limit=50)
+```
+
+### `fee_modules(module=None) -> List[Dict[str, Any]]`
+
+查询本调用方拥有的付费模块（含付费类型、档位与档位费用）。
+
+- **HTTP**：`GET /api/fee/modules`
+- **查询参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `module` | str | 否 | 模块过滤，为空返回全部 |
+
+- **返回**：付费模块元数据列表
+
+```python
+client.fee_modules()
+client.fee_modules(module="sec")
+```
+
+---
+
+## 写类：按量扣费
+
+### `fee_consume(uid, module, amount, *, biz_no, remark="") -> Dict[str, Any]`
+
+消费扣减（仅按量付费 `postpaid` 模块，扣减 `balance`）。
+
+- **HTTP**：`POST /api/fee/consume`（JSON 请求体）
+- **请求体字段**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uid` | str | 是 | 用户唯一标识 |
+| `module` | str | 是 | 付费模块标识 |
+| `amount` | float \| str | 是 | 扣减金额（元），须 ≤ 当前余额 |
+| `biz_no` | str | 是 | **幂等键**：重试须复用原值，新动作须换新值 |
+| `remark` | str | 否 | 备注 |
+
+- **返回**：扣减结果（含扣减后余额等字段）
+
+```python
+client.fee_consume(
+    uid="u1", module="sec", amount=30,
+    biz_no="sec-usage-001", remark="收录查询批量",
+)
+```
+
+---
+
+## 半自动收款：订单类接口
+
+### `fee_order_create(uid, module, pay_type, level="", duration_days=0, amount=0, remark="") -> Dict[str, Any]`
+
+代用户创建支付订单，返回订单号与收款指引。
+
+- **HTTP**：`POST /api/fee/order`（JSON 请求体）
+- **请求体字段**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uid` | str | 是 | 用户唯一标识 |
+| `module` | str | 是 | 付费模块标识（须属本调用方） |
+| `pay_type` | str | 是 | 付费类型：`prepaid` / `postpaid` / `lifetime` |
+| `level` | str | 否 | 付费档位（`prepaid` / `lifetime` 使用，可空） |
+| `duration_days` | int | 否 | 周期天数（`prepaid` / `lifetime` 使用） |
+| `amount` | float \| str | 否 | 金额（`postpaid` 由用户填写；其它类型取档位价） |
+| `remark` | str | 否 | 备注 |
+
+- **返回**：订单对象（含 `order_no` 与收款指引）
+
+```python
+order = client.fee_order_create(
+    uid="u1", module="sec", pay_type="prepaid",
+    level="pro", duration_days=365,
+)
+```
+
+### `fee_order_get(order_no) -> Dict[str, Any]`
+
+按订单号查询订单状态（含凭证列表）。
+
+- **HTTP**：`GET /api/fee/order`
+- **查询参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `order_no` | str | 是 | 订单号（付款标识码） |
+
+- **返回**：订单对象（含 `vouchers` 列表）
+
+```python
+client.fee_order_get(order["order_no"])
+```
+
+### `fee_order_upload_voucher(order_no, file, filename=None) -> Dict[str, Any]`
+
+上传支付凭证（multipart，文件域 `file`）。
+
+- **HTTP**：`POST /api/fee/order/voucher`（multipart/form-data）
+- **查询参数**：`order_no`（str，订单号）
+- **文件参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `file` | str \| bytes \| bytearray \| BytesIO | 本地路径、原始字节或类文件对象（需可 `read()`） |
+| `filename` | Optional[str] | 文件名；传路径时自动取 basename，传字节时默认 `voucher.png` |
+
+- **返回**：上传结果
+
+```python
+client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+# 或传入字节 / 类文件对象：
+client.fee_order_upload_voucher(order["order_no"], b"<bytes>", filename="shot.png")
+```
+
+### `fee_order_cancel(order_no) -> Dict[str, Any]`
+
+取消未支付订单。
+
+- **HTTP**：`POST /api/fee/order/cancel`（JSON 请求体）
+- **请求体字段**：`order_no`（str，订单号）
+- **返回**：取消结果
+
+```python
+client.fee_order_cancel(order["order_no"])
+```
+
+---
+
+## 完整示例
+
+```python
+from openhub_fee import FeeClient
+
+client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")
+
+# 查询类
+balance = client.fee_balance(uid="u1", module="sec")
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="sec", limit=50)
+client.fee_modules()
+
+# 按量扣费（biz_no 务必幂等）
+client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")
+
+# 半自动收款：建单 -> 上传凭证 -> 查单 / 取消
+order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
+client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+client.fee_order_get(order["order_no"])
+client.fee_order_cancel(order["order_no"])
+```

openhub_fee_sdk-0.1.0/openhub_fee/__init__.py

@@ -0,0 +1,39 @@
+"""openhub 费用接口客户端 SDK。
+
+基于 ``requests`` 封装 openhub 的 ``/api/fee`` 费用接口，统一处理 HMAC-SHA256
+请求签名、JSON 序列化与错误判定。接口字段、鉴权与错误码见仓库 ``arch/fee.md``。
+
+典型用法::
+
+    from openhub_fee import FeeClient
+
+    client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")
+
+    # 查询余额（记录不存在返回 None）
+    balance = client.fee_balance(uid="u1", module="sec")
+
+    # 查询全部模块状态 / 流水 / 付费模块
+    client.fee_balances(uid="u1")
+    client.fee_logs(uid="u1", module="sec", limit=50)
+    client.fee_modules()
+
+    # 按量扣费（仅 postpaid，biz_no 务必幂等——重试复用原值，新动作换新值）
+    client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")
+
+    # 半自动收款：建单 -> 上传凭证 -> 查询 / 取消
+    order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
+    client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+    client.fee_order_get(order["order_no"])
+    client.fee_order_cancel(order["order_no"])
+"""
+
+from .client import FeeApiError, FeeClient
+
+__all__ = ["FeeClient", "FeeApiError"]
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("openhub-fee-sdk")
+except Exception:  # pragma: no cover - 非安装态（如直接跑源码）回退
+    __version__ = "0.1.0"

openhub_fee_sdk-0.1.0/openhub_fee/client.py

@@ -0,0 +1,317 @@
+"""openhub 费用接口客户端实现。
+
+安全说明
+--------
+``secret`` 只在客户端本地参与 HMAC-SHA256 签名计算，**绝不**随请求发往服务端；
+网络层只传输签名值 ``X-Signature`` 与时间戳 / nonce，因此密钥本身不会泄露。
+服务端使用相同的 ``secret`` 独立验签，实现调用方鉴权（详见仓库 ``arch/fee.md``）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import io
+import time
+from secrets import token_hex
+from typing import Any, Dict, List, Optional, Union
+
+try:
+    import requests
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("openhub-fee-sdk 需要 requests：pip install requests") from exc
+
+
+class FeeApiError(Exception):
+    """API 调用失败（HTTP 错误或非 success 响应）。"""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+    ) -> None:
+        """构造 API 错误。
+
+        :param message: 错误描述
+        :param code: 业务错误码（openhub 响应目前不含此字段，恒为 ``None``）
+        :param status_code: HTTP 状态码，可选
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        if self.code:
+            return "[{}] {}".format(self.code, self.message)
+        return self.message
+
+
+class FeeClient:
+    """openhub 费用接口 HTTP 客户端（``/api/fee``）。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        app_id: str,
+        secret: str,
+        timeout: float = 10.0,
+        session: Optional["requests.Session"] = None,
+    ) -> None:
+        """
+        :param base_url: API 根地址，如 ``https://openhub.example.com``
+        :param app_id: 调用方标识（对应 ``hub_fee_app.app_id``，随 ``X-App-Id`` 头传输）
+        :param secret: 调用方密钥（与服务端 ``secret`` 一致，仅本地签名用，不随请求传输）
+        :param timeout: 请求超时（秒）
+        :param session: 可复用的 ``requests.Session``；缺省自动创建
+        """
+        self._base_url = base_url.rstrip("/")
+        self._app_id = app_id
+        self._secret = secret
+        self._timeout = timeout
+        self._session = session or requests.Session()
+
+    # -- 签名与底层请求 ----------------------------------------------------
+    def _auth_headers(self) -> Dict[str, str]:
+        # 每次请求都重新生成时间戳与随机 nonce，保证签名不可重放
+        ts = str(int(time.time()))
+        nonce = token_hex(8)
+        # 待签名字符串 = 时间戳与 nonce 直接拼接（如 "1700000000a1b2c3d4"），
+        # 用 secret 做 HMAC-SHA256 得到十六进制签名值（与服务端验签算法一致）
+        sign = hmac.new(
+            self._secret.encode("utf-8"),
+            (ts + nonce).encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return {
+            "X-App-Id": self._app_id,
+            "X-Timestamp": ts,
+            "X-Nonce": nonce,
+            "X-Signature": sign,
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """发起一次签名鉴权的 HTTP 请求并统一解析业务响应。
+
+        :param method: HTTP 方法（``GET`` / ``POST`` ...）
+        :param path: 接口路径，如 ``/api/fee/balance``
+        :param params: 查询参数（GET）
+        :param json: 请求体（POST），以 JSON 序列化
+        :param files: 多部分文件（POST 上传凭证用），文件域 ``file``
+        :return: 业务成功时返回响应体中的 ``data`` 字段
+        :rtype: Any
+        :raises FeeApiError: HTTP 错误（>= 400）或业务层 ``success is False`` 时抛出
+        """
+        resp = self._session.request(
+            method,
+            self._base_url + path,
+            params=params,
+            json=json,
+            files=files,
+            headers=self._auth_headers(),
+            timeout=self._timeout,
+        )
+        # 统一解析 JSON：非 JSON 且为错误状态码时直接以原始文本报错
+        try:
+            body = resp.json()
+        except ValueError:
+            if resp.status_code >= 400:
+                raise FeeApiError(
+                    resp.text or "HTTP {}".format(resp.status_code),
+                    status_code=resp.status_code,
+                ) from None
+            raise FeeApiError("invalid json response") from None
+        # 业务层约定：HTTP >= 400 或 body.success is False 都视为失败
+        if resp.status_code >= 400 or body.get("success") is False:
+            raise FeeApiError(
+                body.get("message") or "request failed",
+                code=body.get("code"),
+                status_code=resp.status_code,
+            )
+        return body.get("data")
+
+    # -- 查询类 ------------------------------------------------------------
+    def fee_balance(
+        self, uid: str, module: str
+    ) -> Optional[Dict[str, Any]]:
+        """查询某个用户的指定模块费用状态（余额 / 生效 / 到期 / 档位）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识
+        :return: 费用状态对象（dict）；记录不存在时返回 ``None``
+        :rtype: Optional[Dict[str, Any]]
+        """
+        return self._request(
+            "GET", "/api/fee/balance",
+            params={"uid": uid, "module": module},
+        )
+
+    def fee_balances(
+        self,
+        uid: str,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """查询用户全部模块的费用状态（仅返回本调用方拥有的模块）。
+
+        :param uid: 用户唯一标识
+        :param limit: 返回条数上限
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 费用状态对象列表
+        :rtype: List[Dict[str, Any]]
+        """
+        return self._request(
+            "GET", "/api/fee/balances",
+            params={"uid": uid, "limit": limit, "offset": offset},
+        )
+
+    def fee_logs(
+        self,
+        uid: str,
+        module: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """查询费用流水（充值 / 消费记录，倒序）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识过滤，为空返回全部模块
+        :param limit: 返回条数上限（封顶 200）
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 流水记录列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params: Dict[str, Any] = {
+            "uid": uid, "limit": limit, "offset": offset,
+        }
+        if module:
+            params["module"] = module
+        return self._request("GET", "/api/fee/logs", params=params)
+
+    def fee_modules(
+        self, module: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """查询本调用方拥有的付费模块（含付费类型、档位与档位费用）。
+
+        :param module: 模块标识过滤，为空返回全部
+        :return: 付费模块元数据列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params = {"module": module} if module else None
+        return self._request("GET", "/api/fee/modules", params=params)
+
+    # -- 写类：按量扣费 ----------------------------------------------------
+    def fee_consume(
+        self,
+        uid: str,
+        module: str,
+        amount: Union[float, str],
+        *,
+        biz_no: str,
+        remark: str = "",
+    ) -> Dict[str, Any]:
+        """消费扣减（仅按量付费 ``postpaid`` 模块，扣减 ``balance``）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识
+        :param amount: 扣减金额（元，须 ≤ 当前余额）
+        :param biz_no: 幂等键，重试须复用原值，新动作须换新值
+        :param remark: 备注（可选）
+        :return: 扣减结果（含扣减后余额等字段）
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/fee/consume", json={
+            "uid": uid, "module": module, "amount": amount,
+            "biz_no": biz_no, "remark": remark,
+        })
+
+    # -- 半自动收款：订单 ---------------------------------------------------
+    def fee_order_create(
+        self,
+        uid: str,
+        module: str,
+        pay_type: str,
+        level: str = "",
+        duration_days: int = 0,
+        amount: Union[float, str] = 0,
+        remark: str = "",
+    ) -> Dict[str, Any]:
+        """代用户创建支付订单，返回标识码与收款指引。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识（须属本调用方）
+        :param pay_type: 付费类型 ``prepaid`` / ``postpaid`` / ``lifetime``
+        :param level: 付费档位（``prepaid`` / ``lifetime`` 使用，可空）
+        :param duration_days: 周期天数（``prepaid`` / ``lifetime`` 使用）
+        :param amount: 金额（``postpaid`` 由用户填写；其它类型取档位价）
+        :param remark: 备注（可选）
+        :return: 订单对象（含 ``order_no`` 与收款指引）
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/fee/order", json={
+            "uid": uid, "module": module, "pay_type": pay_type,
+            "level": level, "duration_days": duration_days,
+            "amount": amount, "remark": remark,
+        })
+
+    def fee_order_get(self, order_no: str) -> Dict[str, Any]:
+        """按订单号查询订单状态（含凭证列表）。
+
+        :param order_no: 订单号（付款标识码）
+        :return: 订单对象（含 ``vouchers`` 列表）
+        :rtype: Dict[str, Any]
+        """
+        return self._request(
+            "GET", "/api/fee/order", params={"order_no": order_no}
+        )
+
+    def fee_order_upload_voucher(
+        self,
+        order_no: str,
+        file: Union[str, bytes, bytearray, "io.BytesIO"],
+        filename: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """上传支付凭证（multipart，文件域 ``file``）。
+
+        :param order_no: 订单号
+        :param file: 本地文件路径（str）、原始字节，或类文件对象（已 ``read()`` 可读）
+        :param filename: 文件名（传路径时自动取 basename，传字节时默认 ``voucher.png``）
+        :return: 上传结果
+        :rtype: Dict[str, Any]
+        """
+        if isinstance(file, str):
+            with open(file, "rb") as fp:
+                content = fp.read()
+            name = filename or file.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+        elif isinstance(file, (bytes, bytearray)):
+            content = bytes(file)
+            name = filename or "voucher.png"
+        else:
+            content = file.read()
+            name = filename or "voucher.png"
+        files = {"file": (name, content, "application/octet-stream")}
+        return self._request(
+            "POST", "/api/fee/order/voucher",
+            params={"order_no": order_no}, files=files,
+        )
+
+    def fee_order_cancel(self, order_no: str) -> Dict[str, Any]:
+        """取消未支付订单。
+
+        :param order_no: 订单号
+        :return: 取消结果
+        :rtype: Dict[str, Any]
+        """
+        return self._request(
+            "POST", "/api/fee/order/cancel", json={"order_no": order_no}
+        )

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: openhub-fee-sdk
+Version: 0.1.0
+Summary: openhub 费用接口 Python 客户端（/api/fee），基于 requests 封装 HMAC-SHA256 签名
+Author: staugur
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+
+# openhub-fee-sdk
+
+openhub 费用接口的 Python 客户端，基于 `requests` 封装 `/api/fee` 的全部接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。鉴权、字段与错误码见仓库
+根目录 `arch/fee.md` 第 5 节。
+
+> 注意：与 pcs 的费用接口不同，openhub **不开放直接入账**（`recharge`），资金只能经
+> 管理员审核进入账本；SDK 因此不提供 `recharge`，转而提供**半自动收款**的订单类接口
+> （建单 / 上传凭证 / 查单 / 取消）。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install openhub-fee-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk/fee
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk/fee 子目录
+pip install "git+https://github.com/staugur/open-hub.git#subdirectory=sdk/fee"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `openhub_fee/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/fee/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/fee/` 目录的改动会触发自动发布；改 `src/`、`arch/`、`README.md`
+> 等其他目录（含 `sdk/` 下的其他项目，如 `sdk/ipamcli`）不会触发，避免无关改动误发版本。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish-sdk.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/fee/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `openhub-fee-sdk`
+> 项目配置 Trusted Publisher（Owner=`staugur`、Repository name=`open-hub`、
+> Workflow name=`publish-sdk.yml`、Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from openhub_fee import FeeClient
+
+client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="sec")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="sec", limit=50)
+client.fee_modules()
+
+# 费用：按量扣费（仅 postpaid；biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")
+
+# 半自动收款：建单 -> 上传凭证 -> 查单 / 取消
+order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
+client.fee_order_upload_voucher(order["order_no"], "transfer.png")
+client.fee_order_get(order["order_no"])
+client.fee_order_cancel(order["order_no"])
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `openhub_fee.FeeApiError`，可读取
+`message` 与 `status_code`：
+
+```python
+from openhub_fee import FeeClient, FeeApiError
+
+try:
+    client.fee_consume(uid="u1", module="sec", amount=999, biz_no="x-1")
+except FeeApiError as e:
+    print(e.status_code, e.message)
+```
+
+> openhub 的业务错误响应目前不含 `code` 字段，故 `FeeApiError.code` 恒为 `None`。
+
+## 复用连接
+
+`FeeClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+.gitignore
+README.md
+api.md
+pyproject.toml
+openhub_fee/__init__.py
+openhub_fee/client.py
+openhub_fee_sdk.egg-info/PKG-INFO
+openhub_fee_sdk.egg-info/SOURCES.txt
+openhub_fee_sdk.egg-info/dependency_links.txt
+openhub_fee_sdk.egg-info/requires.txt
+openhub_fee_sdk.egg-info/scm_file_list.json
+openhub_fee_sdk.egg-info/top_level.txt

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.20

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/scm_file_list.json

@@ -0,0 +1,10 @@
+{
+  "files": [
+    ".gitignore",
+    "README.md",
+    "api.md",
+    "openhub_fee/__init__.py",
+    "openhub_fee/client.py",
+    "pyproject.toml"
+  ]
+}

openhub_fee_sdk-0.1.0/openhub_fee_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+openhub_fee

openhub_fee_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openhub-fee-sdk"
+dynamic = ["version"]
+description = "openhub 费用接口 Python 客户端（/api/fee），基于 requests 封装 HMAC-SHA256 签名"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.20"]
+authors = [{ name = "staugur" }]
+
+[tool.setuptools]
+packages = ["openhub_fee"]
+
+# 版本号由 git 自动派生（无需手改 __version__）：
+# - 打了 v* tag（如 v0.1.0）→ 正式版 0.1.0
+# - 开发期手动快速发（workflow_dispatch）→ 0.1.0.dev<日期>（如 0.1.0.dev20261005，
+#   日期取自 UTC，天然唯一、可直发 PyPI；PyPI 要求 PEP 440，故用 .dev 前缀而非连字符）
+# - local_scheme=no-local-version 去掉 +g<sha> 本地后缀（PyPI 会拒收本地版本）
+[tool.setuptools_scm]
+version_scheme = "guess-next-dev"
+local_scheme = "no-local-version"
+fallback_version = "0.1.0"

openhub_fee_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+