altdatahub 0.1.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.
- altdatahub-0.1.0/LICENSE +21 -0
- altdatahub-0.1.0/PKG-INFO +374 -0
- altdatahub-0.1.0/README.md +356 -0
- altdatahub-0.1.0/pyproject.toml +64 -0
- altdatahub-0.1.0/setup.cfg +4 -0
- altdatahub-0.1.0/src/altdatahub/__init__.py +61 -0
- altdatahub-0.1.0/src/altdatahub/__main__.py +5 -0
- altdatahub-0.1.0/src/altdatahub/_data/products.json +8420 -0
- altdatahub-0.1.0/src/altdatahub/catalog.py +81 -0
- altdatahub-0.1.0/src/altdatahub/cli.py +115 -0
- altdatahub-0.1.0/src/altdatahub/client.py +136 -0
- altdatahub-0.1.0/src/altdatahub/credentials.py +98 -0
- altdatahub-0.1.0/src/altdatahub/endpoints.py +93 -0
- altdatahub-0.1.0/src/altdatahub/errors.py +106 -0
- altdatahub-0.1.0/src/altdatahub/http_transport.py +73 -0
- altdatahub-0.1.0/src/altdatahub/models.py +1554 -0
- altdatahub-0.1.0/src/altdatahub/records.py +72 -0
- altdatahub-0.1.0/src/altdatahub/transport.py +80 -0
- altdatahub-0.1.0/src/altdatahub/wire.py +173 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/PKG-INFO +374 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/SOURCES.txt +36 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/dependency_links.txt +1 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/entry_points.txt +2 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/requires.txt +8 -0
- altdatahub-0.1.0/src/altdatahub.egg-info/top_level.txt +1 -0
- altdatahub-0.1.0/tests/test_capabilities.py +61 -0
- altdatahub-0.1.0/tests/test_catalog.py +83 -0
- altdatahub-0.1.0/tests/test_cli.py +56 -0
- altdatahub-0.1.0/tests/test_client.py +89 -0
- altdatahub-0.1.0/tests/test_contract_vectors.py +96 -0
- altdatahub-0.1.0/tests/test_errors.py +119 -0
- altdatahub-0.1.0/tests/test_generated.py +61 -0
- altdatahub-0.1.0/tests/test_http_transport.py +164 -0
- altdatahub-0.1.0/tests/test_integration.py +70 -0
- altdatahub-0.1.0/tests/test_models.py +66 -0
- altdatahub-0.1.0/tests/test_verify.py +87 -0
- altdatahub-0.1.0/tests/test_wire.py +152 -0
- altdatahub-0.1.0/tests/test_wire_parity.py +67 -0
altdatahub-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Altdatahub Contributors
|
|
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.
|
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: altdatahub
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: 封装中国人民银行征信中心「金融信用信息基础数据库替代数据通」产品的第三方 Python SDK(非官方)—— 10 个产品大类、51 个 productCode 的强类型封装与离线目录
|
|
5
|
+
Author: Altdatahub Contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: credit,enterprise-risk,alternative-data,sdk
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Provides-Extra: dev
|
|
12
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
13
|
+
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
|
|
14
|
+
Requires-Dist: ruff<1,>=0.5; extra == "dev"
|
|
15
|
+
Provides-Extra: extract
|
|
16
|
+
Requires-Dist: pdfplumber<1,>=0.11; extra == "extract"
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# altdatahub
|
|
20
|
+
|
|
21
|
+
封装中国人民银行征信中心「**金融信用信息基础数据库替代数据通**」产品的第三方 Python SDK
|
|
22
|
+
(**非官方**,与征信中心无隶属关系)—— **10 个产品大类、51 个 `productCode`** 的强类型封装,
|
|
23
|
+
外加一份可重放的离线产品目录。
|
|
24
|
+
|
|
25
|
+
数据契约来自《替代数据通 产品数据分册(V1.0)》(中国人民银行征信中心,2025-12);
|
|
26
|
+
传输契约按《接口规范》示例代码实现(POST + 8 个 `eds_*` 公共参数 + 业务参数平铺,
|
|
27
|
+
**无签名**,鉴权靠 `eds_account`)。响应信封与业务错误码已由真实响应确认 —— 见「诚实口径」。
|
|
28
|
+
|
|
29
|
+
## 诚实口径
|
|
30
|
+
|
|
31
|
+
| 能力 | 状态 | 说明 |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| 产品目录(51 个 `productCode`、557 个顶层字段、12 个子结构 / 397 个字段) | ✅ 可用 | 由分册 PDF 解析生成,含中文名 / 类型 / 长度 / 非空 |
|
|
34
|
+
| 强类型模型(51 + 12 个 dataclass) | ✅ 可用 | 未知字段落 `raw`,前向兼容 |
|
|
35
|
+
| 10 个大类方法 + `productCode` 枚举 | ✅ 可用 | 类别与编码不匹配时**本地**报错 |
|
|
36
|
+
| 传输层(POST 到 EDS 网关) | ✅ 已验证 | 按《接口规范》示例代码逐字段对齐;S0101 真实查询 HTTP 200 / 1 行 |
|
|
37
|
+
| 业务错误码(1000/2000/3000/9999) | ✅ 已实现 | 按值判定,带 `category` / `retryable` / `hint`,OpenAPI 有 `x-error-codes` |
|
|
38
|
+
| 响应信封 | ✅ 已确认 | `data[].data` 两层按展平解包;错误码 `code` / 描述 `msg` |
|
|
39
|
+
| **能力服务 / MCP / Skill** | ✅ 可用 | 独立部署的 HTTP 服务 + AI 接入层;**离线目录完全可用,S0101 在线查询已验证**;其余产品仍需 `EDS_*` 凭据,见下节 |
|
|
40
|
+
|
|
41
|
+
S0101 之外仍未确认 2 项:各产品服务号清单、`eds_validday` 类型原文,详见
|
|
42
|
+
[`docs/api/transport.md`](docs/api/transport.md)。**没有签名环节** —— 示例代码里鉴权只靠
|
|
43
|
+
`eds_account` 授权串,本 SDK 不发明签名字段。
|
|
44
|
+
|
|
45
|
+
## 安装
|
|
46
|
+
|
|
47
|
+
本包发布在 **CNB PyPI 制品库 `h1s97x/pypi`**(不是 PyPI 官方源):
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install --index-url https://pypi.cnb.cool/h1s97x/pypi/-/packages/simple altdatahub
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
若制品库设为私有,按平台的「拉取制品」指引配置凭据后再安装。
|
|
54
|
+
从仓库源码安装(开发 / 离线):
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install . # 核心零第三方依赖(stdlib only)
|
|
58
|
+
pip install -e ".[dev]" # 开发:pytest / ruff
|
|
59
|
+
pip install -e ".[extract]" # 只有重新解析分册 PDF 时才需要(pdfplumber)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## 快速开始
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
altdatahub categories # 10 个大类
|
|
66
|
+
altdatahub products --category judicial # 某个大类下的 productCode
|
|
67
|
+
altdatahub schema S0101 # 某产品的字段字典(名称/类型/长度/非空/中文名)
|
|
68
|
+
altdatahub schema S1201 --json # 机器可读
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from altdatahub import HubClient, MappingTransport, PRODUCT_CODES
|
|
73
|
+
|
|
74
|
+
# 离线(把上游响应喂进模型层)
|
|
75
|
+
client = HubClient(MappingTransport({"S0101": {"data": [{"entType": "有限责任公司"}]}}))
|
|
76
|
+
row = client.enterprise_basic(PRODUCT_CODES.S0101, entName="贵州茅台")[0]
|
|
77
|
+
row.entType # '有限责任公司'
|
|
78
|
+
row.raw # {'entType': '有限责任公司'} —— 分册未覆盖的新字段不会丢
|
|
79
|
+
|
|
80
|
+
# 真实调用:从 EDS_* 环境变量取网关参数
|
|
81
|
+
client = HubClient.from_env()
|
|
82
|
+
client.enterprise_basic(PRODUCT_CODES.S0101, entName="贵州茅台", page="1", pageSize="20", queryReason="贷前审查")
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
公共参数(缺任何一个都会在**本地**报错并列出变量名,不回显取值):
|
|
86
|
+
|
|
87
|
+
| 环境变量 | 说明 |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `EDS_BASE_URL` | 网关地址(示例里是内网 `http://<host>:9080/edsservice/api/gateway`) |
|
|
90
|
+
| `EDS_ACCOUNT` | 授权字串(凭据,不传或传错将无法查询) |
|
|
91
|
+
| `EDS_OPERATE_USER_ID` / `EDS_OPERATE_USER_NAME` | 用户编号 / 查询用户名 |
|
|
92
|
+
| `EDS_SCENE` | 来源系统简称(大写英文字母,全行统一) |
|
|
93
|
+
| `EDS_ORG_ID` / `EDS_ORG_ID_NAME` | 查询机构编号 / 机构名 |
|
|
94
|
+
| `EDS_VALID_DAY` | 选填,数据有效期(0=每次查最新,N=N 天内复用),默认 0 |
|
|
95
|
+
| `EDS_TIMEOUT` | 选填,秒,默认 30 |
|
|
96
|
+
| `EDS_SERVICE_CODE_PATTERN` | 选填,服务号模板,默认 `izxzx{product_code}` |
|
|
97
|
+
|
|
98
|
+
## 10 个大类 → 51 个产品
|
|
99
|
+
|
|
100
|
+
| 大类方法 | 章节 | 产品数 | 例 |
|
|
101
|
+
|---|---|---|---|
|
|
102
|
+
| `enterprise_basic` | 1 企业基本信息 | 6 | S0101 基本概况 |
|
|
103
|
+
| `market_supervision` | 2 市场监管 | 6 | S0206 年报信息 |
|
|
104
|
+
| `judicial` | 3 司法 | 4 | S0401 民事判决 |
|
|
105
|
+
| `intellectual_property` | 4 知识产权 | 7 | S0502 商标 |
|
|
106
|
+
| `stock` | 5 股票 | 7 | S0701 股票基本信息 |
|
|
107
|
+
| `bond` | 6 债券 | 9 | S0801 债券基本信息 |
|
|
108
|
+
| `administration` | 7 行政管理 | 4 | S0901 行政许可 |
|
|
109
|
+
| `honor` | 8 诚实守信荣誉 | 1 | S1001 荣誉信息 |
|
|
110
|
+
| `operation` | 9 经营 | 6 | S1101 招标 |
|
|
111
|
+
| `finance` | 10 财务 | 1 | S1201 财务信息(三表) |
|
|
112
|
+
|
|
113
|
+
完整清单(含每个产品的字段数与子结构)见 [`catalog/PRODUCTS.md`](catalog/PRODUCTS.md)。
|
|
114
|
+
|
|
115
|
+
## TypeScript SDK
|
|
116
|
+
|
|
117
|
+
`sdks/typescript/`,零运行时依赖(`fetch` + `node:test`):
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
cd sdks/typescript && npm ci && npm test
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
消费方 `npm install @h1s97x/altdatahub`;内网只配 scope 级 `.npmrc`,不改全局 registry
|
|
124
|
+
(见 [`sdks/typescript/README.md`](sdks/typescript/README.md))。
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import { HubClient, PRODUCT_CODES } from '@h1s97x/altdatahub';
|
|
128
|
+
|
|
129
|
+
const client = HubClient.fromEnv(); // 或 new HubClient(new MappingTransport({ ... })) 离线跑
|
|
130
|
+
const rows = await client.enterpriseBasic(PRODUCT_CODES.S0101, { entName: '贵州茅台' });
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
与 Python 版的差异只有三处:方法名 camelCase、业务参数走对象(TS 没有 `**kwargs`)、
|
|
134
|
+
全程 `Promise`。错误码表、重试语义、「先判错再取数据行」的链路顺序两边一致。
|
|
135
|
+
`src/types.ts`(51 个产品接口 + 12 个子结构)由同一个生成器产出,`gen_code.py --check` 守着。
|
|
136
|
+
详见 [`sdks/typescript/README.md`](sdks/typescript/README.md)。
|
|
137
|
+
|
|
138
|
+
## Java SDK
|
|
139
|
+
|
|
140
|
+
`sdks/java/`,Java 17 + `record`,唯一依赖 `jackson-databind`:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
cd sdks/java && mvn verify
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
```java
|
|
147
|
+
import com.altdatahub.HubClient;
|
|
148
|
+
import com.altdatahub.Types;
|
|
149
|
+
|
|
150
|
+
import java.util.List;
|
|
151
|
+
import java.util.Map;
|
|
152
|
+
|
|
153
|
+
HubClient client = HubClient.fromEnv(); // 或 new HubClient(new Transport.Mapping(...)) 离线跑
|
|
154
|
+
List<Types.S0101BasicProfile> rows = client.enterpriseBasic(Map.of("entName", "贵州茅台"));
|
|
155
|
+
rows.get(0).entType();
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
`Types.java`(51 个产品 record + 12 个子结构)同样由 `tools/gen_code.py` 产出,**不许手改**。
|
|
159
|
+
错误码表、重试语义、链路顺序与 Python / TypeScript 版一致,三边用同一份
|
|
160
|
+
`contract/vectors.json` 断言。详见 [`sdks/java/README.md`](sdks/java/README.md)。
|
|
161
|
+
|
|
162
|
+
## Go SDK
|
|
163
|
+
|
|
164
|
+
`sdks/go/`,标准库零依赖(`net/http` + `encoding/json`):
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
cd sdks/go && go vet ./... && go test ./...
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
```go
|
|
171
|
+
import altdatahub "github.com/h1s97x/altdatahub"
|
|
172
|
+
|
|
173
|
+
client, err := altdatahub.FromEnv() // 或 altdatahub.NewHubClient(altdatahub.NewMapping(...)) 离线跑
|
|
174
|
+
rows, err := client.EnterpriseBasic("S0101", map[string]any{"entName": "贵州茅台"})
|
|
175
|
+
profile := rows[0].(*altdatahub.S0101BasicProfile)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
`types_gen.go`(51 个产品 struct + 12 个子结构)同样由 `tools/gen_code.py` 产出,**不许手改**。
|
|
179
|
+
详见 [`sdks/go/README.md`](sdks/go/README.md)。
|
|
180
|
+
|
|
181
|
+
## C# SDK
|
|
182
|
+
|
|
183
|
+
`sdks/csharp/`,.NET 8 零 NuGet(`System.Text.Json` + `HttpClient`):
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
cd sdks/csharp && dotnet build Altdatahub.sln -c Release
|
|
187
|
+
dotnet run --project tests/Altdatahub.Tests -c Release
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```csharp
|
|
191
|
+
using Altdatahub;
|
|
192
|
+
|
|
193
|
+
var client = HubClient.FromEnv(); // 或 new HubClient(new MappingTransport(...)) 离线跑
|
|
194
|
+
var rows = client.EnterpriseBasic<S0101BasicProfile>("S0101",
|
|
195
|
+
new Dictionary<string, object?> { ["entName"] = "贵州茅台" });
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`Types.cs`(51 个产品 record + 12 个子结构)同样由 `tools/gen_code.py` 产出,**不许手改**。
|
|
199
|
+
详见 [`sdks/csharp/README.md`](sdks/csharp/README.md)。
|
|
200
|
+
|
|
201
|
+
## Rust SDK
|
|
202
|
+
|
|
203
|
+
`sdks/rust/`,`serde_json` + `ureq`(rustls,无系统库依赖,最低工具链 1.88):
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
cd sdks/rust && cargo fmt --check && cargo test
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
```rust
|
|
210
|
+
use altdatahub::{HubClient, S0101BasicProfile};
|
|
211
|
+
|
|
212
|
+
let client = HubClient::from_env()?; // 或 HubClient::new(Box::new(MappingTransport::new(..))) 离线跑
|
|
213
|
+
let rows: Vec<S0101BasicProfile> = client.enterprise_basic("S0101", params)?;
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
`src/types.rs`(51 个产品 struct + 12 个子结构)同样由 `tools/gen_code.py` 产出,**不许手改**。
|
|
217
|
+
详见 [`sdks/rust/README.md`](sdks/rust/README.md)。
|
|
218
|
+
|
|
219
|
+
## C SDK
|
|
220
|
+
|
|
221
|
+
`sdks/c/`,C11 标准库 + libcurl,JSON 与模型都在仓内实现(不引第三方 JSON 库):
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
# Debian/Ubuntu 系统依赖
|
|
225
|
+
apt-get install -y make gcc pkg-config libcurl4-openssl-dev
|
|
226
|
+
|
|
227
|
+
cd sdks/c && make test # 编译静态库 + 自跑测试,退出码即结论
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
```c
|
|
231
|
+
#include "altdatahub.h"
|
|
232
|
+
|
|
233
|
+
ad_config *config = ad_config_from_env(&error);
|
|
234
|
+
ad_transport *transport = ad_http_transport_new(config);
|
|
235
|
+
ad_client *client = ad_client_new(transport);
|
|
236
|
+
ad_rows *rows = ad_client_query_by_code(client, "S0101", params, &error);
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`include/altdatahub_types.h`(51 + 12 个模型)同样由 `tools/gen_code.py` 产出,**不许手改**。
|
|
240
|
+
`tests/test_contract_vectors.c` 与其它六种语言读同一份 `contract/vectors.json`;
|
|
241
|
+
CI 里还会跑 ASan/UBSan 构建。详见 [`sdks/c/README.md`](sdks/c/README.md)。
|
|
242
|
+
|
|
243
|
+
## C++ SDK
|
|
244
|
+
|
|
245
|
+
`sdks/cpp/` 是 **header-only 薄封装**,用 `extern "C"` 直接复用 C 库,不重复
|
|
246
|
+
51+12 个模型、不改 `tools/gen_code.py`:
|
|
247
|
+
|
|
248
|
+
```cpp
|
|
249
|
+
#include "altdatahub.hpp"
|
|
250
|
+
|
|
251
|
+
auto client = altdatahub::Client::from_env();
|
|
252
|
+
altdatahub::Rows rows = client.query("S0101", {{"entName", "贵州茅台"}});
|
|
253
|
+
// 失败抛 altdatahub::Error;RAII 管理 config → transport → client 的释放顺序
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
C++17 + 标准库,无需额外安装依赖;`make test` 会自动先构建 C 静态库。
|
|
257
|
+
报文 / 错误码 / 信封三组跨语言向量仍由 C SDK 覆盖,CI 的 `ci-cpp-sdk`
|
|
258
|
+
会同时跑 C 与 C++ 的测试(含 ASan/UBSan)。详见
|
|
259
|
+
[`sdks/cpp/README.md`](sdks/cpp/README.md)。
|
|
260
|
+
|
|
261
|
+
## 目录结构
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
catalog/
|
|
265
|
+
products.json 数据契约真源(解析产物,勿手改)
|
|
266
|
+
names_en.json 中文名 → 英文类名的显式映射(缺映射生成器直接失败)
|
|
267
|
+
PRODUCTS.md 人读速查表(生成)
|
|
268
|
+
src/altdatahub/
|
|
269
|
+
models.py 51 + 12 个模型(生成)
|
|
270
|
+
endpoints.py 10 个大类 + productCode 枚举
|
|
271
|
+
client.py 大类方法 + query,传输可注入
|
|
272
|
+
transport.py 传输协议与 Mock(PendingTransport / MappingTransport)
|
|
273
|
+
http_transport.py 真实传输(stdlib urllib,按示例代码 POST JSON)
|
|
274
|
+
credentials.py EDS 网关公共参数(8 个 eds_* 字段)
|
|
275
|
+
wire.py 请求体组装 + 响应解包
|
|
276
|
+
records.py 模型基类(payload → 强类型,保留 raw)
|
|
277
|
+
catalog.py 运行时目录访问
|
|
278
|
+
cli.py 离线元数据 CLI
|
|
279
|
+
tools/
|
|
280
|
+
extract_catalog.py 分册 PDF → products.json(坐标解析 + --check 质量门禁)
|
|
281
|
+
gen_code.py products.json → 模型 / OpenAPI / 速查表
|
|
282
|
+
docs/
|
|
283
|
+
catalog.md 解析细节、踩过的坑、易误判事实、升版流程
|
|
284
|
+
api/transport.md 传输契约待补清单
|
|
285
|
+
openapi/openapi.yaml 51 个逻辑接口 + 51 对请求/响应 schema(生成;真实端点见 x-gateway-path)
|
|
286
|
+
.spectral.yml OpenAPI 契约校验规则(CI 跑,0 errors)
|
|
287
|
+
contract/vectors.json 跨语言契约向量(报文形状 / 错误码判定 / 信封解包,各语言跑同一份)
|
|
288
|
+
sdks/typescript/ TypeScript SDK(零运行时依赖;types.ts 由本生成器产出)
|
|
289
|
+
sdks/java/ Java SDK(仅 jackson-databind;Types.java 由本生成器产出)
|
|
290
|
+
sdks/go/ Go SDK(标准库零依赖;types_gen.go 由本生成器产出)
|
|
291
|
+
sdks/csharp/ C# SDK(.NET 8 零 NuGet;Types.cs 由本生成器产出)
|
|
292
|
+
sdks/rust/ Rust SDK(serde_json + ureq;src/types.rs 由本生成器产出)
|
|
293
|
+
sdks/c/ C SDK(C11 + libcurl;include/altdatahub_types.h 由本生成器产出)
|
|
294
|
+
tests/test_contract_vectors.c 与其余六种语言读同一份 contract/vectors.json
|
|
295
|
+
sdks/cpp/ C++ SDK(header-only,复用 C 库;不新增生成器产物)
|
|
296
|
+
service/ 能力服务:通用查询 + 离线目录 + Token 注册表(纯标准库)
|
|
297
|
+
Dockerfile / compose.yml / compose.internal.yml / README.md
|
|
298
|
+
tests/ 零联网 unittest
|
|
299
|
+
mcp/ MCP stdio + Streamable HTTP 双 transport(纯标准库)
|
|
300
|
+
skills/altdatahub-service/ Agent Skill:SKILL.md + 查询脚本 + 目录参考
|
|
301
|
+
openapi/service.yaml 调用方视角的能力级契约(与 openapi.yaml 的 51 个逻辑接口不同)
|
|
302
|
+
.env.example 服务端环境变量模板
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Python SDK 在根目录(`src/`),其余语言在 `sdks/`,服务层在 `service/`。
|
|
306
|
+
|
|
307
|
+
## 服务化与 AI 接入
|
|
308
|
+
|
|
309
|
+
SDK 是库,不会自己监听端口。若要把替代数据通接给主系统或 AI 客户端,用
|
|
310
|
+
`service/`(与 SDK 同仓、零第三方依赖):
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
cp .env.example .env # 填 EDS_* 与调用方 Token(.env 已 gitignore)
|
|
314
|
+
PYTHONPATH=src python -m service # 或直接跑,回环 8802
|
|
315
|
+
docker compose -f service/compose.yml --env-file .env up -d --build # 只绑回环
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
| 层 | 入口 | 说明 |
|
|
319
|
+
|---|---|---|
|
|
320
|
+
| 能力服务 | `service/README.md` | `GET /v1/categories`、`/v1/catalog`、`/v1/schema/{code}`(**离线可用**);`POST /v1/query/{code}`(在线,需 `EDS_*`) |
|
|
321
|
+
| MCP | `mcp/README.md` | `python -m mcp`(stdio)或 `python -m mcp --http`(`POST /mcp`) |
|
|
322
|
+
| Agent Skill | `skills/altdatahub-service/SKILL.md` | 先查目录定 productCode,再查字段字典,最后才发在线查询 |
|
|
323
|
+
|
|
324
|
+
**在线查询已验证(S0101),缺配置仍显式降级**:2026-11-16 经能力服务完成一次真实查询
|
|
325
|
+
(HTTP 200 / 1 行,响应字段与 `altdatahub schema S0101` 一致);服务端没配 `EDS_*` 时
|
|
326
|
+
仍返回 `success=false` + `degrade_reason=未配置 EDS 网关公共参数`,不伪造数据。
|
|
327
|
+
其余产品的服务号清单拿到后,按 `docs/api/transport.md` 把拼装模板改为显式映射。
|
|
328
|
+
调用方只持服务地址 + 调用方 Token,`EDS_ACCOUNT` 等 8 个公共参数只在服务端。
|
|
329
|
+
|
|
330
|
+
生产形态用 `service/compose.internal.yml`(不发布端口,只加入调用方网络);
|
|
331
|
+
AI 客户端可另起 `mcp/compose.yml`。三者都由 `.ci-service` 进 CI。
|
|
332
|
+
|
|
333
|
+
## 文档站
|
|
334
|
+
|
|
335
|
+
文档站(MkDocs Material)在**独立仓库**,主仓不放站点文件、不加第三方依赖。
|
|
336
|
+
两仓之间只传「脱敏后的文档契约快照」:
|
|
337
|
+
|
|
338
|
+
```bash
|
|
339
|
+
python tools/verify.py all # 统一门禁:生成物 / 向量 / 链接 / 脱敏 / 快照
|
|
340
|
+
python tools/verify.py export # 只产快照:contract/snapshot/(含 manifest.json)
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
CI 的 `ci-contracts` 把快照打成 `docs-snapshot.tar.gz` 作为构建产物;
|
|
344
|
+
**当前阶段只出产物、不部署**。文档仓地址、跨仓同步(方式 A)与 Pages 上线
|
|
345
|
+
等事项见 [`todo.md`](todo.md)。
|
|
346
|
+
|
|
347
|
+
## 开发
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
python -m pytest tests/ -q --cov=altdatahub # 覆盖率门禁 95%(CI 强制)
|
|
351
|
+
python -m ruff check src/ tests/ tools/
|
|
352
|
+
python tools/gen_code.py --check # 生成物必须与目录一致(CI 也跑)
|
|
353
|
+
cd sdks/java && mvn verify # 改生成器后 Java 侧也要跑(67 个用例)
|
|
354
|
+
cd sdks/go && gofmt -l . && go test ./... # Go 侧(79 个用例)
|
|
355
|
+
cd sdks/csharp && dotnet run --project tests/Altdatahub.Tests -c Release # C# 侧(56 个用例)
|
|
356
|
+
cd sdks/rust && cargo fmt --check && cargo test # Rust 侧(36 个用例)
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
CI 在 CNB(`.cnb.yml`):push / PR 按改动的目录分别跑 Python(ruff + pytest + 生成物一致性)、
|
|
360
|
+
TypeScript(`npm run build` + `node --test`)、Java(`mvn verify`)、Go(`gofmt` 门禁 + `go test`)、C#(`dotnet build` + 自跑测试)、Rust(`cargo fmt --check` + `cargo test`);
|
|
361
|
+
`ci-contracts` 单独跑 `tools/verify.py all` 并把脱敏快照打成 `docs-snapshot.tar.gz`
|
|
362
|
+
构建产物(当前不部署,见 `todo.md`);每周一跑 Python 3.10 / 3.12 全量。
|
|
363
|
+
|
|
364
|
+
## 数据来源与合规
|
|
365
|
+
|
|
366
|
+
- 本项目是**第三方实现**,非征信中心官方发布,与征信中心无隶属关系;产品名
|
|
367
|
+
「金融信用信息基础数据库替代数据通」仅用于说明封装对象,不代表官方背书;
|
|
368
|
+
- 分册 PDF **不入库**(`*.pdf` 已 gitignore),入库的是解析产物 `catalog/products.json`;
|
|
369
|
+
- 目录只含产品结构定义,**不含任何真实企业数据**;
|
|
370
|
+
- 分册升版流程见 [`docs/catalog.md`](docs/catalog.md)。
|
|
371
|
+
|
|
372
|
+
## License
|
|
373
|
+
|
|
374
|
+
MIT,见 [LICENSE](LICENSE)。
|