# 架构设计

> 本文讲系统结构、职责划分、数据模型、技术难点和开发顺序。具体技术选型见 [技术栈](03-tech-stack.md)。

## 一、系统结构

```text
第三方系统
  |
  | HTTPS JSON
  v
Flask API / middleware
  |
  | 参数校验、鉴权、幂等
  v
Application service
  |
  | 查询编排 / 上报编排 / 标准业务模型
  v
Mapper / transformer
  |
  | CHIS 保存请求模型
  v
CHIS client + auth manager
  |
  | cookies / session cache
  v
Redis
  |
  v
基卫 CHIS *.jsonRequest / 登录接口
```

## 二、职责划分

**API / view**

- 接收第三方请求。
- 完成第三方鉴权、trace_id、基础参数校验。
- 调用 application service。
- 返回统一响应。
- 不写 CHIS 字段映射和登录细节。

**middleware**

- 可以负责第三方鉴权、trace_id、请求体大小限制、日志上下文。
- 不建议每个请求无脑登录 CHIS。
- 如果做 CHIS 会话准备，也应调用 `ChisSessionManager.ensure_session()`，由 session manager 决定复用或重登。

**application service**

- 编排单条体检上报流程。
- 编排 CHIS 只读查询验证流程。
- 处理幂等查询、业务校验、调用 mapper、调用 CHIS client。
- 将 CHIS 错误翻译为本项目统一错误。

**mapper / transformer**

- 将第三方输入转换为内部标准模型。
- 将内部标准模型转换为 CHIS 请求体。
- 管理字段默认值、字典映射、日期格式、空值策略。
- 重点参考 `HealthCheckHtmlForm.js` 中 `getSaveRequest` 和 `saveToServer` 的行为。

**CHIS auth manager**

- 负责登录 CHIS、获取角色 / 应用 / 会话上下文。
- 负责查询当前账号信息或等价接口，判断会话是否有效。
- 负责 Redis 会话缓存、清理和重登。
- 登录链路参考 `D:\hans\chupd\chis\login_client_v2.py`，但不能原样依赖 Django model/cache。
- CHIS public key 从 Flask 配置或环境变量读取，不从代码硬编码。

**CHIS client**

- 封装 `*.jsonRequest` 和其他 CHIS HTTP 请求。
- 自动携带会话 cookie 和必要 header。
- 处理超时、重试、登录失效、错误码、日志脱敏。
- 先用 `getLanderInfo`、`getEncryType`、`getHMNIListOfHTML` 等只读接口验证通道，再接入保存接口。

**Redis repository**

- 保存 CHIS 会话对象。
- 保存幂等键和处理结果摘要。
- 可保存短期锁，避免同一账号并发重登。

## 三、建议项目结构

```text
chisup/
├── app/
│   ├── __init__.py
│   ├── api/
│   │   └── health_check.py
│   ├── middleware/
│   ├── services/
│   │   ├── health_check_query.py
│   │   └── health_check_submit.py
│   ├── mappers/
│   │   └── health_check.py
│   ├── chis/
│   │   ├── auth.py
│   │   ├── client.py
│   │   ├── crypto.py
│   │   ├── session_store.py
│   │   └── errors.py
│   ├── repositories/
│   ├── validators/
│   └── config.py
├── tests/
├── docs/
├── reverse_file/
├── requirements.txt
└── README.md
```

## 四、核心数据对象

### 4.1 第三方上报请求

具体字段待定，建议至少包含：

| 字段 | 说明 |
| --- | --- |
| `request_id` | 第三方业务流水号，用于幂等 |
| `account_ref` | CHIS 账号或机构配置引用；不推荐直接传明文密码 |
| `person.id_card` | 居民身份证号，日志必须脱敏 |
| `check_date` | 体检日期 |
| `health_check` | 体检主体数据 |
| `source` | 第三方来源系统 |

### 4.2 Redis CHIS 会话对象

建议结构：

```json
{
  "base_url": "CHIS_BASE_URL_ALIAS",
  "uid": "CHIS_USER_ID",
  "role_id": "CHIS_ROLE_ID",
  "manage_unit": "CHIS_MANAGE_UNIT",
  "cookies": {},
  "login_at": "2026-07-04T00:00:00+08:00",
  "expires_at": "2026-07-04T02:00:00+08:00",
  "last_validated_at": "2026-07-04T00:10:00+08:00"
}
```

不要保存明文密码。确需保存账号凭证时，应使用安全配置或密钥管理，并在文档中明确加密和权限边界。

### 4.3 CHIS 体检保存请求

从逆向脚本可确认体检保存不是单表直传，至少涉及：

- `hcData`
- 生活方式数据
- 查体数据
- 辅助检查数据
- 健康评价 / 指导数据
- 用药、住院、非免疫规划接种等列表数据

最终字段以真实 CHIS 请求和 schema 验证为准。

### 4.4 CHIS 体检详情查询请求

已确认 `reverse_file/20260704_query_health_check.har` 中的体检详情查询需要：

```json
{
  "serviceId": "chis.healthCheckService",
  "method": "execute",
  "serviceAction": "getHMNIListOfHTML",
  "schema": "chis.application.hc.schemas.HC_HealthCheck",
  "body": {
    "healthCheck": "体检主键",
    "phrId": "健康档案号",
    "idCard": "身份证号"
  }
}
```

检查报告信息查询需要：

```json
{
  "serviceId": "chis.healthCheckService",
  "serviceAction": "getCheckInfoDetail",
  "method": "execute",
  "body": {
    "idCard": "身份证号",
    "checkDate": "体检日期"
  }
}
```

注意：当前资料不能证明“只传 `healthCheck` 就能查详情”。若外部 API 要支持只传体检 id，需要先验证如何由 `healthCheck` 反查 `phrId`、`idCard`、`checkDate`、`empiId`、`createUser`。

## 五、关键技术难点

| 难点 | 说明 | 应对 |
| --- | --- | --- |
| CHIS 登录链路 | 可能涉及公钥、加密、角色、应用、机构上下文 | 等用户提供现有代码后接入，先写 auth 边界 |
| 会话有效性 | cookie 存在不代表 CHIS 会话仍有效 | 用账号信息查询接口确认，失败则清理缓存并重登 |
| 只传体检 id 查询详情 | `getHMNIListOfHTML` 还需要 `phrId` 和 `idCard` | 先要求调用方传全参数，后续验证反查链路 |
| 体检字段转换 | CHIS 前端保存逻辑复杂，数据块多 | 先做最小样例 mapper，逐步补字段测试 |
| 幂等 | 第三方重试可能导致重复体检记录 | 使用 `source + request_id` 或业务唯一键保存结果 |
| 隐私与日志 | 涉及身份证号、体检数据、账号凭证 | 统一脱敏，敏感字段禁止落日志 |
| CHIS 接口变化 | 逆向接口可能因版本变化失效 | client 层集中封装，转换层有测试样例 |

## 六、推荐开发顺序

1. 初始化 Flask 项目骨架和测试命令。
2. 接入 CHIS 登录代码，验证能获取有效会话。
3. 实现账号信息查询 / 会话有效性确认。
4. 实现 Redis 会话缓存、锁和失效重登。
5. 实现通用 CHIS `*.jsonRequest` client。
6. 先跑通体检详情只读查询，验证登录、会话、角色/机构、SM2 加密和错误处理。
7. 定义第三方体检上报 API 和统一响应。
8. 实现最小体检 mapper。
9. 通过通用 CHIS request 提交最小样例。
10. 补幂等、日志脱敏、错误码和测试。