Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
205 lines (143 loc) · 7.06 KB

ARCHITECTURE.md

File metadata and controls

205 lines (143 loc) · 7.06 KB
Raw

Architecture / 架构说明

English

This document describes the current repository structure and the main execution flow for this water supply simulation tool and its EPANET web workbench.

High-level layout

  • app/
    • Flask application bootstrap, routes, templates, static assets, and EPANET-related backend helpers
  • frontend/
    • Vue 3 workbench source bundled with Vite
  • scripts/
    • local validation scripts, including Playwright-based headless regression runners
  • docs/
    • open-source project documentation and screenshots
  • original/
    • reference material from the original project baseline

Runtime architecture

Backend

The backend is a Flask application exposed through web_epanet.py and initialized in app/init.py.

Core routes live in app/routes.py, including:

  • /upload
  • /api/upload
  • /api/demo
  • /api/create-object
  • /api/export-inp
  • /download/<filename>
  • /download-report/<filename>

These routes handle file upload, demo loading, simulation/rerun, object creation, INP export, and report download.

Frontend

The main workbench is implemented as a single Vue application in frontend/src/main.js.

Current structure highlights:

  • central application state in data()
  • many derived views and synchronization rules in computed
  • interaction and workflow logic in methods
  • a window.__epanetWorkbench test helper surface for headless automation and diagnostics

The front-end UI is rendered through Flask templates, with app/templates/upload.html acting as the main workbench entry.

Main workflow

1. Load a model

  • User uploads a file or loads a demo
  • Flask parses or copies the source file
  • Backend prepares report/simulation payload
  • Frontend hydrates Browser / Map / Property / Report state from that payload

2. Edit state

  • User edits either:
    • object properties
    • analysis options
    • create-object draft data
  • Frontend keeps draft edits separate from applied state until rerun or export

3. Rerun or export

  • /api/upload applies pending edits and reruns the model
  • /api/export-inp applies pending edits to an export copy without rerunning
  • Frontend updates applied state after successful rerun

4. Inspect results

  • snapshot timeline
  • graphs
  • map-linked selection
  • report-driven navigation
  • compare/baseline context

Validation strategy

Validation is intentionally layered:

  • npm run build
    • front-end bundle integrity
  • python -m py_compile ...
    • basic Python syntax safety for critical backend files
  • targeted Playwright scripts
    • verify UI flows and synchronization behavior

Important scripts:

Current architectural tradeoffs

  • The front-end workbench logic is concentrated in one large module, which keeps iteration fast but increases coupling.
  • The backend route layer owns significant flow orchestration, which is practical now but may need refactoring later.
  • Headless regression coverage is strong for interactive behavior, but CI-safe automated coverage is still lighter than ideal.

中文

本文档用于说明当前这个供水仿真工具及其 EPANET Web 工作台仓库的组织方式，以及主要运行链路是如何串起来的。

仓库结构概览

  • app/
    • Flask 应用初始化、路由、模板、静态资源，以及 EPANET 相关后端辅助逻辑
  • frontend/
    • 使用 Vite 打包的 Vue 3 工作台源码
  • scripts/
    • 本地验证脚本，包括基于 Playwright 的无头回归脚本
  • docs/
    • 开源项目文档与截图资源
  • original/
    • 原始项目参考材料

运行时架构

后端

后端通过 web_epanet.py 暴露入口，并在 app/init.py 中初始化 Flask。

核心路由主要集中在 app/routes.py，包括：

  • /upload
  • /api/upload
  • /api/demo
  • /api/create-object
  • /api/export-inp
  • /download/<filename>
  • /download-report/<filename>

这些接口承担了文件上传、示例加载、模拟重跑、对象创建、INP 导出和报表下载等职责。

前端

主工作台当前由 frontend/src/main.js 中的单个 Vue 应用承载。

当前结构重点：

  • data() 中集中维护主状态
  • computed 中维护大量派生视图与联动规则
  • methods 中承载主要交互与工作流逻辑
  • 通过 window.__epanetWorkbench 暴露无头自动化与诊断辅助入口

前端 UI 通过 Flask 模板渲染，其中 app/templates/upload.html 是主工作台入口模板。

主要业务流

1. 模型加载

  • 用户上传文件或加载示例
  • Flask 解析或复制源文件
  • 后端组装 report / simulation payload
  • 前端据此还原 Browser / Map / Property / Report 状态

2. 编辑状态

  • 用户可以编辑：
    • 对象属性
    • 分析选项
    • 新建对象草稿
  • 前端会把草稿修改与已应用状态分离，直到重跑或导出时才真正落地

3. 重跑或导出

  • /api/upload：应用待处理修改并重新分析
  • /api/export-inp：仅将待处理修改写入导出副本，不重跑
  • 成功重跑后，前端会同步更新 applied state

4. 结果查看

  • 快照时间轴
  • 图表视图
  • 地图联动选择
  • 报表驱动导航
  • 对比 / 基线上下文

验证策略

当前验证采用分层方式：

  • npm run build
    • 确认前端打包链路正常
  • python -m py_compile ...
    • 对关键后端文件做基础语法检查
  • Playwright targeted 脚本
    • 校验 UI 流程与多面板联动行为

关键脚本包括：

当前架构取舍

  • 前端工作台逻辑目前集中在一个较大的模块里，迭代快，但耦合度偏高
  • 后端路由层承担了较多流程编排职责，短期实用，长期可能需要拆分
  • 无头回归对交互行为覆盖较强，但适合放进 CI 的自动化覆盖仍有提升空间