JeevaKS03/AI-Powered-Crisis-Response-System

## 📋 目录 - [概述](#-overview) - [核心功能](#-key-features) - [架构](#-architecture) - [技术栈](#-tech-stack) - [快速开始](#-quick-start) - [项目结构](#-project-structure) - [页面与界面](#-pages--interfaces) - [API 参考](#-api-reference) - [AI 流水线](#-ai-pipeline) - [测试流程](#-testing-flow) - [配置](#%EF%B8%8F-configuration) - [贡献](#-contributing) - [许可证](#-license) ## 🌟 概述 **CrisisAI** 是一个可运行的 MVP（最小可行性产品），展示了人工智能如何改变酒店业和设施管理中的紧急响应方式。该系统提供了从事件报告到解决的端到端流程，并由 Google 的 Gemini AI 驱动进行智能分类。 ### 问题 传统的紧急响应依赖于人工评估和沟通，导致在关键时刻出现延误。对事件严重程度的误判可能导致资源分配不足或过度。 ### 解决方案 CrisisAI 使整个流程自动化： 1. **访客**通过 SOS 按钮或文本描述**报告**紧急情况 2. **Gemini AI** 根据类型、严重程度和置信度对事件进行**分类** 3. **决策引擎**分配相应的人员和响应区域 4. **员工接收**警报并管理事件的生命周期 5. **管理员**通过实时分析仪表盘**监控**所有活动 ## ✨ 核心功能 ### 🧠 AI 驱动的分类 - 集成 **Google Gemini 2.0 Flash** 用于实时事件分析 - 将事件分类为 **fire**（火灾）、**medical**（医疗）、**security**（安保）或 **unknown**（未知） - 分配严重程度级别：**low**（低）、**medium**（中）、**high**（高）、**critical**（严重） - 提供置信度分数和自然语言解释 - 当未配置 API 密钥时，内置**基于关键词的备用方案** ### ⚡ 智能决策引擎 - 按严重程度（1-3 名响应人员）扩展的自动人员分配 - 针对每种事件类型的专业人员池（消防队、医疗人员、安保人员） - 基于区域的路由（消防集合点、医疗区、安保办公室） - 为每次调度决策提供 AI 生成的推理 ### 👁️ 视觉分析（模拟） - 模拟计算机视觉服务，通过文本上下文检测危险 - 检测内容：火灾、洪水、入侵者、结构性损坏、医疗紧急情况 - 返回检测标签和置信度分数 ### 🔊 语音指导 - 16 条涵盖所有 类型 × 严重程度 组合的独特安全信息 - 上下文感知的疏散指示和安全协议 - 已准备好集成 TTS（文本转语音） ### 📡 实时更新 - 5 秒轮询间隔以获取实时事件动态 - 状态转换验证（`pending` → `in-progress` → `resolved`） - 用于问责制的人员身份跟踪 ### 🎨 高级深色 UI - 带有背景模糊效果的毛玻璃（Glassmorphism）设计 - 带有脉冲环动画的 SOS 按钮 - 按严重程度编码的颜色徽章（红/黄/绿） - 流畅的入场动画和微交互 - 跨设备的完全响应式设计 ## 🏗 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ FRONTEND (Next.js) │ │ │ │ ┌──────────┐ ┌──────────────┐ ┌───────────────────┐ │ │ │ /guest │ │ /staff │ │ /admin │ │ │ │ SOS Form │ │ Manage List │ │ Analytics View │ │ │ └─────┬────┘ └──────┬───────┘ └────────┬──────────┘ │ │ │ │ │ │ └─────────┼──────────────────┼───────────────────────┼─────────────────┘ │ POST /incident │ GET /incident │ GET /incident │ │ PATCH /incident/status │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ BACKEND (FastAPI) │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Routes Layer │ │ │ │ POST /incident │ GET /incident │ PATCH /:id/status │ │ │ └────────┬─────────┴────────────────┴───────────────────┘ │ │ │ │ │ ┌────────▼────────────────────────────────────────────────┐ │ │ │ Services Layer │ │ │ │ │ │ │ │ ┌──────────────┐ ┌────────────────┐ ┌────────────┐ │ │ │ │ │ Gemini AI │ │ Decision │ │ Vision │ │ │ │ │ │ Classification│ │ Engine │ │ (Simulated)│ │ │ │ │ └──────┬───────┘ └────────────────┘ └────────────┘ │ │ │ │ │ ┌────────────────┐ │ │ │ │ │ │ Voice Guidance │ │ │ │ │ │ └────────────────┘ │ │ │ └─────────┼────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────▼──────────────────────────────────────────────┐ │ │ │ In-Memory Data Store (List) │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ ┌───────────────────┐ │ Google Gemini API │ │ (External, Free) │ └───────────────────┘ ``` ### 请求流 ``` Guest Report ──► Gemini AI ──► Classification ──► Decision Engine ──► Staff Assignment │ │ Vision Service Voice Guidance (Simulated) (Text-based) │ │ └───────────── Incident Record ─────────┘ │ ┌────────┼────────┐ ▼ ▼ ▼ Guest Staff Admin (View) (Manage) (Monitor) ``` ## 🛠 技术栈 | 层级 | 技术 | 用途 | |-------|-----------|---------| | **前端** | Next.js 16 (App Router) | 服务器/客户端渲染，路由 | | **语言** | TypeScript | 类型安全的前端代码 | | **样式** | Tailwind CSS 4 | 实用优先的深色主题 UI | | **后端** | FastAPI 0.115 | 异步 Python REST API | | **AI 模型** | Gemini 2.0 Flash | 事件分类 | | **HTTP 客户端** | httpx | 异步 Gemini API 调用 | | **校验** | Pydantic 2.9 | 请求/响应数据结构 | | **服务器** | Uvicorn | 带有热重载的 ASGI 服务器 | | **实时** | 轮询 (5s) | 实时事件动态更新 | ## 🚀 快速开始 ### 前置条件 | 工具 | 版本 | 检查命令 | |------|---------|-------| | Python | 3.10+ | `python --version` | | Node.js | 20+ | `node --version` | | npm | 10+ | `npm --version` | | pip | 24+ | `pip --version` | ### 1. 克隆仓库 ``` git clone cd Solution\ Challange ``` ### 2. 启动后端 ``` cd backend # 安装 Python 依赖 pip install -r requirements.txt # 启动 FastAPI 服务器 (带 hot reload) python -m uvicorn main:app --reload --port 8000 ``` API 将在以下地址可用： - **API 根目录：** http://localhost:8000 - **Swagger 文档：** http://localhost:8000/docs - **ReDoc 文档：** http://localhost:8000/redoc ### 3. 启动前端 ``` cd frontend # 安装 Node 依赖 npm install # 启动 Next.js 开发服务器 npm run dev ``` 应用将在以下地址可用： - **主页：** http://localhost:3000 - **访客 SOS：** http://localhost:3000/guest - **员工面板：** http://localhost:3000/staff - **管理员仪表盘：** http://localhost:3000/admin ### 4. （可选）启用 Gemini AI 默认情况下，系统使用**基于关键词的备用分类器**。要启用完整的 Gemini AI 集成： 1. 从 [Google AI Studio](https://aistudio.google.com/apikey) 获取免费的 API 密钥 2. 编辑 `backend/.env`： GEMINI_API_KEY=your_actual_api_key_here 3. 重启后端服务器 ## 📁 项目结构 ``` Solution Challange/ │ ├── README.md # This file │ ├── backend/ # FastAPI Python Backend │ ├── main.py # App entry point, CORS, router registration │ ├── requirements.txt # Python dependencies │ ├── .env # Environment variables (Gemini API key) │ │ │ ├── models/ # Pydantic Data Models │ │ ├── __init__.py │ │ └── incident.py # Incident, AIClassification, DecisionResult, etc. │ │ │ ├── routes/ # API Route Handlers │ │ ├── __init__.py │ │ └── incidents.py # CRUD endpoints with AI pipeline │ │ │ └── services/ # Business Logic Services │ ├── __init__.py │ ├── gemini_service.py # Gemini API integration + fallback │ ├── decision_engine.py # Staff assignment & zone routing │ ├── vision_service.py # Simulated computer vision │ └── voice_service.py # Context-aware safety guidance │ └── frontend/ # Next.js TypeScript Frontend ├── package.json # Node dependencies & scripts ├── tsconfig.json # TypeScript configuration ├── postcss.config.mjs # PostCSS + Tailwind config ├── next.config.ts # Next.js configuration │ └── app/ # App Router Pages ├── layout.tsx # Root layout with Navbar ├── globals.css # Design system (dark theme, glass, animations) ├── page.tsx # Landing page ├── types.ts # Shared TypeScript interfaces ├── api.ts # Backend API client functions │ ├── components/ │ └── Navbar.tsx # Navigation bar with active state │ ├── guest/ │ └── page.tsx # SOS button + emergency report form │ ├── staff/ │ └── page.tsx # Incident list + accept/resolve actions │ └── admin/ └── page.tsx # Dashboard with analytics + incident table ``` ## 📄 页面与界面 ### 🚨 访客界面 (`/guest`) 用于报告紧急情况的主要界面。 | 功能 | 描述 | |---------|-------------| | **SOS 按钮** | 用于即时紧急报告的大型脉冲红色按钮 | | **快速报告** | 预设按钮：火灾 🔥、医疗 🏥、安保 🔒 | | **文本输入** | 自由格式的紧急情况描述（3–1000 个字符） | | **AI 结果** | 显示分类类型、严重程度、置信度条 | | **响应卡片** | 显示分配的员工、区域和决策推理 | | **视觉面板** | 带有标签和置信度的模拟检测结果 | | **安全指导** | 上下文感知的疏散/安全指示 | ### 👷 员工界面 (`/staff`) 供响应人员使用的事件管理面板。 | 功能 | 描述 | |---------|-------------| | **实时动态** | 自动刷新事件列表（5 秒轮询） | | **状态过滤器** | 标签页：全部、待处理、处理中、已解决 | | **统计计数器** | 每个状态类别的实时计数 | | **接受操作** | 将事件状态从 `pending` 转换为 `in-progress` | | **解决操作** | 将事件状态从 `in-progress` 转换为 `resolved` | | **员工 ID** | 每个会话自动生成的唯一标识符 | ### 📊 管理员仪表盘 (`/admin`) 综合分析和监控视图。 | 功能 | 描述 | |---------|-------------| | **统计网格** | 总数、待处理、处理中、已解决、平均置信度 | | **类型细分** | 带有比例的事件类型可视化条形图 | | **详情检查器** | 点击任意事件展开完整的 AI 分析 | | **事件表格** | 包含类型、严重程度、状态、员工、时间的可排序表格 | | **实时更新** | 每 5 秒自动轮询 | ## 🔌 API 参考 Base URL: `http://localhost:8000` ### `POST /incident` 通过完整的 AI 处理流水线创建一个新事件。 **请求体：** ``` { "message": "Fire in first floor kitchen" } ``` **响应 (`201 Created`)：** ``` { "id": "a1b2c3d4", "message": "Fire in first floor kitchen", "timestamp": "2026-04-28T16:17:03.829715", "ai_classification": { "type": "fire", "severity": "high", "confidence": 0.85, "explanation": "Fire-related keywords detected in message." }, "vision_result": { "detected": true, "label": "fire", "confidence": 0.88 }, "decision": { "assigned_staff": ["staff_fire_1", "staff_fire_2"], "zone": "Zone A – Fire Assembly Point", "reason": "High severity fire incident detected. Dispatching 2 staff." }, "voice_guidance": { "message": "🔥 FIRE ALERT: Please evacuate calmly using the nearest exit." }, "status": "pending", "accepted_by": null } ``` ### `GET /incident` 检索所有事件，按最新排序。 **响应 (`200 OK`)：** 事件对象数组。 ### `GET /incident/{incident_id}` 通过 ID 检索特定事件。 **响应 (`200 OK`)：** 单个事件对象。 **错误 (`404`)：** `{ "detail": "Incident not found" }` ### `PATCH /incident/{incident_id}/status` 更新事件状态（由员工使用）。 **请求体：** ``` { "status": "in-progress", "staff_id": "staff_abc" } ``` **有效转换：** | 从 | 到 | |------|----| | `pending` | `in-progress` | | `in-progress` | `resolved` | **错误 (`400`)：** `{ "detail": "Cannot transition from resolved to pending" }` ### `GET /health` 健康检查端点。 **响应：** `{ "status": "ok" }` ## 🧠 AI 流水线 每个事件在后端都会经过一个 **4 阶段的 AI 流水线**： ### 阶段 1：Gemini AI 分类 ``` # 发送给 Gemini 2.0 Flash 的 Prompt """ You are an emergency incident classifier for a hotel/resort crisis response system. Analyze the following emergency message and return a JSON object with: - "type": one of "fire", "medical", "security", or "unknown" - "severity": one of "low", "medium", "high", "critical" - "confidence": a float between 0 and 1 - "explanation": a brief explanation of your classification """ ``` **输出：** ``` { "type": "fire", "severity": "high", "confidence": 0.92, "explanation": "Message indicates an active fire in a kitchen area with potential for rapid spread." } ``` ### 阶段 2：模拟视觉分析 基于关键词检测，模拟摄像头画面： | 关键词 | 检测标签 | 置信度 | |----------|----------------|------------| | fire, smoke, flame, burning | `fire` | 0.88 | | flood, water, leak | `flood` | 0.82 | | intruder, suspicious, weapon | `intruder` | 0.78 | | collapse, debris, structural | `structural_damage` | 0.75 | | medical, unconscious, bleeding | `medical_emergency` | 0.80 | ### 阶段 3：决策引擎 将 AI 分类映射为操作响应： | 严重程度 | 派遣员工数 | |----------|-----------------| | Low | 1 名响应人员 | | Medium | 1 名响应人员 | | High | 2 名响应人员 | | Critical | 3 名响应人员 | **人员池：** | 类型 | 可用员工 | |------|----------------| | Fire | `staff_fire_1`, `staff_fire_2`, `staff_fire_3` | | Medical | `staff_med_1`, `staff_med_2` | | Security | `staff_sec_1`, `staff_sec_2`, `staff_sec_3` | | Unknown | `staff_general_1` | **区域路由：** | 类型 | 区域 | |------|------| | Fire | Zone A – 消防集合点 | | Medical | Zone B – 医疗区 | | Security | Zone C – 安保办公室 | | Unknown | Zone D – 一般区域 | ### 阶段 4：语音指导 通过 `type × severity` 映射的 16 条预制安全信息： | 严重程度 | 火灾示例 | |----------|-------------| | Critical | 🚨 严重火灾警报：立即撤离！请使用最近的消防通道... | | High | 🔥 火灾警报：请使用最近的出口冷静撤离... | | Medium | ⚠️ 火灾警告：请远离受影响区域... | | Low | ℹ️ 报告轻微火灾隐患。工作人员正在检查该区域... | ## 🧪 测试流程 按照以下步骤测试完整的端到端流程： ``` Step 1 ─── Open /guest ──────────────────── Guest reports emergency │ Step 2 ─── Type: "Fire in the kitchen" ──── Submit via SOS or Send button │ Step 3 ─── AI classifies ───────────────── Gemini or fallback returns type/severity │ Step 4 ─── Pipeline runs ──────────────── Vision + Decision + Voice stages execute │ Step 5 ─── Incident stored ─────────────── Full record saved in memory │ Step 6 ─── Open /staff ─────────────────── Staff sees new pending incident │ Step 7 ─── Click "Accept" ──────────────── Status → in-progress, staff ID recorded │ Step 8 ─── Click "Resolve" ─────────────── Status → resolved │ Step 9 ─── Open /admin ─────────────────── Dashboard shows updated analytics ``` ### 通过 cURL 快速测试 ``` # 创建 incident curl -X POST http://localhost:8000/incident \ -H "Content-Type: application/json" \ -d '{"message": "Fire in first floor kitchen"}' # 列出所有 incident curl http://localhost:8000/incident # 更新状态 (将 替换为实际的 incident ID) curl -X PATCH http://localhost:8000/incident//status \ -H "Content-Type: application/json" \ -d '{"status": "in-progress", "staff_id": "staff_1"}' ``` ### 通过 PowerShell 快速测试 ``` # 创建 incident Invoke-WebRequest -Uri http://localhost:8000/incident ` -Method POST ` -ContentType "application/json" ` -Body '{"message": "Medical emergency in lobby"}' | Select -Expand Content # 列出所有 incident Invoke-WebRequest -Uri http://localhost:8000/incident | Select -Expand Content ``` ## ⚙️ 配置 ### 环境变量 | 变量 | 是否必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `GEMINI_API_KEY` | 否 | `your_gemini_api_key_here` | Gemini API 密钥。如果未设置，则回退到关键词分类器。 | | `NEXT_PUBLIC_API_URL` | 否 | `http://localhost:8000` | 前端使用的后端 API URL（在前端 `.env.local` 中设置） | ### 后端配置 后端的 `.env` 文件位于 `backend/.env`： ``` GEMINI_API_KEY=your_gemini_api_key_here ``` ### 前端配置（可选） 如果在不同的主机/端口上运行后端，请创建 `frontend/.env.local`： ``` NEXT_PUBLIC_API_URL=http://your-backend-host:8000 ``` ## 🗂 数据模型 ### Incident 模型 ``` interface Incident { id: string; // Auto-generated 8-char UUID message: string; // Original emergency description timestamp: string; // ISO 8601 UTC timestamp ai_classification: { type: "fire" | "medical" | "security" | "unknown"; severity: "low" | "medium" | "high" | "critical"; confidence: number; // 0.0 – 1.0 explanation: string; // AI reasoning }; vision_result: { detected: boolean; // Hazard detected? label: string; // Detection label confidence: number; // 0.0 – 1.0 }; decision: { assigned_staff: string[]; // Staff IDs assigned zone: string; // Response zone reason: string; // Decision reasoning }; voice_guidance: { message: string; // Safety instructions }; status: "pending" | "in-progress" | "resolved"; accepted_by: string | null; // Staff ID who accepted } ``` ## 🎨 设计系统 UI 使用基于 Tailwind CSS 构建的自定义带有毛玻璃效果的深色主题： | Token | 值 | 用途 | |-------|-------|-------| | `--background` | `#0a0e1a` | 页面背景 | | `--card` | `#111827` | 卡片表面 | | `--accent-red` | `#ef4444` | 火灾 / 严重警报 | | `--accent-orange` | `#f59e0b` | 警告 / 中等严重程度 | | `--accent-green` | `#22c55e` | 已解决 / 低严重程度 | | `--accent-blue` | `#3b82f6` | 医疗 / 信息高亮 | | `--accent-purple` | `#8b5cf6` | AI 置信度指示器 | ### CSS 类 | 类 | 描述 | |-------|-------------| | `.glass-card` | 带有模糊和边框的毛玻璃卡片 | | `.sos-pulse` | SOS 按钮的脉冲环动画 | | `.severity-*` | 渐变徽章：`critical`、`high`、`medium`、`low` | | `.status-*` | 状态徽章：`pending`、`in-progress`、`resolved` | | `.glow-*` | 阴影发光效果：`red`、`blue`、`purple` | | `.shimmer` | 加载骨架屏动画 | | `.animate-fade-in` | 带有 Y 轴平移的入场动画 | ## 🤝 贡献 1. **Fork** 该仓库 2. 创建一个功能分支：`git checkout -b feature/my-feature` 3. 提交您的更改：`git commit -m "Add my feature"` 4. 推送到该分支：`git push origin feature/my-feature` 5. 发起一个 **Pull Request** ### 开发提示 - 后端在文件更改时会自动重新加载（`--reload` 标志） - 前端使用 Turbopack 进行即时热重载 - API 文档在 `/docs` (Swagger) 和 `/redoc` 处自动生成 - 事件存储在内存中——重启后端将清除所有数据 ## 📜 许可证 本项目是开源的，并基于 [MIT 许可证](LICENSE) 提供。

**用 ❤️ 为 Google Solution Challenge 构建** [报告 Bug](../../issues) · [请求功能](../../issues) · [API 文档](http://localhost:8000/docs)

标签：AI危机响应, AI辅助决策, AV绕过, FastAPI, MVP, Python, SaaS平台, Tailwind CSS, TypeScript, 事件分类, 人工智能, 住宿业管理, 危机协调, 员工调度系统, 安全插件, 实时响应, 应急指挥系统, 应急管理, 无后门, 智能调度, 用户模式Hook绕过, 管理面板, 自动化攻击, 自动化调度, 设施管理, 逆向工具