AdikaNathaniel/Boafo

## 📋 目录 - [🌍 概述](#-overview) - [🏗️ 系统架构](#️-system-architecture) - [⚡ 技术栈](#-tech-stack) - [🔧 微服务](#-microservices) - [🗄️ 数据库设计](#️-database-design) - [📡 通信与消息传递](#-communication--messaging) - [📱 前端 (Flutter)](#-frontend-flutter) - [🔌 API 接口](#-api-endpoints) - [🚀 快速入门](#-getting-started) - [📁 项目结构](#-project-structure) - [⚙️ 环境变量](#️-environment-variables) ## 🌍 概述 在包括加纳在内的许多非洲国家，警察局、医院、消防站和救护车单位等应急服务机构通常是独立运作的。在紧急情况下，协调工作是最大的挑战——确定哪个响应者最近、哪家医院有空床，或者哪辆救护车可以立即响应。 **Boafo** 通过提供一个统一的平台解决了这个问题，该平台： - 📝 允许呼叫中心管理员通过 Google Maps **记录带有位置数据的紧急事件** - 🎯 使用 Haversine 公式计算距离，**自动调度最近的可用响应者** - 📍 通过基于 WebSocket 的 GPS 流**实时追踪应急车辆** - 📊 提供关于响应时间、事件分布和资源利用率的**分析和洞察** - 🔐 支持针对不同类型管理员的**基于角色的访问控制** ### 👥 系统角色 | 角色 | 职责 | |:------|:-----| | 🖥️ **系统管理员** | 接听紧急电话并记录事件的呼叫中心操作员 | | 🏥 **医院管理员** | 更新医院容量和救护车可用性 | | 🚑 **救护车司机** | 操作救护车；车辆传输实时位置更新 | | 🚔 **警察局管理员** | 管理警察局资源和警员 | | 🚒 **消防服务管理员** | 管理消防站资源和人员 | | 👤 **市民** | 通过电话报告紧急情况（不登录系统） | ## 🏗️ 系统架构 ``` ┌───────────────────────┐ │ 📱 Flutter Frontend │ │ (Mobile / Web App) │ └───────────┬───────────┘ │ HTTP / WebSocket │ ┌───────────▼───────────┐ │ 🌐 API Gateway │ │ (Port 3000) │ │ ⚡ Rate Limiting │ │ 🔐 JWT Auth Guard │ │ 🔀 Request Proxying │ └───────────┬───────────┘ │ ┌──────────┬───────────┴───────────┬──────────┐ │ │ │ │ ┌──────▼─────┐ ┌─▼──────────┐ ┌─────▼──────┐ ┌─▼────────────┐ │ 🔑 Auth │ │ 🚨 Incident│ │ 🚗 Dispatch│ │ 📊 Analytics │ │ Service │ │ Service │ │ Service │ │ Service │ │ (Port 3001)│ │ (Port 3002)│ │ (Port 3003)│ │ (Port 3004) │ └──────┬─────┘ └─────┬──────┘ └──────┬─────┘ └──────┬───────┘ │ │ │ │ ┌──────▼─────┐ ┌────▼──────┐ ┌──────▼─────┐ ┌─────▼───────┐ │ 🗄️ auth_db │ │🗄️incident │ │🗄️dispatch │ │🗄️analytics │ │ PostgreSQL │ │ _db │ │ _db │ │ _db │ │ Port 5432 │ │ Port 5433 │ │ Port 5434 │ │ Port 5435 │ └────────────┘ └─────┬─────┘ └──────┬─────┘ └──────┬──────┘ │ │ │ └──────┬ ┌─────┘ │ │ │ │ ┌──────▼─────▼────┐ │ │ 🐰 RabbitMQ │◄─────────────┘ │ Message Queue │ │ (Port 5672) │ └─────────────────┘ ``` ### 🔄 工作原理 ``` 📞 Citizen calls ➜ 🖥️ Admin logs ➜ 🎯 System finds ➜ 🚗 Responder ➜ 📍 Real-time emergency incident nearest unit dispatched tracking ``` 1. 📞 一位**市民拨打**紧急热线 2. 🖥️ 一位**系统管理员**登录 Boafo 并填写事件报告表 3. 🧮 **事件服务** 确定事件类型，并使用 **Haversine 距离公式** 计算最近的可用响应者 4. 📤 系统**调度响应者**并向 RabbitMQ 发布事件 5. 📍 **调度服务** 通过 WebSocket 实时追踪响应者的车辆 6. 📊 **分析服务** 消费来自 RabbitMQ 的事件以生成运营洞察 7. 🗺️ 管理员可以**在地图上查看实时车辆位置**并监控事件状态 ## ⚡ 技术栈

### 🖥️ 后端 | 技术 | 用途 | |:------------|:---------| |  | 微服务框架 | |  | 类型安全的后端语言 | |  | 运行时环境 (Alpine Linux) | |  | 数据库 (4 个实例) | |  | 对象关系映射器 | |  | 消息队列 (AMQP) | |  | 实时 WebSocket | |  | 身份验证 | |  | 容器化 | |  | 测试框架 |

### 📱 前端 | 技术 | 用途 | |:------------|:---------| | -02569B?style=flat-square&logo=flutter&logoColor=white) | 跨平台框架 | |  | 状态管理 | |  | 地图集成 | |  | 实时更新 | |  | 数据可视化 | |  | UI 组件库 |

## 🔧 微服务 ### 🌐 API Gateway 所有客户端请求的单一入口点。 | 功能 | 描述 | |:--------|:-----------| | 🔀 **请求代理** | 将请求路由到相应的微服务 | | ⚡ **速率限制** | 每个客户端每 60 秒 100 个请求 | | 🔐 **JWT 认证守卫** | 验证受保护路由上的令牌 | | 💚 **健康检查** | 用于监控的 `/health` 端点 | | 路由前缀 | ➜ | 目标服务 | |:-------------|:-:|:---------------| | `/auth/*` | ➜ | 🔑 Auth Service (3001) | | `/incidents/*` | ➜ | 🚨 Incident Service (3002) | | `/vehicles/*` | ➜ | 🚗 Dispatch Service (3003) | | `/analytics/*` | ➜ | 📊 Analytics Service (3004) | ### 🔑 Auth Service 管理所有系统用户及基于角色的访问控制。 **支持的角色：** | 角色 | 描述 | |:-----|:------------| | 🖥️ `SYSTEM_ADMIN` | 呼叫中心操作员 | | 🏥 `HOSPITAL_ADMIN` | 医院工作人员 | | 🚑 `AMBULANCE_DRIVER` | 救护车操作员 | | 🚔 `POLICE_ADMIN` | 警察局工作人员 | | 🚒 `FIRE_SERVICE_ADMIN` | 消防服务人员 | **✨ 核心功能：** - ✅ 用户注册及角色分配 - 🔑 登录获取 JWT 访问令牌（15 分钟）和刷新令牌（7 天） - 🔄 自动令牌刷新 - 🛡️ 使用 bcrypt 进行密码哈希处理 - 📧 邮箱唯一性验证 ### 🚨 Incident Service 记录紧急事件并处理自动调度的核心服务。 **事件类型：** | 类型 | |:-----| | 🔥 `FIRE` | | 🏥 `MEDICAL_EMERGENCY` | | 💥 `ACCIDENT` | | 🔫 `ROBBERY` | | 🚔 `CRIME` | **事件生命周期：** ``` 📝 CREATED ➜ 📤 DISPATCHED ➜ 🔄 IN_PROGRESS ➜ ✅ RESOLVED ``` **🎯 自动调度算法：** ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1️⃣ Receive incident with type + GPS coordinates │ │ 2️⃣ Map incident type ➜ responder type │ │ • ROBBERY / CRIME ➜ 🚔 Police Vehicle │ │ • FIRE ➜ 🚒 Fire Truck │ │ • MEDICAL / ACCIDENT ➜ 🚑 Ambulance │ │ 3️⃣ Fetch available units from Dispatch Service │ │ 4️⃣ Calculate distance using 📐 Haversine formula │ │ 5️⃣ For medical: check 🏥 hospital capacity │ │ 6️⃣ Select nearest available unit ➜ dispatch │ │ 7️⃣ Publish event to 🐰 RabbitMQ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 🚗 Dispatch Tracking Service 管理车辆注册、状态追踪和实时 GPS 位置流。 | 类别 | 值 | |:---------|:-------| | 🚗 **车辆类型** | `AMBULANCE` · `FIRE_TRUCK` · `POLICE_VEHICLE` | | 📊 **车辆状态** | 🟢 `AVAILABLE` · 🟡 `DISPATCHED` · 🟠 `EN_ROUTE` · 🔴 `ON_SCENE` | | 🏢 **站点类型** | `HOSPITAL` · `POLICE_STATION` · `FIRE_STATION` | **📍 实时位置追踪：** - 📡 车辆通过 WebSocket (Socket.io) 发送 `updateLocation` 事件 - 💾 服务存储位置历史（每辆车最近 100 条记录） - 📢 更新的位置实时广播给所有连接的管理员客户端 - 🗺️ 管理员在地图上查看实时车辆移动 ### 📊 Analytics Service 通过消费来自 RabbitMQ 的事件并聚合数据来生成运营洞察。 | 指标 | 描述 | |:-------|:------------| | ⏱️ **响应时间** | 每种事件类型的平均、最小和最大响应时间 | | 🗺️ **按区域划分的事件** | 按区域和类型细分的事件分布 | | 📈 **资源利用率** | 医院床位使用统计和已部署响应者数量 | | 📅 **日期范围筛选** | 所有分析均支持自定义日期范围查询 | ## 🗄️ 数据库设计 ### 🔑 `auth_db` — 用户表 | 列名 | 类型 | 描述 | |:-------|:-----|:------------| | `id` | `UUID` (PK) | 唯一用户标识符 | | `name` | `VARCHAR` | 全名 | | `email` | `VARCHAR` (唯一) | 登录邮箱 | | `role` | `ENUM` | 用户角色 | | `passwordHash` | `VARCHAR` | bcrypt 哈希密码 | | `createdAt` | `TIMESTAMP` | 注册日期 | ### 🚨 `incident_db` — 事件表 | 列名 | 类型 | 描述 | |:-------|:-----|:------------| | `id` | `UUID` (PK) | 唯一事件标识符 | | `citizenName` | `VARCHAR` | 报告人姓名 | | `incidentType` | `ENUM` | 紧急情况类型 | | `latitude` | `DECIMAL(10,7)` | 事件 GPS 纬度 | | `longitude` | `DECIMAL(10,7)` | 事件 GPS 经度 | | `notes` | `TEXT` | 附加详情 | | `createdBy` | `UUID` (FK) | 创建报告的管理员 | | `assignedUnit` | `VARCHAR` | 分配的响应单位名称 | | `assignedUnitId` | `UUID` | 分配车辆的 ID | | `status` | `ENUM` | 当前事件状态 | | `createdAt` | `TIMESTAMP` | 创建时间戳 | | `updatedAt` | `TIMESTAMP` | 最后更新时间戳 | ### 🚗 `dispatch_db` — 车辆与位置历史

📋 点击展开车辆表

**车辆：** | 列名 | 类型 | 描述 | |:-------|:-----|:------------| | `id` | `UUID` (PK) | 唯一车辆标识符 | | `vehicleType` | `ENUM` | 车辆类型 | | `stationId` | `UUID` | 所属站点 ID | | `stationName` | `VARCHAR` | 站名称 | | `stationType` | `ENUM` | 站点类型 | | `latitude` | `DECIMAL(10,7)` | 当前 GPS 纬度 | | `longitude` | `DECIMAL(10,7)` | 当前 GPS 经度 | | `status` | `ENUM` | 车辆可用状态 | | `driverId` | `UUID` | 分配的司机 | | `updatedAt` | `TIMESTAMP` | 最后位置更新时间 | **车辆位置（历史）：** | 列名 | 类型 | 描述 | |:-------|:-----|:------------| | `id` | `UUID` (PK) | 记录标识符 | | `vehicleId` | `UUID` (FK) | 车辆引用 | | `latitude` | `DECIMAL(10,7)` | GPS 纬度 | | `longitude` | `DECIMAL(10,7)` | GPS 经度 | | `timestamp` | `TIMESTAMP` | 位置读取时间 |

### 📊 `analytics_db` — 指标表

📋 点击展开分析表

**响应指标** · **资源快照** · **事件日志** 存储聚合的响应时间数据、资源容量快照和原始事件日志 (JSONB)，以支持灵活查询。

## 📡 通信与消息传递 ### 🔗 同步 (HTTP/REST) | 流程 | 描述 | |:-----|:-----------| | 📱 ➜ 🌐 | **前端 → API Gateway** — 所有客户端请求都通过网关 | | 🌐 ➜ 🔧 | **API Gateway → 微服务** — 网关代理到内部服务 | | 🚨 ➜ 🚗 | **Incident → Dispatch** — 在自动调度期间获取可用单位 | ### 🐰 异步 (RabbitMQ / AMQP) 事件通过 RabbitMQ 流动，以实现解耦的异步处理： | 事件 | 发布者 | 消费者 | 触发条件 | |:------|:----------|:---------|:--------| | `incident.created` | 🚨 Incident Service | 📊 Analytics Service | 记录新事件 | | `incident.status_updated` | 🚨 Incident Service | 📊 Analytics Service | 状态变更 | | `incident.responder_assigned` | 🚨 Incident Service | 📊 Analytics, 🚗 Dispatch | 单位已调度 | ### ⚡ 实时 (WebSocket / Socket.io) | 事件 | 方向 | 描述 | |:------|:----------|:-----------| | `updateLocation` | 🚗 ➜ 🖥️ | 车辆发送 GPS 坐标 | | `locationUpdated` | 🖥️ ➜ 📱 | 服务器广播给所有管理员仪表板 | ## 📱 前端 (Flutter) ### 📲 界面 | 界面 | 描述 | |:-------|:------------| | 🔑 **登录** | 邮箱/密码认证，包含错误处理和加载状态 | | 🏠 **仪表板** | 底部导航中心，显示角色和登出按钮 | | 🚨 **事件列表** | 未解决事件列表，带有状态颜色编码、类型图标和下拉刷新 | | 📝 **创建事件** | 报告新事件的表单，包含位置输入、类型选择和备注 | | 🚗 **调度** | 车辆列表，支持类型/状态筛选和颜色编码的状态指示器 | | 📊 **分析** | 响应时间指标、区域事件分布和资源利用率数据 | ### 🧩 状态管理 | Provider | 用途 | |:---------|:--------| | **AuthProvider** | 🔐 管理登录/登出、JWT 令牌、从共享偏好设置自动登录 | | **IncidentProvider** | 🚨 管理事件列表、创建和状态更新 | ### ✨ 核心前端功能 - 🔑 所有 API 请求注入 JWT 令牌 - 🔄 收到 401 响应时自动刷新令牌 - 🗺️ 集成 Google Maps 用于位置选择和车辆追踪 - 📍 通过 Socket.io 实时更新车辆位置 - 📊 使用 FL Chart 进行分析数据可视化 - 💾 应用重启后保持会话持久性 ## 🔌 API 接口 ### 🔑 身份验证 | 方法 | 端点 | 描述 | |:------:|:---------|:------------| | `POST` | `/auth/register` | 注册新用户 | | `POST` | `/auth/login` | 登录并获取 JWT 令牌 | | `POST` | `/auth/refresh-token` | 刷新过期的访问令牌 | | `GET` | `/auth/profile` | 获取当前用户资料 | ### 🚨 事件 | 方法 | 端点 | 描述 | |:------:|:---------|:------------| | `POST` | `/incidents` | 创建新事件（触发自动调度） | | `GET` | `/incidents/open` | 列出所有未解决的事件 | | `GET` | `/incidents/:id` | 通过 ID 获取事件详情 | | `PUT` | `/incidents/:id/status` | 更新事件状态 | | `PUT` | `/incidents/:id/assign` | 手动分配响应单位 | ### 🚗 车辆 / 调度 | 方法 | 端点 | 描述 | |:------:|:---------|:------------| | `POST` | `/vehicles/register` | 注册新的应急车辆 | | `GET` | `/vehicles` | 列出车辆（按类型、状态、站点筛选） | | `GET` | `/vehicles/:id/location` | 获取当前车辆位置 | ### 📊 分析 | 方法 | 端点 | 描述 | |:------:|:---------|:------------| | `GET` | `/analytics/response-times` | 按事件类型统计的平均/最小/最大响应时间 | | `GET` | `/analytics/incidents-by-region` | 按区域和类型分组的事件计数 | | `GET` | `/analytics/resource-utilization` | 医院床位和响应者部署统计 | ### 💚 健康 | 方法 | 端点 | 描述 | |:------:|:---------|:------------| | `GET` | `/health` | API Gateway 健康检查 | ## 🚀 快速入门 ### 📋 前置条件 | 需求 | 版本 | |:------------|:--------| | 🐳 Docker & Docker Compose | 最新版 | | 📱 Flutter SDK | 3.10+ | | 🟢 Node.js *（可选 — 仅在 Docker 外使用时需要）* | 20+ | ### 1️⃣ 克隆仓库 ``` git clone https://github.com//boafo.git cd boafo ``` ### 2️⃣ 启动后端 ``` docker-compose up --build ``` 这将启动整个后端基础设施： | 服务 | 端口 | 状态 | |:--------|:-----|:------:| | 🌐 API Gateway | `localhost:3000` | 🟢 | | 🔑 Auth Service | `localhost:3001` | 🟢 | | 🚨 Incident Service | `localhost:3002` | 🟢 | | 🚗 Dispatch Service | `localhost:3003` | 🟢 | | 📊 Analytics Service | `localhost:3004` | 🟢 | | 🐰 RabbitMQ Management | `localhost:15672` | 🟢 | | 🗄️ PostgreSQL (auth) | `localhost:5432` | 🟢 | | 🗄️ PostgreSQL (incident) | `localhost:5433` | 🟢 | | 🗄️ PostgreSQL (dispatch) | `localhost:5434` | 🟢 | | 🗄️ PostgreSQL (analytics) | `localhost:5435` | 🟢 | ### 3️⃣ 运行前端 ``` cd frontend flutter pub get flutter run -d chrome # 🌐 For web flutter run # 📱 For mobile (with device/emulator) ``` ### 4️⃣ 验证系统 ``` # 💚 Health check curl http://localhost:3000/health # 👤 注册用户 curl -X POST http://localhost:3000/auth/register \ -H "Content-Type: application/json" \ -d '{"name": "Admin", "email": "admin@boafo.com", "password": "password123", "role": "SYSTEM_ADMIN"}' ``` ## 📁 项目结构 ``` Boafo/ ├── 🐳 docker-compose.yml # Multi-container orchestration │ ├── 🖥️ backend/ │ ├── 🌐 api-gateway/ # Entry point — routes, auth guard, rate limiting │ │ └── src/ │ │ ├── proxy/ # Request proxying to microservices │ │ ├── auth/ # JWT strategy and guards │ │ └── health/ # Health check endpoint │ │ │ ├── 🔑 auth-service/ # User management and authentication │ │ └── src/ │ │ ├── auth/ # Login, register, JWT, refresh │ │ └── users/ # User entity and repository │ │ │ ├── 🚨 incident-service/ # Incident CRUD and auto-dispatch │ │ └── src/ │ │ ├── incidents/ # Incident entity, service, controller │ │ └── dispatch/ # Haversine calculation, nearest unit logic │ │ │ ├── 🚗 dispatch-service/ # Vehicle tracking and WebSocket gateway │ │ └── src/ │ │ ├── vehicles/ # Vehicle entity, service, controller │ │ └── location/ # WebSocket gateway for GPS streaming │ │ │ └── 📊 analytics-service/ # Metrics aggregation and reporting │ └── src/ │ ├── analytics/ # Analytics service and controller │ └── events/ # RabbitMQ event consumer │ └── 📱 frontend/ # Flutter cross-platform app ├── lib/ │ ├── config/ # API configuration and base URLs │ ├── models/ # User, Incident, Vehicle data models │ ├── providers/ # AuthProvider, IncidentProvider (state) │ ├── screens/ # Login, Dashboard, Incidents, Dispatch, Analytics │ ├── services/ # ApiService (HTTP + token management) │ └── widgets/ # Reusable UI components ├── android/ # Android platform files ├── ios/ # iOS platform files ├── web/ # Web platform files └── pubspec.yaml # Flutter dependencies ``` ## ⚙️ 环境变量 | 变量 | 描述 | 示例 | |:---------|:------------|:--------| | `DATABASE_HOST` | PostgreSQL 主机 | `auth-db` | | `DATABASE_PORT` | PostgreSQL 端口 | `5432` | | `DATABASE_USER` | 数据库用户 | `postgres` | | `DATABASE_PASSWORD` | 数据库密码 | `postgres` | | `DATABASE_NAME` | 数据库名称 | `auth_db` | | `RABBITMQ_URL` | RabbitMQ 连接字符串 | `amqp://guest:guest@rabbitmq:5672` | | `JWT_SECRET` | JWT 签名密钥 | `your-secret-key` | | `AUTH_SERVICE_URL` | Auth Service 基础 URL | `http://auth-service:3001` | | `INCIDENT_SERVICE_URL` | Incident Service 基础 URL | `http://incident-service:3002` | | `DISPATCH_SERVICE_URL` | Dispatch Service 基础 URL | `http://dispatch-service:3003` | | `ANALYTICS_SERVICE_URL` | Analytics Service 基础 URL | `http://analytics-service:3004` |

### 🌟 如果觉得有用，请给个 Star！ **🚨 Boafo** — *协调应急响应，挽救生命。* 在加纳用 ❤️ 制作

标签：Docker, Flutter, GPS车辆追踪, JWT, MITM代理, NestJS, PostgreSQL, RabbitMQ, Socket.io, TypeScript, 代码示例, 公共安全, 加纳, 医疗急救, 后端开发, 国家应急响应, 安全插件, 安全防御评估, 实时事件报告, 实时通讯, 微服务架构, 数据分析, 数据库设计, 智慧城市, 最近响应者调度, 测试用例, 消息队列, 消防系统, 紧急救援, 警务系统, 请求拦截, 调度协调平台, 跨平台移动应用, 非洲科技