Oshinobi-obi/safechain_mobile
GitHub: Oshinobi-obi/safechain_mobile
一个基于 Flutter 的社区个人安全系统，通过 LoRa、GPS 与 BLE 打造去中心化应急响应网络。
Stars: 2 | Forks: 0
# SafeChain 移动应用程序
一个使用 Flutter 构建的社区个人安全应用程序，旨在通过智能数字安全钥匙链设备提供安心保障。SafeChain 通过蓝牙低功耗（BLE）、LoRa 和 GPS 跟踪，将居民与所在 barangay 的应急响应网络连接起来。
## 🚀 功能
### 🔐 安全认证
- 使用邮箱、强密码验证和滑块验证码（CAPTCHA）进行用户注册
- 支持会话持久化和“记住我”功能的登录
- 通过深度链接邮箱重置令牌的忘记密码流程
- 实时反馈的密码强度指示器
- 需验证当前密码的密码修改功能
### 👤 动态资料管理
- 查看和编辑个人信息（姓名、邮箱、地址、联系电话）
- 支持 `+63` 前缀的菲律宾手机号格式化
- 从设备图库上传头像或使用 Fluttermoji 创建自定义头像
- 管理健康状况（支持多选并包含“其他”自由文本选项）
- 实时邮箱验证状态
- 资料未完成时显示引导横幅，提示用户补充信息
### 🔗 BLE 设备配对流程
- 带有动画过渡的分步引导式配对向导
- 二维码扫描器用于获取设备的蓝牙 MAC 地址
- 蓝牙与位置权限请求并具备优雅的降级处理
- 本地 BLE 验证（连接与断开测试）后再进行云端注册
- 云端所有权检查——防止将已注册到其他账户的设备绑定
- ESP32 BLE 配置：通过 Nordic UART Service (NUS) 写入分配的 `device_id`
- LoRa 网关测试：发送 `safe` 数据包并等待网络 ACK 响应
- 设备重命名、解除绑定和“报告丢失”（停用设备以防止误报）
- 每个设备显示电池电量指示器
### 🗺️ 实时 GPS 追踪
- 在交互式地图上显示设备实时位置（使用 CartoDB Voyager 瓦片）
- 填充并带有边框覆盖层的 Barangay Gulod 边界多边形
- Barangay Hall / 疏散中心的标记点
- 基于指南针的航向锥体显示追踪设备
- 显示用户自身位置的设备 GPS
### 📍 地理围栏
- 使用射线投射算法检测设备进出 Barangay Gulod 边界
- 设备进入或离开地理围栏区域时推送本地通知
### 🔔 推送与本地通知
- 使用 Firebase Cloud Messaging (FCM) 发送远程推送通知（公告、警报）
- 后台 FCM 消息处理器并静默保存收件箱
- 使用 `flutter_local_notifications` 显示前台横幅通知
- 内置通知收件箱，支持未读徽章计数、多选删除、滑动关闭和全部标记已读
- 所有屏幕间实时未读计数数据流
### 📢 公告
- 从服务器获取分页的社区公告动态
- 支持展开的卡片式布局，显示作者信息、时间戳（timeago）和查看次数
- 图像媒体附件支持
- 每 30 秒自动刷新；支持下拉刷新
### 📵 后台 BLE 连接服务
- 由 `flutter_foreground_task` 驱动的单例 `BleConnectionService`
- 即使屏幕关闭也保持设备连接并持续传输 GPS 数据
- 断开连接后自动重连，可配置重试延迟
- 每次接收 GPS 坐标时进行地理围栏检查
### 📶 离线检测
- 定期向 `safechain.site` 发送 HTTP Ping 检测连接性
- 动画形式的 `OfflineBanner` 在每页顶部滑入/滑出
- 离线状态下会阻止可能失败的操作，并显示友好的 SnackBar 提示
### 🛡️ 账户限制系统
- 响应人员可将居民账户设置为 `restricted` 状态，且只能由 baranggay 管理员解除
- 受限设备会显示横幅，并禁用所有 BLE / GPS 追踪功能
- 每次加载主页时从服务器刷新状态
### 🧭 用户指南
- 可展开的指南章节：紧急按钮、GPS 测试、电池与充电、故障排除
- 内置支持联系对话框
### 🎨 现代 UI/UX
- 带有淡入动画的启动页
- 全局流畅的淡入页面路由过渡
- 动态卡片入场动画（交错滑动 + 淡入）
- 带渐变标题的自定义形状应用栏
- 动画形式的成功与错误弹窗
- 针对不同设备尺寸的响应式设计
## 🛠️ 使用的技术
### 框架与语言
| 技术 | 用途 |
|---|---|
| [Flutter](https://flutter.dev/) | 跨平台移动 UI 框架 |
| [Dart](https://dart.dev/) | 主要编程语言 |
### 后端与数据库
| 技术 | 用途 |
|---|---|
| [Firebase Authentication](https://firebase.google.com/products/auth) | 未直接使用 —— 采用自定义 PHP 认证 |
| [Firebase Cloud Messaging (FCM)](https://firebase.google.com/products/cloud-messaging) | 远程推送通知 |
| [Firebase Core](https://firebase.google.com/docs/flutter/setup) | Firebase SDK 初始化 |
| [PHP](https://www.php.net/) | RESTful 后端 API |
| [MySQL](https://www.mysql.com/) | 关系型数据库（托管于 Hostinger） |
### 地图与定位
| 包 | 用途 |
|---|---|
| [flutter_map ^8.2.2](https://pub.dev/packages/flutter_map) | 交互式地图渲染 |
| [latlong2 ^0.9.1](https://pub.dev/packages/latlong2) | 地理坐标类型 |
| [geolocator ^13.0.0](https://pub.dev/packages/geolocator) | 设备 GPS 位置 |
| [flutter_compass ^0.8.1](https://pub.dev/packages/flutter_compass) | 设备指南针航向 |
| [location ^8.0.1](https://pub.dev/packages/location) | 位置服务封装 |
| CartoDB Voyager | 地图瓦片提供者（基于 OpenStreetMap 数据） |
### 蓝牙与硬件
| 包 | 用途 |
|---|---|
| [flutter_blue_plus ^1.36.8](https://pub.dev/packages/flutter_blue_plus) | BLE 扫描、连接与 GATT 特性读写通知 |
| [mobile_scanner ^7.2.0](https://pub.dev/packages/mobile_scanner) | 二维码 / 条形码扫描 |
### 通知
| 包 | 用途 |
|---|---|
| [firebase_messaging ^15.2.10](https://pub.dev/packages/firebase_messaging) | FCM 远程推送通知 |
| [flutter_local_notifications ^21.0.0](https://pub.dev/packages/flutter_local_notifications) | 本地前台通知横幅 |
### 后台任务
| 包 | 用途 |
|---|---|
| [flutter_foreground_task ^8.17.0](https://pub.dev/packages/flutter_foreground_task) | Android 前台服务以保持后台 BLE 活跃 |
### UI 与 UX
| 包 | 用途 |
|---|---|
| [animations ^2.1.1](https://pub.dev/packages/animations) | 用于分步流程的 `FadeThroughTransition` |
| [fluttermoji ^1.0.2](https://pub.dev/packages/fluttermoji) | SVG 头像构建与显示 |
| [slider_captcha ^1.0.2](https://pub.dev/packages/slider_captcha) | 注册与密码重置用的滑块验证码 |
| [timeago ^3.7.1](https://pub.dev/packages/timeago) | 人类可读的相对时间戳 |
| [flutter_svg ^2.2.3](https://pub.dev/packages/flutter_svg) | SVG 渲染 |
### 网络与存储
| 包 | 用途 |
|---|---|
| [http ^1.6.0](https://pub.dev/packages/http) | 用于 REST API 调用的 HTTP 客户端 |
| [shared_preferences ^2.5.4](https://pub.dev/packages/shared_preferences) | 本地键值存储（会话、通知、FCM 令牌） |
| [image_picker ^1.2.1](https://pub.dev/packages/image_picker) | 相机 / 图库图像选择 |
| [permission_handler ^11.4.0](https://pub.dev/packages/permission_handler) | 运行时权限请求 |
| [app_links ^3.5.1](https://pub.dev/packages/app_links) | 密码重置的深度链接处理 |
## 🗄️ 后端 API 端点
所有端点托管在 `https://echain.site/api/mobile/`。
| 端点 | 方法 | 描述 |
|---|---|---|
| `login.php` | POST | 验证用户并返回会话数据 |
| `register.php` | POST | 创建新的居民账户 |
| `forgot_password.php` | POST | 生成重置令牌并发送 HTML 邮件 |
| `reset_password.php` | POST | 验证令牌并更新密码 |
| `change_password.php` | POST | 验证当前密码后修改密码 |
| `get_profile.php` | GET | 通过 `resident_id` 获取居民资料 |
| `update_profile.php` | POST（multipart） | 更新资料字段和/或上传头像 |
| `get_contacts.php` | GET | 获取居民的紧急联系人列表 |
| `add_contact.php` | POST | 添加新的紧急联系人 |
| `update_contact.php` | POST | 编辑现有紧急联系人 |
| `delete_contact.php` | POST | 删除紧急联系人 |
| `get_devices.php` | GET | 获取居民已配对的设备列表 |
| `add_device.php` | POST | 注册新的 BLE 设备 |
| `check_device.php` | GET | 检查设备 MAC 是否可用、已拥有或被占用 |
| `update_device.php` | POST | 重命名设备 |
| `delete_device.php` | POST | 解除设备绑定 |
| `mark_missing.php` | POST | 标记设备为丢失（停用设备） |
## ⚙️ 安装与设置
### 先决条件
- 已安装 Flutter SDK `>=3.38.1`
- Android Studio 或 VS Code 并安装 Flutter 插件
- 已配置 Android 应用的 Firebase 项目
- 用于后端的 PHP / MySQL 服务器（或 Hostinger 托管）
### 安装步骤
1. **克隆仓库：**
git clone https://github.com/your_username/safechain.git
cd safechain
2. **配置 Firebase：**
- 在 [Firebase 控制台](https://console.firebase.google.com/) 创建新项目。
- 添加包名为 `com.safechain.safechain` 的 Android 应用。
- 下载 `google-services.json` 并放置到 `android/app/` 目录。
- 在项目中启用 **Firebase Cloud Messaging**。
- 必须使用 FlutterFire CLI 或手动配置 `lib/firebase_options.dart` 文件。
3. **配置后端：**
- 将 `api/` 目录内容上传到 PHP 服务器。
- 更新 `api/mobile/db_connection.php` 中的 MySQL 凭据。
- 在数据库中创建 `password_resets` 表：
CREATE TABLE password_resets (
id INT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) NOT NULL,
token VARCHAR(64) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
- 上传 FCM 令牌存储端点到 `api/fcm/save_token.php`。
4. **安装依赖：**
flutter pub get
5. **运行应用：**
flutter run
### Android 所需权限
在 `AndroidManifest.xml` 中声明以下权限：
- `INTERNET` — API 通信
- `ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION` — GPS 追踪
- `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`, `BLUETOOTH_ADVERTISE` — BLE 设备配对
- `POST_NOTIFICATIONS` — 本地与推送通知
- `CAMERA` — 二维码扫描
- `VIBRATE` — 通知振动
- `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_CONNECTED_DEVICE` — 后台 BLE 服务
- `RECEIVE_BOOT_COMPLETED` — 计划通知接收器
## 🏗️ 项目结构
```
lib/
├── main.dart # App entry point, FCM setup, deep link init
├── firebase_options.dart # Firebase configuration
├── modals/ # Reusable dialog widgets (success, error)
├── screens/
│ ├── add_device/ # 9-step BLE device pairing wizard
│ ├── announcement/ # Paginated community announcements
│ ├── forgot_password/ # Forgot & reset password screens
│ ├── guide/ # User guide with expandable sections
│ ├── home/ # Home screen, device list, BLE card
│ ├── login/ # Login screen with Remember Me
│ ├── notification/ # In-app notification inbox
│ ├── profile/ # Profile, contacts, change password
│ ├── signup/ # Registration with CAPTCHA & Terms
│ ├── startup/ # Animated splash screen
│ ├── tracking/ # Live GPS map with geofence overlay
│ └── welcome/ # Onboarding / landing screen
├── services/
│ ├── ble_connection_service.dart # Background BLE singleton
│ ├── connectivity_service.dart # Internet connectivity watcher
│ ├── geofence_service.dart # Ray-casting geofence checker
│ ├── notification_service.dart # FCM + local notifications + inbox
│ └── session_manager.dart # SharedPreferences session CRUD
└── widgets/
├── battery_indicator.dart # Custom battery level widget
├── curved_app_bar.dart # Clipped gradient app bar
├── fade_page_route.dart # Fade transition page route
├── offline_banner.dart # Animated offline/online banner
├── phone_number_formatter.dart # PH number formatter (XXX-XXX-XXXX)
├── phone_number_input.dart # Phone input field widget
├── profile_completion_banner.dart # Incomplete profile warning
└── safechain_logo.dart # Logo text widget
```
## 🤝 贡献
欢迎提交 Pull Request。如需进行重大更改，请先打开 Issue 讨论您希望修改的内容。
## 📄 许可证
本项目专为 Barangay Gulod、Novaliches、Quezon City 开发。所有权利保留 © 2026 SafeChain。
标签：BLE, CartoDB Voyager, ESP32, Flutter, Fluttermoji, GPS定位, Keychain设备, LoRa, Mesh网络, Nordic UART Service, NUS, QR码扫描, 个人安全防护, 云端设备所有权, 会话持久化, 加63, 医疗状况管理, 地理位置权限, 坚固设计, 多选与其它, 头像生成, 实时追踪, 密码强度指示, 手机号格式, 找回密码, 数字安全钥匙, 热力图, 物联网, 电子邮箱验证, 电池状态, 社区保护网络, 社区安全, 移动应用, 紧急响应, 菲律宾本地化, 蓝牙低功耗, 设备丢失报告, 设备配对向导, 设备重命名, 资料编辑