feat: extend operational investigation workflows

docs/mcp-analysis-tools.md

@@ -52,17 +52,37 @@ Agent 原生工具统一使用 `mcp_tjwater_` 前缀。Server目录共67项：42
 - 数据源和计算假设必须有依据。定位漏水量和DMA总漏损约束使用m³/s；冲洗使用服务实际接收的m³/h，不沿用旧REST误标的L/s。工频泵序列0/1，变频泵序列为Hz；每项对应模型水力步长。冲洗当前限LPS/CMH模型。选址当前推荐压力点，不冒充污染溯源优化。
 - 调查结果经现有快照/证据/回执链保存，只有返回evidence_id后才引用为系统证据；普通聊天不自动保存调查证据。模拟结果始终是analysis而非实测。已知模拟事件源管段是输入背景，不是算法定位准确性的证明。
 
+## 关阀隔离输入与影响范围
+
+REST `/api/v1/valve-isolation-analyses` 与 MCP `analyze_valve_isolation` 共用同一服务。
+`accident_element_type` 默认为 `auto`：先识别管段 ID，再识别节点 ID；指定 `link` 时只匹配管段，指定 `node` 时只匹配节点。
+节点表和管段表分别保证 ID 唯一，但不同类型可以重号；分析同名节点必须显式指定 `node`。
+多个 ID 表示联合事故，不表示分别比较；类型参数作用于本次调用中的所有 ID。
+
+服务从模型主表的一致快照读取连接关系、初始开关状态和水源，不依赖 GIS 几何或物化视图刷新。
+不可关阀按保持现状处理；已关闭的管段、泵和阀门不参与连通，已关闭阀门不再列为建议关阀。
+未知的事故 ID、未知的不可关阀 ID 和空事故列表会被拒绝。
+
+- `affected_nodes` / `affected_node_count` 仍表示最近可关阀门围成的直接隔离区。不可隔离时列表为空，计数保留。
+- `supply_affected_nodes` / `supply_affected_node_count` 表示按建议关阀后新增失去水源连接的节点，包含间接受影响区域，排除原本就不连通水源的节点。不可隔离或缺少水源资料时为 `null`。
+- `source_check_performed` 表示是否已执行水源连通检查。`isolatable=true` 要求存在关阀边界，且关闭这些阀门后直接隔离区不再连通任何水源。
+- `isolation_failure_reason` 可为 `connected_to_water_source`、`water_sources_unavailable`、`no_boundary_valves`；可隔离时为 `null`。
+
+以上是模型初始开关状态下的无向拓扑分析，水库和水池均按潜在水源处理；不模拟泵或止回阀的单向性、时变控制、水池蓄水量、压力与流量。
+因此“失去水源连接”不能直接当作经过水力计算或现场核实的停水范围。已保存的旧调查证据不会自动重算，需重新调用隔离分析生成新结果。
+本次无需数据库迁移。
+
 ## 资源边界与发布
 
 长计算采用[后台计算队列](calculation-queue.md)。10项分析计算与2项重计算写入的正式执行阶段快速返回任务编号，再使用 `get_calculation_job`、`get_calculation_result`、`list_calculation_jobs`、`cancel_calculation_job` 管理。原有预览与审批仍有效；排队回执不作为分析证据。
 
-`timeout_seconds` 对队列工具表示计算 Worker 的执行预算，与模拟时间 `duration` 和单次 HTTP 请求时限独立。各工具默认值与管理员上限继续由目录公布。Agent的提交/查询采用30秒调用预算和35秒宿主预算，不延长Bun的5分钟HTTP空闲超时。
+HTTP 预算由宿主从目录元数据读取，Server 默认 120 秒、Agent 默认 180 秒；爆管定位不再设置单独的长超时。`timeout_seconds` 保留在 Server 兼容入口，Agent 对模型隐藏并拒绝覆盖。Server 上限 240 秒，Agent 加 60 秒余量并封顶 270 秒，外层原生 MCP 保留 300 秒总时限与上游 Bun 的 5 分钟空闲超时。后台执行时限由管理员配置 `TJWATER_MCP_MAX_CALCULATION_TIMEOUT_SECONDS`（默认 3600 秒），不受该 HTTP 参数控制；模拟时间仍由 `duration` 表示。
 
 `analyze_valve_isolation` 和 `calculate_demand_allocation` 保持同步。队列消费者独立于Uvicorn的4个API进程，默认全部配置项目合计并发2项，并通过元数据库单实例锁防止重复启动。取消、超时和租约失效需要停止计算子进程组；成功结果按原运行授权保存证据，未完成计算阻止调查提前结案。
 
 在线重算逐个时刻写入基线，超时或中途失败可能已有部分时刻更新，不能把工具失败解释为整个窗口已回滚；不要自动重试整个窗口。
 
-队列接入需要在目标项目BizDB应用 `resources/sql/026_calculation_jobs.sql` 并启动独立计算Worker。Server与Agent需配套发布，client模式还需重载原生连接。既有OAuth与项目权限保持不变；完整部署与回滚步骤见后台计算队列文档。
+队列接入需要在目标项目BizDB依次应用 `resources/sql/026_calculation_jobs.sql`、`resources/sql/027_calculation_job_lifecycle.sql` 并启动独立计算Worker。Server与Agent需配套发布，client模式还需重载原生连接。既有OAuth与项目权限保持不变；完整部署与回滚步骤见后台计算队列文档。
 
 本次验证限schema、权限、协议目录和mock业务函数，不运行真实模拟、优化或付费模型。真实项目的模板同步状态、运算耗时、SCADA覆盖和结果准确性仍需另行验收。