zc-center-sdk-python 1.0.0__tar.gz

zc_center_sdk_python-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 liujunlin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

zc_center_sdk_python-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: zc-center-sdk-python
+Version: 1.0.0
+Summary: ZC Center SAPI Python SDK (HMAC-SHA256, AES-256-GCM, exam notice push)
+Author-email: liujunlin <ljl763606865@gmail.com>
+Maintainer-email: liujunlin <ljl763606865@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/763606865/zc-center-sdk-python
+Project-URL: Documentation, https://github.com/763606865/zc-center-sdk-python#readme
+Project-URL: Repository, https://github.com/763606865/zc-center-sdk-python
+Project-URL: Issues, https://github.com/763606865/zc-center-sdk-python/issues
+Project-URL: Changelog, https://github.com/763606865/zc-center-sdk-python/releases
+Keywords: zc-center,sapi,sdk,hmac,aes-gcm,exam-notice,flask
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# ZC Center Python SDK
+
+适用于 Python 3.10+ 的中台 SAPI 服务端 SDK，提供 HMAC-SHA256 请求签名、AES-256-GCM 加解密、响应验签，以及招考公告推送封装。
+
+协议与中台 [`docs/sapi/`](../../docs/sapi/README.md)、ThinkPHP / Spring Boot SDK 保持一致。许可证：Apache-2.0。
+
+`app_secret` 只能保存在爬虫/服务端，禁止写入前端或客户端。
+
+## 安装
+
+PyPI（发布后）：
+
+```bash
+pip install zc-center-sdk
+```
+
+源码开发（推荐虚拟环境，避免 macOS `externally-managed-environment`）：
+
+```bash
+cd sdk/python
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+发布到 PyPI 的完整步骤见 [PUBLISH.md](./PUBLISH.md)。
+
+## 配置
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `ZC_CENTER_BASE_URL` | 中台根地址，如 `https://zc-center.example.com` |
+| `ZC_CENTER_APP_KEY` | 中台应用 `app_key` |
+| `ZC_CENTER_APP_SECRET` | 中台应用 `app_secret` |
+| `ZC_CENTER_ENCRYPTION` | `1`/`0`，须与中台 `SAPI_ENCRYPTION_ENABLED` 一致 |
+
+联调可关闭加密；生产必须开启。
+
+## 爬虫推荐流程
+
+1. 在中台「业务管理 → 应用管理」为爬虫创建生态应用，拿到 `app_key` / `app_secret`，配置 IP 白名单。
+2. 爬虫抓取并组合数据后，**不要依赖中台扫盘读 JSON**；直接调用 `exam_notice.report_batch`。
+3. 每条至少传 `title`、`collect_source`；强烈建议再传稳定幂等键之一：
+   - `uuid`（来源系统 UUID v4）
+   - 或 `collect_ref`（来源站点内唯一 ID）
+   - 或稳定的 `official_url` / `collect_url`
+4. 单次最多 100 条；示例脚本会自动分批。
+
+### 代码示例
+
+```python
+from zc_center import Client
+
+client = Client(
+    base_url="https://zc-center.example.com",
+    app_key="...",
+    app_secret="...",
+    encryption=True,
+)
+
+client.ping().send("crawler-ready")
+
+result = client.exam_notice().report_batch([
+    {
+        "title": "某市事业单位招聘公告",
+        "collect_source": "某市人社局",
+        "collect_ref": "src-2026-001",
+        "official_url": "https://example.com/notices/1",
+        "publish_time": 1788888888,
+        "content": "<p>公告正文</p>",
+    }
+]).data()
+
+print(result["created"], result["exists"], result["failed"])
+```
+
+Flask 等框架无特殊依赖，在服务端任务里直接 `from zc_center import Client` 即可。
+
+### 一键推送 JSON 文件
+
+```bash
+export ZC_CENTER_BASE_URL=https://zc-center.example.com
+export ZC_CENTER_APP_KEY=...
+export ZC_CENTER_APP_SECRET=...
+
+python examples/push_exam_notices.py /data/crawler/notices-2026-09-09.json
+```
+
+JSON 支持数组，或 `{"items":[...]}` / `{"list":[...]}`。
+
+## 字段约定（招考公告）
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `title` | 是 | 公告标题 |
+| `collect_source` | 是 | 采集来源站点/单位名 |
+| `uuid` | 推荐 | UUID v4，来源稳定 ID |
+| `collect_ref` | 推荐 | 来源侧业务主键 |
+| `official_url` / `collect_url` | 推荐 | 用于排重 |
+| `code` / `exam_type` / `area_code` | 否 | 业务编码、招考类型、地区码 |
+| `publisher_name` / `summary` / `content` | 否 | 发布单位、摘要、正文 |
+| `publish_time` 等时间字段 | 否 | Unix 秒；也可传可解析时间字符串 |
+
+排重优先级见 [`docs/sapi/招考公告.md`](../../docs/sapi/招考公告.md)。
+
+## 与「扫盘导入」的关系
+
+本 SDK 走推模式：爬虫写完即上报。中台无需再为「几点读哪个目录」建配置表；若仍保留本地 JSON，仅作备份或对账即可。

zc_center_sdk_python-1.0.0/README.md

@@ -0,0 +1,110 @@
+# ZC Center Python SDK
+
+适用于 Python 3.10+ 的中台 SAPI 服务端 SDK，提供 HMAC-SHA256 请求签名、AES-256-GCM 加解密、响应验签，以及招考公告推送封装。
+
+协议与中台 [`docs/sapi/`](../../docs/sapi/README.md)、ThinkPHP / Spring Boot SDK 保持一致。许可证：Apache-2.0。
+
+`app_secret` 只能保存在爬虫/服务端，禁止写入前端或客户端。
+
+## 安装
+
+PyPI（发布后）：
+
+```bash
+pip install zc-center-sdk
+```
+
+源码开发（推荐虚拟环境，避免 macOS `externally-managed-environment`）：
+
+```bash
+cd sdk/python
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+发布到 PyPI 的完整步骤见 [PUBLISH.md](./PUBLISH.md)。
+
+## 配置
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `ZC_CENTER_BASE_URL` | 中台根地址，如 `https://zc-center.example.com` |
+| `ZC_CENTER_APP_KEY` | 中台应用 `app_key` |
+| `ZC_CENTER_APP_SECRET` | 中台应用 `app_secret` |
+| `ZC_CENTER_ENCRYPTION` | `1`/`0`，须与中台 `SAPI_ENCRYPTION_ENABLED` 一致 |
+
+联调可关闭加密；生产必须开启。
+
+## 爬虫推荐流程
+
+1. 在中台「业务管理 → 应用管理」为爬虫创建生态应用，拿到 `app_key` / `app_secret`，配置 IP 白名单。
+2. 爬虫抓取并组合数据后，**不要依赖中台扫盘读 JSON**；直接调用 `exam_notice.report_batch`。
+3. 每条至少传 `title`、`collect_source`；强烈建议再传稳定幂等键之一：
+   - `uuid`（来源系统 UUID v4）
+   - 或 `collect_ref`（来源站点内唯一 ID）
+   - 或稳定的 `official_url` / `collect_url`
+4. 单次最多 100 条；示例脚本会自动分批。
+
+### 代码示例
+
+```python
+from zc_center import Client
+
+client = Client(
+    base_url="https://zc-center.example.com",
+    app_key="...",
+    app_secret="...",
+    encryption=True,
+)
+
+client.ping().send("crawler-ready")
+
+result = client.exam_notice().report_batch([
+    {
+        "title": "某市事业单位招聘公告",
+        "collect_source": "某市人社局",
+        "collect_ref": "src-2026-001",
+        "official_url": "https://example.com/notices/1",
+        "publish_time": 1788888888,
+        "content": "<p>公告正文</p>",
+    }
+]).data()
+
+print(result["created"], result["exists"], result["failed"])
+```
+
+Flask 等框架无特殊依赖，在服务端任务里直接 `from zc_center import Client` 即可。
+
+### 一键推送 JSON 文件
+
+```bash
+export ZC_CENTER_BASE_URL=https://zc-center.example.com
+export ZC_CENTER_APP_KEY=...
+export ZC_CENTER_APP_SECRET=...
+
+python examples/push_exam_notices.py /data/crawler/notices-2026-09-09.json
+```
+
+JSON 支持数组，或 `{"items":[...]}` / `{"list":[...]}`。
+
+## 字段约定（招考公告）
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `title` | 是 | 公告标题 |
+| `collect_source` | 是 | 采集来源站点/单位名 |
+| `uuid` | 推荐 | UUID v4，来源稳定 ID |
+| `collect_ref` | 推荐 | 来源侧业务主键 |
+| `official_url` / `collect_url` | 推荐 | 用于排重 |
+| `code` / `exam_type` / `area_code` | 否 | 业务编码、招考类型、地区码 |
+| `publisher_name` / `summary` / `content` | 否 | 发布单位、摘要、正文 |
+| `publish_time` 等时间字段 | 否 | Unix 秒；也可传可解析时间字符串 |
+
+排重优先级见 [`docs/sapi/招考公告.md`](../../docs/sapi/招考公告.md)。
+
+## 与「扫盘导入」的关系
+
+本 SDK 走推模式：爬虫写完即上报。中台无需再为「几点读哪个目录」建配置表；若仍保留本地 JSON，仅作备份或对账即可。

zc_center_sdk_python-1.0.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zc-center-sdk-python"
+version = "1.0.0"
+description = "ZC Center SAPI Python SDK (HMAC-SHA256, AES-256-GCM, exam notice push)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+  { name = "liujunlin", email = "ljl763606865@gmail.com" },
+]
+maintainers = [
+  { name = "liujunlin", email = "ljl763606865@gmail.com" },
+]
+keywords = [
+  "zc-center",
+  "sapi",
+  "sdk",
+  "hmac",
+  "aes-gcm",
+  "exam-notice",
+  "flask",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "requests>=2.31.0",
+  "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "build>=1.2",
+  "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/763606865/zc-center-sdk-python"
+Documentation = "https://github.com/763606865/zc-center-sdk-python#readme"
+Repository = "https://github.com/763606865/zc-center-sdk-python"
+Issues = "https://github.com/763606865/zc-center-sdk-python/issues"
+Changelog = "https://github.com/763606865/zc-center-sdk-python/releases"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["zc_center*"]
+
+[tool.setuptools.package-data]
+zc_center = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

zc_center_sdk_python-1.0.0/setup.cfg

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

zc_center_sdk_python-1.0.0/src/zc_center/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from .client import Client
+from .exceptions import (
+    ApiException,
+    CryptoException,
+    SapiException,
+    SignatureException,
+    TransportException,
+)
+from .response import Response
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Client",
+    "Response",
+    "SapiException",
+    "ApiException",
+    "CryptoException",
+    "SignatureException",
+    "TransportException",
+    "__version__",
+]

zc_center_sdk_python-1.0.0/src/zc_center/api/__init__.py

@@ -0,0 +1,5 @@
+from .abstract import AbstractApi
+from .exam_notice import ExamNoticeApi
+from .ping import PingApi
+
+__all__ = ["AbstractApi", "ExamNoticeApi", "PingApi"]

zc_center_sdk_python-1.0.0/src/zc_center/api/abstract.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+from ..response import Response
+
+if TYPE_CHECKING:
+    from ..client import Client
+
+
+class AbstractApi:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def post(self, path: str, payload: Mapping[str, Any] | None = None) -> Response:
+        return self._client.post(path, payload or {})

zc_center_sdk_python-1.0.0/src/zc_center/api/exam_notice.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from ..response import Response
+from .abstract import AbstractApi
+
+
+class ExamNoticeApi(AbstractApi):
+    def list(self, params: Mapping[str, Any] | None = None) -> Response:
+        return self.post("/sapi/exam-notice/list", dict(params or {}))
+
+    def report(self, notice: Mapping[str, Any]) -> Response:
+        return self.post("/sapi/exam-notice/report", dict(notice))
+
+    def report_batch(self, items: Sequence[Mapping[str, Any]]) -> Response:
+        return self.post("/sapi/exam-notice/report-batch", {"items": list(items)})

zc_center_sdk_python-1.0.0/src/zc_center/api/ping.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from ..response import Response
+from .abstract import AbstractApi
+
+
+class PingApi(AbstractApi):
+    def send(self, echo: str = "ping") -> Response:
+        return self.post("/sapi/ping", {"echo": echo})

zc_center_sdk_python-1.0.0/src/zc_center/client.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable, Mapping
+from urllib.parse import urlparse
+
+import requests
+
+from .api.exam_notice import ExamNoticeApi
+from .api.ping import PingApi
+from .crypto import Crypto
+from .exceptions import (
+    ApiException,
+    CryptoException,
+    SapiException,
+    SignatureException,
+    TransportException,
+)
+from .response import Response
+
+Logger = Callable[[str, Mapping[str, Any]], None]
+
+
+class Client:
+    """ZC Center SAPI 客户端：签名、加解密、验签与业务入口。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        app_key: str,
+        app_secret: str,
+        encryption: bool = True,
+        timeout: float = 10.0,
+        connect_timeout: float = 3.0,
+        verify_ssl: bool = True,
+        debug: bool = False,
+        logger: Logger | None = None,
+        session: requests.Session | None = None,
+        crypto: Crypto | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.app_key = app_key.strip()
+        self.app_secret = app_secret
+        self.encryption = encryption
+        self.timeout = (connect_timeout, timeout)
+        self.verify_ssl = verify_ssl
+        self.debug = debug
+        self._logger = logger
+        self._session = session or requests.Session()
+        self._crypto = crypto or Crypto()
+        self._apis: dict[type[Any], Any] = {}
+
+        parsed = urlparse(self.base_url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise SapiException("ZC Center SDK的base_url配置无效")
+        if not self.app_key or not self.app_secret:
+            raise SapiException("ZC Center SDK的app_key或app_secret未配置")
+
+    def ping(self) -> PingApi:
+        return self._api(PingApi)
+
+    def exam_notice(self) -> ExamNoticeApi:
+        return self._api(ExamNoticeApi)
+
+    def get(self, path: str, query: Mapping[str, Any] | None = None) -> Response:
+        return self.request("GET", path, {}, query or {})
+
+    def post(
+        self,
+        path: str,
+        payload: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+    ) -> Response:
+        return self.request("POST", path, payload or {}, query or {})
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+    ) -> Response:
+        path = "/" + path.lstrip("/")
+        if not path.startswith("/sapi/"):
+            raise SapiException("SAPI请求路径必须以/sapi/开头")
+
+        payload = dict(payload or {})
+        query = dict(query or {})
+        timestamp = str(int(time.time()))
+        nonce = self._crypto.nonce()
+        aad = self._crypto.aad(self.app_key, timestamp, nonce)
+
+        try:
+            body_obj: Mapping[str, Any] = (
+                self._crypto.encrypt(payload, self.app_secret, aad) if self.encryption else payload
+            )
+            body = self._crypto.json_encode(body_obj)
+        except (CryptoException, TypeError, ValueError) as exc:
+            raise SapiException("SAPI请求JSON编码或加密失败") from exc
+
+        canonical = self._crypto.canonical_request(method, path, query, timestamp, nonce, body)
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "X-App-Key": self.app_key,
+            "X-Timestamp": timestamp,
+            "X-Nonce": nonce,
+            "X-Signature": self._crypto.sign(canonical, self.app_secret),
+            "X-Encrypted": "1" if self.encryption else "0",
+        }
+        url = self.base_url + path
+
+        self._log(
+            "SAPI request",
+            {
+                "method": method.upper(),
+                "url": url,
+                "query": query,
+                "request_headers": headers,
+                "request_params": payload,
+            },
+        )
+
+        try:
+            http_response = self._session.request(
+                method=method.upper(),
+                url=url,
+                params=query or None,
+                data=body.encode("utf-8"),
+                headers=headers,
+                timeout=self.timeout,
+                verify=self.verify_ssl,
+            )
+        except requests.RequestException as exc:
+            self._log(
+                "SAPI request transport error",
+                {"method": method.upper(), "url": url, "error": str(exc)},
+            )
+            raise TransportException(f"SAPI网络请求失败：{exc}") from exc
+
+        return self._parse_response(http_response, timestamp, nonce, aad)
+
+    def _parse_response(
+        self,
+        response: requests.Response,
+        timestamp: str,
+        nonce: str,
+        aad: str,
+    ) -> Response:
+        raw_body = response.text
+        status_code = response.status_code
+        response_headers = {k: v for k, v in response.headers.items()}
+        signature = (response.headers.get("X-Response-Signature") or "").strip()
+        encrypted = (response.headers.get("X-Encrypted") or "") == "1"
+
+        self._log(
+            "SAPI response",
+            {
+                "http_status": status_code,
+                "response_headers": response_headers,
+            },
+        )
+
+        try:
+            decoded = json.loads(raw_body) if raw_body else None
+        except json.JSONDecodeError as exc:
+            raise TransportException("SAPI响应不是有效JSON") from exc
+        if not isinstance(decoded, dict):
+            raise TransportException("SAPI响应必须是JSON对象")
+
+        if signature == "":
+            if status_code >= 400:
+                raise self._api_exception(decoded, status_code, False)
+            raise SignatureException("SAPI响应缺少X-Response-Signature")
+
+        if encrypted:
+            if not self._crypto.verify_encrypted_response(
+                decoded, signature, timestamp, nonce, self.app_secret
+            ):
+                raise SignatureException("SAPI加密响应签名验证失败")
+            try:
+                payload = self._crypto.decrypt(decoded, self.app_secret, aad)
+            except CryptoException as exc:
+                raise SapiException("SAPI响应解密失败") from exc
+        else:
+            if not self._crypto.verify_plaintext_response(
+                raw_body, signature, timestamp, nonce, self.app_secret
+            ):
+                raise SignatureException("SAPI明文响应签名验证失败")
+            payload = decoded
+
+        self._log(
+            "SAPI response payload",
+            {"http_status": status_code, "response_payload": payload},
+        )
+
+        if status_code >= 400 or int(payload.get("code") or 0) != 0:
+            raise self._api_exception(payload, status_code, True)
+
+        return Response(status_code, payload, response_headers, raw_body)
+
+    def _api_exception(
+        self,
+        payload: Mapping[str, Any],
+        http_status: int,
+        signature_verified: bool,
+    ) -> ApiException:
+        data = payload.get("data")
+        return ApiException(
+            str(payload.get("msg") or "SAPI接口调用失败"),
+            code=int(payload.get("code") or 0),
+            http_status=http_status,
+            data=data if isinstance(data, (dict, list)) else None,
+            signature_verified=signature_verified,
+        )
+
+    def _api(self, api_cls: type[Any]) -> Any:
+        if api_cls not in self._apis:
+            self._apis[api_cls] = api_cls(self)
+        return self._apis[api_cls]
+
+    def _log(self, message: str, context: Mapping[str, Any]) -> None:
+        if not self.debug:
+            return
+        if self._logger is not None:
+            self._logger(message, context)
+            return
+        logging.getLogger("zc_center").info("%s %s", message, json.dumps(context, ensure_ascii=False))

zc_center_sdk_python-1.0.0/src/zc_center/crypto.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+from typing import Any, Mapping
+from urllib.parse import quote
+
+from .exceptions import CryptoException
+
+
+class Crypto:
+    """与 ThinkPHP / Spring Boot SDK 对齐的签名与 AES-GCM 工具。"""
+
+    def encrypt(self, payload: Mapping[str, Any], app_secret: str, aad: str) -> dict[str, str]:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+        plaintext = self.json_encode(payload).encode("utf-8")
+        iv = secrets.token_bytes(12)
+        aesgcm = AESGCM(self._key(app_secret))
+        sealed = aesgcm.encrypt(iv, plaintext, aad.encode("utf-8"))
+        ciphertext, tag = sealed[:-16], sealed[-16:]
+        return {
+            "algorithm": "AES-256-GCM",
+            "ciphertext": base64.b64encode(ciphertext).decode("ascii"),
+            "iv": base64.b64encode(iv).decode("ascii"),
+            "tag": base64.b64encode(tag).decode("ascii"),
+        }
+
+    def decrypt(self, envelope: Mapping[str, Any], app_secret: str, aad: str) -> dict[str, Any]:
+        from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+        for field in ("ciphertext", "iv", "tag"):
+            value = envelope.get(field)
+            if not isinstance(value, str) or value == "":
+                raise CryptoException(f"SAPI加密响应缺少字段：{field}")
+
+        try:
+            ciphertext = base64.b64decode(envelope["ciphertext"], validate=True)
+            iv = base64.b64decode(envelope["iv"], validate=True)
+            tag = base64.b64decode(envelope["tag"], validate=True)
+        except Exception as exc:  # noqa: BLE001
+            raise CryptoException("SAPI加密响应格式错误") from exc
+
+        if len(iv) != 12 or len(tag) != 16:
+            raise CryptoException("SAPI加密响应格式错误")
+
+        aesgcm = AESGCM(self._key(app_secret))
+        try:
+            plaintext = aesgcm.decrypt(iv, ciphertext + tag, aad.encode("utf-8"))
+        except Exception as exc:  # noqa: BLE001
+            raise CryptoException("SAPI响应解密或完整性验证失败") from exc
+
+        try:
+            payload = json.loads(plaintext.decode("utf-8"))
+        except json.JSONDecodeError as exc:
+            raise CryptoException("SAPI解密响应不是JSON对象") from exc
+        if not isinstance(payload, dict):
+            raise CryptoException("SAPI解密响应不是JSON对象")
+        return payload
+
+    def canonical_request(
+        self,
+        method: str,
+        path: str,
+        query: Mapping[str, Any],
+        timestamp: str,
+        nonce: str,
+        raw_body: str,
+    ) -> str:
+        normalized_path = "/" + path.lstrip("/")
+        canonical_query = self._canonical_query(query)
+        return "\n".join(
+            [
+                method.upper(),
+                normalized_path,
+                canonical_query,
+                timestamp,
+                nonce,
+                self.sha256_hex(raw_body),
+            ]
+        )
+
+    def sign(self, canonical: str, app_secret: str) -> str:
+        return hmac.new(app_secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    def aad(self, app_key: str, timestamp: str, nonce: str) -> str:
+        return "\n".join([app_key, timestamp, nonce])
+
+    def verify_encrypted_response(
+        self,
+        envelope: Mapping[str, Any],
+        signature: str,
+        timestamp: str,
+        nonce: str,
+        app_secret: str,
+    ) -> bool:
+        for field in ("iv", "tag", "ciphertext"):
+            if not isinstance(envelope.get(field), str):
+                return False
+        canonical = "\n".join(
+            [
+                timestamp,
+                nonce,
+                str(envelope["iv"]),
+                str(envelope["tag"]),
+                str(envelope["ciphertext"]),
+            ]
+        )
+        expected = self.sign(canonical, app_secret)
+        return signature != "" and hmac.compare_digest(expected, signature.lower())
+
+    def verify_plaintext_response(
+        self,
+        raw_body: str,
+        signature: str,
+        timestamp: str,
+        nonce: str,
+        app_secret: str,
+    ) -> bool:
+        canonical = "\n".join([timestamp, nonce, self.sha256_hex(raw_body)])
+        expected = self.sign(canonical, app_secret)
+        return signature != "" and hmac.compare_digest(expected, signature.lower())
+
+    def json_encode(self, payload: Mapping[str, Any] | list[Any]) -> str:
+        return json.dumps(payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+
+    def nonce(self) -> str:
+        # 与 PHP rtrim(strtr(base64_encode(random_bytes(18)), '+/', '-_'), '=') 等价
+        raw = base64.b64encode(secrets.token_bytes(18)).decode("ascii")
+        return raw.translate(str.maketrans("+/", "-_")).rstrip("=")
+
+    def sha256_hex(self, value: str) -> str:
+        return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+    def _key(self, app_secret: str) -> bytes:
+        return hashlib.sha256(app_secret.encode("utf-8")).digest()
+
+    def _canonical_query(self, query: Mapping[str, Any]) -> str:
+        if not query:
+            return ""
+        parts: list[str] = []
+        for key in sorted(query.keys()):
+            value = query[key]
+            if value is None:
+                continue
+            encoded_key = quote(str(key), safe="-_.~")
+            encoded_value = quote(str(value), safe="-_.~")
+            parts.append(f"{encoded_key}={encoded_value}")
+        return "&".join(parts)

zc_center_sdk_python-1.0.0/src/zc_center/exceptions.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+
+class SapiException(Exception):
+    """SDK / 协议层异常基类。"""
+
+
+class CryptoException(SapiException):
+    """加解密失败。"""
+
+
+class SignatureException(SapiException):
+    """请求或响应签名校验失败。"""
+
+
+class TransportException(SapiException):
+    """网络或响应格式错误。"""
+
+
+class ApiException(SapiException):
+    """业务接口返回非成功。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int = 0,
+        http_status: int = 0,
+        data: object | None = None,
+        signature_verified: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.http_status = http_status
+        self.data = data
+        self.signature_verified = signature_verified

zc_center_sdk_python-1.0.0/src/zc_center/py.typed

@@ -0,0 +1 @@
+# marker for PEP 561 typed package

zc_center_sdk_python-1.0.0/src/zc_center/response.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class Response:
+    def __init__(
+        self,
+        status_code: int,
+        payload: Mapping[str, Any],
+        headers: Mapping[str, str],
+        raw_body: str,
+    ) -> None:
+        self._status_code = status_code
+        self._payload = dict(payload)
+        self._headers = dict(headers)
+        self._raw_body = raw_body
+
+    def status_code(self) -> int:
+        return self._status_code
+
+    def payload(self) -> dict[str, Any]:
+        return self._payload
+
+    def data(self) -> Any:
+        return self._payload.get("data")
+
+    def message(self) -> str:
+        return str(self._payload.get("msg") or "")
+
+    def headers(self) -> dict[str, str]:
+        return self._headers
+
+    def raw_body(self) -> str:
+        return self._raw_body

zc_center_sdk_python-1.0.0/src/zc_center_sdk_python.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: zc-center-sdk-python
+Version: 1.0.0
+Summary: ZC Center SAPI Python SDK (HMAC-SHA256, AES-256-GCM, exam notice push)
+Author-email: liujunlin <ljl763606865@gmail.com>
+Maintainer-email: liujunlin <ljl763606865@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/763606865/zc-center-sdk-python
+Project-URL: Documentation, https://github.com/763606865/zc-center-sdk-python#readme
+Project-URL: Repository, https://github.com/763606865/zc-center-sdk-python
+Project-URL: Issues, https://github.com/763606865/zc-center-sdk-python/issues
+Project-URL: Changelog, https://github.com/763606865/zc-center-sdk-python/releases
+Keywords: zc-center,sapi,sdk,hmac,aes-gcm,exam-notice,flask
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# ZC Center Python SDK
+
+适用于 Python 3.10+ 的中台 SAPI 服务端 SDK，提供 HMAC-SHA256 请求签名、AES-256-GCM 加解密、响应验签，以及招考公告推送封装。
+
+协议与中台 [`docs/sapi/`](../../docs/sapi/README.md)、ThinkPHP / Spring Boot SDK 保持一致。许可证：Apache-2.0。
+
+`app_secret` 只能保存在爬虫/服务端，禁止写入前端或客户端。
+
+## 安装
+
+PyPI（发布后）：
+
+```bash
+pip install zc-center-sdk
+```
+
+源码开发（推荐虚拟环境，避免 macOS `externally-managed-environment`）：
+
+```bash
+cd sdk/python
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+发布到 PyPI 的完整步骤见 [PUBLISH.md](./PUBLISH.md)。
+
+## 配置
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `ZC_CENTER_BASE_URL` | 中台根地址，如 `https://zc-center.example.com` |
+| `ZC_CENTER_APP_KEY` | 中台应用 `app_key` |
+| `ZC_CENTER_APP_SECRET` | 中台应用 `app_secret` |
+| `ZC_CENTER_ENCRYPTION` | `1`/`0`，须与中台 `SAPI_ENCRYPTION_ENABLED` 一致 |
+
+联调可关闭加密；生产必须开启。
+
+## 爬虫推荐流程
+
+1. 在中台「业务管理 → 应用管理」为爬虫创建生态应用，拿到 `app_key` / `app_secret`，配置 IP 白名单。
+2. 爬虫抓取并组合数据后，**不要依赖中台扫盘读 JSON**；直接调用 `exam_notice.report_batch`。
+3. 每条至少传 `title`、`collect_source`；强烈建议再传稳定幂等键之一：
+   - `uuid`（来源系统 UUID v4）
+   - 或 `collect_ref`（来源站点内唯一 ID）
+   - 或稳定的 `official_url` / `collect_url`
+4. 单次最多 100 条；示例脚本会自动分批。
+
+### 代码示例
+
+```python
+from zc_center import Client
+
+client = Client(
+    base_url="https://zc-center.example.com",
+    app_key="...",
+    app_secret="...",
+    encryption=True,
+)
+
+client.ping().send("crawler-ready")
+
+result = client.exam_notice().report_batch([
+    {
+        "title": "某市事业单位招聘公告",
+        "collect_source": "某市人社局",
+        "collect_ref": "src-2026-001",
+        "official_url": "https://example.com/notices/1",
+        "publish_time": 1788888888,
+        "content": "<p>公告正文</p>",
+    }
+]).data()
+
+print(result["created"], result["exists"], result["failed"])
+```
+
+Flask 等框架无特殊依赖，在服务端任务里直接 `from zc_center import Client` 即可。
+
+### 一键推送 JSON 文件
+
+```bash
+export ZC_CENTER_BASE_URL=https://zc-center.example.com
+export ZC_CENTER_APP_KEY=...
+export ZC_CENTER_APP_SECRET=...
+
+python examples/push_exam_notices.py /data/crawler/notices-2026-09-09.json
+```
+
+JSON 支持数组，或 `{"items":[...]}` / `{"list":[...]}`。
+
+## 字段约定（招考公告）
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `title` | 是 | 公告标题 |
+| `collect_source` | 是 | 采集来源站点/单位名 |
+| `uuid` | 推荐 | UUID v4，来源稳定 ID |
+| `collect_ref` | 推荐 | 来源侧业务主键 |
+| `official_url` / `collect_url` | 推荐 | 用于排重 |
+| `code` / `exam_type` / `area_code` | 否 | 业务编码、招考类型、地区码 |
+| `publisher_name` / `summary` / `content` | 否 | 发布单位、摘要、正文 |
+| `publish_time` 等时间字段 | 否 | Unix 秒；也可传可解析时间字符串 |
+
+排重优先级见 [`docs/sapi/招考公告.md`](../../docs/sapi/招考公告.md)。
+
+## 与「扫盘导入」的关系
+
+本 SDK 走推模式：爬虫写完即上报。中台无需再为「几点读哪个目录」建配置表；若仍保留本地 JSON，仅作备份或对账即可。

zc_center_sdk_python-1.0.0/src/zc_center_sdk_python.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/zc_center/__init__.py
+src/zc_center/client.py
+src/zc_center/crypto.py
+src/zc_center/exceptions.py
+src/zc_center/py.typed
+src/zc_center/response.py
+src/zc_center/api/__init__.py
+src/zc_center/api/abstract.py
+src/zc_center/api/exam_notice.py
+src/zc_center/api/ping.py
+src/zc_center_sdk_python.egg-info/PKG-INFO
+src/zc_center_sdk_python.egg-info/SOURCES.txt
+src/zc_center_sdk_python.egg-info/dependency_links.txt
+src/zc_center_sdk_python.egg-info/requires.txt
+src/zc_center_sdk_python.egg-info/top_level.txt
+tests/test_crypto.py

zc_center_sdk_python-1.0.0/src/zc_center_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zc_center_sdk_python-1.0.0/src/zc_center_sdk_python.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.31.0
+cryptography>=42.0.0
+
+[dev]
+pytest>=7.0
+build>=1.2
+twine>=5.0

zc_center_sdk_python-1.0.0/src/zc_center_sdk_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+zc_center

zc_center_sdk_python-1.0.0/tests/test_crypto.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from zc_center.crypto import Crypto
+
+
+def test_canonical_request_matches_thinkphp_fixture() -> None:
+    crypto = Crypto()
+    query = {"z": "最后", "a": "first value"}
+    body = '{"echo":"hello"}'
+    canonical = crypto.canonical_request(
+        "post",
+        "/sapi/ping",
+        query,
+        "1787823238",
+        "g3N4RKzB9QMHYVqE4-ug_SDl",
+        body,
+    )
+    expected = (
+        "POST\n/sapi/ping\na=first%20value&z=%E6%9C%80%E5%90%8E\n"
+        "1787823238\ng3N4RKzB9QMHYVqE4-ug_SDl\n"
+        + crypto.sha256_hex(body)
+    )
+    assert canonical == expected
+
+
+def test_aes_gcm_round_trip() -> None:
+    crypto = Crypto()
+    secret = "sdk-test-secret"
+    aad = crypto.aad("sdk-test-app-key", "1787823238", "g3N4RKzB9QMHYVqE4-ug_SDl")
+    payload = {"hello": "世界"}
+
+    envelope = crypto.encrypt(payload, secret, aad)
+    decrypted = crypto.decrypt(envelope, secret, aad)
+    assert decrypted == payload
+
+    signature = crypto.sign(
+        "\n".join(
+            [
+                "1787823238",
+                "g3N4RKzB9QMHYVqE4-ug_SDl",
+                envelope["iv"],
+                envelope["tag"],
+                envelope["ciphertext"],
+            ]
+        ),
+        secret,
+    )
+    assert crypto.verify_encrypted_response(
+        envelope, signature, "1787823238", "g3N4RKzB9QMHYVqE4-ug_SDl", secret
+    )