init:创建harness coding docs
This commit is contained in:
+222
@@ -0,0 +1,222 @@
|
||||
# API / 模块合约
|
||||
|
||||
> 本文定义第三方 API、统一响应和内部模块合约的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- 传输：HTTPS JSON。
|
||||
- 编码：UTF-8 JSON。
|
||||
- 时间格式：`YYYY-MM-DD` 用于业务日期，时间戳使用 ISO 8601。
|
||||
- 第三方鉴权：待定，推荐 `Authorization: Bearer <token>` 或 `X-App-Key` + `X-Signature`。
|
||||
- 每个响应包含 `trace_id`。
|
||||
|
||||
成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"trace_id": "TRACE_ID",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
错误响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"trace_id": "TRACE_ID",
|
||||
"error": {
|
||||
"code": "bad_request",
|
||||
"message": "请求参数不正确"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 第三方 API
|
||||
|
||||
### `POST /api/v1/health-checks/query-detail`
|
||||
|
||||
用途：查询 CHIS 中某次体检详情。第一版用于验证 CHIS 登录、Redis 会话、通用请求和查询链路。
|
||||
|
||||
第一版请求要求调用方传全参数：
|
||||
|
||||
```json
|
||||
{
|
||||
"account_ref": "chis-account-alias",
|
||||
"healthCheck": "0000000000481718",
|
||||
"phrId": "44162511100102877",
|
||||
"idCard": "440000********1234",
|
||||
"checkDate": "2014-06-05"
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `healthCheck + phrId + idCard` 用于调用 CHIS `getHMNIListOfHTML`。
|
||||
- `idCard + checkDate` 用于调用 CHIS `getCheckInfoDetail`。
|
||||
- 当前资料不能证明只传 `healthCheck` 就能查完整详情；后续任务会验证反查链路。
|
||||
|
||||
成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"trace_id": "TRACE_ID",
|
||||
"data": {
|
||||
"healthCheck": "0000000000481718",
|
||||
"detail": {},
|
||||
"check_info": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/v1/health-checks/submit`
|
||||
|
||||
用途：提交单条体检数据到 CHIS。
|
||||
|
||||
请求示例（字段待后续业务样例细化）：
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "third-party-unique-id",
|
||||
"source": "third-party-system",
|
||||
"account_ref": "chis-account-alias",
|
||||
"person": {
|
||||
"id_card": "440000********1234",
|
||||
"name": "张三"
|
||||
},
|
||||
"check_date": "2026-07-04",
|
||||
"health_check": {
|
||||
"height": 170,
|
||||
"weight": 65
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
成功响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"trace_id": "TRACE_ID",
|
||||
"data": {
|
||||
"request_id": "third-party-unique-id",
|
||||
"idempotent": false,
|
||||
"chis_result": {
|
||||
"code": 200,
|
||||
"message": "success"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
重复提交响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"trace_id": "TRACE_ID",
|
||||
"data": {
|
||||
"request_id": "third-party-unique-id",
|
||||
"idempotent": true,
|
||||
"chis_result": {
|
||||
"code": 200,
|
||||
"message": "success"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码
|
||||
|
||||
| code | HTTP | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `unauthorized` | 401 | 第三方鉴权失败 |
|
||||
| `forbidden` | 403 | 第三方无权限使用该账号或机构 |
|
||||
| `bad_request` | 400 | 请求体格式错误或必填字段缺失 |
|
||||
| `invalid_health_check_data` | 400 | 体检字段校验失败 |
|
||||
| `missing_health_check_query_params` | 400 | 查询体检详情缺少 `healthCheck`、`phrId`、`idCard` 或 `checkDate` |
|
||||
| `chis_login_failed` | 502 | CHIS 登录失败 |
|
||||
| `chis_session_invalid` | 502 | CHIS 会话无效且重登失败 |
|
||||
| `chis_request_failed` | 502 | CHIS 业务接口失败 |
|
||||
| `chis_timeout` | 504 | CHIS 请求超时 |
|
||||
| `idempotency_conflict` | 409 | 相同幂等键对应不同请求体 |
|
||||
|
||||
## 内部模块合约
|
||||
|
||||
### `ChisSessionManager.ensure_session(account_ref)`
|
||||
|
||||
输入：
|
||||
|
||||
```python
|
||||
account_ref: str
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```python
|
||||
ChisSession(
|
||||
cookies=dict,
|
||||
uid=str,
|
||||
role_id=str | None,
|
||||
manage_unit=str | None,
|
||||
expires_at=datetime,
|
||||
)
|
||||
```
|
||||
|
||||
职责：
|
||||
|
||||
- 优先读取 Redis 有效会话。
|
||||
- 会话不存在或验证失败时登录 CHIS。
|
||||
- 登录成功后缓存会话。
|
||||
- 不返回明文密码。
|
||||
|
||||
### `ChisCrypto.sm2_encrypt(public_key, raw_text)`
|
||||
|
||||
职责：
|
||||
|
||||
- 使用配置中的 CHIS public key 加密密码和时间戳 `d`。
|
||||
- 兼容已有 `hans_chis.sm2.sm2_encrypt` 行为：`gmssl.sm2.CryptSM2(mode=0)`，返回带 `04` 前缀的十六进制密文。
|
||||
- 不记录明文和密文到普通业务日志。
|
||||
|
||||
### `HealthCheckQueryClient.get_detail(session, health_check, phr_id, id_card)`
|
||||
|
||||
输出：CHIS `getHMNIListOfHTML` 的标准化结果。
|
||||
|
||||
职责：
|
||||
|
||||
- 组装 `chis.healthCheckService / getHMNIListOfHTML` 请求。
|
||||
- 不做第三方鉴权。
|
||||
- 不保存数据。
|
||||
|
||||
### `HealthCheckQueryClient.get_check_info(session, id_card, check_date)`
|
||||
|
||||
输出：CHIS `getCheckInfoDetail` 的标准化结果。
|
||||
|
||||
职责：
|
||||
|
||||
- 组装 `chis.healthCheckService / getCheckInfoDetail` 请求。
|
||||
- 身份证号日志脱敏。
|
||||
|
||||
### `HealthCheckMapper.to_chis_payload(input_model, session_context)`
|
||||
|
||||
输入：内部体检标准模型和 CHIS 会话上下文。
|
||||
|
||||
输出：CHIS `*.jsonRequest` 请求体。
|
||||
|
||||
职责：
|
||||
|
||||
- 字段映射。
|
||||
- 字典值转换。
|
||||
- 默认值和空值处理。
|
||||
- 不访问网络，不访问 Redis。
|
||||
|
||||
### `ChisClient.json_request(session, payload)`
|
||||
|
||||
职责：
|
||||
|
||||
- 发送 CHIS `*.jsonRequest`。
|
||||
- 携带 cookie 和 header。
|
||||
- 处理 timeout、CHIS 错误、未登录。
|
||||
- 返回标准化 CHIS 响应对象。
|
||||
Reference in New Issue
Block a user