MedicalInsurance/openspec/changes/his-sync-auto-trigger/proposal.md

Why

当前 DRG 医保控费系统的 HIS 业务数据同步（接口 02010067）依赖前端菜单手动触发，无法保证数据时效性与连续性。后端已具备自动同步所需的基础能力：SyncTaskService（RunScheduledTasks=02010083、InitScheduleTask=02010084）、SyncSchedulerTask、BS_HISSyncConfig 配置表，以及前端配置页 SyncTaskConfig.tsx 与日志查询接口 02010077。

但"自动触发"这一环尚未在生产环境真正落地：

1. 调度器主入口 ShouldRunNow 的 hourly 分支存在跨天去重 bug——用"一天内的秒数"判等，导致"昨天整点跑过、今天同一整点"被误判为"本小时已跑"而跳过，自动同步实际不会按每小时执行。
2. RunScheduledTasks 中 debugOn = 1 硬编码开启，每次扫描都会向 ^DRG.HIS.SyncConfig.Debug 写入大量诊断全局变量，生产环境必须关闭。
3. 既有部署脚本 Invoke-HisSyncScheduler.ps1 的 URL（指向 57772/healthshare/DRGHis，无鉴权头）与真实生产端点不符，直接运行会 404/405。
4. 缺少一个常驻、可运维的外部触发器来周期性调用 02010083。

本方案在 IRIS 2019（原生 %SYS.Task 只能"每天一次"，无法承担每小时粒度）的约束下，复用并完善现有代码，通过两个互补的外部触发器在生产服务器（172.16.2.15）上实现 HIS 业务数据的每小时自动同步。

What Changes

• 后端修复（复用现有类）
  • 修复 src.DRG.HISData.SyncTaskService.ShouldRunNow 的 hourly 跨天去重 bug：改为直接比较完整 $h 时间戳。
  • 关闭/可配置化 RunScheduledTasks 中的 debugOn（默认关闭，仅当 ^DRG.HIS.SyncConfig.DebugOn=1 时开启）。
  • 为 daily/weekly 增加 ±2 分钟容错窗口，避免调度器在整点时刻短暂抖动导致漏跑。
• 外部触发器一：C# 常驻服务 + 托盘程序（新建项目）
  • 新建 HISAutoSyncService/（.NET，无第三方依赖）：内置 System.Timers.Timer 每 60 秒向 02010083 发起一次 POST；交互运行时显示 NotifyIcon 托盘（启动/停止/上次运行时间/退出），以 --service 参数启动时作为 Windows 服务运行。
  • 通过 appsettings.json 配置端点、调用间隔、Basic 鉴权令牌（不硬编码）。
  • 本地滚动日志 HISAutoSyncService.log，记录每次调用结果。
• 外部触发器二：Windows 任务计划 + PowerShell（修复既有脚本）
  • 修复 Invoke-HisSyncScheduler.ps1：URL 改为 http://127.0.0.1:52773/csp/drg/sysInternalMutiple，Body {"code":"02010083","params":[{}]}，并带 Authorization: Basic X1NZU1REMTpwcnlrQDIwMjA= 头。
  • 新增 Register-TaskScheduler.ps1，用 schtasks 注册每分钟触发该 PS1 的计划任务。
• 部署与文档
  • 新增 Install-Service.bat / Uninstall-Service.bat（用 sc create 注册/注销 Windows 服务）。
  • 新增部署说明文档，讲清"两个触发器都调 02010083、由 ShouldRunNow + ^DRG.HIS.SyncConfig.LastRunTime 去重保证不会重复执行"这一安全机制。

Capabilities

New Capabilities

• his-sync-auto-trigger: HIS 同步自动触发器（外部常驻进程）。负责按固定间隔周期性调用 IRIS 接口 02010083，驱动 SyncTaskService.RunScheduledTasks 执行所有启用中的同步配置；提供 C# 服务/托盘与 Windows 任务计划两种部署形态，并保证并发触发下的幂等去重。

Modified Capabilities

• sync-task-management（既有 spec）：本次不新增能力，但修复其调度判定的跨天 bug 与诊断日志开关，使"每小时自动同步"这一既有能力在生产环境真正可用。

Impact

• 后端：修改 src.DRG.HISData.SyncTaskService.cls 的 ShouldRunNow 与 RunScheduledTasks（约 30 行改动），不新增后端接口，不修改表结构。
• 新增 C# 项目：HISAutoSyncService/（约 1 个 .sln/.csproj + 3~4 个 .cs 文件），依赖 .NET 6/8 运行时（Windows），无 NuGet 第三方包。
• 部署脚本：修改 Invoke-HisSyncScheduler.ps1，新增 Register-TaskScheduler.ps1、Install-Service.bat、Uninstall-Service.bat、部署说明文档。
• 前端：无改动（SyncTaskConfig.tsx、SyncLog.tsx、02010077 已存在且可复用）。
• 运维：生产服务器（172.16.2.15）需安装 .NET 运行时、注册 Windows 服务或计划任务；两个触发器同时部署可互为兜底。