# 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 | 相同幂等键对应不同请求体 |

## 内部模块合约

### `ChisLoginClient.from_config(config).login(username, password)`

输入：

```python
username: str
password: str
```

输出：

```python
ChisLoginSession(
    cookie=str,
    jsessionid=str,
    role_id=str,
    role_name=str,
    user_name=str,
    roles_result=dict,
    apps_result=dict,
)
```

职责：

- 从 `CHIS_BASE_URL`、`CHIS_PUBLIC_KEY`、`CHIS_PROXY` 创建登录客户端。
- 调用 `logon/myRoles`，使用 SM2 加密密码和时间戳 `d`。
- 优先选择 `责任医生助理` 或 `责任医生` 角色。
- 调用 `logon/myApps` 获取应用上下文。
- 从 `Set-Cookie` 提取 `JSESSIONID`，组装 CHIS cookie。
- 登录失败、缺少允许角色、缺少 cookie 时抛出 `ChisLoginError`，错误对象包含稳定 `code`。

### `ChisLoginClient.get_lander_info(cookie)`

输入：

```python
cookie: str
```

输出：CHIS `chis.myPageService / getLanderInfo` 原始字典响应。

职责：

- 使用已有 CHIS cookie 调用 `*.jsonRequest?`。
- 请求体固定为 `serviceId=chis.myPageService`、`serviceAction=getLanderInfo`、`method=execute`。
- 成功时返回当前账号信息响应。
- CHIS 返回非 200 业务码时抛出 `ChisLoginError(code="chis_session_invalid")`，用于判断会话无效。

### `RedisChisSessionStore`

职责：

- 使用 Redis key `chis:session:{account_ref}` 保存 CHIS 会话对象。
- `save(account_ref, session)` 按 `expires_at` 计算 TTL 并调用 Redis `setex`。
- `get(account_ref)` 只返回未过期会话；发现过期会话时删除缓存并返回 `None`。
- `delete(account_ref)` 清理指定账号引用的缓存。
- 会话 JSON 包含 `base_url`、`uid`、`role_id`、`manage_unit`、`cookies`、`login_at`、`expires_at`、`last_validated_at`，不得包含明文密码。

### `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 响应对象。