93 lines
6.3 KiB
Markdown
93 lines
6.3 KiB
Markdown
# 需求
|
||
|
||
> 本文只描述要什么与怎么算达成。技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。
|
||
|
||
## 一、业务现状
|
||
|
||
| 项 | 状态 |
|
||
| --- | --- |
|
||
| 用户 | 第三方系统需要把体检数据提交到基卫 CHIS |
|
||
| 数据 | 已有 CHIS 体检前端脚本、schema 和 HAR；第三方最终请求体待定 |
|
||
| 现有系统 | CHIS 是外部系统；本项目负责中间 API 和请求转发 |
|
||
| 约束 | 涉及 CHIS 账号权限、居民个人信息、体检隐私数据、内网接口和会话安全 |
|
||
|
||
## 二、用户角色
|
||
|
||
- 第三方系统：调用 `chisup` API 提交体检数据，接收统一成功或失败结果。
|
||
- `chisup` 服务：校验、转换、维护 CHIS 会话、提交 CHIS。
|
||
- CHIS 账号持有人 / 机构：提供合法账号、角色、机构权限。
|
||
- 运维 / 开发人员：排查上报失败、会话失效、字段转换错误。
|
||
|
||
## 三、功能清单
|
||
|
||
### 第一版 MVP
|
||
|
||
| 功能 | 用户能做什么 | 优先级 |
|
||
| --- | --- | --- |
|
||
| 第三方鉴权 | 通过 app_key / token 等方式调用上报接口 | P0 |
|
||
| 单条体检上报 | 提交一条体检数据并获得统一结果 | P0 |
|
||
| CHIS 会话管理 | 系统复用 Redis 会话，失效时自动重登 | P0 |
|
||
| 会话有效性确认 | 通过账号信息查询或等价接口确认登录有效 | P0 |
|
||
| 体检详情只读查询 | 根据体检主键和必要关联参数查询 CHIS 体检详情 | P0 |
|
||
| 体检数据转换 | 将第三方输入转换为 CHIS `hcData` 等保存结构 | P0 |
|
||
| 通用 CHIS request | 统一处理超时、错误码、登录失效、日志摘要和请求归档 | P0 |
|
||
| CHIS 代理配置 | 访问 CHIS 时可按配置走 SOCKS5 代理，未配置时直连 | P0 |
|
||
| 日志与请求归档 | `logs/` 每天滚动保留 1 年；`archives/` 每请求一个完整原始归档文件 | P0 |
|
||
| 幂等控制 | 第三方重试不会重复创建体检记录 | P0 |
|
||
|
||
### 后续迭代
|
||
|
||
| 功能 | 描述 | 阶段 |
|
||
| --- | --- | --- |
|
||
| 更多业务类型 | 高血压、糖尿病、老年人等专项随访或档案业务 | V2 |
|
||
| 管理后台 | 查看上报流水、失败重试、机构配置 | V2 |
|
||
| 异步队列 | 大批量上报、失败重试、削峰 | V2 |
|
||
| 字典管理 | CHIS 字典同步、映射配置可维护 | V3 |
|
||
|
||
## 四、核心用户故事（MVP）
|
||
|
||
1. 作为第三方系统，我可以携带合法鉴权信息提交体检数据。
|
||
2. 如果 CHIS 账号密码错误或没有权限，系统会提前返回清晰错误，不继续提交业务数据。
|
||
3. 如果 Redis 中已有有效 CHIS 会话，系统直接复用，不重复登录。
|
||
4. 如果 CHIS 会话失效，系统会重登一次并重试当前请求。
|
||
5. 作为开发和运维人员，我可以先用只读体检详情查询验证 CHIS 登录、加密、cookie 和通用请求是否可用。
|
||
6. 如果同一业务流水重复提交，系统返回同一处理结果或明确提示重复，不在 CHIS 产生重复记录。
|
||
7. 当字段校验失败、CHIS 接口失败或网络超时时，第三方能收到统一错误码和 trace_id。
|
||
|
||
## 五、验收标准（MVP）
|
||
|
||
- 第三方鉴权：未授权请求被拒绝，响应不泄露内部细节。
|
||
- 参数校验：缺少身份证号、体检日期、CHIS 账号引用、业务流水号等关键字段时返回参数错误。
|
||
- CHIS 登录：给定有效账号时可获取会话；无效账号提前返回登录失败。
|
||
- 会话复用：同一账号在 Redis 会话有效时，不重复执行完整登录链路。
|
||
- 会话失效：CHIS 返回未登录或账号信息查询失败时，自动清理缓存并重登一次。
|
||
- 体检详情查询：给定 `healthCheck + phrId + idCard + checkDate` 时，能查询 `getHMNIListOfHTML` 和 `getCheckInfoDetail`，且不产生写入副作用。
|
||
- 数据转换：最小体检样例能生成 CHIS 保存请求所需的 `hcData` 和相关数据块。
|
||
- CHIS 提交：能通过通用 request 提交到 CHIS 的目标接口，并返回 CHIS 业务结果。
|
||
- CHIS 代理：`CHIS_PROXY` 为空时所有 CHIS 请求直连；有值时 CHIS 登录、会话验证、查询和保存请求均通过 SOCKS5 代理访问 CHIS。
|
||
- 幂等：相同幂等键重复提交不会重复创建记录。
|
||
- 日志：`logs/` 中每天一个综合日志文件，包含不同级别摘要日志，保留 1 年；日志包含 trace_id、接口、耗时、结果，不包含明文密码、Cookie、完整身份证号。
|
||
- 请求归档：`archives/` 中每个 API 请求生成一个 archive JSON 文件，文件名包含日期、trace_id、request_id 等唯一字段；内容包含 `api` 和 `chis` 请求 / 响应数组；archive 不脱敏，仅用于内网前置机本地受控排查。
|
||
|
||
## 六、范围边界与决策
|
||
|
||
| 问题 | 决策 |
|
||
| --- | --- |
|
||
| 第一版平台 | 后端 API 服务 |
|
||
| 是否需要账号 | 第三方调用需要鉴权；CHIS 调用需要合法 CHIS 账号会话 |
|
||
| 第一版范围 | 单条体检上报闭环 |
|
||
| 暂不支持 | 管理后台、批量 UI、直接数据库写入、绕过权限 |
|
||
|
||
## 七、待确认 / 风险点
|
||
|
||
- CHIS 登录细节：已有 `D:\hans\chupd\chis\login_client_v2.py` 可参考；该代码依赖 Django，迁移到 Flask 时只复用登录链路和加密算法。
|
||
- 会话有效性接口：已有 `getLanderInfo` 代码可参考，仍需在 Flask 项目中实现并验证。
|
||
- CHIS public key：由配置文件或环境变量提供，不从代码硬编码。
|
||
- CHIS SOCKS5 代理：已确认需要可选配置；真实代理地址不写入仓库，后续通用 CHIS client 实现时验证代理可用性。
|
||
- 体检详情查询：已有 `reverse_file/20260704_query_health_check.har`；第一版查询需要调用方传 `healthCheck + phrId + idCard + checkDate`。
|
||
- 仅凭体检 id 查询：缺少从 `healthCheck` 反查 `phrId/idCard/checkDate` 的已验证链路，需后续验证。
|
||
- 第三方请求体：字段、字典、幂等键、账号引用方式待定。
|
||
- CHIS 保存接口：最终 `serviceId`、`method`、`schema`、`module` 和请求体需要用真实请求验证。
|
||
- 账号安全：是否允许第三方每次传 CHIS 账号密码需要业务确认；推荐平台配置账号，第三方只传机构或账号引用。
|
||
- 隐私合规：体检数据和身份证号属于敏感信息；运行日志必须摘要化，archive 按当前决策保存完整原始数据且不脱敏，因此必须受控访问、不进 git、不通过 API 暴露。
|