# WaterSciAnalyzer **Repository Path**: K4Ricky2Win/water-sci-analyzer ## Basic Information - **Project Name**: WaterSciAnalyzer - **Description**: AquaInsight - AI 驱动的水质监测系统，基于 React + TypeScript 构建，提供数据处理、智能预测与可视化分析。学习和实践项目，欢迎交流探讨。 By Ricky from NengDa - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: https://water-sci-analyzer.initricky.lol/ - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-20 - **Last Updated**: 2026-03-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AquaInsight - 水气耦合智能研判系统 ![Version](https://img.shields.io/badge/version-1.0.0-blue.svg) ![License](https://img.shields.io/badge/license-MIT-green.svg) ![React](https://img.shields.io/badge/react-18.x-61dafb.svg) ![TypeScript](https://img.shields.io/badge/typescript-5.x-3178c6.svg) **AquaInsight** (原名 **WaterSciAnalyzer**) 是一个面向地表水监测、趋势分析与智能研判的现代化前端平台。它结合实时地理信息系统 (GIS)、大数据可视化与大语言模型 (LLM) 技术，为用户提供全国国控断面的水质实时监控、趋势分析、智能报告生成，以及基于 OpenClaw 风格的 Agent Demo 演示。平台当前同时覆盖监测驾驶舱、数据录入&分析 Demo、Agent Demo 三类典型场景。 ## ✨ 核心功能 ### 1. 🗺️ 交互式水质地图 - **全国站点覆盖**：基于 Leaflet 的高性能地图引擎，支持全国数千个国控断面的可视化展示。 - **动态聚合**：使用 MarkerCluster 实现大规模点位的流畅聚合与散开。 - **智能弹窗**：支持深色/浅色模式自适应的站点详情弹窗，实时展示 pH、溶解氧、浊度等核心指标。 - **状态感知**：通过不同颜色的标记（Marker）直观展示数据的新鲜度与选中状态。 ### 2. 📊 实时数据驾驶舱 - **核心指标卡片**： - 展示 pH、溶解氧 (DO)、氨氮 (NH3-N)、总磷 (TP)、总氮 (TN)、高锰酸盐指数等关键参数。 - **国标比对**：内置 GB 3838-2002 标准，自动判定水质等级（I-V类、劣V类）并以色块高亮显示。 - **趋势微图**：集成 Sparkline 迷你图，直观展示 7天/30天 的数据变化趋势。 - **多维度分析**： - **多指标对比**：支持在同一图表中叠加 pH、溶解氧、氨氮等多项指标，进行关联分析。 - **智能归一化**：内置 Min-Max 和 Z-Score 归一化算法，解决不同量纲数据（如 0.1 mg/L 的氨氮与 2000 μS/cm 的电导率）无法同屏对比的难题。 - **自适应坐标轴**：单指标模式下自动适配数值范围显示真实值；多指标模式下智能切换为趋势视图。 - **周期切换**：支持切换 7天/30天 分析周期，X轴自动适配显示具体日期。 ### 3. 🤖 AI 智能研判 (Powered by Qwen) - **气象-水质耦合分析 (Beta)**： - 集成 **和风天气 (QWeather)** 历史数据接口，自动获取监测站点过去 7-10 天的真实气象（气温、降水、风速）与空气质量（AQI）数据。 - AI 模型基于“通用气象水文耦合机理”，深度分析降水冲刷（对浊度/TP的影响）、气温波动（对DO/氨氮的影响）等复合因子，提供更具科学性的归因推断。 - *注：该功能目前处于测试阶段，后续将支持更长周期的气象数据回溯与更精细的空间匹配。* - **单项指标分析**：点击任意指标卡片上的 AI 按钮，即可生成该指标的深度科学分析与成因推断。 - **趋势波动研判**：在历史趋势图（单指标模式）中，点击“AI 趋势分析”按钮，对选定时段的数据波动特征、成因及环境风险进行深度研判。 - **综合研判报告**：一键生成完整的流域水质健康报告，包含水质现状、主要污染物分析及治理建议。 - **打字机特效**：沉浸式的报告生成体验，模拟终端输出效果。 ### 4. 📲 数据采集系统 (Demo) - **全流程模拟**：内置完整的 IoT 设备连接、GPS 定位、传感器数据采集、蓝牙传输与分析结果查看流程。 - **交互式体验**：可视化的设备状态、数据传输进度条与模拟 AI 分析动画。 - **现场模式**：独立的地图定位模块，专为现场作业场景设计。 ### 5. 🤖 Agent Demo - **任务编排视图**：支持异常事件快报、预警推演、多源融合溯源、全国水质采集分析等任务场景切换。 - **技能与工具链展示**：通过“启用技能”和“工具执行链路”模拟 OpenClaw 风格的 agent 编排过程。 - **Agent Chat**：内置快捷问答与自由提问入口。非预设问题会返回明确的 Demo 演示回复，避免与真实结论混淆。 - **全国流域分析 mock**：新增全国断面采集、七大流域聚合分析、跨区域风险排序等拟真演示数据。 ### 6. 🛠️ 现代化工程特性 - **极致 UI/UX**： - **双模主题**：完美适配 Light/Dark Mode，包括地图瓦片的滤镜反转处理。 - **微交互**：精美的呼吸灯效果、流光边框、玻璃拟态 (Glassmorphism) 设计。 - **响应式布局**：完全适配桌面端与移动端操作。 - **性能优化**：懒加载图表组件、WebP 格式图片压缩、SVG 图标按需引入。 - **数据导出**： - **PDF 报告**：一键生成高清分析报告，支持图表与文字混排。 - **Markdown**：支持将分析结果导出为 Markdown 格式，便于二次编辑。 - **用户体验**： - **Toast 通知**：使用 `react-hot-toast` 提供友好的操作反馈。 - **智能搜索**：支持拼音与首字母模糊匹配。 ## 📖 使用指南 ### 平台操作流程 1. **位置授权**：首次访问时，平台会请求地理位置权限以自动定位到您所在的城市。 2. **选择站点 / 搜索**： - **地图交互**：在地图上点击任意水滴标记（代表国控断面监测站）。 > **💡 提示**：地图上的数字圆圈代表该区域内的站点聚合数量，点击即可放大查看具体站点。 - **智能搜索**：支持 **中文/拼音/首字母** 混合检索。使用左上角的搜索框，输入城市名称（如“杭州/hangzhou/hz”）或流域名称快速定位。 3. **查看指标**：左侧卡片展示 pH、溶解氧、氨氮等核心指标，颜色代表水质等级（绿色-优良，黄色-一般，红色-较差，白色-无国标）。点击图例中的 **GB** 按钮可查看详细的国家标准说明与指标含义。 4. **历史趋势分析**： - 点击任意指标卡片中的折线图，弹出全屏历史趋势分析窗口。 - **单指标视图**：默认显示选中的单一指标，Y轴展示真实数值。 - **多指标对比**：在右上角勾选其他指标，图表自动切换至“归一化”模式，方便对比不同指标的波动相关性。 - **模式切换**：多指标模式下，可手动切换“原始值”、“Min-Max归一化”或“Z-Score标准化”视图。 5. **智能分析**： - **单项分析**：点击指标卡片右下角的 AI 图标，获取该指标的详细解读。 - **趋势研判**：在历史趋势图弹窗中（仅选中单一指标时），点击左上角的 **AI 趋势分析** 按钮，生成专业的数据波动特征分析报告。 - **综合报告**：点击仪表盘下方的“智能分析”按钮，生成完整的流域水质健康报告。 6. **数据录入&分析 (Demo)**： - 侧边栏“数据录入&分析(Demo)”模块提供 IoT 设备连接、定位、采集、传输与智能分析的全流程模拟演示。 7. **Agent Demo**： - 侧边栏“Agent（Demo）”模块展示任务编排、技能调用、工具执行链路与 Agent Chat。 - 当前内置异常快报、预警推演、多源溯源、全国水质采集分析等拟真场景。 > **🤖 AI 功能提示**： > - 默认情况下，AI 分析功能展示的是演示数据。如需获取针对实时数据的真实科学研判，请在“设置”页面配置您的 **Qwen (通义千问) API Key**。 > - Agent Demo 中的任务结论、技能执行、工具链结果、聊天回复同样均为演示内容，仅用于展示产品交互与能力形态。 > - **⚠️ 免责声明**：AI 分析结果基于大语言模型生成，仅供参考，可能存在误判或偏差，不作为最终法律或科学依据。 ### 水质指标释义 - **pH值**：衡量水体酸碱度的指标。7.0 为中性，低于 7.0 为酸性，高于 7.0 为碱性。 - **溶解氧 (DO)**：溶解在水中的氧气含量，维持水生生物生存的关键指标。 - **浊度 (NTU)**：反映水体透明度的指标，受悬浮颗粒物影响。 - **总氮 (TN)**：水体中氮的总含量，衡量水质污染程度的重要指标。 - **氨氮 (NH3-N)**：水体中以游离氨或铵盐形式存在的氮，是水体富营养化的重要指标。 - **高锰酸盐指数 (CODmn)**：反映水体中有机污染物含量的综合指标。 - **总磷 (TP)**：水体中磷的总含量，是水体富营养化的主要限制因子。 - **水温**：水体的温度，影响水中溶解氧含量和生物活性。 - **电导率**：反映水中溶解盐类的总量，是水质纯度的重要指标。 ## 🏗️ 技术架构 本项目采用 **React + TypeScript + Vite** 现代前端技术栈构建。 ### 技术栈清单 - **核心框架**: React 18, TypeScript - **构建工具**: Vite - **样式方案**: Tailwind CSS, clsx, lucide-react - **交互反馈**: react-hot-toast - **地图引擎**: Leaflet, React-Leaflet, Pinyin-Match (搜索优化) - **状态管理**: Zustand (轻量级状态管理) - **AI 集成**: OpenAI-compatible SDK (对接 Qwen/通义千问) - **工具库**: html2canvas, jsPDF (PDF导出), Recharts (图表) ### 目录结构 ``` src/ ├── components/ # UI 组件库 │ ├── WaterQualityMap.tsx # 核心地图组件 (Leaflet + MarkerCluster) │ ├── DashboardView.tsx # 仪表盘视图组件 (View Layer) │ ├── MetricCard.tsx # 数据指标卡片 │ ├── HistoryChartModal.tsx # 历史趋势图表 (Lazy Load) │ ├── AnalysisModal.tsx # AI 分析报告模态框 │ ├── GuideModal.tsx # 平台使用指南 │ ├── SettingsModal.tsx # 系统设置 │ ├── Sparkline.tsx # 迷你趋势图 (Recharts) │ ├── TechLoader.tsx # 科技感加载动画 │ ├── TypewriterReport.tsx # 打字机效果组件 │ ├── StationSearch.tsx # 站点搜索组件 │ └── ... ├── services/ # 业务逻辑层 │ ├── surfaceWater.ts # 水质数据获取与标准化 │ ├── weather.ts # 实时天气服务 │ ├── weatherHistory.ts # 历史天气服务 │ ├── aiEngine.ts # AI 分析引擎 (Prompt Engineering) │ ├── location.ts # 地理位置服务 │ └── ... ├── store/ # Zustand 状态管理 │ ├── useDashboardStore.ts # 仪表盘全局状态 │ ├── useSettingsStore.ts # 设置与配置 │ └── useStore.ts # 全局应用状态 ├── pages/ # 页面视图 │ ├── Dashboard.tsx # 主控制台 (Logic Layer) │ ├── DataEntry.tsx # 数据录入&分析演示页 │ ├── AgentDemo.tsx # Agent 编排演示页 │ └── Settings.tsx # 设置页面 ├── utils/ # 工具函数 │ ├── dashboardUtils.ts # 仪表盘辅助函数 │ ├── qualityStandards.ts # 水质标准判定逻辑 │ └── normalization.ts # 数据归一化算法 ├── constants/ # 常量定义 │ └── dashboard.ts # 仪表盘配置与常量 ├── hooks/ # 自定义 Hooks │ └── useTheme.ts # 主题切换逻辑 ├── types/ # TypeScript 类型定义 │ └── index.ts # 全局类型定义 └── data/ # 静态数据与 Mock 数据 ``` ## 🚀 快速开始 ### 环境要求 - Node.js >= 16.0.0 - npm 或 yarn ### 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/K4Ricky2Win/water-sci-analyzer.git cd water-sci-analyzer ``` 2. **安装依赖** ```bash npm install ``` 3. **配置环境** 本项目支持 API 代理配置，请确保 `vite.config.ts` 中的代理目标指向正确的数据源服务。 4. **启动开发服务器** ```bash npm run dev ``` 访问 `http://localhost:5173` 即可预览。 5. **构建生产版本** ```bash npm run build ``` ## 🏗️ 构建 ### 前置要求 - Node.js >= 18.0.0 (Vite 6 构建要求) ### 构建步骤 ```bash npm run build ``` 构建产物将输出至 `dist/` 目录。 ## 🔌 数据源说明 本项目采用 **混合数据模式 (Hybrid Data Mode)**： 1. **实时 API**: 优先通过配置的 AppCode 访问实时地表水监测接口。 2. **本地缓存**: 实现了基于 LocalStorage 的数据缓存机制，减少 API 调用频率。 3. **容灾降级**: 在 API 不可用时，自动降级使用本地静态快照数据，确保演示环境的高可用性。 ## 📝 开发规范 - **代码风格**: 遵循 ESLint + Prettier 规范。 - **组件设计**: 采用函数式组件与 Hooks，追求组件的原子化与可复用性。 - **样式管理**: 全面使用 Tailwind CSS Utility-first 类名，避免传统 CSS 的样式冲突。 ## 🚀 未来开发计划 本项目仍在持续迭代中，后续计划包括： - **独立数据库**：建立专属数据库，支持更灵活的数据管理与历史回溯。 - **扩展监测**：支持 **ESP32** 等 IoT 设备接入，增加非国控断面水域的实时采样数据录入与分析功能。 - **气象分析深化**：进一步提升气象数据的时空分辨率（支持 >10天 的历史回溯），优化降雨-径流模型的 Prompt 逻辑。 - **科学性提升**：结合专业采样方法，提升监测结果的科学性与广度。 - **深度研判**：优化 AI 模型，提供更精准的流域治理建议。 - **智能体集成**：深化 **OpenClaw Agent** 能力，扩展技能编排、全国流域分析、工具调用轨迹与跨平台联动，打造更完整的智能水质监测助手。 敬请期待！ ## 📄 许可证 本项目版权归 **water-sci-analyzer (AquaInsight By Ricky)** 所有。 未经作者书面许可，禁止以任何形式复制、分发或使用本项目的任何部分。 详情请参阅 [LICENSE](./LICENSE) 文件。