isud-tm 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,40 @@
1
+ name: Build and publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ test:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: "3.11"
19
+ - name: Install dev deps
20
+ run: python -m pip install -U pip build pytest httpx
21
+ - name: Contract tests
22
+ run: PYTHONPATH=src python -m pytest tests -q
23
+
24
+ publish:
25
+ needs: test
26
+ runs-on: ubuntu-latest
27
+ environment: pypi
28
+ permissions:
29
+ id-token: write
30
+ steps:
31
+ - uses: actions/checkout@v4
32
+ - uses: actions/setup-python@v5
33
+ with:
34
+ python-version: "3.11"
35
+ - name: Build sdist + wheel
36
+ run: |
37
+ python -m pip install -U pip build
38
+ python -m build
39
+ - name: Publish (Trusted Publisher / OIDC, no token)
40
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,16 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ *.egg-info/
8
+ build/
9
+ dist/
10
+ .venv/
11
+ venv/
12
+ .env
13
+ .env.*
14
+ !.env.example
15
+ *.log
16
+ .DS_Store
isud_tm-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 优标宝开放平台 (isud.cn)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
isud_tm-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.5
2
+ Name: isud-tm
3
+ Version: 1.0.0
4
+ Summary: 优标宝商标数据开放 API 的 Python SDK(商标排查/档案查询/外观设计的契约驱动客户端)
5
+ Project-URL: Homepage, https://docs.isud.cn/
6
+ Project-URL: Documentation, https://docs.isud.cn/docs/quickstart
7
+ Project-URL: Repository, https://github.com/isud-opensource/isud-sdk-python
8
+ Project-URL: Issues, https://github.com/isud-opensource/isud-sdk-python/issues
9
+ Author-email: 优标宝开放平台 <opensource@isud.cn>
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 优标宝开放平台 (isud.cn)
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: ip,sdk,trademark,商标,知识产权
33
+ Classifier: Development Status :: 4 - Beta
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: License :: OSI Approved :: MIT License
36
+ Classifier: Programming Language :: Python :: 3
37
+ Classifier: Programming Language :: Python :: 3.9
38
+ Classifier: Programming Language :: Python :: 3.10
39
+ Classifier: Programming Language :: Python :: 3.11
40
+ Classifier: Programming Language :: Python :: 3.12
41
+ Classifier: Programming Language :: Python :: 3.13
42
+ Requires-Python: >=3.9
43
+ Requires-Dist: httpx<1,>=0.24
44
+ Provides-Extra: dev
45
+ Requires-Dist: datamodel-code-generator>=0.20; extra == 'dev'
46
+ Requires-Dist: pytest>=7; extra == 'dev'
47
+ Description-Content-Type: text/markdown
48
+
49
+ # isud-tm
50
+
51
+ [![PyPI version](https://img.shields.io/pypi/v/isud-tm)](https://pypi.org/project/isud-tm/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/isud-tm)](https://pypi.org/project/isud-tm/)
53
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
54
+
55
+ 优标宝商标数据开放 API 的 Python SDK —— 商标排查、档案查询、外观设计的**契约驱动**客户端。
56
+
57
+ - **依赖极简**:运行时只要 `httpx`
58
+ - **契约驱动**:数据模型从 [OpenAPI 3.1 契约](https://docs.isud.cn/openapi.yaml) 自动生成
59
+ - **体验完整**:自动 Retry-After 退避、幂等键、扣点回读、分页迭代、友好异常
60
+
61
+ > 密钥从[控制台](https://app.isud.cn)创建(**注册即送调用次数**),仅创建时完整展示一次。
62
+
63
+ ## 安装
64
+
65
+ ```bash
66
+ pip install isud-tm
67
+ ```
68
+
69
+ ## 3 分钟上手
70
+
71
+ ```bash
72
+ export ISUD_API_KEY="lgr_live_你的密钥" # Windows 用 set 或 PowerShell $env:
73
+ python hello.py
74
+ ```
75
+
76
+ `hello.py`:
77
+
78
+ ```python
79
+ from isud_tm import Client
80
+
81
+ client = Client() # 自动读取环境变量 ISUD_API_KEY
82
+ result = client.search_trademarks(jurisdictionCode="CN", keyword="优标宝")
83
+ print(result["conclusion"])
84
+ print("本次扣点:", client.last_meta.credits_charged)
85
+ ```
86
+
87
+ 运行输出:
88
+
89
+ ```
90
+ 存在中度相似商标,建议进一步人工评估
91
+ 本次扣点: 10
92
+ ```
93
+
94
+ ## 核心能力
95
+
96
+ ```python
97
+ from isud_tm import Client, RateLimitError
98
+
99
+ client = Client(api_key="lgr_live_...")
100
+
101
+ # 1. 商标排查(自动幂等 + 429 退避 + 扣点回读)
102
+ r = client.search_trademarks(
103
+ jurisdictionCode="CN", keyword="优标宝", niceClasses=["35"]
104
+ )
105
+
106
+ # 2. 分页迭代:自动翻完所有页,无需关心 current/size
107
+ for item in client.iter_trademarks(keyword="优标", size=50):
108
+ print(item["markText"], item["status"])
109
+
110
+ # 3. 用量自助对账
111
+ usage = client.get_usage()
112
+ print("余额:", usage["balance"])
113
+
114
+ # 4. 失败有语义,不裸 traceback
115
+ try:
116
+ client.search_trademarks(jurisdictionCode="XX", keyword="x")
117
+ except RateLimitError as e:
118
+ print(e.friendly()) # 含错误码、建议、requestId
119
+ print("请等", e.retry_after, "秒")
120
+ ```
121
+
122
+ 所有方法:
123
+
124
+ | 方法 | 说明 |
125
+ |---|---|
126
+ | `search_trademarks()` | 商标检索与冲突判定(10 点) |
127
+ | `search_designs()` | 外观设计检索(10 点) |
128
+ | `list_trademarks()` / `iter_trademarks()` | 商标档案分页 / 自动翻页迭代 |
129
+ | `list_reports()` | 排查报告分页 |
130
+ | `get_workbench_stats()` | 工作台汇总统计 |
131
+ | `get_usage()` | 点数余额与用量 |
132
+ | `query_request_log(requestId)` | 按追踪 ID 回查调用结果 |
133
+ | `get_mcp_health()` / `call_mcp()` | MCP 探活 / JSON-RPC 调用 |
134
+
135
+ ## 示例项目
136
+
137
+ - [`examples/conflict_check`](examples/conflict_check) —— 近似商标排查(输入商标名 → 风险分级)
138
+ - [`examples/batch_screen`](examples/batch_screen) —— 批量风险筛查(CSV 批量读 → 汇总导出)
139
+
140
+ 每个示例都是 `clone → 填 key → run` 三步跑通,出错给友好提示。
141
+
142
+ ## 错误处理
143
+
144
+ | 异常 | 触发 | 可重试 |
145
+ |---|---|---|
146
+ | `AuthenticationError` | 8889 / 401,密钥问题 | 否 |
147
+ | `RateLimitError` | 9002/9003 / 429 限流 | 是(按 Retry-After) |
148
+ | `ValidationError` | 9001 参数错误 | 否 |
149
+ | `CapabilityError` | 0002 数据源未接入 | 否 |
150
+ | `ApiError` | 0001 通用业务错误 | 视信封 |
151
+ | `NetworkError` | 超时/连接失败/5xx | 是 |
152
+
153
+ ## 重新生成模型层
154
+
155
+ 数据模型由 OpenAPI 契约生成,**不要手改** `src/isud_tm/models.py`:
156
+
157
+ ```bash
158
+ python -m datamodel_codegen \
159
+ --input openapi.yaml --input-file-type openapi \
160
+ --output-model-type dataclasses.dataclass \
161
+ --target-python-version 3.11 \
162
+ --output src/isud_tm/models.py
163
+ ```
164
+
165
+ ## 契约与文档
166
+
167
+ - 契约源:<https://docs.isud.cn/openapi.yaml>
168
+ - 完整文档:<https://docs.isud.cn/>
169
+ - 设计规范:[SDK-DESIGN.md](SDK-DESIGN.md)
170
+
171
+ ## License
172
+
173
+ MIT
@@ -0,0 +1,125 @@
1
+ # isud-tm
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/isud-tm)](https://pypi.org/project/isud-tm/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/isud-tm)](https://pypi.org/project/isud-tm/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
6
+
7
+ 优标宝商标数据开放 API 的 Python SDK —— 商标排查、档案查询、外观设计的**契约驱动**客户端。
8
+
9
+ - **依赖极简**:运行时只要 `httpx`
10
+ - **契约驱动**:数据模型从 [OpenAPI 3.1 契约](https://docs.isud.cn/openapi.yaml) 自动生成
11
+ - **体验完整**:自动 Retry-After 退避、幂等键、扣点回读、分页迭代、友好异常
12
+
13
+ > 密钥从[控制台](https://app.isud.cn)创建(**注册即送调用次数**),仅创建时完整展示一次。
14
+
15
+ ## 安装
16
+
17
+ ```bash
18
+ pip install isud-tm
19
+ ```
20
+
21
+ ## 3 分钟上手
22
+
23
+ ```bash
24
+ export ISUD_API_KEY="lgr_live_你的密钥" # Windows 用 set 或 PowerShell $env:
25
+ python hello.py
26
+ ```
27
+
28
+ `hello.py`:
29
+
30
+ ```python
31
+ from isud_tm import Client
32
+
33
+ client = Client() # 自动读取环境变量 ISUD_API_KEY
34
+ result = client.search_trademarks(jurisdictionCode="CN", keyword="优标宝")
35
+ print(result["conclusion"])
36
+ print("本次扣点:", client.last_meta.credits_charged)
37
+ ```
38
+
39
+ 运行输出:
40
+
41
+ ```
42
+ 存在中度相似商标,建议进一步人工评估
43
+ 本次扣点: 10
44
+ ```
45
+
46
+ ## 核心能力
47
+
48
+ ```python
49
+ from isud_tm import Client, RateLimitError
50
+
51
+ client = Client(api_key="lgr_live_...")
52
+
53
+ # 1. 商标排查(自动幂等 + 429 退避 + 扣点回读)
54
+ r = client.search_trademarks(
55
+ jurisdictionCode="CN", keyword="优标宝", niceClasses=["35"]
56
+ )
57
+
58
+ # 2. 分页迭代:自动翻完所有页,无需关心 current/size
59
+ for item in client.iter_trademarks(keyword="优标", size=50):
60
+ print(item["markText"], item["status"])
61
+
62
+ # 3. 用量自助对账
63
+ usage = client.get_usage()
64
+ print("余额:", usage["balance"])
65
+
66
+ # 4. 失败有语义,不裸 traceback
67
+ try:
68
+ client.search_trademarks(jurisdictionCode="XX", keyword="x")
69
+ except RateLimitError as e:
70
+ print(e.friendly()) # 含错误码、建议、requestId
71
+ print("请等", e.retry_after, "秒")
72
+ ```
73
+
74
+ 所有方法:
75
+
76
+ | 方法 | 说明 |
77
+ |---|---|
78
+ | `search_trademarks()` | 商标检索与冲突判定(10 点) |
79
+ | `search_designs()` | 外观设计检索(10 点) |
80
+ | `list_trademarks()` / `iter_trademarks()` | 商标档案分页 / 自动翻页迭代 |
81
+ | `list_reports()` | 排查报告分页 |
82
+ | `get_workbench_stats()` | 工作台汇总统计 |
83
+ | `get_usage()` | 点数余额与用量 |
84
+ | `query_request_log(requestId)` | 按追踪 ID 回查调用结果 |
85
+ | `get_mcp_health()` / `call_mcp()` | MCP 探活 / JSON-RPC 调用 |
86
+
87
+ ## 示例项目
88
+
89
+ - [`examples/conflict_check`](examples/conflict_check) —— 近似商标排查(输入商标名 → 风险分级)
90
+ - [`examples/batch_screen`](examples/batch_screen) —— 批量风险筛查(CSV 批量读 → 汇总导出)
91
+
92
+ 每个示例都是 `clone → 填 key → run` 三步跑通,出错给友好提示。
93
+
94
+ ## 错误处理
95
+
96
+ | 异常 | 触发 | 可重试 |
97
+ |---|---|---|
98
+ | `AuthenticationError` | 8889 / 401,密钥问题 | 否 |
99
+ | `RateLimitError` | 9002/9003 / 429 限流 | 是(按 Retry-After) |
100
+ | `ValidationError` | 9001 参数错误 | 否 |
101
+ | `CapabilityError` | 0002 数据源未接入 | 否 |
102
+ | `ApiError` | 0001 通用业务错误 | 视信封 |
103
+ | `NetworkError` | 超时/连接失败/5xx | 是 |
104
+
105
+ ## 重新生成模型层
106
+
107
+ 数据模型由 OpenAPI 契约生成,**不要手改** `src/isud_tm/models.py`:
108
+
109
+ ```bash
110
+ python -m datamodel_codegen \
111
+ --input openapi.yaml --input-file-type openapi \
112
+ --output-model-type dataclasses.dataclass \
113
+ --target-python-version 3.11 \
114
+ --output src/isud_tm/models.py
115
+ ```
116
+
117
+ ## 契约与文档
118
+
119
+ - 契约源:<https://docs.isud.cn/openapi.yaml>
120
+ - 完整文档:<https://docs.isud.cn/>
121
+ - 设计规范:[SDK-DESIGN.md](SDK-DESIGN.md)
122
+
123
+ ## License
124
+
125
+ MIT
@@ -0,0 +1,198 @@
1
+ # 优标宝 SDK 跨语言设计规范 (SDK-DESIGN.md)
2
+
3
+ > 适用:Python SDK / TypeScript SDK(及后续 Go / Java / PHP)。
4
+ > 本文件是**契约驱动的体验层约定**:生成层由 `openapi.yaml` 自动产出,本文件锁定的
5
+ > 是生成器做不到的「体验」部分。两语言必须逐条对齐,用户从一门切到另一门零学习成本。
6
+ >
7
+ > 契约源:`https://docs.isud.cn/openapi.yaml`(OpenAPI 3.1,9 端点,v1.0.0)
8
+
9
+ ---
10
+
11
+ ## 0. 设计原则(不可妥协)
12
+
13
+ 1. **契约驱动**:请求/响应模型从 `openapi.yaml` 生成,标记「勿手改」;API 变更时一条命令重新生成。
14
+ 2. **依赖克制**:Python 运行时只依赖 `httpx`;TypeScript 零运行时依赖(原生 `fetch`,Node ≥18 / 浏览器)。
15
+ 3. **三步跑通**:`clone → 填 key → run`,Time-to-Hello-World < 3 分钟。
16
+ 4. **错误不裸奔**:任何失败都要转成有语义的异常 + 人类可读提示,绝不把 traceback / stack 甩给用户。
17
+ 5. **安全默认值**:key 从环境变量读;超时、重试、退避都有合理默认;不打印密钥。
18
+
19
+ ---
20
+
21
+ ## 1. 对外 API 面(两语言严格对齐)
22
+
23
+ `operationId` 是唯一锚点,命名按语言习惯转换:
24
+
25
+ | operationId | Python (snake_case) | TypeScript (camelCase) | HTTP |
26
+ |---|---|---|---|
27
+ | `searchTrademarks` | `search_trademarks()` | `searchTrademarks()` | POST /ip/trademark/search |
28
+ | `listTrademarks` | `list_trademarks()` | `listTrademarks()` | GET /ip/trademark/list |
29
+ | `searchDesigns` | `search_designs()` | `searchDesigns()` | POST /ip/design/search |
30
+ | `listReports` | `list_reports()` | `listReports()` | GET /ip/report/list |
31
+ | `getWorkbenchStats` | `get_workbench_stats()` | `getWorkbenchStats()` | GET /ip/workbench/stats |
32
+ | `getOpenApiUsage` | `get_usage()` | `getUsage()` | GET /ip/usage |
33
+ | `queryRequestLog` | `query_request_log()` | `queryRequestLog()` | GET /ip/requests |
34
+ | `getMcpHealth` | `get_mcp_health()` | `getMcpHealth()` | GET /mcp/health |
35
+ | `callMcp` | `call_mcp()` | `callMcp()` | POST /mcp |
36
+
37
+ - 客户端统一入口:`Client`(Python:`isud_tm.Client`;TS:`new Client()`)。
38
+ - 分页迭代器:Python `client.iter_trademarks(...)`(generator);TS `client.listTrademarksAll(...)`(async generator),
39
+ 自动翻页直到取完 `total`。
40
+ - 初始化统一接受:`api_key`(必填)、`base_url`(可选,默认 `https://app.isud.cn/api/v1/open`)、
41
+ `timeout`(可选,默认 30s)、`max_retries`(可选,默认 3)。
42
+
43
+ ---
44
+
45
+ ## 2. 响应信封解析
46
+
47
+ 所有响应信封:`{ code, msg, data, requestId, suggestion, retryable, retryAfter }`。
48
+
49
+ 统一解析规则:
50
+ - `code == "0000"` → 返回 `data`(业务对象),并把**元数据**挂在返回的 `ResponseMeta` 上(见 §5)。
51
+ - `code != "0000"` → 按 §3 映射成异常抛出。
52
+ - 每次调用都解析响应头 `X-Request-Id` / `X-Credits-Charged` / `X-Credits-Remaining`
53
+ / `X-RateLimit-Limit` / `X-RateLimit-Remaining`,即使失败也要保留(便于对账)。
54
+
55
+ ---
56
+
57
+ ## 3. 异常体系(错误码 → 异常类型)
58
+
59
+ 两语言用**同名**异常类(Python 首字母大写驼峰,TS 相同),继承关系一致:
60
+
61
+ ```
62
+ SdkError (基类,携带 message / code / request_id / suggestion / retryable)
63
+ ├── AuthenticationError # 8889 / HTTP 401 —— key 缺失/无效/禁用/过期/scope 不足。retryable=false
64
+ ├── RateLimitError # 9002 限流 / 9003 每日额度 —— HTTP 429,带 retry_after 秒数
65
+ ├── ValidationError # 9001 参数错误(含幂等键误用)—— 带 suggestion,retryable=false
66
+ ├── CapabilityError # 0002 数据源未接入/类型未开放 —— retryable=false,不扣点
67
+ ├── ApiError # 0001 通用业务错误 —— retryable 由信封字段决定
68
+ └── NetworkError # 连接失败/超时/5xx —— 可重试
69
+ ```
70
+
71
+ 映射优先级:**先看 HTTP 状态码(401/429),再看信封 code**。因为 8889/9002/9003 有真实 HTTP 码,
72
+ 其余业务错误 HTTP 恒 200,靠 code 区分。
73
+
74
+ | HTTP | code | 异常 | 默认可重试 |
75
+ |---|---|---|---|
76
+ | 401 | 8889 | `AuthenticationError` | 否 |
77
+ | 429 | 9002 | `RateLimitError` | 是(按 Retry-After) |
78
+ | 429 | 9003 | `RateLimitError` | 是(按 Retry-After,次日重置则提示) |
79
+ | 200 | 9001 | `ValidationError` | 否 |
80
+ | 200 | 0002 | `CapabilityError` | 否 |
81
+ | 200 | 0001 | `ApiError` | 依 `retryable` |
82
+ | 200 | 0000 | —(成功) | — |
83
+ | 网络/5xx | — | `NetworkError` | 是(指数退避) |
84
+
85
+ ---
86
+
87
+ ## 4. Retry-After 退避(核心体验,两语言一致)
88
+
89
+ 触发条件:`RateLimitError`(9002/9003)或 `NetworkError` 且 `retryable=true` 且未超 `max_retries`。
90
+
91
+ 退避取值的**优先级**:
92
+ 1. 信封字段 `retryAfter`(秒)——服务端明确给出,最权威
93
+ 2. 响应头 `Retry-After`(整数秒;也支持 HTTP-date,转成秒差)
94
+ 3. 兜底指数退避:`base=1s`,第 n 次 `min(2^n, 30)` 秒(n 从 0 起)
95
+
96
+ 行为约定:
97
+ - 每次重试前重新读取退避值(服务端可能动态调整)。
98
+ - 尊重 `retryable=false`:**绝不重试**(0002/8889/9001 大多属此类)。
99
+ - 只有**幂等安全**的请求才自动重试:
100
+ - GET 全部安全;
101
+ - POST 检索类(search)通过自动注入的 `Idempotency-Key` 保证安全(§5);
102
+ - `callMcp` 视 method 而定,默认不自动重试。
103
+ - 重试耗尽后抛最后一次异常,异常-message 里说明「已重试 N 次」。
104
+ - 429 的 `Retry-After` 可能长达 60s;**单次等待上限默认 60s**,超过则直接抛,不长时间阻塞用户。
105
+
106
+ ---
107
+
108
+ ## 5. 幂等键 / 扣点回读 / 请求追踪
109
+
110
+ ### 幂等键
111
+ - `search_trademarks` / `search_designs` 每次调用自动生成 `Idempotency-Key`(UUID4,去掉连字符),
112
+ 也允许用户通过 `idempotency_key=` 显式传入(用业务单号)。
113
+ - 同源同键同体 24h 内重放不重复扣点;SDK 解析 `Idempotency-Replayed: true` 头挂到 meta。
114
+ - 长度约束 1~128 字符:客户端**本地校验**,超长直接抛 `ValidationError`,不发请求。
115
+
116
+ ### 客户端参数校验(避免无谓扣点)
117
+ - `size` 必须在 1~100:本地校验,非法直接抛 `ValidationError`(后端对 size=0 静默按默认,SDK 要挡住)。
118
+ - `keyword` 与 `owner` 至少一项(商标检索):本地校验。
119
+ - `requestId` 查询长度 ≤64:本地校验。
120
+
121
+ ### 扣点回读(ResponseMeta)
122
+ 每次成功/失败都提供元数据对象(Python `resp.meta` 或 returned-data 的 `.meta` 属性;TS `result.meta`):
123
+
124
+ ```
125
+ request_id # X-Request-Id / 信封 requestId
126
+ credits_charged # X-Credits-Charged(失败/幂等回放为 0)
127
+ credits_remaining # X-Credits-Remaining
128
+ rate_limit # X-RateLimit-Limit
129
+ rate_remaining # X-RateLimit-Remaining
130
+ idempotent_replay # Idempotency-Replayed == 'true'
131
+ ```
132
+
133
+ SDK 额外维护 `client.last_meta`(最近一次调用的 meta),方便示例/调试。
134
+
135
+ ---
136
+
137
+ ## 6. 分页迭代器
138
+
139
+ - `iter_trademarks(**filters)` / `listTrademarksAll(filters)`:从 `current=1` 起,按 `size` 翻页,
140
+ 直到 `current >= ceil(total/size)` 或 `records` 为空。
141
+ - 每页之间遵守 §4 退避(GET 安全重试)。
142
+ - 提供 `max_pages` 参数防止意外拉爆(默认不限,示例里设小值)。
143
+ - 迭代器 yield 单条记录(Python)/ 单条记录(TS `for await`),用户无需关心翻页。
144
+
145
+ ---
146
+
147
+ ## 7. 生成层 vs 手写层边界
148
+
149
+ ```
150
+ isud-sdk-python/
151
+ ├── src/isud_tm/
152
+ │ ├── models.py # 【生成】openapi.yaml → dataclass,头部标注 GENERATED,勿手改
153
+ │ ├── client.py # 【手写】Client 主体 + 9 个端点方法
154
+ │ ├── errors.py # 【手写】异常体系(§3)
155
+ │ ├── retry.py # 【手写】退避策略(§4)
156
+ │ └── extras/ # 【手写】分页迭代器、便捷方法
157
+ ├── examples/
158
+ │ ├── conflict_check/ # 示例1:近似商标排查
159
+ │ └── batch_screen/ # 示例2:批量风险筛查
160
+ ├── tests/ # 契约测试(mock,不依赖真实 key)
161
+ ├── pyproject.toml # 仅 httpx 运行时依赖
162
+ ├── README.md # 首屏 = 3 行 Hello World + 运行截图占位
163
+ └── LICENSE # MIT
164
+ ```
165
+
166
+ - **生成命令**写进 README/CONTRIBUTING:`datamodel-codegen --input openapi.yaml ...`。
167
+ - 生成模型只负责「数据结构」,不含任何行为;行为全在手写层。
168
+ - 契约测试要校验:9 个端点方法都存在、模型能解析契约示例、错误码映射正确。
169
+
170
+ ---
171
+
172
+ ## 8. 示例项目规范(内容营销单元)
173
+
174
+ 首批两个示例(两语言各一份,结构对齐):
175
+
176
+ 1. **conflict_check — 近似商标排查**:输入商标名 + 法域 → 调 `search_trademarks` → 打印风险分级与结论。
177
+ - 演示点:key 从环境变量读、信封解析、错误友好提示、扣点回读展示。
178
+ 2. **batch_screen — 批量风险筛查**:读 CSV(商标名列表)→ 逐个检索 → 汇总 high/medium/low → 导出 CSV。
179
+ - 演示点:幂等键、429 退避、分页、批量场景下的用量查询。
180
+
181
+ 硬门槛(做不到就不发):
182
+ - `clone → 填 key → run` 三步内跑通,README 首屏是**运行输出截图**不是架构图;
183
+ - 不依赖任何自建中间层/额外服务;
184
+ - 出错给友好提示,不裸 traceback;
185
+ - 明示「注册即送 N 次调用」的获取入口(key 从控制台领)。
186
+
187
+ ---
188
+
189
+ ## 9. 版本与演进
190
+
191
+ - SDK 版本跟随 API 主版本(`1.0.x`)。
192
+ - `status` / `riskLevel` 是开放枚举,新增值不构成破坏性变更:模型层用 `str` 不用封闭 Enum,
193
+ 客户端按未知值兜底(不要 `raise`)。
194
+ - 日期字段统一 Unix 毫秒 int64,`0` = 未知;SDK 提供可选的人类可读格式化 helper(不改动原始值)。
195
+
196
+ ---
197
+
198
+ *本文件在两仓库各存一份,内容必须一致。任一语言修改体验层约定,先改本文件再同步另一语言。*
@@ -0,0 +1,26 @@
1
+ # 示例 2:批量风险筛查
2
+
3
+ 读 CSV 批量检索商标,汇总高/中/低风险,导出结果 CSV。适合知产代理人日常批量排查。
4
+
5
+ ## 运行(3 步)
6
+
7
+ ```bash
8
+ pip install isud-tm
9
+ export ISUD_API_KEY="lgr_live_你的密钥"
10
+ python main.py marks.sample.csv results.csv CN
11
+ ```
12
+
13
+ > 密钥从 https://app.isud.cn 控制台创建,**注册即送调用次数**。
14
+
15
+ ## 输入 / 输出
16
+
17
+ 输入 `marks.sample.csv`:每行一个商标名,`#` 开头为注释。
18
+
19
+ 输出 `results.csv`:商标名、命中总数、高/中/低风险、结论、requestId(可用 `client.query_request_log()` 回查每次调用)。
20
+
21
+ ## 演示的能力
22
+
23
+ - **幂等键**:用业务序号当 `idempotency_key`,脚本重跑不重复扣点
24
+ - **429 退避**:检索类 30 次/分钟,SDK 自动按 Retry-After 退避;示例额外做了 2s 节流
25
+ - **用量对账**:跑完调 `get_usage()` 看剩余点数
26
+ - **批量容错**:单个商标失败不影响整批,错误逐行记录