Files
next-tjwater-server/docs/periodic-task-execution.md
T
jiang 9cd1400723
Generic Container CI/CD / test-build-publish (push) Successful in 4m23s
Server CI/CD v2 / build-test-publish-and-deploy (push) Successful in 4m23s
fix(replay): preserve failed periodic execution boundaries
2026-11-16 16:21:58 +08:00

54 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 播放时间驱动的周期任务
2026-11-11:SCADA 数据诊断与管网定时模拟接入实际处理,管网智能调度与泵站能耗检查保留现有动作模板。任务名称、列表、报告及 Agent 指令使用业务表述;内部执行来源与证据限制分别保存。
## 时钟与周期
新建回放请求 `scheduled_tasks_enabled: true` 启用两类实际任务,供水前端默认发送该字段。省略字段的旧客户端与已有回放继续保持原有处理行为。项目监测周期读取 MetaDB `projects.settings.scada_monitoring_interval_seconds`,本业务约定为 `900` 秒;前端保留的 SCADA 任务模板也改为 15 分钟。5 分钟时间轴定位刻度、180 倍播放速度、设备采样周期和接口轮询间隔各自独立。
播放或单步在业务周期终点 T 读取并提交本周期观测、诊断回执和调查关联,随后创建周期执行记录并提交水力计算。水力任务未结束时暂停时间推进,已有调查可以独立执行。关闭页面停止继续推进;已提交的计算仍由现有 calculation worker 完成。跨日期推进保留原始业务时间,查看历史指针不触发处理;向已处理时刻重新监测沿用新建回放的因果边界。
## SCADA 数据诊断
执行步骤为读取观测、检查新鲜度完整率、诊断压力流量与水质、判断潜在事件、整理诊断结论。复用现有清洗、动态压力阈值、爆管侦测及指标规则,不按已知事件日期生成异常。
周期记录分别保留数据质量、压力/流量运行异常、疑似爆管与疑似污染线索。水质必须有指标名称、单位及明确业务阈值;只知道 `mg/L` 不能推断测量对象。水质规则尚未配置时明确记录污染风险未评估。水质有效异常进入现有独立 `water_pollution` 调查,不等待压力基线或爆管模型就绪,纯水质异常不强制进入爆管定位。周期报告从已冻结周期批次事件和持续异常状态读取水质证据,保留关联调查;周期内发生后恢复的异常仍记入本周期,水质证据不计入爆管支持分。
仪表量程用于读数有效性校验,业务阈值用于异常判断;可靠采集的异常值保留。异常持续期间复用已有调查;恢复与再次发生沿用现有异常事件生命周期。正常周期由 Server 生成报告,不启动 Agent。
## 管网定时模拟
在创建本轮回放时,以只读一致事务导出 EPANET 2 输入并保存摘要。完整模型按 gzip 压缩保存,原文限制为 64 MiB、压缩后限制为 8 MiB,冻结设备目录与周期输入后,计算 worker 使用相同模型版本和不超过本周期 `batch_sequence`、`knowledge_cutoff` 的观测。计算不重新查询实时 TSDB,不更新在线模型、正式 raw 或实时基线。
现有 `wntr==1.3.2` 与 EPANET 内核运行逐观测时刻的稳态水力复核,与原在线滚动重算的计算语义一致。每个时刻计算全部节点和管段,将已关联测点的压力、流量按单位转换后与实测比较。水箱水位、工频泵状态和需水量只有在单位及关联明确时覆盖模型边界;变频频率与水源液位缺少已核实换算依据时保留冻结模型设定,并明确报告限制。
输出压力/流量平均相对偏差、最大节点压差、偏差测点及关联要素、全模型规模、原始比较明细与缺项。近零实测不计算百分比。模板压力 8%/12%、流量 10%/15%、最大压差 5m/8m 的关注/异常阈值用于本版复核,不能解释为爆管确诊阈值。比较已完成的相邻周期及本轮模型下此前七天同窗结果,缺少参考时列出实际日期,不补造基线。偏差来源输出待核查原因,不将参数或边界问题当作已证实事实。
## 持久化与重试
不新增数据库表。压缩模型输入保存在 `peripheral_sample.scada_replay_batches` 的零号 `model_snapshot` 批次,回放主文档只保存摘要和就绪标记,避免轮询和每帧处理重复加载、重写完整模型。执行记录保存在业务批次的 `document.scheduled_tasks`,不通过回放快照返回完整模型。
每条执行身份由回放、任务类型和周期终点确定,同周期重复命令复用记录。水力计算复用 `workbench.calculation_jobs`,内部工具键为 `scheduled_network_simulation`。提交与执行分别核验项目成员和 SCADA 读取、清洗、水力计算权限。任务直接由 Server 执行,不伪造 Agent 会话、运行租约或 OAuth 上下文。
worker 沿用现有并发限制、子进程隔离、超时、租约及代次栅栏。成功结果和终态在同一栅栏事务内回写周期记录,计算队列结果过期不删除已保存的业务报告。失败或中断可按原模型、批次和时间边界重试,增加 attempt,保留同一执行身份。
水力计算排队或运行期间保留当前周期;失败、超时、中断或计算记录丢失后,播放与单步均停止推进。报告保留已完成的冻结步骤,将计算步骤标为失败、后续比较和复核步骤标为跳过;队列容量不足的失败同样适用。可在工况任务中重试本周期计算,成功后再继续播放,或停止后重新开始一轮。重复发送已接受命令仍返回原回执,不重新执行。SCADA 诊断已提交的正常、异常或数据不足结论均保留。
管网智能调度与泵站能耗检查继续使用原有 mock 动作模板,尚未接入执行算法。
## 接口与前端
- `GET /api/v1/scada-replays/{replay_id}/scheduled-tasks?offset=0&limit=100`:分页查询周期记录,仅读取已提交结果;不创建任务。
- `POST /api/v1/scada-replays/{replay_id}/scheduled-tasks/{execution_id}/retry`:提交 `{ "request_id": "UUID" }`,重试失败的水力计算。
- 回放快照增加 `scheduled_tasks_enabled`、`periodic_pending`、`periodic_error`;轮询实际队列状态,不把排队视为完成。
前端以当前回放业务时间生成保留的调度与能耗任务,暂停后进度冻结。SCADA 和管网定时模拟仅使用后端持久化周期记录,不因未启动回放、未启用周期作业或接口失败而退回生成模板。无回放时提示启动监测,旧回放未启用时提示重新开始;读取失败显示错误并保留已读取的后端记录。列表显示最近六小时,接口保留分页历史。执行状态和诊断结论分开,报告展示实际步骤、指标、证据、缺项、调查与重试入口;刷新保留当前选中报告。
## 验证与启用
后端使用 `tests/unit/test_periodic_tasks.py`、`test_periodic_hydraulics.py` 及现有回放、计算 worker 和架构边界测试;真实 SQL 与 EPANET 联合检查为 `PERIODIC_TASK_STORAGE_TEST=1 python -m pytest tests/integration/test_periodic_task_storage.py -q`。该集成检查只使用独立项目 UUID,所有记录强制回滚,不保留测试观测或任务。
前端运行 `pnpm lint`、`pnpm typecheck`、`pnpm test`、`pnpm build`,聚焦浏览器检查为 `pnpm test:browser tests/browser/periodic-tasks.e2e.ts`,覆盖桌面、手机、失败重试、刷新恢复与水平溢出。接口变更后重新导出 Server OpenAPI 并同步 Agent 的生成契约。
部署使用现有 API 与 calculation worker,不增加服务或迁移。两个进程都需要加载本轮代码,旧 worker 无法执行新增内部工具。未运行实际 Agent、现场审批或设备操作时,不将静态检查、固定浏览器响应和原生计算验证报告为现场业务验收。