design.md 13 KB

Context

DRG 医保控费系统需要从 HIS 同步住院患者就诊数据(接口 02010067 = src.DRG.HISData.HisDataService.GetInpatientData)。现有自动同步机制依赖后端 SyncTaskService(02010083/02010079/02010080/02010084)+ 前端 SyncTaskConfig.tsx + 日志 02010077。原先配套的桌面触发程序 HISAutoSyncService(仅"敲门" 02010083,不构建 session、不调 02010067)已从本项目移除,其功能由本方案小程序替代。

本方案要交付一个独立桌面小程序,由业务人员/运维在 Windows 上运行,直接面向 DRG 平台:

  • 先拉 01010064(FindHospDetail,返回机构数组 HospitalInfoItem { id, hospCode, code(=医保机构编码 OrganizationCode), descripts, MedinsLv, ... });
  • 据此构建业务 session(机构字段全部来自 01010064);
  • 拉 02010079(GetSyncConfig(hospCode) 返回单条配置 { syncType, frequency, scheduledTime, lookbackDays, enabled, synFlag, warningFlag, status, ... });
  • 调用 02010067(GetInpatientData,入参 admID, hospID, stDate, endDate, SynFlag,必须带 session)。

系统约束:

  • 生产/部署端点 127.0.0.1:52773(或 172.16.2.15:52773)CSP 路径 /csp/drg/sysInternalMutiple,Basic 鉴权 _SYSTEM:pryk@2020(base64 X1NZU1RFTTpwcnlrQDIwMjA=)。
  • 前端 SessionInfo 完整字段约 30 个(见 frontend/src/api/request.ts),其中机构相关:hospYBCode/hospCode/hospDesc/hospID/medinsLv;其余(userID/userName/locID/locDesc/sessionID/groupID/...)为非机构字段,由程序默认值填充。
  • 请求体标准结构:{ "code": "...", "params": [ {...} ], "session": [ {...} ] }。

Goals / Non-Goals

Goals:

  • 交付独立可运行的 C# 桌面小程序,可最小化到托盘、可查看本地接口调用日志。
  • 程序内下拉选择机构(01010064),选机构后加载并展示 02010079 同步配置。
  • 调用 02010067 必须带 session,且 session 机构字段来自 01010064;未选机构时拦截并提示。
  • 支持手动「立即执行一次」,以及经 Windows 任务计划程序驱动的外部定时调用(程序需提供无头 --sync 模式与「注册任务计划」能力)。
  • 每一次接口调用均写入本地滚动日志,可在界面内查看或打开日志文件。

Non-Goals:

  • 不复用已移除的 HISAutoSyncService 代码(保持独立项目)。
  • 不改动后端接口、表结构、前端页面。
  • 不在程序内部实现独立的定时器轮询(定时交给外部 Windows 任务计划程序,符合已确认决策)。
  • 不做同步失败的主动告警/推送(仅本地日志 + 标准响应记录)。

Decisions

决策1:项目定位——新建独立项目 DRGInterfaceClient(替代已移除的 HISAutoSyncService)

选择:新建 DRGInterfaceClient/,代码完全独立。本小程序是"业务客户端"(带 session 调 02010067),替代原先仅做无状态周期敲门的桌面触发器,二者无需同时运行。

理由:职责不同——本小程序需要感知机构与同步配置、构建业务 session、调用具体业务接口;原 HISAutoSyncService 仅做无状态的周期敲门,现已移除。本方案独立实现,避免耦合与回归风险。


决策2:技术栈——.NET Framework 4.8 + WinForms,无第三方包

选择:TargetFramework = net48(Windows 系统自带运行时,免安装),引用 System.Windows.Forms、System.Net.Http、System.Web.Extensions(JavaScriptSerializer)、System.Drawing。无任何第三方 NuGet 包。

复用:HTTP 调用与 JSON 序列化逻辑沿用既有成熟模式(HttpClient + JavaScriptSerializer,请求/响应/日志处理),但作为新文件 DrgApiClient.cs 独立存在。


决策3:机构选择与会话构建

流程:

  1. 启动后首屏仅加载机构下拉(调用 01010064,参数 active="" 取全部),不自动执行同步(已确认"需手动开始")。
  2. 操作员从下拉框选择单个机构;下拉项显示 descripts,值为 hospCode(同时保存 id/code/MedinsLv 供 session 与定时匹配使用)。
  3. 选机构后点「加载配置」→ 调 02010079(带 session,此时 session 已含机构字段)→ 展示配置。

Session 映射(SessionBuilder.Build(hospital, defaults)):

session 字段 来源
hospYBCode hospital.code(医保机构编码 OrganizationCode)
hospCode hospital.hospCode
hospDesc hospital.descripts
hospID hospital.id
medinsLv hospital.MedinsLv
其余字段(userID/userName/locID/locDesc/groupID/groupDesc/sessionID/langID/langDesc/changeFlag/...) appsettings.json 的 SessionDefaults 默认值(如 userID="DRGClient"、userName="接口客户端"、sessionID="" 等)

必填校验(已确认:机构字段必填,未选中时给出提示):在调用 02010079/02010067 前检查当前已选机构;若为空,DrgApiClient 直接返回错误提示 UI 并写日志"请先选择医疗机构",不发起 HTTP 请求。


决策4:02010067 调用的日期区间计算规则

「立即执行一次」/「--sync」调用 02010067 时,参数依据 02010079 配置计算:

  • admID = ""
  • hospID = 当前机构 hospCode
  • SynFlag = 配置 synFlag(默认 "Y")
  • 日期区间:
    • syncType = "incremental"(增量):endDate = 今天(YYYY-MM-DD),stDate = 今天 - LookbackDays 天(如 LookbackDays=3 → 3 天前)。
    • syncType = "full"(全量):endDate = 今天,stDate = appsettings.FullSyncStartDays 天前(默认 365,可配);若 FullSyncStartDays <= 0 则 stDate = ""(交由后端默认)。
  • 日期格式 YYYY-MM-DD,使用 DateTime/ToString("yyyy-MM-dd"),不引入 dayjs/第三方日期库。

备注:以上日期计算为客户端约定,与后端 SyncTaskService.ExecuteScheduledSync 的增量/全量语义保持一致;若后端对 stDate/endDate 另有强制要求,以后端返回为准,客户端仅负责按配置传入。


决策5:外部定时——--sync 无头模式 + 「注册任务计划」

两种运行模式:

  1. GUI 模式(默认双击运行):托盘 + 主界面,需人工选机构、点按钮(已确认"需手动开始")。
  2. 无头 --sync 模式(供 Windows 任务计划调用):程序检测到 --sync 参数时:
    • 读取 appsettings.json 的 ScheduledHospCode(用于定时运行的机构,匹配字段为机构 code 即医保机构编码,由运维在 GUI「设为定时机构」中写入,或手动编辑配置);
    • 调 01010064 → 按 code 匹配机构 → 构建 session → 调 02010079 → 计算日期 → 调 02010067 一次 → 写日志 → 以退出码 0(成功)/1(失败) 结束进程。
    • 若 ScheduledHospCode 为空或按 code 匹配不到机构,写日志报错并以退出码 1 结束。

调度启动(满足"根据 02010079 配置设置定时调用任务" + 已确认 hourly 走程序内整点轮询):操作员点「开始调度」后,按当前 02010079 配置的 frequency 启用对应机制:

frequency 调度机制 说明
hourly 程序内整点轮询(不注册 Windows 任务) 程序常驻(托盘),内部 Timer 在下一个整点(nowMM=0)首次触发,之后每小时整点触发一次 02010067;托盘显示"下次运行 HH:00"倒计时
daily 注册 Windows 计划任务(外部) schtasks /SC DAILY /ST HH:mm,操作 "<程序目录>\DRGInterfaceClient.exe" --sync
weekly 注册 Windows 计划任务(外部) schtasks /SC WEEKLY /D MON /ST HH:mm,操作同上
manual 不调度 仅可手动「立即执行一次」
  • hourly(程序内整点轮询):MainForm/SchedulerService 持有一个 System.Timers.Timer(每分钟检查一次,命中整点 nowMM==0 且距上次执行 > 55 分钟时触发),触发即执行一次 02010067(session + 增量日期区间)。若程序退出则轮询停止(已确认"外部任务计划"为总体取向,hourly 仅在程序驻留时生效;如需关机能自动跑,可改用 daily/weekly 外部任务或另配 --sync 的 schtasks)。
  • daily/weekly(外部 schtasks):点「开始调度」即调用 Process.Start("schtasks", ...) 创建/更新名为 DRGInterfaceClientSync(可配)的计划任务,操作指向 --sync;程序可继续驻留也可关闭,真正定时由 Windows 任务计划程序承担。
  • 任务名固定为 DRGInterfaceClientSync(可在 appsettings 配置);「停止调度」按钮:hourly 停止内部 Timer,daily/weekly 调 schtasks /Delete 移除任务。

说明:本程序对 daily/weekly 采用外部 Windows 任务计划;对 hourly 采用程序内整点轮询(已确认)。「开始调度」是把 02010079 配置"翻译"成具体调度动作,从而兑现需求 #5。


决策6:本地日志设计

  • 文件:DRGInterfaceClient.log(与 exe 同目录),按大小滚动(超过 MaxLogSizeMB 默认 5MB 时重命名为 .log.1 并新建)。
  • 每条记录:[yyyy-MM-dd HH:mm:ss.fff] [LEVEL] [接口码] 消息(LEVEL: INFO/ERROR/WARN),含 HTTP 状态码、耗时(ms)、响应前 200 字摘要或异常信息。
  • 查看:主界面内嵌多行只读 TextBox 实时追加(带自动滚动);右键菜单「打开日志」用 Process.Start 打开日志文件;另提供「清空日志」按钮。
  • 复用既有滚动日志思路,但作为新文件 Logger.cs 独立存在。

决策7:接口地址窗体可编辑 + 非空校验

选择:主界面顶部提供「接口地址」TextBox,初始值取自 appsettings.json 的 Endpoint(默认 http://127.0.0.1:52773/csp/drg/sysInternalMutiple);操作员可随时在窗体上修改。每次发起接口调用前 SHALL 校验文本框非空:为空则弹 MessageBox 提示"接口地址不能为空"并中断本次调用(不发起 HTTP 请求);非空则将文本框当前值写入运行时 Config.Current.Endpoint,供 DrgApiClient.CallAsync 使用。

理由:不同部署环境(本机 127.0.0.1 / 生产 172.16.2.15)端点不同,交由操作员在界面直接改比改配置文件更方便;非空校验避免拼出非法 URL。

细节:

  • MainForm 持有一个 Endpoint 运行时值(初始化自 Config.Current.Endpoint),文本框绑定该值。
  • 调用 01010064/02010079/02010067 前统一走 EnsureEndpoint():空 → 提示并返回 false;非空 → Config.Current.Endpoint = 文本框值 并继续。
  • 可选:程序退出时若勾选"记住地址",将文本框值写回 appsettings.json(初版仅运行时生效,不强制持久化;如需持久化在 tasks.md 6.6 README 说明)。

Risks / Trade-offs

Risk 1:定时模式与本程序每次都调 02010067 可能重复同步

风险:若 frequency=hourly 注册为每分钟任务,程序每次都直接调 02010067,可能造成后端重复写入。 缓解:02010067 后端 SyncEngine 本身对"已同步患者"有幂等/去重(按 admID 更新而非插入);且 LookbackDays 为滑动窗口,重复调用仅刷新窗口内数据,不会产生脏数据。也可以在 appsettings 设 SkipIfSuccessWithinMinutes 由客户端限流(可选增强,初版不实现)。

Risk 2:ScheduledHospCode 未配置导致 --sync 失败

风险:运维部署后忘设定时机构,计划任务每次跑都报错退出。 缓解:--sync 启动时若缺失则写明确错误日志(含如何设置 ScheduledHospCode 的说明),退出码 1,便于任务计划程序"失败触发"诊断;GUI 提供「设为定时机构」一键写入。

Risk 3:端点/令牌变更

风险:生产端点或 Basic 令牌变化导致调用失败。 缓解:端点与令牌集中在 appsettings.json,本地日志记录 HTTP 非 200 便于发现;凭证集中配置,变更策略统一。

Risk 4:机构下拉数据为空

风险:01010064 返回空列表(接口失败或权限问题),无法选机构。 缓解:下拉为空时禁用「加载配置」「立即执行一次」按钮,并显示提示;日志记录 01010064 失败原因。

Open Questions

  1. 全量同步起始日:syncType=full 时 stDate 取 今天-365天(可配 FullSyncStartDays)。(已确认:今天-365天,可配)
  2. ScheduledHospCode 取值:定时机构用医保机构编码 code 匹配(非 hospCode)。(已确认:用 code)
  3. hourly 调度粒度:hourly 采用程序内整点轮询(常驻托盘时每分钟检查、整点触发),不注册 Windows 任务;daily/weekly 才注册 schtasks。(已确认:程序内整点轮询)