App 离线数据与缓存清理规则

本文档说明 DMsysGApp（移动端）「个人中心 → 离线数据与缓存清理」功能的一键清理范围、保留策略、存储路径与实现对照，供测试、运维与二次开发参考。登录页离线访客、用户协议与首次在线认证规则见 App离线登录与用户协议设计.md。

实现入口：

一、功能概述

现场运维 App 在无网或弱网环境下会缓存图包、技术资料及查看器临时文件。用户可在个人中心查看各类缓存占用，并通过 「一键清理全部离线缓存」 释放存储空间。

清理前会弹出 确认对话框；清理完成后 Toast 提示 实际释放的字节数，并返回个人中心。AI 对话会清空历史，并自动创建一条系统提示的新会话。

二、清理范围（会删除或重置）

2.1 已下载图包缓存

适用状态： 图包 downloadStatus 为 DOWNLOADED 或 DOWNLOADING。

文件操作：

• 删除图包目录下所有以 cloud_ 开头的缓存文件。
• 目录：{filesDir}/blueprint_packs/{packId}/

数据库操作：

• 各图页 imageUrl 若已指向本地路径，恢复为服务端远程路径（BlueprintDrawingCache.canonicalRemotePath）。
• 图包状态重置为 NOT_DOWNLOADED（未下载）。

说明： 仅清理云端同步后落盘的缓存文件，不删除图包元数据记录；用户可重新在「图纸中心」下载。

2.2 已缓存技术资料

判定条件： 资料目录 documents/{docId}/ 下存在有效本地文件，且满足以下任一情况：

• filePath 为远程 URL（/api/doc-files/、/files/、http(s)://）；或
• filePath 为指向该资料目录的本地绝对路径。

文件操作：

• 递归删除 documents/{docId}/ 目录。

数据库操作：

• filePath 恢复为 DocumentPathResolver.canonicalRemotePath 定义的远程鉴权路径。

说明： 清理的是「已拉取到本机的副本」，资料树节点与收藏状态保留；有网时可重新打开并自动缓存。

2.3 图纸查看器临时缓存

清空以下 WebView 查看器为 DXF / STEP / GLB 准备的内部副本目录（删除后自动重建空目录）：

2.4 应用临时缓存

• 清空 Android context.cacheDir 下全部内容。
• 典型包括：AI 对话拍照/选图产生的临时 JPEG（chat_capture_*.jpg）等。

2.5 AI 对话历史

数据库操作：

• 删除 ai_chat_sessions 表全部会话（关联 chat_messages 级联删除）。

• 新建标题为「新对话」的会话，并插入一条模型角色提示消息：

  已经一键清理所有离线数据与缓存，系统已经重置为干净出厂状态。

三、保留范围（不删除）

以下数据 不在 一键清理范围内：

四、占用统计规则

进入「离线数据与缓存」页面时，调用 OfflineCacheCleaner.scan() 实时扫描，展示四大类占用及合计：

额外展示：AI 对话会话数量（仅计数，会话内容不计入文件占用）。

释放空间 = 清理前 totalBytes − 清理后 totalBytes（不小于 0）。

五、用户操作流程

1. 打开 App 底部 「我的」 Tab（顶部标题为 「个人中心」）。
2. 点击 「离线数据与缓存清理」。
3. 查看占用概览（加载中显示进度指示）。
4. 点击 「一键清理全部离线缓存」。
5. 在确认对话框中阅读说明，点击 「确认清理」 或 「取消」。
6. 清理完成后：
   • Toast：清理完成，已释放 {大小}
   • 自动返回个人中心
   • 占用概览可再次进入页面刷新查看

六、存储路径速查

根路径均为应用私有目录 context.filesDir（一般为 /data/data/{包名}/files/）。

files/
├── blueprint_packs/{packId}/
│   ├── cloud_{drawingId}_{name}.{ext}   ← 云端图页缓存（可清理）
│   └── {用户文件名}.dxf / .pdf / …      ← LOCAL 自建图包导入原件（保留，非 cloud_ 前缀）
├── documents/{docId}/                   ← 技术资料本地副本（可清理）
├── dxf_web/                             ← DXF 查看器缓存（可清理）
├── cad3d_web/                           ← STEP 查看器缓存（可清理）
├── cad3d_glb_web/                       ← GLB 预览缓存（可清理）
├── dxf_markup/                          ← 图页标注（保留）
└── avatars/                             ← 用户头像（保留）

cache/                                   ← 应用临时缓存（可清理）

七、与图包「单独删除/清理」的区别

在 图纸中心 对单个图包执行删除/清理时（MainViewModel.removeBlueprintPackInternal）：

• 自建图包（LOCAL）： 整包删除（含数据库记录与目录）。
• 已缓存图包（DOWNLOADED）： 仅将状态改为未下载（历史实现可能未删磁盘 cloud_* 文件，与一键清理逻辑独立）。

一键离线清理 针对所有已下载/下载中的云端图包批量执行缓存文件删除与路径回滚，且 不会删除自建图包。

八、测试检查清单

九、相关代码索引

延伸阅读： 自建图包打开、联网同步与云端缓存的完整设计见 App图纸中心本地与云端图页设计.md。

文档版本与 App 实现同步；若清理逻辑变更，请同步更新本文档与 OfflineCacheCleaner.kt。