admin/Obsidian

0 Fork 0

Files

T

admin 669f49b1d6 first commit

2026-11-05 14:35:04 +08:00

16 KiB

Raw Blame History

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 的主要目标：

Map 分区只保存约 8.39GB 的压缩包，不再保存约 13.12GiB 的展开目录。
地图初始化时只解压高德需要的地图和语音资源。
不在 sdcard 创建完整临时地图副本。
保留后台执行、进度恢复、取消重试和差异补齐能力。
旧设备 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 内部结构

压缩包必须包含：

amapauto9/data/navi/compile_v2/chn/...
amapauto9/data/voice/...

只解压以下两个白名单前缀：

amapauto9/data/navi/compile_v2/chn/
amapauto9/data/voice/

解压时去掉首层 amapauto9/，最终写入：

/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. 新旧设备分流

用户点击导航
  -> 判断是否为 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 工程模式入口

入口：工程菜单 -> 地图数据管理。

三个独立操作：

删除Map分区地图
从U盘导入到Map分区
复制地图到sdcard目录

推荐恢复顺序：

删除Map分区地图
  -> 从U盘导入到Map分区
  -> 复制地图到sdcard目录

三个操作不会自动串联。

6. 地图状态判断

6.1 U盘地图状态

同时满足以下条件时认为U盘地图存在：

/mnt/usb_storage 状态为 MEDIA_MOUNTED。
/mnt/usb_storage/amapauto9.zip 是非空普通文件。

真正导入前还会读取 ZIP64 中央目录，确认地图、语音和核心文件存在。

6.2 Map源状态

/mnt/map/amapauto9/amapauto9.zip 是非空普通文件时，认为Map压缩包存在。

该快速状态只用于页面和入口判断。真正解压前仍会完整读取中央目录并执行白名单结构校验。

6.3 内部地图状态

快速检查顺序：

.yaxon_map_copying 存在时判定未完成。
chn/a0/m1.ans 必须是非空文件。
chn 至少有一个 a+数字 区域目录。
voice 至少有一个非空文件。
Map中存在ZIP时，.yaxon_map_complete 必须与当前ZIP的“文件大小 + 修改时间”一致。
Map中没有ZIP时，允许兼容升级前已经存在的内部地图。

完成标记用于识别“内部地图是否由当前Map ZIP解压完成”，不替代解压过程中的逐文件校验。

7. 工程操作一：删除Map分区地图

删除范围：

清空 /mnt/map/amapauto9 内全部内容
保留 /mnt/map/amapauto9 根目录

流程：

检查32G设备
  -> 检查Map目录中是否有数据
  -> 显示确认弹框
  -> 检查根目录可写
  -> 清空目录内容
  -> 确认根目录存在且为空

不会删除 /mnt/sdcard/amapauto9。删除没有回滚能力，权限失败时可能留下部分数据。

8. 工程操作二：从U盘导入到Map分区

8.1 固定路径

源：/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 前置条件

设备为PX3+32G。
U盘已挂载且根目录存在非空 amapauto9.zip。
/mnt/map/amapauto9 已由系统预先创建并可写。
Map目录中没有正式ZIP或旧展开地图数据。
Map可用空间不少于ZIP大小加300MiB安全余量。
ZIP中央目录能够读取，并包含 chn、voice 和 chn/a0/m1.ans。

当前真机Map分区约13.3G，旧地图仍占约8.0G时只剩5.3G，无法同时放入8.39GB ZIP，必须先执行删除操作。

8.4 执行流程

校验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 空间检查

允许解压的条件：

sdcard可用空间 >= 解压过程峰值新增空间 + 300MiB

覆盖文件时不会直接写正式文件。当前单个文件先写同目录临时文件，校验后再替换，因此空间计算包含当前临时文件的峰值占用。

9.4 单文件处理

从ZIP流式读取条目
  -> 写入同目录“文件名.yaxon_part”
  -> 更新真实解压字节进度
  -> fsync
  -> 校验解压后大小
  -> 校验CRC32
  -> 删除旧目标文件
  -> 重命名临时文件为正式文件

最大临时文件约121MB，不创建完整13GB临时地图目录。

9.5 完整流程

打开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缺失或不可访问”统一提示为：

地图数据不可用，请联系服务人员

12. 权限前提

应用是平台签名system UID，但仍受Linux文件权限约束。最低要求：

/mnt/map 对system UID可读、可执行。
/mnt/map/amapauto9 对system UID可读、可写、可执行。
权限在每次开机挂载完成后稳定生效。
/mnt/sdcard/amapauto9及其目标子目录可写。

历史真机曾出现重启后 /mnt/map 模式为000。该问题会导致ZIP被误判为不存在，仍是量产前P0验证项。临时验证命令：

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导入

将U盘格式化为NTFS。
将amapauto9.zip放在U盘根目录。
插入PX3，确认/mnt/usb_storage状态为mounted。
确认ZIP文件大小为8,387,521,520。
先删除Map中的旧展开数据，确认Map剩余空间足够。
执行“从U盘导入到Map分区”。
确认正式ZIP生成且.part不存在。
拔U盘、取消任务各验证一次，确认不会生成残缺正式ZIP。

建议检查命令：

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

清理内部chn和voice测试数据，不删除高德根目录其他数据。
从导航入口进入，确认自动开始初始化。
检查进度连续刷新且Home后任务继续。
中途停止后重新进入，确认已完成文件被跳过。
完成后确认.yaxon_map_copying消失、.yaxon_map_complete存在。
抽查文件数量、大小和语音文件。
再次点击导航，确认高德能加载离线地图和语音。
分别验证高德未运行和已运行两种情况。

14.3 旧设备兼容

带TF卡旧设备仍检查/mnt/external_sd0/amapauto9。
有目录时启动高德。
无目录时仍提示插入离线地图TF卡。
不进入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盘约束、真实压缩包基线和真机验收矩阵。

16 KiB Raw Blame History Unescape Escape