drhouse-ops/AEROGRID-2

# AEROGRID ### AI 驱动的超局部污染早期预警与市政响应智能平台。 ## 📋 团队声明 * **团队名称**：Helix Orbit * **黑客马拉松**：Build with AI: Code for Communities * **赛道**：Track 2 — CleanAir & Clear Streets * **试点地区**：印度马哈拉施特拉邦浦那 ## 🚨 问题 传统的城市空气质量指数 (AQI) 依赖于范围广泛但分布稀疏的政府遥测站。虽然它们对于宏观区域背景很有价值，但无法捕捉高度局部化、快速的街道级污染危害。诸如以下事件： * 无人监管的露天城市/塑料垃圾焚烧 * 活跃的地铁和基础设施挖掘引起的悬浮粗尘柱 * 在低风速扩散窗口下聚集的重型车队尾气 * 飘入附近住宅边缘的工业烟囱排放物 由于城市主管部门缺乏直接的微观态势可见性，这些事件在毫无阻碍地不断恶化。 ## 💡 解决方案 **AEROGRID** 是一个优质的超局部、实时空间智能平台，专为市政指挥中心和 civic 响应者设计。AEROGRID 并非试图重建完整的物理传感器网络，而是将公民的多模态证据（文本描述、音频录音、摄像头观察）与现有的公共传感器和卫星大气扫描进行关联，从而检测、确认并优先处理局部污染事件热点。 ## 🎯 核心原则 AEROGRID 不会仅凭单个市民的投诉就触发市政警报或拉响紧急警报。只有当独立的、多来源的环境指标在空间和时间上同时对齐时，平台才会将该事件提升为已验证的市政信号。 ## ⚙️ AEROGRID 工作原理 ``` CITIZEN REPORT [Text/Voice + Photo + GPS] │ ▼ MULTIMODAL GEMINI ENGINE [Analyzes smoke columns, density & flags events] │ ▼ ENVIRONMENTAL CONTEXT LAYER [Anomalies vs Hyperlocal AQI Ground Stations + Wind speed] │ ▼ HEURISTIC SIGNAL FUSION [Correlates multiple reports within 500m & 30m window] │ ▼ PROTOTYPE 24H FORECAST [Projects immediate local AQI spikes and hazards] │ ▼ MUNICIPAL COMMAND DESK [Recommended Action Plan & Simulation Dispatch] ``` ### 1. Gemini 多模态证据分析 当市民报告事件时，我们服务器端的 Gemini 3.5 Flash 模型会执行环境证据提取。它会查看提交的声明（解释英语、印地语和马拉地语的转录内容）以及上传的图像，以标记可见的污染特征。它负责处理视觉检查（例如灰色烟雾的浓度），同时遵守相关约束（绝不仅凭照片来估算 PM2.5 浓度）。 ### 2. 环境上下文引擎 对于每份报告，后端都会查询区域气象和地理遥测数据，以计算上下文异常。正在运行的浦那原型实现了： * **市民多模态观察和 GPS**：来源于直接的市民事件输入，包括局部坐标边界。 * **Gemini 多模态证据分析**：从报告文本和图像中进行服务器端的视觉燃烧和污染特征提取。 * **地理时间市民报告关联**：时空聚合，以验证附近的佐证观察。 * **NASA FIRMS 热量上下文** (卫星热量上下文 — NASA FIRMS)：从 Suomi NPP 和 NOAA 卫星实时映射的活跃热量异常。 * **data.gov.in / CPCB 政府 AQ 上下文**：来自市政地面监测的局部颗粒物基准和异常指数。 * **Google 天气扩散上下文**：大气通风因子、风矢量场和局部污染持续指数。 * **AEROGRID 信号融合**：多证据启发式组合，用于计算局部危害等级并提升已验证的热点。 ### 3. 启发式信号融合 AEROGRID 的融合引擎根据以下因素计算确认置信度： $$H = 0.20 \cdot C + 0.20 \cdot V + 0.25 \cdot S + 0.15 \cdot G + 0.10 \cdot T + 0.10 \cdot M$$ 其中： * **C**：市民报告关联 * **V**：Gemini 视觉分析置信度 * **S**：地面传感器异常评分 * **G**：地理空间距离关联（如果在 500 米质心范围内则为 1.0） * **T**：时间关联（如果在 30 分钟内则为 1.0） * **M**：气象扩散约束（低风速停滞因子） ### 4. 24 小时原型预报 预测短期污染指数变化。它会根据停滞的风速和持续的报告，向操作员发出迫在眉睫的峰值危害高峰窗口（例如 +6H PM2.5 激增风险）警报。 ### 5. 市政响应工作流 一旦热点跨越 `0.75` 的阈值，它就会被提升为**已验证的环境信号**。系统会生成带有行动建议（如部署水雾、检查垃圾火情等）的指令，允许进行模拟响应派遣。 ## 🛡️ 系统运行模式与数据披露 AEROGRID 在其**演示原型沙盒模式**和生产环境可辩护的**实时试点模式**之间，实行了严格而稳健的架构分离。这保证了在专业的黑客马拉松评审团面前拥有绝对的透明度和技术诚信。 ### 🚥 模式对比矩阵 | 操作属性 | 演示原型沙盒 (`VITE_DEMO_MODE=true`) | 实时试点模式 (`VITE_DEMO_MODE=false`) | | :--- | :--- | :--- | | **API 错误处理** | 优雅的本地模拟回退返回经过校准的数据配置文件，用于确定性演示。 | 严格的错误传播。网络超时、403 Forbidden 和错误的密钥返回显式的不可用状态 (`available: false`)。 | | **缺失 API 密钥** | 使用描述性的 `PROTOTYPE CONTEXT` 回退替换缺失的环境集成。 | 返回显式的错误代码（例如 `THERMAL_CONTEXT_UNAVAILABLE`、`GROUND_CONTEXT_UNAVAILABLE`）—— 绝无伪造的证据。 | | **种子证据关联** | 自动定位支持的观察结果（例如 `prototype_report_02` 在约 420 米外）以测试关联 pipeline。 | 完全禁用合成的市民报告。所有关联均专门基于真实的独立实时观察结果进行计算。 | | **视觉归属** | 交互式卡片和视觉徽章会清晰地标记上黄色的 `DEMO ANALYSIS` 或 `PROTOTYPE CONTEXT` 警告。 | 显示高保真度的真实 API 遥测数据，或向市政调度员透明地发送离线/不可用传感器状态信号。 | * **科学局限性免责声明**：启发式融合公式和预测图表是说明性的校准配置。它们未经过科学验证，必须在现实部署中使用局部连续监测数据进行微调。 * **数据来源**：基准坐标代表浦那中心区。卫星热量上下文源自 NASA FIRMS。Google 天气详情通过 Google Maps Platform 获取。地面传感器上下文映射到官方的 data.gov.in (CPCB) schema。 ### 🔬 架构审计与升级 AEROGRID 原型已更新为简洁的、服务器端模块化服务架构： 1. **真实的 Gemini 主路径**： - 市民报告分析通过服务器端路由 `/api/v1/reports/analyze` 执行，使用 `@google/genai` SDK 和模型 `gemini-3.5-flash`。 - 真实的 Gemini 分析在 API 响应中标记为 `"analysisSource": "GEMINI_MULTIMODAL"`，并显示绿色的 `GEMINI MULTIMODAL` 徽章。 - 智能 fallbacks 仅在 API 密钥缺失或无效，或者 `DEMO_ONLY` 设置为 `true` 时触发，并显示黄色的 `DEMO ANALYSIS` 徽章。 2. **模块化地面与卫星服务**： - 将环境遥测解析重构为单独的类（`GroundMonitoringService` 和 `SatelliteContextService`）。 - 模拟数据源已明确重命名为 `"PROTOTYPE_GROUND_CONTEXT"` 和 `"PROTOTYPE_SATELLITE_CONTEXT"`，并标记为 `isPrototype: true`。 - UI 在数据卡片中正确显示 `PROTOTYPE CONTEXT` 徽章，以防暗示正在积极查询实时的 CPCB 或 GEE 网络。 3. **解耦的信号融合引擎**： - 信号关联计算被隔离在 `SignalFusionService.ts` 中，应用指定的权重公式和分类阈值。 4. **NASA FIRMS 活跃火灾热量上下文集成**： - **数据集来源**：VIIRS 375 m 活跃火灾热量异常产品。 - **查询机制**：从事件质心计算一个 ±10 km（0.09 度纬度/经度）的边界框，格式为 `min_lon,min_lat,max_lon,max_lat`。在 24 小时的观察窗口内进行搜索。 - **启发式评分逻辑**：使用 Haversine 公式计算距离，并权衡近因度以生成 `thermalContextScore`（0.0 到 1.0）。如果 FIRMS 不可用或失败，它会中和（排除）该分数。如果未发现附近的检测，它会给出一个低的中性基准分数。 - **视觉指示器**：在市政矢量地图上显示带有独立工具提示的自定义卫星十字准线、6 步信号关联扫描仪，以及专用的 `REAL SATELLITE CONTEXT` 或 `PROTOTYPE SATELLITE CONTEXT` 卡片，以确保完全透明。 - **辅助角色披露**：绝不声称是独立的街道级火灾验证；卫星异常严格作为次要的大气支持性上下文。 5. **Google Maps Platform 天气 API 与大气扩散动力学**： - **服务来源**：通过 Google Maps Platform 天气 API `currentConditions:lookup` REST endpoint 获取当前天气状况。 - **提取字段**：实时温度、风速 (kph)、风向（度）、相对湿度 (%)、降水量 (mm)、天气状况以及精确的观察时间戳。 - **原型持续性评分启发式算法**：使用以 0.0 到 1.0 为界限的评分公式（分数越高 = 空气停滞、污染积累风险越高）来绘制风速、相对湿度和降水量。显著的降水或强风会降低局部持续性。 - **科学披露**：此评分逻辑是说明性的原型启发式算法。AEROGRID 目前未实施 CFD（计算流体力学）、化学传输模型或监管扩散模型。天气观察提供支持性大气上下文，而持续性评分是原型启发式算法。 - **Fallback 机制**：以前的天气指标是静态的模拟值。系统已升级以支持真实的 API 查询。当未提供 `GOOGLE_WEATHER_API_KEY` 时，界面会显式显示“PROTOTYPE CONTEXT”的 fallback，且没有真实的 Google 归属。 ### 🛰️ 剩余的实施差距 - **地面监测集成**：在生产环境中，`GroundMonitoringService` 将使用真实的站点标识符连接到 CPCB 的国家空气质量 API。 - **持久化持久性**：所有用户编写的事件状态目前都驻留在临时的内存集合和 `localStorage` 中，适用于单用户试点模拟。现实世界的扩展需要迁移到托管的 Cloud SQL/Firestore 数据库。 ## 🔮 未来的生产集成 * **通过 Google Earth Engine 获取 Sentinel-5P 区域气溶胶上下文**： Sentinel-5P 可以为烟雾和粉尘羽流评估提供区域的吸光气溶胶上下文。 *注意：Sentinel-5P / Google Earth Engine 不是当前活跃的浦那原型证据流的一部分，目前尚未集成。* ## 💻 技术栈 * **前端**：React 19, Vite, TypeScript, Tailwind CSS v4 * **AI 引擎**：`@google/genai`（使用 `gemini-3.5-flash` 模型） * **后端**：Express, Node.js 运行在 3000 端口 * **视觉效果**：Recharts（用于清晰的预测图表）、Lucide Icons、自定义 GIS SVG 矢量地图 * **部署**：配置为可在 Google Cloud Run container 上即时部署 ## 🔧 本地设置与运行时 ### 环境变量 在根目录下配置与 `.env.example` 匹配的 `.env` 文件： ``` GEMINI_API_KEY="YOUR_GOOGLE_AI_STUDIO_KEY" VITE_DEMO_MODE="true" ``` ### 运行开发服务器 要启动带有热加载 Vite 静态资源的 Express 后端： ``` npm run dev ``` ### 构建与生产环境启动 构建并打包完整应用，以进行优化的 Cloud Run 部署： ``` npm run build npm start ``` 服务器按照反向代理的要求绑定到端口 `3000` 上的 `0.0.0.0`。

标签：MITM代理, 人工智能, 地理空间分析, 多模态AI, 市政应急响应, 智慧城市, 环境监测, 用户模式Hook绕过, 自动化攻击