cmshoppe/docs/packaging.md

# 打包与分发

> 当前发布仍是免安装 onedir；T-615 已增加自动升级所需的机器可验证清单和发布元数据，但尚不下载或替换客户端程序。

## 一、打包前提

- 在 Windows 环境执行。
- Python 环境已能运行源码版 `python main.py`。
- 打包脚本固定使用 Windows Python Launcher 的 `py -3.10`，不使用当前 PATH 中的 `python`；正式出包前先确认 `py -3.10 --version` 可用。
- 安装运行依赖和打包依赖：

```powershell
py -3.10 -m pip install -r requirements-build.txt
```

`requirements-build.txt` 会先安装 `requirements.txt` 的运行依赖，再精确安装 PyInstaller 6.11.1、pyinstaller-hooks-contrib 2026.6、setuptools 80.9.0 和 backports.tarfile 1.2.0。依赖必须安装到 Python 3.10 环境里，避免 PATH 上的 Python 3.7/3.12/3.14 或未锁定的全局构建包装出不可比对的包。运行依赖固定使用 NumPy 1.26.4，以兼容 PySide6/Shiboken 6.5.3；正式打包前不得单独升级到 NumPy 2.x。

## 二、打包命令

```powershell
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
```

脚本会执行：

```powershell
py -3.10 -m PyInstaller --noconfirm --clean cmshopee.spec
```

成功后输出：

```text
dist\cmshopee\
  cmshopee.exe
  _internal\
    <PyInstaller 依赖文件和依赖目录>
```

正式分发入口是 `release\蝦皮圈優化助手<APP_VERSION>.zip`。`dist\cmshopee\` 只是 PyInstaller 构建中间产物，不直接作为正式发包名称。

当前 `requirements-build.txt` 锁定完整构建工具链，`cmshopee.spec` 还会显式检查并收集 `backports.tarfile`，避免 setuptools 的 `pkg_resources/jaraco` 运行时钩子因 vendored 依赖漏收集而在应用入口前崩溃。onedir 产物必须是 `cmshopee.exe` + `_internal\` 集中依赖布局。`scripts\build_exe.ps1` 会校验 `_internal\` 存在，并在组装 release 和压缩 ZIP 前运行 `cmshopee.exe --startup-smoke-test`；自检会完成 PyInstaller 运行时钩子与 GUI 模块导入后立即退出，不创建 GUI、不准备 `data\`、不检查更新或会员状态。自检非零退出或 30 秒超时会直接判定构建失败。

发布包只包含程序文件和依赖文件：

```text
cmshopee\
  cmshopee.exe
  _internal\
    <PyInstaller 依赖文件和依赖目录>
```

首次运行后才会在同级生成 `data\`，用于保存用户本地数据。

## 三、版本号与发布目录

版本控制采用“单一版本源 + 发布目录带版本号 + 可验证 manifest”的方案。

### 3.1 单一版本源

新增 `app/version.py`，作为软件名称和版本号的唯一来源：

```python
APP_NAME = "蝦皮圈優化助手"
APP_CODE_NAME = "cmshopee"
APP_VERSION = "0.1.0"
APP_UPDATE_CHECK_URL = "https://cm.833729.com/api/v1/client/releases/latest?platform=windows"
```

规则：

- 修改版本号只改 `app/version.py` 的 `APP_VERSION`。
- 线上版本检查接口只改 `app/version.py` 的 `APP_UPDATE_CHECK_URL`；当前正式接口为 `https://cm.833729.com/api/v1/client/releases/latest?platform=windows`。如需本地开发临时跳过启动检查，可把该值置空。
- GUI 窗口标题读取同一版本源，显示为 `蝦皮圈優化助手 v0.1.0`。
- 打包脚本读取同一版本源生成发布目录、压缩包和 `version.txt`。
- 禁止在 GUI、构建脚本或文档示例之外重复硬编码不同版本号。

### 3.2 发布目录结构

`scripts\build_exe.ps1` 仍先产出 PyInstaller 原始目录 `dist\cmshopee\`，再组装面向用户分发的 `release\` 目录：

```text
release\
  蝦皮圈優化助手0.1.0\
    cmshopee.exe
    _internal\
      <PyInstaller 依赖文件和依赖目录>
    version.txt
    README.txt
    package-manifest.json
  蝦皮圈優化助手0.1.0.zip
  release-metadata0.1.0.json
```

说明：

- `dist\cmshopee\` 是构建中间产物，不直接作为正式发包名称。
- `release\蝦皮圈優化助手<APP_VERSION>\` 是人工验收和分发目录。
- `release\蝦皮圈優化助手<APP_VERSION>.zip` 是交付给用户的便携压缩包。
- `version.txt` 使用 ASCII/UTF-8 无 BOM 写入 `APP_VERSION`，用于人工排查和未来更新机制读取。
- `README.txt` 用中文写明启动方式、不要放入 `Program Files`、保留 `data\`、升级时覆盖程序文件但不覆盖 `data\`。
- `package-manifest.json` 记录包格式、版本、入口、更新器协议、允许替换根项目，以及除清单自身外每个程序文件的规范化路径、字节数和 SHA-256。
- `release-metadata<APP_VERSION>.json` 记录对应版本整个 zip 的准确字节数和 SHA-256，并提供服务端发布字段模板；例如 `0.1.6` 生成 `release-metadata0.1.6.json`。它不放进 zip。

当前 PyInstaller 6.11.1 的 onedir 为集中依赖结构，所以 `release\蝦皮圈優化助手<APP_VERSION>\` 必须包含 `cmshopee.exe` 和 `_internal\`，不得只复制单个 exe。

### 3.3 正式出包流程

1. 修改 `app/version.py` 中的 `APP_VERSION`。
2. 运行语法检查和单元测试。
3. 运行 `powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1`；确认日志包含 `Verified packaged startup smoke test`。
4. 检查 `version.txt`、GUI 标题栏、`package-manifest.json`、压缩包文件名和 `release-metadata<APP_VERSION>.json` 的版本一致。
5. 在无 Python 环境的 Windows 10/11 机器上解压 `蝦皮圈優化助手<APP_VERSION>.zip` 并启动验证。

正式发布构建固定使用 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 启动版本检查（T-544 第一版）

T-544 第一版目标是**启动时检查是否必须升级**，但仍不做自动覆盖升级。

客户端启动流程：

1. `appconfig.prepare_data_dir()` 成功后、创建 `MainWindow` 前，请求 `app/version.py` 中 `APP_UPDATE_CHECK_URL` 指向的服务器版本接口。
2. 当前版本从 `app/version.py` 的 `APP_VERSION` 读取；`APP_UPDATE_CHECK_URL` 为空时跳过检查并允许进入软件，用于本地开发或尚未配置线上接口的构建。
3. 如果服务器明确返回“当前版本必须升级”，弹中文阻断框，不进入主界面。
4. 弹窗只提供「下载新版」和「退出程序」。点击「下载新版」用系统浏览器打开下载地址；用户下载后按第六节手动覆盖程序文件。
5. 网络失败、接口超时、JSON 非法或字段缺失时，第一版允许进入软件；只记录本地诊断日志或给低打扰提示，避免服务器故障导致所有用户不可用。

建议版本接口返回结构：

```json
{
  "latest_version": "0.1.1",
  "min_supported_version": "0.1.1",
  "force_update": true,
  "download_url": "https://example.com/蝦皮圈優化助手0.1.1.zip",
  "sha256": "optional-release-zip-sha256",
  "message": "发现必须升级的新版本，请下载后覆盖当前程序文件，保留 data 目录。"
}
```

客户端同时兼容当前线上接口返回结构：

```json
{
  "platform": "windows",
  "release": {
    "version": "0.1.0",
    "download_url": "https://example.com/蝦皮圈優化助手0.1.0.zip",
    "sha256": "",
    "release_notes": "发布说明"
  }
}
```

映射规则：`release.version` 作为 `latest_version`，`release.download_url` 作为下载地址，`release.sha256` 作为校验值，`release.release_notes` 作为弹窗说明。若该结构未返回 `min_supported_version` 或 `force_update=true`，客户端只记录可用新版本信息，不会阻断启动。

客户端判定规则：

- `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 自动升级发布基础（T-615）

`app/release_manifest.py` 是发布清单与 zip 元数据的唯一生成逻辑。构建脚本按以下顺序执行：组装 release 目录、拒绝用户数据和未知根项目、生成 `package-manifest.json`、压缩 zip、计算 zip hash/大小、生成 `release-metadata<APP_VERSION>.json`。同版本重打只覆盖当前版本元数据，保留其他版本文件，并清理历史无版本 `release-metadata.json`。允许的根项目仅为 `cmshopee.exe`、`_internal/`、`version.txt`、`README.txt`、清单和后续独立更新器；明确禁止 `data/` 与 `.cmshopee-update/`。

T-615 不改变客户端行为：T-544 仍只打开浏览器下载。客户端下载、解压校验、独立进程替换、回滚和重启分别由 T-616 至 T-619 实现。清单预留签名字段，但当前只验证完整性，不宣称已验证发布者身份。

T-616 提供无Qt依赖的安全下载暂存层 `app/update_installer.py`。安装包下载到 `<安装目录>/.cmshopee-update/downloads/`，完成大小与zip SHA-256校验后安全解压到同盘 `staging/`；路径穿越、符号链接、大小写重复、Windows保留名、ADS、异常压缩比、文件数/解压总量超限，以及manifest缺失或逐文件hash不一致都会拒绝。完整验证后才原子写 `pending.json`，当前程序目录和 `data/` 不变。

T-617 增加独立 `cmshopee-updater.exe`。构建脚本用 `cmshopee-updater.spec` 生成无控制台单文件更新器并放进release和manifest。执行更新前，主程序把它复制到系统临时目录；更新器有上限地等待主程序退出，再按manifest白名单将旧程序根项目整体移动到 `.cmshopee-update/backup/`，把已验证暂存根项目移入安装目录。每一步写事务journal，移动或新版启动失败时逆序恢复；`data/` 与安装根未知文件不扫描、不移动、不删除。

T-618 已把安全暂存和独立更新器接回启动门禁。强制升级窗口使用QThread执行下载、hash、解压和manifest校验，主线程持续显示中文阶段、进度和字节数；协作式取消会等待线程清理，避免线程仍运行时销毁。确认独立更新器进程创建成功后旧主程序退出；强制响应后的任何准备失败都保持阻断，只能重试或退出。版本接口完全不可达/非法仍按T-544策略失败放行。

T-619 增加启动健康确认与失败熔断。新版带事务参数启动，在 `.cmshopee-update/transactions/<事务>/health.json` 原子写 `process_started`、`main_window_ready` 或 `environment_blocked`。更新器在主窗口就绪前保留旧根项目；早期退出/超时会回滚并按版本+zip hash写 `failed-versions.json`，防止同一坏包无限循环。主窗口就绪后清理pending、zip、staging和本次成功备份；环境阻断保留新版与备份。备份清理只处理 `.cmshopee-update/backup/` 且保留最近两份，不扫描 `data/`。

T-623 为外部对象存储/CDN下载链接增加临时 HTTP 兼容。版本检查接口仍固定使用受信任 HTTPS；安装包 `download_url` 不限制域名，可以使用任意公网 HTTP/HTTPS 域名或公网 IP，并允许跨域、跨协议重定向。初始地址、每次跳转和最终响应都会拒绝本机、内网、账号信息和非 HTTP(S) 协议。HTTP 不会降低安装校验标准：声明大小、整包 SHA-256、安全解压、包内manifest、事务替换和健康回滚全部照常执行；强制升级窗口会显示临时 HTTP 通道提示。服务端外链支持 HTTPS 后应删除 HTTP 分支。

T-624 将 cmhub 版本接口收敛为实际字段：`version`、`download_url`、`sha256`、`release_notes`、`force_update`、`size_bytes`、`published_at`。服务端不需要返回 `package_format` 或更新器协议；客户端固定使用当前 `cmshopee-portable-v1` 和更新器协议构造安装元数据，并在解压后以包内manifest复核真实格式和协议。因此接口字段减少不等于跳过包格式或协议安全检查。

T-705 复用同一 HTTPS 版本接口顶层 `client_policy` 下发订阅检测策略，不增加新的同步启动请求。最后一次有效策略缓存到 `data/config/client_policy.json`，只含非敏感开关与时间；远端和缓存都不可用时回退观察模式。安装包不得预置该缓存，干净安装第一次启动以线上响应为准。远程 `off` 跳过订阅状态请求，`observe` 只展示不限制，`enforce` 才在主窗口显示后异步查询并按 `real_entitlement_allowed` 执行门禁。

## 四、绝不打包的本地数据

发布包里不能包含以下本地数据、密钥、业务数据或登录态：

- `config.json`
- `config/ai_models.json`
- `cmshopee.db`、`cmshopee.db-wal`、`cmshopee.db-shm`
- `db.sqlite`
- `chrome_user_data_dir/`
- `images/`
- `logs/`
- `prompts/`
- `title_prompt.txt`
- `data/`
- 运营填写后的 Excel 文件

`cmshopee.spec` 不声明任何 `datas`；`scripts/build_exe.ps1` 会在打包后检查 `dist\cmshopee\`，如果发现上述路径会直接失败。

T-548 后 cmhub 图片下载可在 Windows 上优先调用系统自带 curl。curl 在 Windows 10+ 通常位于 `C:\Windows\System32\curl.exe`，发布包不捆绑 curl、wget 或其它下载二进制；如果系统无 curl 或 curl 执行失败，程序会自动回退到内置 requests 下载。

## 五、首次运行与本地数据位置

T-538 后，打包版不再把全进程工作目录切到 `cmshopee.exe` 所在目录；路径由 `app/appconfig.py` 按显式数据根解析。

首次运行时，程序会在 exe 同级创建单独的 `data\` 子目录，并把所有用户本地数据放进去：

```text
cmshopee\
  cmshopee.exe
  _internal\
    <PyInstaller 依赖文件和依赖目录>
  data\
    config.json
    config\
      ai_models.json
      cmhub.json
      client_policy.json
    cmshopee.db
    chrome_user_data_dir\
    images\
    logs\
    prompts\
    title_prompt.txt
```

源码运行时同理使用项目根目录下的 `data\`。`config.json` 内的 `user_data_root`、`image_dir`、`db_path` 默认仍保存为 `chrome_user_data_dir`、`images`、`cmshopee.db` 等相对值，运行时再解析到 `data\` 下，保持便携。

干净安装的默认网关地址已经内置为 `https://cm.833729.com`，用户不需要先填写 Base URL。`data\config\cmhub.json` 不随安装包分发真实 Key；当线上策略为强制模式且检测到 Key 缺失时显示「激活蝦皮圈优化助手」，用户从官方会员中心取得会员 API Key 后在该窗口验证。无效 Key 或网络失败不会写入本地，验证通过后才保存到 `data\config\cmhub.json`，随后显示添加店铺、人工登录、导入 Excel 和开始采集的首次使用清单。关闭或观察模式不得因缺 Key 阻断启动。

这些文件属于用户本地数据，不随新版本程序包覆盖。

### 旧布局迁移

如果用户从 T-524 旧包升级，新版首次启动会检查 exe 顶层是否存在旧布局数据，例如 `config.json`、`config\`、`cmshopee.db`、`chrome_user_data_dir\`、`images\`、`logs\`、`prompts\`、`title_prompt.txt`。若 `data\` 中没有同名目标，程序会自动移动到 `data\` 下。

如果旧布局和 `data\` 中同时存在同名数据，程序不会覆盖，会以“数据迁移冲突”提示用户先手动合并或备份，避免误丢账号、任务、图片或登录态。此类冲突不是目录不可写，不应直接归类为“数据目录不可写”。

启动时会检测 `data\` 是否可写；如果程序放在 `Program Files` 等只读目录导致写入失败，才会以“数据目录不可写”提示“请把程序放到可写目录，勿放 Program Files”并退出。

## 六、用户后续更新方式

尚未安装自动升级引导版本的旧用户仍按以下方式人工覆盖；安装T-619及之后版本后，强制升级窗口可自动下载、替换和重启：

1. 让用户先关闭 cmshopee。
2. 建议用户备份当前整个程序文件夹。
3. 解压新版 `release\蝦皮圈優化助手<APP_VERSION>.zip`。
4. 覆盖新版程序文件和依赖文件。当前 PyInstaller 6.11.1 是 `cmshopee.exe` + `_internal\` onedir，不能只覆盖 `cmshopee.exe`；应把新版 `cmshopee.exe`、`_internal\`、`version.txt`、`README.txt` 等程序文件整体覆盖到旧程序目录。
5. 保留旧目录里的 `data\`，不要删除、覆盖或合并它。

如果用户把整个旧目录删除再放新版，`data\` 里的账号、任务记录、图片和登录态也会一起丢失，只能从备份恢复。

## 七、验证清单

打包前后至少执行：

```powershell
py -3.10 -m compileall app main.py
py -3.10 -m unittest discover -s tests
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
```

打包成功后确认：

- `dist\cmshopee\cmshopee.exe` 存在。
- 当前 PyInstaller 6.11.1 下 `dist\cmshopee\_internal\` 必须存在。
- `dist\cmshopee\` 中没有第四节列出的本地数据，尤其不能含 `data\`。
- `release\蝦皮圈優化助手<APP_VERSION>\version.txt`、GUI 标题栏版本、压缩包文件名三者一致。
- 在干净目录首次启动时能生成 `data\config.json`，默认网关地址为 `https://cm.833729.com`；安装包和新建 `data\` 中不得预置真实 Key 或 `client_policy.json`。线上强制策略且缺 Key 时才出现只要求“会员 API Key”的中文激活窗口。
- 使用测试接口模拟 `off/observe/enforce`、无效 Key、网络失败和有效套餐：关闭模式不请求订阅状态，观察模式不限制，强制模式只有 `real_entitlement_allowed=true` 才启用业务 Tab；输入的无效 Key 和网络失败不得写入本地文件或日志。
- 在目标 Windows 10/11 机器或虚拟机上启动 release exe 后，主窗口标题栏完整可见，左边缘不出屏，用户能用标题栏拖动窗口；小分辨率环境不得出现窗口卡在左上角且标题栏不可拖动的问题（见 T-541）。

涉及 Shopee/CDP 的真实更新能力，仍按任务文档要求用测试商品做人工回归；打包任务本身不新增自动绕过登录、验证码或风控的能力。