River Outfall Status Visualizer 的核心目标是将一个 Excel 工作簿转换为三类产物：场景感知的河流排口状态摘要、适合简报和评审的独立 HTML 图表，以及遵循同一模板的可复用模拟工作簿。
用途与主要能力 该工具面向河流排口状态的可视化分析，支持比较当前、常水位、20 年一遇和 50 年一遇等场景水位。它能够读取混合单表格式的 .xlsx 工作簿，其中排口行携带编码、尺寸、基底高程、里程、岸别和场景水位，控制节点行携带河段或闸门名称、里程、场景水位以及可选的河底高程和堤顶高程。工具会计算各场景下的淹没状态，并生成可直接用于报告的 HTML 图表。
可视化规则 图表在垂直方向保持真实高程，不进行垂直夸大。Y 坐标始终使用真实高程值。水平方向允许缩放或压缩布局，但排口符号宽度在缩放过程中保持固定，仅排口锚点位置随河道布局移动。每个排口锚定在其真实里程和基底高程上。当存在河底高程时，绘制棕色河床阶梯剖面，并在其上方用蓝色填充当前场景水体；当存在堤顶高程时，将堤顶绘制为独立的上下文阶梯剖面。排口顶部根据真实几何高度绘制（当尺寸数据可用时）。形状用于区分几何类型：矩形表示箱涵或矩形排口，圆形表示圆管，且不将圆管压扁为椭圆。岸别通过侧向偏移区分：左岸排口向河道轴线左侧偏移，右岸排口向右侧偏移，并通过连接线方向、标签位置和图例文字强化。状态作为主要语义编码，包括未受淹、部分受淹、完全淹没。选中的场景在视觉上占主导，未选中的场景保持可见但较弱。图表上优先显示编码加尺寸，当图表密集到名称影响可读性时，完整排口名称保留在明细表中。
使用方式 工具提供多个脚本。生成可直接使用的输入模板：python3 scripts/generate_input_template_excel.py --output assets/templates/river-outfall-input-template.xlsx。生成或检查模拟工作簿：python3 scripts/generate_mock_example_excel.py --output assets/examples/example-river-sample.xlsx。计算场景摘要：python3 scripts/calc_submergence.py --input assets/examples/example-river-sample.xlsx --pretty。渲染独立 HTML 报告：python3 scripts/render_status_report.py --input assets/examples/example-river-sample.xlsx --output assets/examples/example-river-sample-report.html。工作流程建议：在修改工作簿模式前阅读 references/data-schema.md；在更改状态逻辑前阅读 references/status-rules.md；在更改图表布局或图例前阅读 references/visual-spec.md。分析类请求优先使用 calc_submergence.py，需要交付图表时使用 render_status_report.py，创建回归夹具或解释预期工作簿形状时使用 generate_mock_example_excel.py，用户需要可直接在 Excel 中填写的空白工作簿时使用 generate_input_template_excel.py。必须显式报告验证警告，不得静默强制转换缺失的高程、缺失的尺寸或模糊的岸别值。
适用场景与限制 适用于需要将河流排口 Excel 数据快速转化为状态摘要和可视化图表的场景，如水利工程简报、排口状态评审等。限制包括：若缺少当前水位，需询问或明确说明输出仅支持可用场景；若工作簿缺少河床或渠底数据，输出应描述为河流排口状态图而非真正的河床纵剖面。输出清单要求说明源工作簿中实际存在的场景、报告总排口数及高亮场景下各状态计数、明确列出完全淹没的排口编码、在相关时说明左右岸计数，并提及是否存在河底高程/堤顶高程，因为这决定图表是否包含河道背景上下文或仅包含水位线加排口。