docs: define forced update check

docs/packaging.md

@@ -107,15 +107,56 @@ release\
 
 正式发布构建固定使用 Python 3.10。源码在 Python 3.7.9 上曾验证可运行，但发布包不再以 3.7.9 作为打包基线；脚本会直接调用 `py -3.10` 并校验返回版本必须是 `3.10.x`，避免同一个 `APP_VERSION` 在不同 Python 版本下打出不可比对的包。CI 仍可继续使用 Python 3.11 做自动测试。
 
-### 3.4 暂不引入自动更新
+### 3.4 启动版本检查（T-544 第一版）
 
-本阶段不迁移 `cmbot` 的 `Launcher.exe`、`manifest.json`、SHA-256 下载校验、强制更新或在线更新机制。原因：
+T-544 第一版目标是**启动时检查是否必须升级**，但仍不做自动覆盖升级。
+
+客户端启动流程：
+
+1. `appconfig.prepare_data_dir()` 成功后、创建 `MainWindow` 前，请求服务器版本接口。
+2. 当前版本从 `app/version.py` 的 `APP_VERSION` 读取。
+3. 如果服务器明确返回“当前版本必须升级”，弹中文阻断框，不进入主界面。
+4. 弹窗只提供「下载新版」和「退出程序」。点击「下载新版」用系统浏览器打开下载地址；用户下载后按第六节手动覆盖程序文件。
+5. 网络失败、接口超时、JSON 非法或字段缺失时，第一版允许进入软件；只记录本地诊断日志或给低打扰提示，避免服务器故障导致所有用户不可用。
+
+建议版本接口返回结构：
+
+```json
+{
+  "latest_version": "0.1.1",
+  "min_supported_version": "0.1.1",
+  "force_update": true,
+  "download_url": "https://example.com/cmshopee-0.1.1-portable.zip",
+  "sha256": "optional-release-zip-sha256",
+  "message": "发现必须升级的新版本，请下载后覆盖当前程序文件，保留 data 目录。"
+}
+```
+
+客户端判定规则：
+
+- `APP_VERSION < min_supported_version`：必须升级。
+- `force_update=true` 且 `APP_VERSION < latest_version`：必须升级。
+- 只比较语义化数字段，不能用字符串字典序比较版本号。
+- `download_url` 为空时不能进入自动下载；弹窗提示联系管理员或查看发布地址。
+
+第一版明确不做：
+
+- 不自动下载并覆盖正在运行的 `cmshopee.exe`。
+- 不自动覆盖 `_internal\`。
+- 不删除、不覆盖、不合并 `data\`。
+- 不做 Launcher、后台替换、增量补丁、签名校验或失败回滚。
+
+原因：Windows 下运行中的 `cmshopee.exe` 和 PyInstaller onedir 依赖目录很容易出现文件占用、半覆盖失败、权限不足或杀毒拦截。第一版只做“强制提示 + 下载新版 + 用户手动覆盖”，和当前便携包更新方式一致。
+
+### 3.5 暂不引入自动覆盖升级
+
+本阶段不迁移 `cmbot` 的 `Launcher.exe`、`manifest.json`、SHA-256 下载校验、自动替换程序目录或增量补丁。原因：
 
 - 当前用户已验证“拷贝发布目录到无 Python 环境运行”的第一版交付路径。
 - `cmshopee` 刚完成 `data\` 数据隔离，先把手动发版和版本号一致性做稳。
 - 自动更新需要安装根可写、下载暂存、目录切换、回滚和安全校验，属于独立后续任务，不能混入当前打包版本号控制。
 
-后续如果要做在线更新，再另起任务，参考 `cmbot` 的 `Launcher.exe + app\ + manifest.json + sha256 + version.txt` 设计。
+后续如果要做真正自动覆盖升级，再另起任务，参考 `cmbot` 的 `Launcher.exe + app\ + manifest.json + sha256 + version.txt` 设计。
 
 ## 四、绝不打包的本地数据
 
@@ -173,7 +214,7 @@ cmshopee\
 
 ## 六、用户后续更新方式
 
-第一版不做自动更新。给用户发新版本时：
+第一版不做自动覆盖升级。给用户发新版本时，或 T-544 启动检查弹出“必须升级”时：
 
 1. 让用户先关闭 cmshopee。
 2. 建议用户备份当前整个程序文件夹。