next-tjwater-server/docs/water-pollution-response-workflow.md

水污染侦测事件调查

水质监测侦测到异常后创建 workflow=water_pollution、event_kind=water_pollution 的事件调查，分发 water-pollution-event。water_quality_complaint 保持供水水质投诉上报语义，使用原投诉流程。两者不共用触发条件；污染事件不依赖爆管评分、压力下降或工单上报。

flowchart TD
    detection[有效水质观测命中业务规则] --> task[独立水污染事件调查]
    task --> evidence[全量观测及七天同期核验]
    evidence --> trace[快速候选溯源]
    trace --> node[展示已核验节点]
    node --> report[候选源阶段结论]
    report --> action[立即提出现场核查采样工单供审批派发]
    report --> simulation[污染传播模拟与累计浓度影响范围]
    report --> isolation[节点隔离与阀门边界]
    simulation --> impact[同一调查补充证据地图与报告]
    isolation --> impact
    action --> feedback[采样处置复测反馈]
    feedback --> review[接续原调查复核]
    impact --> review
    review --> final[最终报告及事件收尾]

侦测入口

现有 ScadaReplayService 使用冻结的水质设备类型 quality / water_quality 判别水质规则事件。仪表无效值、缺测产生的 data_quality 告警单独处理。水质业务规则命中直接创建污染调查，即使同时运行压力／流量周期诊断，也不被合并成爆管调查。持续规则事件沿用同一任务，规则恢复后接续该任务的新一轮。压力／流量与水质同时异常时各自保留调查。

当前侦测来源沿用既有 SCADA 历史回放处理器；本次没有新增实时采集或常驻水质侦测调度器。其他可信侦测生产者可经现有 operational-tasks 创建接口提交同一 workflow，保留实际侦测信号与发生时间；普通任务无需 replay_context。

临时溯源契约

run_contaminant_source_trace 要求 simulation.run，只读当前项目模型，禁止只读调查子角色调用。输入包含从水质设备映射或资产查询取得的 candidate_node_ids（1–20 个不同节点）及带时区、最长24小时的 start/end。回放窗口不能越过知识截止。接口直接返回结果，当前不入计算队列。

临时实现从提交的候选中核验模型节点，按字符串排序返回首个存在的节点，不执行反演或拟合。返回 located_node、top_candidates、validated_node_ids、missing_node_ids、selection_basis、algorithm_status=provisional；证据 origin=synthetic，不编造相似度或置信度。所有节点不存在时明确返回 no_candidate。后续正式算法替换服务内部选择逻辑，保留节点结果契约及后续调查步骤。

候选节点只是当前可分析目标；定位后先保存 interim/concluded，立即提出关联 general 现场核查／采样处置工单，随后继续污染传播模拟和 accident_element_type=node 的隔离。审核和派发不依赖模拟完成；等待工单时继续独立分析，模拟结果补入同一 task_id，不重复创建工单或改写已审核动作，权限与版本校验保持原有流程。

污染传播模拟与影响覆盖

run_contaminant_simulation 增加 include_impact_coverage（默认 false）与 impact_threshold_mg_l（默认0，严格大于）。开启时，在筛选最多20个展示节点之前，使用原生结果的全网节点、整个模拟窗口的报告采样汇总累计超阈值节点数、各节点首个超阈值报告时刻和峰值。原生浓度 MGL / UGL 分别转换为 mg/L 后比较；缺失、无效浓度、错误时间网格或不支持的单位保留为缺口，不能转成零浓度或安全范围。几何超过10000节点上限时仍返回数值估计，并明确地图不可用。

阈值仅为模型展示条件，默认0表示模型正浓度，不是水质安全限值。沿用当前模型初始水质、已有源和反应条件；统计的是总模型浓度，不能称为本次源的独立贡献。源浓度、模式、业务起算时刻、预测时长及其假设必须有依据，不能把余氯下降或浊度换算成污染源浓度。

回放同样允许该工具，要求启用影响覆盖且起算不晚于知识截止；预测时段可以越过截止，但后续时刻只是模型预测。与爆管情景一样，使用当前模型和空 SCADA 映射传入临时模型计算，不读取可变实时监测，不重建历史模型。仍禁止借此放开未授权观测或其他水力工具。

工具沿用计算队列和 owner/run 校验，返回终态后通过 get_calculation_result 读取并持久保存证据。presentation_preview 提供基于 evidence_id 的地图请求；用正式调查展示事件保存模型曲线和覆盖，历史播放还原已保存证据。审批、派发可在计算排队或运行期间进行；存在未终态计算时继续保留原运行，不允许发布 final 或成功结束调查，已有工单不受模拟失败影响。

展示、反馈与收尾

水质图表使用 chart.scada.metric=quality，沿用真实单位、三小时当前趋势、前七天同期散点及证据校验；不同指标分图。同单位不同水质指标通过图表纵轴名称区分展示分组。Server、Agent、Frontend 的图表协议同步支持 quality，正式报告仍需引用本轮全量 SCADA 证据。

关联现场任务使用 general 工单。成功创建后保存在 handling_context.work_orders，进入 waiting_work_order；全部有效工单 completed 后进入 field_review，接续 Agent，而非执行爆管压力恢复计算。最终 concluded 报告必须引用全部有效工单最新的 feedback_evidence_id，然后由 Server 完成任务并解除关联告警。完工反馈或新版本复测资料会重新进入复核；证据不齐时 Agent 使用现有提问／新动作流程等待事实。该机制校验反馈引用与调查收尾，不自动判断实验室水质合格。

所有新增状态保存在既有 JSON 文档，无数据库迁移、环境配置或新服务。现有服务更新代码及流程包后才生效；单元测试和契约校验不等同真实模型 Agent 调查验收。