chisup/docs/04-architecture.md

架构设计

本文讲系统结构、职责划分、数据模型、技术难点和开发顺序。具体技术选型见 技术栈。

一、系统结构

第三方系统
  |
  | 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 会话对象。
• 保存幂等键和处理结果摘要。
• 可保存短期锁，避免同一账号并发重登。

三、建议项目结构

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 会话对象

建议结构：

{
  "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 中的体检详情查询需要：

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

检查报告信息查询需要：

{
  "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. 补幂等、日志脱敏、错误码和测试。