chisup/docs/02-requirements.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
日志与请求归档	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 业务结果。
• 幂等：相同幂等键重复提交不会重复创建记录。
• 日志：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：由配置文件或环境变量提供，不从代码硬编码。
• 体检详情查询：已有 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 暴露。