mahek-builds/CrisisLink-AI

# CrisisLink-AI 平台 CrisisLink-AI 是一个紧急响应平台，结合 Flutter 客户端和 FastAPI 后端，用于捕获 SOS 报告、聚类附近事件、优先响应紧急程度，并为调度团队提供 AI 支持的建议。 ## 目录 - [1. 业务背景](#1-business-context) - [2. 核心架构与创新](#2-core-architecture-and-innovations) - [3. 系统设计](#3-system-design) - [4. 技术栈](#4-technology-stack) - [5. 仓库结构](#5-repository-structure) - [6. 安装](#6-installation) - [7. 运维运行手册](#7-operation-runbook) - [8. API 接口](#8-api-surface) - [9. 测试与质量](#9-testing-and-quality) - [10. 安全与合规说明](#10-security-and-compliance-notes) - [11. 已知约束与改进待办](#11-known-constraints-and-improvement-backlog) ## 1. 业务背景 紧急呼叫中心在高压力事件中会收到大量非结构化报告。CrisisLink-AI 通过以下方式解决此问题： - 将基于位置的重复 SOS 报告合并为统一的事件记录。 - 跟踪唯一上报者以估算事件置信度与紧急程度。 - 使用 AI 支持的建议和欺诈风险信号指导调度团队。 - 为市民、响应人员和管理员提供角色导向的移动体验。 ## 2. 核心架构与创新 ### 2.1 高级组件 1. **Flutter 客户端 (`crisislink_ai_app`)** - 多屏幕紧急工作流程，用于报告摄入和基于角色的仪表盘。 - 使用连接性和位置服务支持实时和离线感知行为。 - 通过 HTTP API 与后端通信。 2. **FastAPI 后端 (`backend_python`)** - 提供 SOS、事件生命周期、分配、管理员洞察和 AI 分析所需的 REST 端点。 - 使用 SQLAlchemy 会话与 PostgreSQL 兼容的连接。 - 封装用于优先级预测、建议和可疑模式检查的 AI 逻辑。 3. **关系数据层** - 核心实体包括事件、报告和响应者。 - 事件状态转换（活跃 -> 进行中 -> 已解决）支持操作流程。 ### 2.2 架构创新 - **摄入时间的实例聚类：** 使用坐标邻近逻辑将传入的 SOS 请求匹配到附近的活动事件，以减少重复事件创建。 - **从人群信号进行优先级升级：** 唯一上报者数量被转换为优先级级别（`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`）。 - **可操作的 AI 建议：** 响应人员和指挥中心接收针对事件类型的具体建议（团队/设备/升级提示）。 - **欺诈风险启发式：** 标记可疑上报模式以供人工分诊。 - **模块化 API 分段：** 业务能力拆分到专用路由器（`sos`、`assign`、`ai`、`incident`、`admin`、`report`）以提升可维护性。 ## 3. 系统设计 ### 3.1 逻辑流程 1. 公民从移动应用提交 SOS。 2. 后端验证有效负载并查找附近的活动事件。 3. 如果找到，请求作为报告附加；否则，打开新事件。 4. 同一电话号码对同一事件的重复报告将被忽略。 5. 重新计算唯一上报者数量并映射到更新后的优先级。 6. 调度/管理员模块查询活动事件并分配响应者。 7. AI 分析端点生成建议和欺诈风险信号。 ### 3.2 组件交互图 ``` flowchart LR U[User Mobile App] -->|HTTP JSON| API[FastAPI Backend] API --> SOS[Router: /api/sos] API --> INC[Router: /api/incidents] API --> ASN[Router: /api/assign] API --> ADM[Router: /api/admin] API --> AI[Router: /api/ai] API --> RPT[Router: /api/reports] SOS --> DB[(PostgreSQL / SQL layer)] INC --> DB ASN --> DB ADM --> DB AI --> DB AI --> ML[AI Rules + Heuristics] ``` ### 3.3 数据与领域模型（运营） - **事件** - 位置、类型、状态、优先级、唯一上报者数量。 - **报告** - 事件引用、电话号码、报告类型、时间戳。 - **响应者** - 可用状态、类别/类型、最后位置、当前事件绑定。 ## 4. 技术栈 ### 4.1 客户端 - Flutter / Dart（应用配置中的 SDK 约束）。 - 核心包：`geolocator`、`flutter_map`、`latlong2`、`http`、`shared_preferences`。 ### 4.2 后端 - FastAPI + Uvicorn。 - SQLAlchemy + psycopg2。 - Pydantic 和 pydantic-settings。 - 使用 Pytest 进行集成和 API 工作流测试。 ### 4.3 平台 - Flutter 目标平台：Android、iOS、macOS、Linux、Windows、Web（包含项目脚手架）。 ## 5. 仓库结构 ``` CrisisLink-AI/ |-- crisislink_ai_app/ | |-- lib/ | | |-- main.dart | | |-- app.dart | | |-- screens/ | | |-- services/ | | |-- widgets/ | | `-- utils/ | |-- test/ | |-- android/ ios/ macos/ linux/ windows/ web/ | `-- pubspec.yaml | `-- backend_python/ |-- app/ | |-- main.py | |-- api/ | |-- ai/ | |-- db/ | |-- config/ | |-- services/ | |-- schemas/ | `-- utils/ |-- tests/ |-- requirements.txt `-- pytest.ini ``` ## 6. 安装 ### 6.1 先决条件 - Flutter SDK（推荐稳定通道）。 - Python 3.10+。 - PostgreSQL 兼容的数据库（或基于 Supabase 的 Postgres）。 ### 6.2 后端设置 从 `backend_python`： ``` python -m venv .venv source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 pip install -r requirements.txt ``` 在 `backend_python` 中创建 `.env`： ``` DATABASE_URL=postgresql://:@:/ ``` 运行后端： ``` uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` ### 6.3 Flutter 应用设置 从 `crisislink_ai_app`： ``` flutter pub get flutter run ``` 生产构建示例： ``` flutter build apk flutter build windows ``` ## 7. 运维运行手册 ### 7.1 启动顺序（本地） 1. 启动后端 API 服务。 2. 验证健康端点：`GET /`。 3. 启动 Flutter 应用目标（模拟器/设备/桌面）。 4. 对 SOS 创建和事件可见性进行冒烟测试。 ### 7.2 标准运行检查 - 确认 API 可用性和响应时间。 - 验证数据库连接（通过后端数据库工具路径执行 `SELECT 1`）。 - 确认新 SOS 请求到达时事件计数更新。 - 验证响应者分配与释放生命周期。 ### 7.3 事件操作生命周期 1. 摄入：SOS 请求进入系统。 2. 相关性：报告被链接或创建新事件。 3. 优先级：重新计算唯一上报者并映射。 4. 调度：调用响应者分配端点。 5. 解决：通过管理员流程将事件设为已解决。 ## 8. API 接口 基础 URL（本地）：`http://127.0.0.1:8000` 挂载路由器： - `/api/sos` - `POST /create` - `/api/admin` - `GET /stats` - `GET /live-incidents` - `POST /resolve/{incident_id}` - `/api/ai` - `GET /analyze/{incident_id}` - `POST /predict-text` - `/api/assign` - `POST /to-incident` - `GET /nearby-responders` - `POST /release/{responder_id}` - `/api/incidents` - `GET /active` - `GET /{incident_id}` - `/api/reports` - `GET /incident/{incident_id}` - `GET /user/{phone_number}` 交互式文档： - Swagger UI：`http://127.0.0.1:8000/docs` - ReDoc：`http://127.0.0.1:8000/redoc` ## 9. 测试与质量 后端测试： ``` cd backend_python python -m pytest tests -v ``` Flutter 测试： ``` cd crisislink_ai_app flutter test ``` 推荐的 CI 门槛： - 单元测试和集成测试。 - 静态检查（`flutter analyze`、Python linting）。 - 关键端点的 API 契约验证。 ## 10. 安全与合规说明 - 不要提交 `.env` 或秘密凭证。 - 在生产上线前按环境限制 CORS 来源。 - 为管理员和分配端点实现 API 认证/授权。 - 为服务用户应用数据库最小权限角色。 - 在受监管的部署中添加事件状态转换的审计跟踪。 ## 11. 已知约束与改进待办 - 可通过直接在路由器函数签名中使用 Pydantic 架构进一步强化 API 契约类型。 - AI 文本预测输入处理应与生产级 NLP 行为的数据形状期望对齐 - 可将地理匹配从边界框近似升级为基于真实半径或 PostGIS 索引。 - 添加可观测性堆栈（指标、追踪、告警）以支持企业 SLA 运营。 ## 所有权与贡献 本仓库旨在用于紧急响应产品生命周期内的受控开发与部署。团队贡献标准请保持分支工作流、同行评审和环境特定的发布审批。

标签：AI推荐, AI辅助决策, AV绕过, FastAPI, Flutter, HTTP API, PostgreSQL, SOS, SQLAlchemy, 事件聚类, 优先级排序, 后台系统, 多角色平台, 实时定位, 库, 应急响应, 欺诈风险, 测试用例, 离线支持, 移动应用, 紧急事件, 紧急调度, 角色权限, 逆向工具