470 lines
16 KiB
Markdown
470 lines
16 KiB
Markdown
# PX3 地图资源拷贝业务流程
|
||
|
||
## 1. 文档定位
|
||
|
||
| 项目 | 内容 |
|
||
| ---- | -------------------------- |
|
||
| 项目 | 重汽 PX3 地图数据管理 |
|
||
| 适用工程 | `YX_MainInterface_ZhongQi` |
|
||
| 适用平台 | Android 4.4 PX3 车机 |
|
||
| 当前阶段 | ZIP64 方案已编码，等待 PX3 真机联调 |
|
||
| 更新日期 | 2026-08-12 |
|
||
|
||
本文档描述当前有效的 ZIP 压缩包方案。旧的“U盘展开目录复制到Map”“Map展开目录复制到sdcard”方案已废弃，不再作为开发和验收依据。
|
||
|
||
## 2. 背景和目标
|
||
|
||
PX3 存在两代地图存储方案：
|
||
|
||
| 设备类型 | 硬件能力 | 地图方案 |
|
||
|---|---|---|
|
||
| 新 PX3 32G 设备 | 不再预留外置 TF 卡接口 | Map 分区保存地图 ZIP，首次使用时解压到内部共享存储 |
|
||
| 旧 PX3 设备 | 可以插入外置 TF 卡 | 保留原有 TF 卡导航流程 |
|
||
|
||
已确认所有无 TF 卡接口的新 PX3 设备均为 32G，当前代码以“PX3 + eMMC 32G”作为新流程开关。
|
||
|
||
本次改为 ZIP 的主要目标：
|
||
|
||
1. Map 分区只保存约 8.39GB 的压缩包，不再保存约 13.12GiB 的展开目录。
|
||
2. 地图初始化时只解压高德需要的地图和语音资源。
|
||
3. 不在 sdcard 创建完整临时地图副本。
|
||
4. 保留后台执行、进度恢复、取消重试和差异补齐能力。
|
||
5. 旧设备 TF 卡流程保持不变。
|
||
|
||
## 3. 固定路径和数据范围
|
||
|
||
### 3.1 路径表
|
||
|
||
| 用途 | 路径 |
|
||
|---|---|
|
||
| 旧设备 TF 卡地图 | `/mnt/external_sd0/amapauto9` |
|
||
| U盘挂载点 | `/mnt/usb_storage` |
|
||
| U盘地图压缩包 | `/mnt/usb_storage/amapauto9.zip` |
|
||
| Map地图根目录 | `/mnt/map/amapauto9` |
|
||
| Map地图压缩包 | `/mnt/map/amapauto9/amapauto9.zip` |
|
||
| Map导入临时文件 | `/mnt/map/amapauto9/amapauto9.zip.part` |
|
||
| 内部高德根目录 | `/mnt/sdcard/amapauto9` |
|
||
| 内部地图目录 | `/mnt/sdcard/amapauto9/data/navi/compile_v2/chn` |
|
||
| 内部语音目录 | `/mnt/sdcard/amapauto9/data/voice` |
|
||
| 解压中标记 | `/mnt/sdcard/amapauto9/.yaxon_map_copying` |
|
||
| 解压完成标记 | `/mnt/sdcard/amapauto9/.yaxon_map_complete` |
|
||
|
||
`/mnt/sdcard` 与 `/sdcard` 在当前设备上指向同一内部共享存储。本模块代码统一使用 `/mnt/sdcard`。
|
||
|
||
### 3.2 ZIP 内部结构
|
||
|
||
压缩包必须包含：
|
||
|
||
```text
|
||
amapauto9/data/navi/compile_v2/chn/...
|
||
amapauto9/data/voice/...
|
||
```
|
||
|
||
只解压以下两个白名单前缀：
|
||
|
||
```text
|
||
amapauto9/data/navi/compile_v2/chn/
|
||
amapauto9/data/voice/
|
||
```
|
||
|
||
解压时去掉首层 `amapauto9/`，最终写入：
|
||
|
||
```text
|
||
/mnt/sdcard/amapauto9/data/navi/compile_v2/chn
|
||
/mnt/sdcard/amapauto9/data/voice
|
||
```
|
||
|
||
本期不解压：
|
||
|
||
- `amapauto9/detail_list`
|
||
- `amapauto9/res/global.db`
|
||
- ZIP 中除 `chn` 和 `voice` 外的其他内容
|
||
|
||
### 3.3 当前压缩包基线
|
||
|
||
| 项目 | 数值 |
|
||
|---|---|
|
||
| ZIP文件大小 | `8,387,521,520 bytes`，约 `7.81GiB` |
|
||
| SHA-256 | `69B1448C2FB6BA981F14C7D4A0B5DCFF6F6A3130020DB1D52D47202D14BFF1CC` |
|
||
| ZIP总条目 | 2245 |
|
||
| 白名单文件 | 1866 |
|
||
| 白名单解压后大小 | `14,088,198,086 bytes`，约 `13.12GiB` |
|
||
| 最大单文件 | 约 121MB |
|
||
|
||
该文件中央目录使用 ZIP64，不能依赖 Android 4.4 自带 `java.util.zip.ZipFile`。代码使用 Apache Commons Compress 1.9 读取 ZIP64。
|
||
|
||
## 4. 新旧设备分流
|
||
|
||
```text
|
||
用户点击导航
|
||
-> 判断是否为 PX3 + eMMC 32G
|
||
|
|
||
+-- 否：保留历史TF卡流程
|
||
| -> /mnt/external_sd0/amapauto9存在：启动高德
|
||
| -> 不存在：提示插入含离线地图的TF卡
|
||
|
|
||
+-- 是：执行内部地图流程
|
||
-> 内部地图检查通过：启动高德
|
||
-> 检查不通过：进入地图初始化页面
|
||
-> Map压缩包存在：自动解压到sdcard
|
||
-> Map压缩包不存在：提示联系服务人员
|
||
```
|
||
|
||
32G新设备不检查TF卡，也不在Map异常时回退TF流程。
|
||
|
||
## 5. 两个页面入口
|
||
|
||
### 5.1 普通导航入口
|
||
|
||
页面标题：`地图初始化`。
|
||
|
||
页面只显示：
|
||
|
||
- 当前初始化提示
|
||
- 水平进度条
|
||
- 一位小数进度值
|
||
|
||
进入页面后自动执行“Map ZIP 解压到 sdcard”，不显示U盘、删除和路径等工程操作。成功后只提示初始化完成，不自动启动导航；用户再次点击导航后进入高德。
|
||
|
||
### 5.2 工程模式入口
|
||
|
||
入口：工程菜单 -> `地图数据管理`。
|
||
|
||
三个独立操作：
|
||
|
||
1. `删除Map分区地图`
|
||
2. `从U盘导入到Map分区`
|
||
3. `复制地图到sdcard目录`
|
||
|
||
推荐恢复顺序：
|
||
|
||
```text
|
||
删除Map分区地图
|
||
-> 从U盘导入到Map分区
|
||
-> 复制地图到sdcard目录
|
||
```
|
||
|
||
三个操作不会自动串联。
|
||
|
||
## 6. 地图状态判断
|
||
|
||
### 6.1 U盘地图状态
|
||
|
||
同时满足以下条件时认为U盘地图存在：
|
||
|
||
1. `/mnt/usb_storage` 状态为 `MEDIA_MOUNTED`。
|
||
2. `/mnt/usb_storage/amapauto9.zip` 是非空普通文件。
|
||
|
||
真正导入前还会读取 ZIP64 中央目录，确认地图、语音和核心文件存在。
|
||
|
||
### 6.2 Map源状态
|
||
|
||
`/mnt/map/amapauto9/amapauto9.zip` 是非空普通文件时，认为Map压缩包存在。
|
||
|
||
该快速状态只用于页面和入口判断。真正解压前仍会完整读取中央目录并执行白名单结构校验。
|
||
|
||
### 6.3 内部地图状态
|
||
|
||
快速检查顺序：
|
||
|
||
1. `.yaxon_map_copying` 存在时判定未完成。
|
||
2. `chn/a0/m1.ans` 必须是非空文件。
|
||
3. `chn` 至少有一个 `a+数字` 区域目录。
|
||
4. `voice` 至少有一个非空文件。
|
||
5. Map中存在ZIP时，`.yaxon_map_complete` 必须与当前ZIP的“文件大小 + 修改时间”一致。
|
||
6. Map中没有ZIP时，允许兼容升级前已经存在的内部地图。
|
||
|
||
完成标记用于识别“内部地图是否由当前Map ZIP解压完成”，不替代解压过程中的逐文件校验。
|
||
|
||
## 7. 工程操作一：删除Map分区地图
|
||
|
||
删除范围：
|
||
|
||
```text
|
||
清空 /mnt/map/amapauto9 内全部内容
|
||
保留 /mnt/map/amapauto9 根目录
|
||
```
|
||
|
||
流程：
|
||
|
||
```text
|
||
检查32G设备
|
||
-> 检查Map目录中是否有数据
|
||
-> 显示确认弹框
|
||
-> 检查根目录可写
|
||
-> 清空目录内容
|
||
-> 确认根目录存在且为空
|
||
```
|
||
|
||
不会删除 `/mnt/sdcard/amapauto9`。删除没有回滚能力，权限失败时可能留下部分数据。
|
||
|
||
## 8. 工程操作二：从U盘导入到Map分区
|
||
|
||
### 8.1 固定路径
|
||
|
||
```text
|
||
源：/mnt/usb_storage/amapauto9.zip
|
||
临时：/mnt/map/amapauto9/amapauto9.zip.part
|
||
正式：/mnt/map/amapauto9/amapauto9.zip
|
||
```
|
||
|
||
### 8.2 U盘要求
|
||
|
||
ZIP单文件约8.39GB，FAT32不支持超过4GB的单文件。内部工程U盘统一使用NTFS，`amapauto9.zip`固定放在U盘根目录。
|
||
|
||
当前固件存在 `ntfs-3g` 和 `mkntfs`，但仍必须用真实U盘验证能够自动挂载到 `/mnt/usb_storage`。
|
||
|
||
### 8.3 前置条件
|
||
|
||
1. 设备为PX3+32G。
|
||
2. U盘已挂载且根目录存在非空 `amapauto9.zip`。
|
||
3. `/mnt/map/amapauto9` 已由系统预先创建并可写。
|
||
4. Map目录中没有正式ZIP或旧展开地图数据。
|
||
5. Map可用空间不少于ZIP大小加300MiB安全余量。
|
||
6. ZIP中央目录能够读取，并包含 `chn`、`voice` 和 `chn/a0/m1.ans`。
|
||
|
||
当前真机Map分区约13.3G，旧地图仍占约8.0G时只剩5.3G，无法同时放入8.39GB ZIP，必须先执行删除操作。
|
||
|
||
### 8.4 执行流程
|
||
|
||
```text
|
||
校验U盘ZIP64结构
|
||
-> 清理上次残留的amapauto9.zip.part
|
||
-> 检查Map空间
|
||
-> 流式复制到amapauto9.zip.part
|
||
-> fsync
|
||
-> 校验源目标文件大小
|
||
-> 再次校验目标ZIP64结构
|
||
-> 同目录重命名为amapauto9.zip
|
||
```
|
||
|
||
`.part`是当前正在复制的同一份数据，完成后直接重命名，不会同时占用两份8.39GB空间。
|
||
|
||
取消、U盘拔出或复制失败时清理`.part`。正式ZIP只有在完整校验成功后才生成。
|
||
|
||
## 9. 工程操作三及普通初始化：Map解压到sdcard
|
||
|
||
### 9.1 解压计划
|
||
|
||
使用ZIP64中央目录生成白名单文件计划：
|
||
|
||
- 目标不存在：解压。
|
||
- 目标存在但大小不同：重新解压并覆盖。
|
||
- 目标存在且大小相同：跳过。
|
||
- 目标端白名单目录中的多余文件暂不删除。
|
||
|
||
计划同时统计：
|
||
|
||
- 地图、语音和核心文件是否齐全
|
||
- 本次需要解压的文件数和字节数
|
||
- 解压期间的峰值新增空间
|
||
- 跳过文件数
|
||
|
||
### 9.2 路径安全
|
||
|
||
只接受两个固定白名单前缀。每个条目的规范化目标路径必须仍位于对应的 `chn` 或 `voice` 目录内，拒绝反斜杠、`../`和重复目标路径，防止ZIP路径穿越覆盖其他系统或高德文件。
|
||
|
||
### 9.3 空间检查
|
||
|
||
允许解压的条件：
|
||
|
||
```text
|
||
sdcard可用空间 >= 解压过程峰值新增空间 + 300MiB
|
||
```
|
||
|
||
覆盖文件时不会直接写正式文件。当前单个文件先写同目录临时文件，校验后再替换，因此空间计算包含当前临时文件的峰值占用。
|
||
|
||
### 9.4 单文件处理
|
||
|
||
```text
|
||
从ZIP流式读取条目
|
||
-> 写入同目录“文件名.yaxon_part”
|
||
-> 更新真实解压字节进度
|
||
-> fsync
|
||
-> 校验解压后大小
|
||
-> 校验CRC32
|
||
-> 删除旧目标文件
|
||
-> 重命名临时文件为正式文件
|
||
```
|
||
|
||
最大临时文件约121MB，不创建完整13GB临时地图目录。
|
||
|
||
### 9.5 完整流程
|
||
|
||
```text
|
||
打开Map中的amapauto9.zip
|
||
-> 生成白名单差异计划
|
||
-> 清理计划内残留.yaxon_part
|
||
-> 检查空间 + 300MiB
|
||
-> 创建或复用/sdcard/amapauto9
|
||
-> 写入.yaxon_map_copying并fsync
|
||
-> 逐个解压变化文件
|
||
-> 校验全部白名单目标文件存在且大小一致
|
||
-> 写入.yaxon_map_complete并fsync
|
||
-> 删除.yaxon_map_copying
|
||
-> 返回成功
|
||
```
|
||
|
||
成功后Service仅在高德主进程已经运行时发送现有退出通知，让下次启动重新加载地图；高德未运行时不发送，不自动启动导航。
|
||
|
||
### 9.6 失败和恢复
|
||
|
||
- 不删除 `/mnt/sdcard/amapauto9` 根目录。
|
||
- 不创建完整地图临时副本。
|
||
- 已完成并校验的文件保留。
|
||
- 当前失败文件的`.yaxon_part`会尽量清理。
|
||
- `.yaxon_map_copying`在失败或中断后保留，导航判定未完成。
|
||
- 下次进入重新读取ZIP目录并生成差异计划，大小一致文件跳过。
|
||
- 全部成功后才更新完成标记和显示100%。
|
||
|
||
## 10. Service、进度和页面生命周期
|
||
|
||
- 三个地图操作统一由同进程 `MapDataCopyService` 持有。
|
||
- 同一时间只允许一个地图任务。
|
||
- Home后Activity解绑，Service继续执行。
|
||
- 重新进入页面恢复任务类型、累计字节和进度，不重新启动任务。
|
||
- 返回时可选择“后台运行”“停止任务”“继续等待”。
|
||
- Service为 `START_NOT_STICKY`，Launcher进程被杀或断电时任务终止，依靠标记和差异计划恢复。
|
||
- ZIP检查和计划生成阶段显示准备状态。
|
||
- U盘导入进度按压缩包复制字节计算。
|
||
- 内部初始化进度按本次实际解压字节计算。
|
||
- 进度回调最多每500ms一次，页面显示一位小数。
|
||
- 完整校验成功前最高显示99.9%，最终成功才显示100%。
|
||
|
||
## 11. 结果码和提示
|
||
|
||
| 结果码 | 典型原因 | 页面处理 |
|
||
|---|---|---|
|
||
| `SUCCESS` | 导入、解压及校验成功 | 显示成功提示 |
|
||
| `SOURCE_NOT_FOUND` | U盘ZIP或Map ZIP不存在 | 提示源数据不可用 |
|
||
| `TARGET_ALREADY_EXISTS` | Map目录已有正式数据 | 提示先删除Map数据 |
|
||
| `TARGET_PARENT_NOT_FOUND` | sdcard父目录不存在 | 提示目标准备失败 |
|
||
| `STORAGE_NOT_WRITABLE` | 目标不可写 | 提示检查存储或权限 |
|
||
| `NO_ENOUGH_SPACE` | 可用空间不足 | 提示空间不足 |
|
||
| `CREATE_TARGET_FAILED` | 目标目录无法创建 | 提示目标准备失败 |
|
||
| `INVALID_ARCHIVE` | ZIP64打不开、结构错误或缺少必要条目 | 提示压缩包无效或不完整 |
|
||
| `COPY_FAILED` | ZIP复制或解压读写异常 | 提示重新操作 |
|
||
| `VERIFY_FAILED` | 文件大小、CRC或完成标记异常 | 提示校验失败 |
|
||
| `DELETE_FAILED` | Map内容没有完全删除 | 提示删除失败 |
|
||
| `CANCELLED` | 用户停止任务 | 不显示失败弹框 |
|
||
|
||
普通导航入口仍将“Map ZIP缺失或不可访问”统一提示为：
|
||
|
||
```text
|
||
地图数据不可用，请联系服务人员
|
||
```
|
||
|
||
## 12. 权限前提
|
||
|
||
应用是平台签名system UID，但仍受Linux文件权限约束。最低要求：
|
||
|
||
1. `/mnt/map` 对system UID可读、可执行。
|
||
2. `/mnt/map/amapauto9` 对system UID可读、可写、可执行。
|
||
3. 权限在每次开机挂载完成后稳定生效。
|
||
4. `/mnt/sdcard/amapauto9`及其目标子目录可写。
|
||
|
||
历史真机曾出现重启后 `/mnt/map` 模式为`000`。该问题会导致ZIP被误判为不存在，仍是量产前P0验证项。临时验证命令：
|
||
|
||
```bash
|
||
adb shell chmod 0755 /mnt/map
|
||
```
|
||
|
||
永久方案应由底层在Map分区挂载完成后设置正确权限。
|
||
|
||
## 13. 已验证结论
|
||
|
||
### 13.1 已通过
|
||
|
||
- eMMC容量判断可将真机识别为32G。
|
||
- 新旧设备导航分流代码已保留。
|
||
- PC端真实ZIP64中央目录读取成功：2245个条目。
|
||
- 白名单识别成功：1866个文件，解压后`14,088,198,086 bytes`。
|
||
- ZIP中地图、语音和核心文件路径均存在。
|
||
- JDK 8执行Java编译成功。
|
||
- JDK 8执行Debug APK完整构建成功，新增库已通过重复类检查、DEX和打包。
|
||
|
||
### 13.2 尚未验证
|
||
|
||
- NTFS U盘能否在当前PX3固件自动挂载。
|
||
- PX3 Android 4.4运行时能否使用Commons Compress完整读取该ZIP64。
|
||
- 1866个文件的真机完整解压、CRC和耗时。
|
||
- U盘中途拔出、取消、杀进程和断电恢复。
|
||
- 解压时高德已经运行是否稳定。
|
||
- 重启后Map权限是否持续正确。
|
||
- 实际空间只剩边界余量时的处理。
|
||
|
||
## 14. 真机验收步骤
|
||
|
||
### 14.1 U盘和Map导入
|
||
|
||
1. 将U盘格式化为NTFS。
|
||
2. 将`amapauto9.zip`放在U盘根目录。
|
||
3. 插入PX3，确认`/mnt/usb_storage`状态为mounted。
|
||
4. 确认ZIP文件大小为`8,387,521,520`。
|
||
5. 先删除Map中的旧展开数据，确认Map剩余空间足够。
|
||
6. 执行“从U盘导入到Map分区”。
|
||
7. 确认正式ZIP生成且`.part`不存在。
|
||
8. 拔U盘、取消任务各验证一次，确认不会生成残缺正式ZIP。
|
||
|
||
建议检查命令：
|
||
|
||
```bash
|
||
adb shell "cat /proc/mounts | grep usb_storage"
|
||
adb shell "ls -l /mnt/usb_storage/amapauto9.zip"
|
||
adb shell "ls -l /mnt/map/amapauto9"
|
||
adb shell df
|
||
```
|
||
|
||
### 14.2 Map解压到sdcard
|
||
|
||
1. 清理内部`chn`和`voice`测试数据，不删除高德根目录其他数据。
|
||
2. 从导航入口进入，确认自动开始初始化。
|
||
3. 检查进度连续刷新且Home后任务继续。
|
||
4. 中途停止后重新进入，确认已完成文件被跳过。
|
||
5. 完成后确认`.yaxon_map_copying`消失、`.yaxon_map_complete`存在。
|
||
6. 抽查文件数量、大小和语音文件。
|
||
7. 再次点击导航，确认高德能加载离线地图和语音。
|
||
8. 分别验证高德未运行和已运行两种情况。
|
||
|
||
### 14.3 旧设备兼容
|
||
|
||
1. 带TF卡旧设备仍检查`/mnt/external_sd0/amapauto9`。
|
||
2. 有目录时启动高德。
|
||
3. 无目录时仍提示插入离线地图TF卡。
|
||
4. 不进入32G地图初始化页面。
|
||
|
||
## 15. 代码位置
|
||
|
||
以下路径均位于 `YX_MainInterface_ZhongQi/src/main/`：
|
||
|
||
| 职责 | 文件 |
|
||
|---|---|
|
||
| eMMC容量识别 | `java/com/yaxon/base/system/mapdata/EmmcSizeDetector.java` |
|
||
| PX3+32G策略 | `java/com/yaxon/base/system/mapdata/MapDataDevicePolicy.java` |
|
||
| ZIP校验、导入、白名单解压和删除 | `java/com/yaxon/base/system/mapdata/MapDataCopyManager.java` |
|
||
| 后台任务和高德重载 | `java/com/yaxon/base/system/mapdata/MapDataCopyService.java` |
|
||
| 页面状态和交互 | `java/com/yaxon/base/system/mapdata/MapDataCopyActivity.java` |
|
||
| 新旧导航分流 | `java/com/yaxon/until/ProgramLoader.java` |
|
||
| 页面文案 | `res/values/strings.xml` |
|
||
| ZIP64依赖 | `libs/commons-compress-1.9.jar` |
|
||
|
||
## 16. 当前优先级
|
||
|
||
| 优先级 | 工作项 | 完成标准 |
|
||
|---|---|---|
|
||
| P0 | PX3真机ZIP64只读验证 | 能打开ZIP、遍历2245个条目并读取末尾条目 |
|
||
| P0 | 修复/确认Map重启权限 | 连续重启后system UID均可读取和写入Map目录 |
|
||
| P1 | NTFS U盘挂载与8.39GB导入 | 自动挂载、完整复制、校验、重命名成功 |
|
||
| P1 | 13.12GiB完整解压 | 1866个文件完成大小和CRC校验，高德可加载 |
|
||
| P1 | 取消、拔盘、断电恢复 | 不产生残缺正式ZIP，可继续补齐内部地图 |
|
||
| P1 | 高德运行态验证 | 解压过程不损坏地图，完成后能重新加载 |
|
||
| P2 | 恢复工程模式10次点击门槛 | 功能验收完成后恢复正式入口限制 |
|
||
|
||
## 17. 本次更新记录
|
||
|
||
- 2026-08-12：按用户确认直接修改、不新增备份。
|
||
- 将U盘展开目录导入改为根目录单个`amapauto9.zip`导入。
|
||
- 将Map展开目录差异复制改为ZIP64白名单差异解压。
|
||
- 增加ZIP路径安全、单文件临时写入、大小和CRC校验、解压完成标记。
|
||
- 增加NTFS U盘约束、真实压缩包基线和真机验收矩阵。
|