MedicalInsurance/openspec/changes/his-fee-sync-async-optimization/tasks.md

1. M3 费用明细批量落库引擎（优先，可独立上线）

• 1.1 备份现有实现：将 HisDataService.SaveInpatientFeeData 原实现复制为 SaveInpatientFeeDataLegacy，作为回滚基线
• 1.2 重写 SaveInpatientFeeData：按就诊一次性预加载 (FeedetlSn → ID) 到内存映射，替换逐行 &sql(SELECT ID ...) 存在性查询
• 1.3 用 %SQL.Statement 预编译参数化 INSERT 与 UPDATE（各 %Prepare 一次），循环 %Execute 替换逐行 src.util.operatetable.Insert/Update
• 1.4 引入分段事务：每 500 行 TCOMMIT + TSTART，段大小可配置，失败仅回滚当前段
• 1.5 FeeDetailJson 惰性序列化：仅插入时执行 %ToJSON()，更新时沿用原值；超长截断并 LogSyncError 告警
• 1.6 保持返回字段不变（admCount/totalCount/insertCount/updateCount/failedCount/skippedCount/details）与 (AdmDr, FeedetlSn) 增量 Upsert 语义
• 1.7 后端取值规范：新增/改造代码中禁止 $G() 包裹入参，统一 set xxx= params.xxx 形式（%Get(0) 取数组首元素、rs.%Get("Col") 取结果集列除外）
• 1.8 编译 src.DRG.HISData.HisDataService 并校验无语法/括号配对错误

2. M4 主链路缺陷修复

• 2.1 删除 HisDataService.GetInpatientData 中第 446 行的无条件 DeviceFeeWarning 重复调用，保留 if (policyType="DRG") / elseif (policyType="DIP") 分支结果
• 2.2 校验 DIP 机构返回的响应为 GetDIPGroupScoreFeeWarning 结果，不再被覆盖
• 2.3 确认 GetMedicalRecord 每人次调用失败不中断主循环，纳入后续异步阶段
• 2.4 编译并回归 02010067 同步模式（DRG 与 DIP 各验证一次）

3. M1 异步任务受理与状态机

• 3.1 核对生产 BS_HISSyncConfig 实际列结构，确认 FeeFlag 等既有字段状态
• 3.2 新建表类 src/src/User/BSHISSyncTask.cls（SqlTableName = BS_HISSyncTask）：按项目表类规范声明 Extends (%Persistent, %XML.Adaptor, src.util.DynamicObject.Adapter)、SqlRowIdName = ID、Parameter %JSONREFERENCE = "ID" 与完整 Storage 块
• 3.3 建表字段：TaskID/HospCode/HospName/SyncType/StDate/EndDate/AdmID/Status/Phase/AdmTotal/AdmProcessed/FeeTotal/FeeProcessed/SuccessCount/FailedCount/SkippedCount/StartTime/EndTime/ErrorMessage 及公共字段
• 3.4 建索引：TaskIDIndex On TaskID [Unique]、HospStatusIndex On (HospCode, Status)、CreateDateIndex On CreateDate
• 3.5 编译建表并用 PowerShell 统计 { 与 } 数量校验括号配对（写入后延时 20 秒复查，规避 IDE 自动重写）
• 3.6 GetInpatientData 增加 asyncFlag 解析（依次取 params.asyncFlag → BS_HISSyncConfig.AsyncFlag → 'N'）
• 3.7 实现异步受理分支：并发去重（同 (HospCode, StDate, EndDate, AdmID) 存在 pending/running 则复用 taskId）→ 落任务记录 → JOB 启动 RunSyncTaskAsync → 立即返回 {taskId, status:'pending'}
• 3.8 实现 RunSyncTaskAsync(taskId) 后台入口：状态流转 pending→running→success/partial/failed、阶段 fetch/saveAdm/saveFee/done、每就诊或每 500 行回写进度
• 3.9 实现僵死任务回收：running 且超过阈值（默认 30 分钟）无进度更新则置 failed 并写 ErrorMessage

4. M2 任务进度查询接口 02010089

• 4.1 在 src/src/DRG/HISData/HisDataService.cls 实现 GetSyncTaskProgress(jsonObj)：按 taskId 只读查询，返回状态/阶段/计数/percent/时间/错误摘要
• 4.2 在 src/src/DRG/HISData/Interface.cls 增加 GetSyncTaskProgress 委托方法（四行头注释含 /// Code: 02010089）
• 4.3 处理 taskId 不存在的场景：返回非 '0' 的 errorCode 与提示，不抛异常
• 4.4 新建 scripts/insert_his_sync_task_interface.sql 注册 CB_MapInterface：Code='02010089'、ClassName='src.DRG.HISData.Interface'、MethodName='GetSyncTaskProgress'、ServiceType='S'
• 4.5 编译 src.DRG.HISData.* 并验证接口路由可达

5. 配置开关 AsyncFlag 透传

• 5.1 新建 scripts/alter_his_sync_config_asyncflag.sql：为 BS_HISSyncConfig 增加 AsyncFlag 列并回填 'Y'
• 5.2 src/src/User/BSHISSyncConfig.cls 增加 AsyncFlag 属性（InitialExpression = "Y"）
• 5.3 SyncTaskService.GetSyncConfig(02010079) 与 SaveSyncConfig(02010080) 增加 AsyncFlag 字段透传
• 5.4 编译并验证配置查询/保存接口返回 asyncFlag

6. M5 网关与链路加固

• 6.1 在 frontend/nginx.conf 8082 的两个 location 补全 proxy_connect_timeout、proxy_send_timeout、client_max_body_size 与 proxy_buffering 相关参数
• 6.2 排查中间转发器 172.16.1.6:8082 的 proxy_read_timeout 配置并记录实际值（504 大概率源于该跳）
• 6.3 输出更新后的完整 nginx 配置片段供运维替换
• 6.4 验证异步受理请求与轮询请求均不再触发 504

7. M6 前端进度化改造

• 7.1 frontend/src/api/hisData.ts：HisInpatientSyncParams 增加 asyncFlag?: string，新增 getSyncTaskProgress(taskId) 方法（code 02010089）
• 7.2 frontend/src/pages/HIS/DataSync.tsx：同步请求携带 asyncFlag:'Y'，受理后取 taskId 启动轮询
• 7.3 轮询逻辑：每 2s 调 02010089，用现有 Progress 组件展示 percent 与 feeProcessed/feeTotal，含超时保护与失败终止
• 7.4 移除前端 splitDateRange(..., 7) 按天切批逻辑与相关 MAX_RANGE_DAYS 状态，改为一次提交完整日期范围
• 7.5 任务终态后调用 02010075 刷新患者列表，并按 success/partial/failed 给出 message 提示
• 7.6 保留 admID 单患者同步入口，验证其在新流程下仍可用

8. 验证与回归

• 8.1 构造数万行费用明细的测试数据，对比改造前后 SaveInpatientFeeData 总耗时，确认单行平均耗时降至 5ms 以下
• 8.2 重复同步同一就诊，验证 (AdmDr, FeedetlSn) 不产生重复行、insertCount/updateCount 统计正确
• 8.3 验证 asyncFlag='N' 时 02010067 返回结构与改造前逐字一致（回归既有调用方）
• 8.4 验证 asyncFlag='Y' 时受理请求毫秒级返回，且轮询可观测到进度递增直至终态
• 8.5 验证并发去重：同一范围重复提交返回同一 taskId 且不重复起后台进程
• 8.6 验证 FeeFlag='N' 时不落库费用明细，且不影响就诊/分组/预警结果
• 8.7 验证僵死任务回收：模拟后台进程异常退出后，任务可被判定并置为 failed
• 8.8 生产部署：编译 User.BSHISSyncTask、User.BSHISSyncConfig、src.DRG.HISData.*，执行建表与接口注册脚本