docs: define forced update check

docs/06-tasks.md

@@ -149,6 +149,7 @@
 | T-539 | ⑤ 隐藏数据路径设置（设置简化，非防逆向） | T-538, T-517 | 背景：T-538 后用户数据固定收进 exe 同级 `data/`，⑤「路径与端口」里的 DB 路径（`dbPathEdit`）、图片目录（`imageDirEdit`）、账号数据根目录（`userDataRootEdit`）已不该由用户改动——改了会指向 `data/` 之外导致数据分裂/丢失。**定性说明**：本任务是**设置简化**，与 T-517/T-529 隐藏 `test_item_id`/`dry_run` 同一思路；**不是防逆向手段**——`cmshopee.db` 在磁盘上任何 SQLite 浏览器可直接打开，隐藏 UI 字段对逆向无意义，防逆向由另行任务（发布包加固/价值上移 cmhub）承担。方案：① ⑤普通设置页**隐藏** `db_path`/`image_dir`/账号数据根三个输入框（不再占表单位置），`config.json` 对应字段保留为内部兼容——手工编辑配置仍生效（内部回滚路径），加载/保存不丢字段；② **保留可见**：Chrome 路径（每台机器安装位置不同，真实配置需求）与默认端口/端口区间/CDP 就绪超时（端口冲突需可调）；③ 首次运行/迁移后各路径默认解析到 `data/` 下（沿用 T-538 的 `data_dir` 规则），无需用户感知。同步 `docs/routes.md` ⑤ 说明与 GUI 设置单测（隐藏字段不再可见、config 字段仍读写、手工配置值仍被尊重）。边界：只改⑤设置页展示层与文档；不改 `config.json` schema、路径解析逻辑（T-538 范围）、DB、业务流程、CDP/Shopee | DONE |
 | T-540 | 打包版本号与 release 产物命名统一 | T-537, T-538, T-524 | 参考 `D:\chengma\cmbot` 的轻量版本控制方式，但本阶段不引入 Launcher/manifest/自动更新。方案：① 新增 `app/version.py`，统一维护 `APP_NAME="蝦皮圈優化助手"`、`APP_CODE_NAME="cmshopee"`、`APP_VERSION`，作为 GUI 标题、打包脚本、release 目录、zip 文件名和 `version.txt` 的唯一版本源；② 主窗口标题改为 `蝦皮圈優化助手 v<APP_VERSION>`，PySide6 缺失提示继续读中文品牌名；③ `scripts/build_exe.ps1` 从 `app/version.py` 读取版本，并固定通过 Windows Python Launcher 调用 `py -3.10`，返回版本必须是 `3.10.x`；④ PyInstaller 仍输出 `dist\cmshopee\` 作为中间产物，再组装 `release\cmshopee-<APP_VERSION>\` 和 `release\cmshopee-<APP_VERSION>-portable.zip`，发布目录内写 `version.txt`（无 BOM）和中文 `README.txt`；⑤ 发布目录/zip 仍不得包含 `data/`、DB、配置、图片、日志、Chrome 登录态或运营 Excel；当前 PyInstaller 6.11.1 onedir 结构必须包含 `cmshopee.exe` + `_internal\`，脚本会校验 `_internal\` 存在；⑥ 测试覆盖版本文件解析、窗口标题版本、构建脚本 release 命名/排除数据/固定 `py -3.10` 打包。边界：只做手动发版版本号一致性和 release 组装；不做在线更新、启动器、manifest、sha256 下载校验、强制更新或自动替换程序目录 | DONE |
 | T-543 | 状态栏语义色与统一提示入口 | T-511, T-523, T-536 | 需求：当前左下角状态栏提示几乎都通过 `statusBar().showMessage(...)` 直接写入，颜色一致，用户很难快速区分“已保存/已完成”“正在处理”“没有可生成任务”“未登录/数据目录不可写”等不同严重程度。方案：① 在 `MainWindow` 增加统一入口 `show_status(message, level="muted")`，使用 `docs/ui-color-design.md` 已定语义色板映射 `muted/info/success/warning/danger`，内部先设置状态栏文字颜色再 `showMessage()`，普通/就绪提示必须重置为 muted 或默认色，避免上一条红/绿状态残留；② 逐步替换主窗口和 ①②③④⑤ Tab 传入的 `status_callback=self.statusBar().showMessage` 以及直接调用，新增代码必须显式传 level，不长期依赖中文关键词猜测；③ 颜色口径：普通/导航/就绪用 muted 或默认，进行中用 info，保存/完成/回写成功用 success，当前筛选无任务、请先采集/配置等用户可处理问题用 warning，失败、阻断、未登录、数据目录不可写、点数不足等中止当前动作的问题用 danger；④ 状态栏只改文字色，不做大面积背景，不替代弹窗、空状态、按钮禁用、运行日志或任务状态列；⑤ 复用 `app/gui/widgets.py` 语义色常量，不新增第二套颜色；⑥ GUI 单测覆盖 `show_status()` 各等级颜色、普通提示会清掉前一条错误颜色，以及至少一个保存成功/无任务/失败路径调用正确等级。边界：只改 GUI 提示层和测试；不改业务流程、DB schema、AI HTTP、Excel、Shopee/CDP、运行日志持久化 | DONE |
+| T-544 | 启动时检查强制升级（第一版：提示下载，不自动覆盖） | T-540, T-538, T-524 | 需求：程序启动后先请求服务器版本接口；如果线上版本高于当前程序版本且服务端要求强制升级，则必须弹窗阻断进入主界面，用户只能下载新版或退出。第一版方案：① 新增 `app/update_check.py`，读取当前版本 `APP_VERSION`，请求固定版本接口（后续可放配置/构建常量），超时短且错误中文化；② 服务端返回建议结构：`latest_version`、`min_supported_version`、`force_update`、`download_url`、`sha256`、`message`。比较规则：当前版本 `< min_supported_version` 必须升级；或 `force_update=true` 且当前版本 `< latest_version` 必须升级；版本比较使用语义化数字段比较，不用字符串字典序；③ 启动流程在 `appconfig.prepare_data_dir()` 成功后、创建 `MainWindow` 前执行版本检查；命中强制升级时弹中文阻断框，显示当前版本/线上版本/升级说明，按钮只保留「下载新版」和「退出程序」，点击下载用系统浏览器打开 `download_url` 后退出或保持阻断，不允许继续进入主界面；④ 网络失败、接口超时、JSON 非法、版本字段缺失时第一版**允许进入软件**，只在本地诊断日志记录/可选状态提示，不因服务器或用户断网导致全员不可用；只有服务端明确返回强制升级才阻断；⑤ 第一版**不自动下载并覆盖** `cmshopee.exe` 或 `_internal/`，不删除/覆盖 `data/`，不做 Launcher、后台替换、增量补丁、签名校验或回滚；用户仍按打包文档手动下载 zip、关闭程序、覆盖程序文件和 `_internal/`、保留 `data/`；⑥ 单测覆盖版本比较、强制升级判定、网络失败允许进入、非法响应允许进入、启动流程强制阻断弹窗和打开下载链接。边界：只做启动检查与强制提示，不改 DB schema、业务流程、AI、Excel、Shopee/CDP，不自动替换任何本地文件 | TODO |
 
 ## 里程碑
 

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. 建议用户备份当前整个程序文件夹。

progress.md

@@ -1405,3 +1405,11 @@
 - 测试：`tests/test_gui.py` 新增状态栏语义色、颜色重置、保存成功/无任务/失败路径等级覆盖。
 - 验证：`python -m unittest discover -s tests -p test_gui.py` 通过（99 tests）；`python -m ruff check app tests main.py` 通过；`python -m compileall app main.py` 通过；`python -m unittest discover -s tests` 通过（223 tests）。
 - 边界：只改 GUI 状态栏提示层和测试；未改业务流程、DB schema、AI HTTP、Excel、Shopee/CDP 或运行日志持久化。
+
+## 【2026-07-07】T-544 文档 · 启动时检查强制升级
+
+- 需求：启动程序后先请求服务器版本接口；如果线上版本高于当前程序版本且服务端要求强制升级，必须弹窗阻断进入主界面，要求用户升级。
+- 文档：`docs/06-tasks.md` 新增 T-544；`docs/packaging.md` 新增启动版本检查第一版方案、接口结构、版本比较规则、网络失败策略和手动覆盖更新流程；`docs/current-state.md` 将下一步任务更新为 T-544。
+- 第一版方案：只做“启动检查 + 强制弹窗 + 下载新版/退出程序”。命中强制升级时显示当前版本、线上版本、升级说明，点击「下载新版」用系统浏览器打开 `download_url`；不允许继续进入主界面。
+- 策略：只有服务端明确返回强制升级才阻断；网络失败、接口超时、JSON 非法或字段缺失时允许进入软件，避免服务器故障导致用户全部不可用。
+- 边界：第一版不自动下载并覆盖 `cmshopee.exe` 或 `_internal/`，不删除/覆盖 `data/`，不做 Launcher、后台替换、增量补丁、签名校验或回滚；本轮只更新文档，未改代码。