# 水利智学鸿蒙 App 4.5.17 离线完整版 — 安装与使用说明

> 本版彻底解决两个老问题：**① HAP 仅 300KB、纯壳无内容；② 硬编码 IP 导致手机/平板/电脑"同 IP 看不到新网页"。**
> 新方案 = **本地优先（Local-First）**：App 自带全量离线数据包，断网也能用核心功能；联网时自动发现电脑学习服务器，一键切完整版。

---

## 一、这个版本改了什么

| 对比项 | 旧版（4.5.15/4.5.16） | 新版（4.5.17） |
|---|---|---|
| HAP 大小 | **322 KB**（纯 WebView 壳，无任何内容） | **38 MB**（内置 37.6MB 离线包） |
| 离线能力 | 无（依赖外网服务器，连不上就白屏） | **开箱离线**：启动即加载内置离线版，全功能可用 |
| 服务器地址 | 硬编码 `https://192.168.0.203:8443`（IP 一变就失效） | **动态发现**：WAN → 电脑局域网地址 → 网段扫描，IP 变了也能找到 |
| 断网表现 | 白屏/无法使用 | 完整离线核心功能照常运行 |
| 内置内容 | 无 | offline.html（2.8MB）+ 题库 **3161 题**、闪卡 1089、导图 285、笔记 44、教材/视频/讲义清单等 12 个数据 JSON |

**内置离线核心功能**：题库刷题 / 闪卡 / 笔记 / 错题本 / 模拟考试 / 历年真题 / 冲刺 / 记忆曲线 / 学习统计 / 思维导图 / 视频课程列表 / 讲义资料 / 设置。

**需要切换服务器才能用的完整功能**：视频在线播放、AI 答疑、多端实时进度同步（这些依赖电脑端算力和视频文件，离线包不内置大视频）。

---

## 二、安装方式（二选一）

### 方式 A：真机 USB 直装（最快，推荐先用这个验收）

1. 手机/平板开启 **开发者模式 → USB 调试**（设置 → 关于手机 → 连点版本号 7 次 → 开发者选项 → USB 调试），USB 线连接电脑；
2. 电脑上运行：
   ```
   "D:\Huawei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe" install -r "F:\水利智学系统\可运行版（解压即用，双击start.bat）\frontend\downloads\entry-default-4.5.17.hap"
   ```
3. 设备上出现"水利智学"图标（可能提示安装来源未知，允许即可）。

### 方式 B：AGC 邀请测试（正式发布通道，手机/平板不用连线）

1. 登录 AGC（AppGallery Connect）→ 你的应用 → **软件包管理** → 上传：
   `F:\水利智学系统\可运行版（解压即用，双击start.bat）\frontend\downloads\水利智学-4.5.17-发布.app`（8.6MB，已用华为 Release 证书签名，有效期至 2029-09-24）；
2. 创建**邀请测试版本**，添加测试账号（手机/平板登录同一华为账号）；
3. 设备上进入 **华为应用市场 → 我的 → 应用测试**（或收到的测试链接）下载安装。

---

## 三、安装后第一次打开

1. **App 启动 → 立即加载内置离线版**（无需联网、无需等服务器），顶部显示"本地离线模式"；
2. App 后台自动探测学习服务器（约 1~3 秒）：
   - 找到后顶部出现**绿色横幅**：`已发现学习服务器 192.168.1.31（约 8 ms）· 进入完整版（视频/AI/实时同步）` —— 点击横幅即切换到电脑完整版；
   - 找不到则保持离线模式，离线核心功能不受影响；
3. 电脑端需要保持 `start.bat` 运行（后端 8000 端口 + 8443 局域网 HTTPS 已自愈监控）。

**当前有效访问地址**（已实测）：
- 电脑本机：`http://localhost:8000`
- 局域网：`http://192.168.1.31:8000`（App 动态发现的就是这个网段）
- 统一入口（Tailscale，跨网可用）：`https://cherry.tail6f7c9a.ts.net`

---

## 四、版本与更新机制（已对齐）

- 后端版本接口实测：`app_version=4.5.17`、`build_ts=1790393827`（已刷新）、HAP 下载地址 `…/static/downloads/entry-default-4.5.17.hap`（SHA256 校验已配）；
- 旧版 App 会检测到版本更新提示（走应用市场升级流程）；**升级到 4.5.17 后 App 内不再弹更新**（自身已是 latest）；
- 电脑/手机浏览器访问 `http://localhost:8000` 或局域网地址，**标题已更新为 V4.5.17 模块化版**，资源版本戳已刷新，手机/平板刷新一次即为新页面。

---

## 五、验证状态与遗留事项

| 项目 | 状态 |
|---|---|
| HAP 构建（debug 38MB + release .app 8.6MB 签名验证） | ✅ 成功 |
| 离线包入包完整性（19 个文件，37.6MB） | ✅ 已解包核对 |
| 后端重启 / build_ts 刷新 / 版本接口 / HAP 下载链路 | ✅ 已实测 200 |
| 真机安装运行（18443 本地服务器、16.8MB 题库 JSON 分块加载、横幅切完整版） | ⏳ **待真机验收**（当前 hdc 无设备连接） |
| AGC 邀请测试发布 | ⏳ 需你在 AGC 上传 .app + 加测试账号 |

**如真机安装后发现问题**：把现象告诉我（例如"本地离线打不开/横幅没出现/切完整版失败"），我按日志定位修复后重打包。修改离线数据后重新打包：运行 `F:\HAP\shuili-hap\build-offline-bundle.ps1` → 按工程内构建命令重建 HAP → 替换 downloads 副本即可。
