# API / 模块合约

> 本文定义第三方 API、统一响应和内部模块合约的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。

## 通用约定

- 传输：HTTPS JSON。
- 编码：UTF-8 JSON。
- 时间格式：`YYYY-MM-DD` 用于业务日期，时间戳使用 ISO 8601。
- 第三方鉴权：待定，推荐 `Authorization: Bearer <token>` 或 `X-App-Key` + `X-Signature`。
- 每个响应包含 `trace_id`。
- 每个 API 请求都生成一个 archive 文件，保存 API 和 CHIS 请求 / 响应，详见 [架构设计](04-architecture.md) 的请求归档文件章节。

成功响应：

```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。
- 根据配置处理出站代理：`CHIS_PROXY` 为空直连；有值时为 CHIS HTTP 请求设置同一个 SOCKS5 代理。
- 处理 timeout、CHIS 错误、未登录。
- 返回标准化 CHIS 响应对象。