09 — 数据服务（JDBC 视图 / HMAC）

第三方通过 HMAC 调用门户，按管理端预先配置的输出 Profile，读取已映射字段的 JSON（数据来自第三方库视图/表，由门户代查）。

配置面：管理端 /api/sync/jdbc/**（非本文件范围；需门户登录）。
设计方案：doc/37-JDBC数据服务与入向同步.md。
代码锚点：OpenDataController、OpenDataHmacFilter、SyncJdbcOutputProfileService。

基路径：/api/open/data
方法：POST /query。

1. 鉴权头

与 02-事项推送-HMAC.md 完全一致：

Header	必填	说明
`X-Client-Id`	是	SSO `client_id`
`X-Timestamp`	是	Unix 秒
`X-Signature`	是	HMAC-SHA256 Hex

时间窗：±300 秒。Client 须启用、绑定 system_code、CONFIDENTIAL 且可解析 client_secret。

签名串：

text

{clientId}\n{timestamp}\n{rawBody}

system_code 取自 Client 绑定。输出 Profile 的 access_mode：

access_mode	规则
`BOUND_SYSTEMS`	Client 的 `system_code` 须在 `allowed_system_codes` 列表中
`ANY_AUTHED`	任意通过 HMAC 的 Client 可调

未开通 grant_type=client_credentials。

2. 查询 — `POST /api/open/data/query`

Body

字段	必填	说明
`profileCode`	是	管理端输出配置编码
`pageNum`	否	从 1，默认 1
`pageSize`	否	默认 20，上限 200（且受 dataset `page_size_limit` 约束）
`filters`	否	`map` 等值过滤；仅映射中标记 `filterable=true` 的输出字段名可用

成功 `data`

字段	说明
`profileCode`	回显
`pageNum` / `pageSize`	分页
`records`	映射后对象数组（键为 mapping `target`）

一期可不返回精确 total（视实现；有则用于分页）。

示例

bash

curl -sS -X POST "https://portal.example.com/api/open/data/query" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: your-client" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>" \
  -d '{"profileCode":"dept-view-v1","pageNum":1,"pageSize":20}'

3. 错误与边界

场景	典型
缺鉴权头 / 签名失败 / 时间窗	401
Client 停用 / 无 secret / 未绑 system / profile 未授权	403
profile 不存在或停用	业务 404/400
过滤了非 filterable 字段	400

安全约束：门户侧仅白名单对象名 + 固定模板查询；不向调用方回显 JDBC 密码或原始 SQL。

4. 非目标

能力	说明
第三方自助配库连接 / 改映射	仅管理端
开放写组织用户	不做；入向同步见 doc/37 能力 B（管理端触发）
`/api/sync/jdbc/**`	管理面，勿当第三方入站

5. 相关文档

文档	用途
01-接入准备.md	Client、`system_code`
02-事项推送-HMAC.md	签名算法细节
doc/37	双能力方案与管理 API
05-接收出向同步.md	门户→你方推送（相反方向）

09 — 数据服务（JDBC 视图 / HMAC） ​

1. 鉴权头 ​

2. 查询 — POST /api/open/data/query ​

Body ​

成功 data ​

示例 ​

3. 错误与边界 ​

4. 非目标 ​

5. 相关文档 ​