chisup/docs/api.md

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 请求 / 响应，详见 架构设计 的请求归档文件章节。

成功响应：

{
  "ok": true,
  "trace_id": "TRACE_ID",
  "data": {}
}

错误响应：

{
  "ok": false,
  "trace_id": "TRACE_ID",
  "error": {
    "code": "bad_request",
    "message": "请求参数不正确"
  }
}

第三方 API

POST /api/v1/health-checks/query-detail

用途：查询 CHIS 中某次体检详情。第一版用于验证 CHIS 登录、Redis 会话、通用请求和查询链路。

第一版请求要求调用方传全参数：

{
  "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 就能查完整详情；后续任务会验证反查链路。

成功响应：

{
  "ok": true,
  "trace_id": "TRACE_ID",
  "data": {
    "healthCheck": "0000000000481718",
    "detail": {},
    "check_info": {}
  }
}

POST /api/v1/health-checks/submit

用途：提交单条体检数据到 CHIS。

请求示例（字段待后续业务样例细化）：

{
  "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
  }
}

成功响应：

{
  "ok": true,
  "trace_id": "TRACE_ID",
  "data": {
    "request_id": "third-party-unique-id",
    "idempotent": false,
    "chis_result": {
      "code": 200,
      "message": "success"
    }
  }
}

重复提交响应：

{
  "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)

输入：

account_ref: str

输出：

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