chore(merge): Update documentation files and file index

- Update Android client architecture documentation - Update Android client feature specification - Update Android client development plan - Refresh file index metadata
2026-09-03 13:48:09 +08:00
parent ee8238020a
commit a976bf525a
4 changed files with 339 additions and 1 deletions
--- a/.heart/index/files-v1.json
+++ b/.heart/index/files-v1.json
--- a/docs/安卓客户端主框架架构说明.md
+++ b/docs/安卓客户端主框架架构说明.md
@@ -0,0 +1,138 @@
+# 安卓客户端主框架架构说明
+
+> S0 工程骨架交付（2026-09-03）。本文档说明主框架分层、模块职责、关键约定与业务挂载方法，是 S1–S4 功能开发的挂载依据。
+
+## 1. 架构总览
+
+```mermaid
+flowchart TD
+    APP[":app 业务壳<br/>导航 · 主题 · 权限 · 配置注入<br/>M1–M6 页面挂载点"]
+    subgraph CORE["core 基础层"]
+        NET[":core:network<br/>鉴权三要素 · 统一解析"]
+        DB[":core:database<br/>Room · 上传队列"]
+        BLE[":core:ble<br/>扫描 · GATT 封装"]
+        COMMON[":core:common<br/>AppResult · UiState · 日志"]
+    end
+    PROTO[":ble-protocol<br/>IE-1000 / VM208 帧解析<br/>纯 Kotlin JVM · 零依赖"]
+
+    APP --> NET
+    APP --> DB
+    APP --> BLE
+    APP --> PROTO
+    NET --> COMMON
+    DB --> COMMON
+    BLE --> COMMON
+    BLE -. "Notify 字节流" .-> PROTO
+```
+
+**依赖规则**（静态校验脚本强制核查）：
+
+| 规则 | 说明 |
+|---|---|
+| app → core:* + ble-protocol | 业务壳是唯一允许依赖全部模块的层 |
+| core:{network,database,ble} → core:common | core 模块横向互不依赖 |
+| ble-protocol 零依赖 | 纯 Kotlin JVM，无 Android / 第三方框架依赖 |
+| 业务代码禁止绕过 core 层 | S1+ feature 只允许经 core 能力访问网络/存储/蓝牙 |
+
+## 2. 模块职责与关键类
+
+| 模块 | 职责 | 关键类 |
+|---|---|---|
+| `:app` | 单 Activity 导航壳、5 Tab、权限、配置注入 | `SteCmdApplication` `MainActivity` `FeatureMount` `config/ConfigRepository` |
+| `:core:common` | 统一结果/视图状态/日志门面 | `AppResult` `UiState` `AppLog` |
+| `:core:network` | 平台 HTTP 框架：鉴权三要素 + 返回码统一解析 | `NetworkConfig` `TokenProvider` `AuthInterceptor` `ApiEnvelope` `ApiError` `NetworkModule` |
+| `:core:database` | Room 离线优先存储 + 上传队列参考实现 | `AppDatabase` `UploadQueueEntity` `UploadQueueDao` `DatabaseModule` |
+| `:core:ble` | BLE 扫描（名称前缀过滤）与 GATT 连接骨架 | `BleScanner` `BleConnector` `BleSession` `BleUuids` `DeviceType` |
+| `:ble-protocol` | 两类设备协议帧解析/编码（独立单测） | `Ie1000FrameParser` `Vm208FrameParser` `Vm208CommandEncoder` `Ie1000Reading` `Vm208Reading` |
+
+## 3. 关键约定
+
+### 3.1 鉴权三要素流（接口文档 1.2）
+
+```
+ConfigRepository(DataStore+内存快照, app 壳实现 NetworkConfig/TokenProvider)
+    └→ AuthInterceptor(core:network): 请求头注入 SecretKey / SystemCode / Token
+         · Token 为空跳过（登录/验证码接口天然不携带）
+         · 密钥值不进代码库（M7-04），运行期经 S1 配置页写入 DataStore
+```
+
+Hilt 绑定：`config/AppModule.kt` 中 `@Binds` 将 `ConfigRepository` 绑定为 `NetworkConfig` 与 `TokenProvider`，补全 `NetworkModule` 依赖图。
+
+### 3.2 返回码统一解析（接口文档 1.1）
+
+| code | 语义 | 异常类型 |
+|---|---|---|
+| "200" | 成功 | —（`ApiEnvelope.bodyOrThrow()` 返回 data） |
+| "500" | 业务失败 | `ApiError.ServerError` |
+| "429" | 一分钟内同条数据频繁请求超限 | `ApiError.TooManyRequests` |
+| "403" | 同条数据连续报错超限（平台锁定） | `ApiError.Locked` |
+| 传输层失败 | 超时/断网 | `ApiError.NetworkError` |
+
+code 为**字符串**类型；S1+ 业务层只捕获 `ApiError` 并按子类提示。
+
+### 3.3 协议解析流（BLE Notify → 上传队列）
+
+```
+BleSession.notifyBytes(ByteArray 流)
+    └→ Ie1000FrameParser / Vm208FrameParser.feed(bytes)   ← 内部缓冲，天然处理粘包/残包
+         └→ Ie1000Reading / Vm208Reading
+              └→ 组装上传 JSON → UploadQueueDao.enqueue()  ← 离线优先，网络可用后补传
+```
+
+- IE-1000：`'Y' + 4B float(压力,小端) + 'T' + 4B float(温度) + 0D0A`，12 字节定长；
+- VM208：`CC F原值 T原值 E原值 S质量 AA + 0D0A`，缩放 /10 /10 /100；
+- VM208 激励命令：`0F 0F 06 0A XX XX 0D 0A`（大端 16 位），`Vm208CommandEncoder`。
+- ⚠ VM208 服务 UUID 原文档仅 31 位十六进制，`BleUuids` 按末位补 0 占位，**S2 真机联调时用 nRF Connect 校准**。
+
+### 3.4 网络安全白名单
+
+`app/src/main/res/xml/network_security_config.xml`：默认全域禁明文；仅接口文档 1.2.4 测试 IP `106.15.183.20` 开放 cleartext（联调用，发布前如生产全 HTTPS 可移除该 domain-config）。
+
+## 4. 业务挂载指南（S1 挂载步骤）
+
+挂载机制：`FeatureMount.mounts` 注册表声明每个 Tab 的 Fragment 类；导航壳只认注册表，业务页替换注册项即可。
+
+以 S1 首页（M2 项目列表）为例：
+
+1. **建 Fragment**：`app/src/main/kotlin/com/stec/cmd/feature/home/HomeFragment.kt`，`@AndroidEntryPoint` + ViewBinding（或迁移至团队选定的 UI 方案）；
+2. **建 ViewModel**：`HomeViewModel`，注入 S1 新建的 Retrofit Service（声明在 core:network 或独立 feature 模块）；
+3. **换注册项**：`FeatureMount.mounts` 中 `Tab.HOME` 的 `fragmentClass` 从 `HomeFragment::class.java`（占位）改为业务 Fragment；
+4. **加接口**：Retrofit Service 方法返回 `ApiEnvelope<T>`，调用侧 `bodyOrThrow()` 拿业务数据、捕获 `ApiError`；
+5. **跑校验**：`./gradlew :app:assembleDebug`，并确认静态校验脚本（见 §6）通过（menu↔FeatureMount id 对应关系不受影响）。
+
+M1（我的）额外步骤：配置页 UI 读写 `ConfigRepository.updateConnection()/updateToken()`（M1-06）。
+
+## 5. 目录结构对照
+
+```
+SteCmdAndroid/
+├─ app/                      # 业务壳（本表 §2 :app）
+├─ core/
+│  ├─ common/                # AppResult / UiState / AppLog
+│  ├─ network/               # AuthInterceptor / ApiEnvelope / ApiError / NetworkModule
+│  ├─ database/              # AppDatabase / UploadQueue 实体与 DAO / DatabaseModule
+│  └─ ble/                   # BleScanner / BleConnector / BleSession / BleUuids / DeviceType
+├─ ble-protocol/             # 协议解析（src/main + src/test 冒烟单测）
+├─ gradle/
+│  └─ libs.versions.toml     # 版本目录：全工程唯一版本事实源
+├─ docs/                     # 规划文档、协议原文、本说明
+├─ settings.gradle.kts       # 6 模块注册
+└─ build.gradle.kts          # 根：插件版本声明（apply false）
+```
+
+## 6. 环境与验证
+
+| 场景 | 命令 / 操作 |
+|---|---|
+| 首次打开 | Android Studio（JDK 17）打开工程根目录，等待 Gradle Sync |
+| 编译 | `./gradlew :app:assembleDebug` |
+| 协议单测 | `./gradlew :ble-protocol:test` |
+| 静态校验（本机已通过 198 项） | `python3 /tmp/verify_core.py && python3 /tmp/verify_app.py`（脚本随会话生成） |
+| 真机联调 | 配置页写入三要素 + 测试地址后，先验证登录（M1-01） |
+
+## 7. 已知遗留（S1 前处理）
+
+1. Gradle Sync / 编译 / 单测**尚未在真实环境执行**（交付环境无 JDK/Android SDK）；
+2. VM208 服务 UUID 需真机校准（§3.3）；
+3. splash 与导航图标为几何占位，S6 发布前替换正式视觉；
+4. 密钥（SecretKey/SystemCode）首次运行需经配置页写入；协议文档附带密钥文件仅用于联调，不得入库。
--- a/docs/安卓客户端功能明细表.md
+++ b/docs/安卓客户端功能明细表.md
@@ -0,0 +1,133 @@
+# 安卓客户端功能明细表
+
+> 2026-09-03 重建版：原文档随工作树清理丢失，按任务记录与接口解析稿（V4.5）复刻。接口清单以解析稿为准（15 个在用 + 2 个废除子接口）。
+
+## 文档属性
+
+| 属性 | 值 |
+|---|---|
+| 项目 | 上海城建勘测院 · 监测数据不落地平台安卓客户端 |
+| 依据 | 接口管理规范 V4.5、BLE-IE1000/VM208 蓝牙协议说明 |
+| 优先级定义 | P0=应用可发布的最小闭环；P1=重要；P2=增强 |
+| 功能点合计 | 36（P0×23 / P1×11 / P2×2） |
+
+## 模块总览
+
+| 模块 | 名称 | 功能点数 | P0 | P1 | P2 |
+|---|---|---|---|---|---|
+| M1 | 我的（登录与配置） | 7 | 5 | 1 | 1 |
+| M2 | 首页（项目工作台） | 3 | 2 | 1 | 0 |
+| M3 | 任务管理 | 5 | 3 | 2 | 0 |
+| M4 | 采集·蓝牙 | 9 | 7 | 2 | 0 |
+| M5 | 采集·测点数据 | 4 | 0 | 3 | 1 |
+| M6 | 统计与数据上传 | 4 | 2 | 2 | 0 |
+| M7 | 基础工程层 | 4 | 4 | 0 | 0 |
+| 合计 | | 36 | 23 | 11 | 2 |
+
+## M1 我的（登录与配置）
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M1-01 | 账号密码登录 | 2.2.1 | P0 | 请求头带 SecretKey/SystemCode，成功取得 Token |
+| M1-02 | 获取短信验证码 | 2.2.2 | P0 | 手机号 +86 需转 %2B86 |
+| M1-03 | 验证码登录 | 2.2.3 | P0 | 国内手机号全匹配校验 |
+| M1-04 | 修改登录密码 | 2.3.1 | P1 | 登录态下操作 |
+| M1-05 | 当前用户信息展示 | 2.4 | P0 | 头像/姓名/角色等 |
+| M1-06 | 服务器与密钥配置管理 | 无（本地） | P0 | baseUrl/SecretKey/SystemCode/Token 持久化（DataStore+加密），M7-04 落地入口 |
+| M1-07 | 退出登录与 Token 清理 | 无（本地） | P2 | 清除本地 Token 与缓存 |
+
+## M2 首页（项目工作台）
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M2-01 | 当前用户项目列表 | 2.5.1.1 | P0 | 外业人员可参与多项目 |
+| M2-02 | 项目基本信息展示 | 2.5.1.1（data） | P0 | 项目名称/编号/状态 |
+| M2-03 | 项目切换 | 2.5.1.1（本地选中态） | P1 | 切换后任务/统计跟随刷新 |
+
+## M3 任务管理
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M3-01 | APP 端任务列表 | 2.6 | P0 | 外业人员当日/近期任务 |
+| M3-02 | 项目监测计划任务列表 | 2.7 | P0 | 按监测计划组织 |
+| M3-03 | 任务详情 | 2.6/2.7（data） | P0 | 测组、测点、计划周期等 |
+| M3-04 | 任务状态流转展示 | 2.6/2.7（data） | P1 | 未开始/进行中/已完成 |
+| M3-05 | 任务筛选与下拉刷新 | 2.6/2.7 | P1 | 按状态/时间过滤 |
+
+## M4 采集·蓝牙
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M4-01 | 蓝牙与定位权限申请 | 无（系统） | P0 | Android 12L 分版（BLUETOOTH_SCAN/CONNECT vs 旧版+定位） |
+| M4-02 | 设备扫描 | 无（BLE） | P0 | 按名称前缀过滤：IE-1000、VM208 |
+| M4-03 | 设备连接管理 | 无（BLE GATT） | P0 | 两设备各有服务/写/Notify UUID；连接状态流 |
+| M4-04 | IE-1000 数据接收解析 | 无（BLE Notify） | P0 | 帧 `'Y'+4B float+'T'+4B float+0D 0A`（压力/温度） |
+| M4-05 | VM208 数据接收解析 | 无（BLE Notify） | P0 | 帧 `CC F%05d T%03d E%05d S%c AA+0D 0A`；频率/10Hz、温度/10℃、电压/100V |
+| M4-06 | VM208 激励命令下发 | 无（BLE Write） | P0 | `0F 0F 06 0A XX XX 0D 0A`，XX XX 大端 16 位 |
+| M4-07 | 采集数据本地暂存 | 无（Room） | P0 | 先落本地队列，网络可用后上传（离线优先） |
+| M4-08 | 采集会话管理 | 无（本地） | P1 | 开始/停止采集、绑定任务与测点 |
+| M4-09 | 断连与异常处理 | 无（BLE） | P1 | 断连提示、自动重连策略 |
+
+## M5 采集·测点数据
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M5-01 | 测组监测点列表 | 2.9 | P1 | 按测组拉取监测点 |
+| M5-02 | 基准点获取 | 2.14 | P1 | 水平位移等计算的基准 |
+| M5-03 | 工点数据 | 2.15 | P1 | 工点/测项结构（目录页 2.15 笔误 ControlPoint，以正文为准） |
+| M5-04 | 手动录入/补录 | 2.13（配合） | P2 | 无法蓝牙采集时人工录入后走同一上传队列 |
+
+## M6 统计与数据上传
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M6-01 | 原始文件上传与解析 | 2.13 | P0 | 数据解析（原始文件上传），采集文件的兜底通道 |
+| M6-02 | 项目监测计划统计表 | 2.10 | P0 | 项目维度完成度 |
+| M6-03 | 测组统计表 | 2.11 | P1 | 指定监测计划的测组统计 |
+| M6-04 | 监测点统计表 | 2.12 | P1 | 测点维度历史数据 |
+
+## M7 基础工程层
+
+| 编号 | 功能点 | 对应 API | 优先级 | 说明 |
+|---|---|---|---|---|
+| M7-01 | 网络框架 | 全部 | P0 | 鉴权三要素拦截器 + 200/500/429/403 统一解析（core:network） |
+| M7-02 | 本地存储框架 | 无 | P0 | Room 队列 + 加密配置存储（core:database + DataStore） |
+| M7-03 | 协议解析独立模块 | 无 | P0 | 纯 Kotlin JVM，脱离真机可单测（ble-protocol） |
+| M7-04 | 密钥配置管理 | 无 | P0 | SecretKey/SystemCode 不进代码库，可随时更换（.gitignore + ConfigRepository） |
+
+## 第 3 节 待确认问题（8 项）
+
+| # | 问题 | 缺省处理 |
+|---|---|---|
+| 1 | SecretKey/SystemCode 的分发与更换流程 | 做成配置项，支持不换包更换 |
+| 2 | Token 有效期与刷新机制 | 无刷新接口，过期按 401/500 重新登录 |
+| 3 | 429/403 的解锁规则与窗口 | 按接口文档语义提示用户稍后重试 |
+| 4 | 任务状态是否允许 APP 端上报变更 | S0 只读展示，不上报 |
+| 5 | 2.13 原始文件上传的文件格式与大小限制 | 按采集仪原始文件直传 |
+| 6 | 监测值上传是否走 2.8（已废除）替代接口 | 以 2.13 + 待定接口为准，待院方确认 |
+| 7 | 蓝牙后台采集是否需要 | 默认前台采集 |
+| 8 | 多项目并行采集的合并口径 | 单项目单会话 |
+
+## 附录 A 接口覆盖对照
+
+| 章节 | 接口名称 | 状态 | 承载模块 |
+|---|---|---|---|
+| 2.2.1 | 账号密码登录 | 在用 | M1-01 |
+| 2.2.2 | 发送验证码 | 在用 | M1-02 |
+| 2.2.3 | 手机验证码登录 | 在用 | M1-03 |
+| 2.3.1 | 修改登录密码 | 在用 | M1-04 |
+| 2.4 | 获取当前用户信息 | 在用 | M1-05 |
+| 2.5.1.1 | 获取当前用户项目列表 | 在用 | M2-01/02/03 |
+| 2.6 | 获取 APP 端任务列表 | 在用 | M3-01/03/04/05 |
+| 2.7 | 获取项目监测计划任务列表 | 在用 | M3-02/03/04/05 |
+| 2.8.1 | 获取监测计划 | 废除 | 不实现 |
+| 2.8.2 | 上传本次监测值 | 废除 | 不实现（上传通道待院方确认，见待确认 #6） |
+| 2.9 | 获取测组包含的监测点列表 | 在用 | M5-01 |
+| 2.10 | 获取项目监测计划统计表 | 在用 | M6-02 |
+| 2.11 | 获取指定监测计划的测组统计表 | 在用 | M6-03 |
+| 2.12 | 监测点统计表 | 在用 | M6-04 |
+| 2.13 | 数据解析（原始文件上传） | 在用 | M6-01、M5-04 |
+| 2.14 | 获取基准点 | 在用 | M5-02 |
+| 2.15 | 获取工点数据 | 在用 | M5-03 |
+
+> 返回状态值约定（接口文档 1.1）：200 成功；500 失败；429 同一条数据一分钟内频繁请求超限；403 同一条数据连续报错超限。
--- a/docs/安卓客户端开发计划表.md
+++ b/docs/安卓客户端开发计划表.md
@@ -0,0 +1,67 @@
+# 安卓客户端开发计划表
+
+> 2026-09-03 重建版：原文档随工作树清理丢失，按任务记录复刻。工作量与阶段划分保持原口径。
+
+## 技术基线
+
+| 项 | 选型 |
+|---|---|
+| 语言 | Kotlin 2.0.21 |
+| 架构 | MVVM + Hilt 2.52 + Coroutines 1.9.0 |
+| 网络 | Retrofit 2.11.0 + OkHttp 4.12.0 + kotlinx.serialization 1.7.3 |
+| 本地存储 | Room 2.6.1（离线优先）+ DataStore 1.1.1 + EncryptedSharedPreferences |
+| 蓝牙 | Android 原生 BLE；协议解析器独立为纯 Kotlin JVM 模块（ble-protocol） |
+| 构建 | AGP 8.7.3 / Gradle 8.10.2 / JDK 17 / minSdk 26 / targetSdk 34 |
+| 测试环境 | https://jcd.stec.p-q.co（白名单，见 network_security_config） |
+
+## 阶段与迭代计划（6 阶段，12 周）
+
+| 阶段 | 内容 | 工作量 | 周期 | 依赖 |
+|---|---|---|---|---|
+| S0 工程骨架 | Gradle 多模块、core 基础层、ble-protocol、app 壳（导航/主题/权限/配置） | 4 人日 | 0.5 周 | — |
+| S1 登录与首页 | M1 全部 + M2 + M7 配置注入 + 修改密码 | 22 人日 | 2 周 | S0 |
+| S2 任务与采集框架 | M3 全部 + M4 骨架（权限/扫描/连接） | 24 人日 | 2 周 | S1 |
+| S3 蓝牙采集深化 | M4 解析/下发/暂存/会话 + M5 测点数据 | 28 人日 | 3 周 | S2 |
+| S4 统计与上传 | M6 全部 + 离线队列上传调度 | 12 人日 | 2 周 | S3 |
+| S5 联调与测试 | 接口联调、真机回归、性能与弱网测试 | 20 人日 | 2 周 | S4 |
+| S6 发布准备 | 签名、混淆、应用商店/院内分发、文档 | 4 人日 | 0.5 周 | S5 |
+
+- 迭代工作量合计：4+22+24+28+12+4 = **94 人日**（其中开发 86 + S0/S6 管理 8）
+- 测试 20 人日（S5）+ 管理发布 8 人日 → **总计约 114 人日**
+
+## 模块 × 工作量矩阵（开发 86 人日）
+
+| 模块 | M1 我的 | M2 首页 | M3 任务 | M4 采集·蓝牙 | M5 测点 | M6 统计 | M7 基础层 | 合计 |
+|---|---|---|---|---|---|---|---|---|
+| 人日 | 12 | 6 | 10 | 28 | 12 | 8 | 10 | 86 |
+
+## 里程碑（MS1–MS6）
+
+| 里程碑 | 时点 | 验收标准 |
+|---|---|---|
+| MS1 工程可构建 | S0 末（第 0.5 周） | Android Studio 打开即 Sync，:app:assembleDebug 通过，协议单测绿 |
+| MS2 登录闭环 | S1 末（第 2.5 周） | 三种登录方式 + Token 管理 + 项目列表可用 |
+| MS3 任务可用 | S2 末（第 4.5 周） | 任务列表/详情完整，BLE 扫描连接真机通过 |
+| MS4 采集闭环 | S3 末（第 7.5 周） | 真机采集→解析→本地暂存全链路跑通 |
+| MS5 数据闭环 | S4 末（第 9.5 周） | 采集数据上传成功，弱网队列补传可用 |
+| MS6 发布 | S6 末（第 12 周） | 签名包通过验收测试，交付文档齐全 |
+
+## 风险与应对（8 项）
+
+| # | 风险 | 应对 |
+|---|---|---|
+| 1 | SecretKey/SystemCode 更换频繁 | 全配置化，支持不换包更换（M7-04） |
+| 2 | 429/403 限流误伤外业作业 | 队列退避重试 + 明确用户提示 |
+| 3 | BLE 各厂商兼容性差异 | 主流机型真机矩阵测试；协议层独立单测降低解析回归成本 |
+| 4 | 弱网/断网场景数据丢失 | Room 离线队列先落盘，网络恢复自动补传 |
+| 5 | 接口变更（V4.5 之后） | kotlinx.serialization 显式注解，字段演进留默认值 |
+| 6 | 2.8 废除后的上传通道未定 | 预留 UploadQueue 抽象，通道可替换 |
+| 7 | 真机依赖与外业时间窗 | S0–S2 期间提前申请设备与测试账号 |
+| 8 | 人员并行度 | M4（28 人日）为关键路径，S3 阶段优先投入 |
+
+## 交付物清单
+
+- 可发布 APK（签名、混淆配置齐备）
+- 源码工程（本仓库）+ 架构说明文档
+- 测试报告（S5 产出）
+- 《安卓客户端功能明细表》（接口覆盖对照）