# 监测数据不落地平台 · 安卓客户端

外业监测数据「不落地」采集与上传工具：现场用手机通过蓝牙连接振弦式读数仪（IE-1000）与综合采集仪（VM208），解析采集数据并直接上传至院方监测平台，配合离线队列保证弱网/断网可用。

> 本文件为 2026-09-03 重建版（基线文件曾随工作树清理丢失，按任务记录复刻）。

## 技术基线

| 项 | 选型 |
|---|---|
| 语言 / UI | Kotlin 2.0.21、View 体系 + Material 3 |
| 架构 | MVVM（ViewModel + StateFlow/LiveData） |
| 网络 | Retrofit 2.11 + OkHttp 4.12 + kotlinx.serialization 1.7.3 |
| 本地存储 | Room 2.6.1（离线优先队列）+ DataStore 1.1.1 + EncryptedSharedPreferences |
| 依赖注入 | Hilt 2.52 |
| 蓝牙 | Android 原生 BLE API；协议解析独立纯 Kotlin 模块 |
| 构建 | AGP 8.7.3 / Gradle 8.10.2 / JDK 17 / minSdk 26 / targetSdk 34 |

## 模块结构

```
app                 业务壳：导航、主题、权限、配置注入（M1–M6 页面挂载点）
core
 ├ common           AppResult / UiState / 日志门面（纯 Kotlin 优先）
 ├ network          鉴权三要素拦截器、ApiEnvelope 统一解析、Retrofit 装配
 ├ database         Room AppDatabase + 上传队列（离线优先参考实现）
 └ ble              BLE 扫描（按名称前缀过滤）、GATT 连接封装骨架
ble-protocol        纯 Kotlin JVM：IE-1000 / VM208 帧解析（零 Android 依赖，可独立单测）
```

依赖方向：`app → core:* + ble-protocol`；`core:{network,database,ble} → core:common`；`ble-protocol` 零依赖。

## 快速开始

1. Android Studio（Ladybug+，JDK 17）打开工程根目录，等待 Gradle Sync；
2. 服务器地址、SecretKey、SystemCode 通过 `app` 壳的配置仓储注入（见 `core:network` 的 `NetworkConfig`），**一律不写入代码库**；
3. 运行：`./gradlew :app:assembleDebug`；协议单测：`./gradlew :ble-protocol:test`。

## 配置说明

| 配置项 | 说明 | 注入点 |
|---|---|---|
| baseUrl | 平台接口地址（测试环境见接口文档 1.2.4） | ConfigRepository → NetworkConfig |
| SecretKey | 供应商调用密钥（会定期更换，必须可配置） | 同上 |
| SystemCode | 供应商编码（与 SecretKey 一一对应） | 同上 |
| Token | 登录后颁发，登录接口外必带 | TokenProvider（DataStore） |

## 文档索引

- `docs/安卓客户端功能明细表.md` —— 36 个功能点、模块映射、优先级、接口覆盖对照
- `docs/安卓客户端开发计划表.md` —— 6 阶段 12 周迭代计划、人日估算、里程碑、风险
- `docs/BLE-IE1000.txt` —— IE-1000 / VM208 蓝牙协议原始说明
- 接口规范 V4.5 —— 上海城建勘测院《监测数据不落地系统接口文档》（docs/ 下 docx）