feat(activity): 添加 Zip 文件下载解压工具和趣味页面

- 新增 ZipDownloadUtils：支持大文件下载、进度回调、断点续传 - 新增 ZipExtractUtils：支持 Zip 文件解压、进度回调、自动创建目录 - 新增 ModelResourceManager：高层资源管理器，协调下载和解压流程 - 新增 FunActivity：趣味测试页面，包含 3 个按钮 - 按钮 1：下载 Zip 文件 - 按钮 2：解压 Zip 文件 - 按钮 3：读取 JSON 并保存到 ObjectBox 数据库 - 新增 activity_fun.xml：趣味页面布局 - 新增 ZipToolsUsageExample：工具使用示例文档 - 改进 ToastUtils：改为 Context 扩展方法 (toast/toastLong) - 暂时注释 HomeActivity 中 tvTime 的点击事件
2026-03-13 11:27:53 +08:00
parent baee019444
commit c697b4aa65
13 changed files with 1211 additions and 58 deletions
@@ -0,0 +1,52 @@
+请按以下步骤为当前改动生成 Git 提交信息并执行提交：
+
+## 步骤
+
+1. 并行运行以下命令，了解当前改动：
+   - `git diff --staged` 查看已暂存的变更内容
+   - `git diff` 查看未暂存的变更内容
+   - `git status` 查看变更文件列表
+
+2. 若存在未暂存的文件，询问用户是否需要一起提交。
+
+3. 根据变更内容，按以下规范生成提交信息：
+
+   **格式：** `<类型>(<范围>): <简短描述>`
+
+   | 类型 | 适用场景 |
+   |------|---------|
+   | feat | 新增功能 |
+   | fix | 修复 bug |
+   | refactor | 代码重构（不改变行为） |
+   | chore | 构建/配置/依赖调整 |
+   | docs | 文档更新 |
+   | perf | 性能优化 |
+
+   **范围参考本项目模块：**
+   - `face` — 人脸识别相关（LoginByFaceActivity、RecognizeViewModel）
+   - `serial` — 串口/开柜相关（SerialApi、PlateUtils）
+   - `network` — 网络层（ApiService、RemoteRepository、RequestInterceptor）
+   - `activity` — Activity 界面逻辑
+   - `fragment` — Fragment 界面逻辑
+   - `viewmodel` — ViewModel 层
+   - `ui` — 布局/样式调整
+   - `global` — GlobalData、MyApp 等全局配置
+
+   **示例：**
+   - `feat(face): 新增识别失败后自动采集人脸流程`
+   - `fix(serial): 修复开柜编号解析为负数导致串口指令异常`
+   - `refactor(network): 统一 API 地址使用 GlobalData.appBaseUrl 前缀`
+
+4. 向用户展示拟提交的信息，确认后执行：
+   ```
+   git add <相关文件>
+   git commit -m "<提交信息>"
+   ```
+
+5. 提交完成后运行 `git log --oneline -3` 确认结果。
+
+## 约束
+
+- 提交信息必须使用**简体中文**描述
+- 不要使用 `--no-verify` 跳过钩子
+- 不要在未经用户确认的情况下执行 `git push`
@@ -0,0 +1,96 @@
+在本项目中新增一个后端 API 接口，需要同时修改三层：ApiService → RemoteRepository → ViewModel。
+
+## 步骤
+
+### 1. 收集信息
+询问用户以下信息（如已在指令中提供则跳过）：
+- 接口名称/功能描述
+- 请求方式：GET / POST / POST + FormUrlEncoded / Multipart
+- 接口路径（相对路径，如 `/sideboard/app/xxx`）
+- 请求参数字段和类型
+- 响应数据类型（已有类 or 需新建）
+- 归属哪个 ViewModel：`SettingViewModel` / `UserViewModel` / `DeviceViewModel`
+
+### 2. 创建数据模型（如需要）
+**请求参数类：** `app/src/main/java/com/sw/platecabinet/model/request/<XxxParam>.kt`
+**响应数据类：** `app/src/main/java/com/sw/platecabinet/model/response/<XxxModel>.kt`
+
+数据类规范：
+```kotlin
+/**
+ * <描述>
+ */
+data class XxxParam(
+    val fieldName: String  // 字段说明
+)
+```
+
+### 3. 在 ApiService 中添加接口方法
+文件：`app/src/main/java/com/sw/platecabinet/network/api/ApiService.kt`
+
+**关键规则：**
+- 必须使用 `@Url` 注解，URL 格式为：`"${GlobalData.appBaseUrl}/terminal/neglect/<路径>"`
+- 不要使用相对路径（baseUrl 拦截器不适用于本项目）
+- 方法必须为 `suspend` 函数，返回 `ApiResponse<T>`
+
+```kotlin
+/**
+ * <接口功能描述>
+ */
+@POST  // 或 @GET / @FormUrlEncoded @POST / @Multipart @POST
+suspend fun <methodName>(
+    @Url url: String = "${GlobalData.appBaseUrl}/terminal/neglect/<路径>",
+    @Body param: XxxParam  // 或 @Query / @Field / @Part
+): ApiResponse<XxxModel?>
+```
+
+### 4. 在 RemoteRepository 中添加调用方法
+文件：`app/src/main/java/com/sw/platecabinet/repository/RemoteRepository.kt`
+
+```kotlin
+/**
+ * <功能描述>
+ */
+suspend fun <methodName>(/* 参数 */): ApiResponse<XxxModel?> {
+    return safeApiCall {
+        apiService.<methodName>(/* 参数传递 */)
+    }
+}
+```
+
+约束：
+- 必须用 `safeApiCall { }` 包裹，不要裸调用 apiService
+- 参数直接透传，不在 Repository 层做业务逻辑
+
+### 5. 在 ViewModel 中添加调用逻辑
+文件：`app/src/main/java/com/sw/platecabinet/viewmodel/<XxxViewModel>.kt`
+
+```kotlin
+/**
+ * <功能描述>
+ * @param callback 成功时回调，参数为响应数据
+ */
+fun <methodName>(/* 业务参数 */, callback: (XxxModel?) -> Unit) {
+    launch {   // 不需要 loading 时用 launch；需要 loading 时用 launchWithLoading
+        val response = repository.<methodName>(/* 参数 */)
+        if (parseResponse(response)) {
+            runOnMainThread { callback(response.result) }
+        }
+    }
+}
+```
+
+**注意：** `launch` / `launchWithLoading` 在协程中执行，回调若需更新 UI 需切换到主线程（使用 `withContext(Dispatchers.Main)` 或在 Activity 中用 `runOnUiThread`）。
+
+### 6. 在 Activity/Fragment 中调用
+```kotlin
+viewModel.<methodName>(/* 参数 */) { result ->
+    // 处理结果
+}
+```
+
+## 注意事项
+- 所有注释使用简体中文
+- 向用户展示将要修改的文件清单（含 Diff 预览），等待确认后再写文件
+- `RequestInterceptor` 已自动注入认证 header，无需在方法中手动添加
+- 响应体统一为 `ApiResponse<T>`，通过 `response.isSuccess()` 和 `response.result` 取数据