next-tjwater-server/docs/node-coverage-tool.md

节点空间覆盖工具

generate_node_coverage 增加 Agent 可选择的空间表达能力，将已取得的模型节点集合转为 可解释、可复核的覆盖示意。它可以在项目聊天、任务协作和后台调查中使用， 不要求爆管任务、隔离成功或特定报告。生成、发布展示和业务分析是三个独立操作。

适用范围

问题	输入依据	输出含义
候选对象分布在哪里	已核实的候选模型节点	候选节点空间包络
两组监测点覆盖有何不同	已核对的设备到模型节点映射	已接入节点分布比较，不证明监测可观测性
区域成员分布在哪里	已查询的区域成员节点	成员节点包络，不替代已有行政区或 DMA 边界
哪些节点属于模型影响集合	已有拓扑或模拟结果中的节点集合	结果节点的空间示意，不重新计算影响
投诉关联的节点如何分布	已解析并核对的投诉到模型节点关联	已关联节点分布，不证明投诉或污染真实边界

只有地址或未关联设备时，先查询位置和资产关联；已有权威区域几何时优先展示原始边界。 本工具不接收任意坐标、HTML、SQL、脚本或调用者指定的项目身份，不执行关阀、模拟或方案保存。

参数和结果

• groups：最多 8 组，每组提供唯一 group_id、title 和 node_ids；组之间可重叠， 合计最多 10000 个不同节点。不按组名自动赋予隔离、污染或服务覆盖语义。
• concave_ratio：0–1，默认 0.25；越接近 1 越接近凸包。分散的点取单一包络可能包含较大空白， 应按实际比较目标分组，并明确示意含义。
• buffer_m：大于 0、最多 1000 m，默认 25 m，仅是展示缓冲。
• split_by_connectivity：默认 false。true 时按所选节点的模型连接拆分，并排除初始 CLOSED 连接。 excluded_link_ids 可额外指定最多 200 个断开连接，适用于已有关阀建议等有依据的绘图情景。 这不会修改模型，也不能替代完整拓扑分析。

result.map_payload 是多组共存的 GeoJSON；result.coverage 记录算法参数、节点 ID、 已映射数量、缺失几何节点、分组数量和 display_only 边界。缺少部分位置时返回 partial， 不补造坐标。单点、重合点或共线点通过米制缓冲生成可绘制面。

与展示工具配合

生成工具不会移动地图。项目聊天可用 present_view 展示本次返回的几何；后台调查用 publish_task_presentation 的 set_overlay，引用生成结果自己的 evidence_id 并省略 data， Server 从不可变证据解析完整几何。大结果内联缩略时，data.presentation.command 保留可发布命令。 recorded 仍只表示请求已记录，浏览器显示和后台调查完成各自独立。

本次爆管报告只是一个验证样例：可将 24 个直接隔离节点、295 个供水影响节点作为两组， 按已有三阀建议设置连通分组；不将这种调用固定进 analyze_valve_isolation。