build: add pyinstaller packaging

docs/packaging.md

@@ -0,0 +1,100 @@
+# 打包与分发
+
+> T-524 目标：先把当前 Windows 桌面工具打成免安装 onedir `.exe`，方便第一版交付使用。暂不做自动更新器、安装器、增量补丁或在线升级。
+
+## 一、打包前提
+
+- 在 Windows 环境执行。
+- Python 环境已能运行源码版 `python main.py`。
+- 打包脚本使用当前 PATH 中的 `python`；正式出包前先确认 `python --version` 符合项目目标 Python 3.10+。
+- 安装运行依赖和打包依赖：
+
+```powershell
+python -m pip install -r requirements-build.txt
+```
+
+`requirements-build.txt` 会先安装 `requirements.txt` 的运行依赖，再安装 PyInstaller。
+
+## 二、打包命令
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
+```
+
+脚本会执行：
+
+```powershell
+python -m PyInstaller --noconfirm --clean cmshopee.spec
+```
+
+成功后输出：
+
+```text
+dist\cmshopee\cmshopee.exe
+```
+
+发布给用户时，以整个 `dist\cmshopee\` 文件夹为单位压缩分发，用户双击 `cmshopee.exe` 启动。
+
+## 三、绝不打包的本地数据
+
+发布包里不能包含以下本地数据、密钥、业务数据或登录态：
+
+- `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`
+- 运营填写后的 Excel 文件
+
+`cmshopee.spec` 不声明任何 `datas`；`scripts/build_exe.ps1` 会在打包后检查 `dist\cmshopee\`，如果发现上述路径会直接失败。
+
+## 四、首次运行与本地数据位置
+
+打包版启动时，`main.py` 会把工作目录切到 `cmshopee.exe` 所在目录。
+
+因此首次运行时，现有代码会按默认值在 exe 同级目录生成或使用本地文件：
+
+- `config.json`
+- `config/ai_models.json`
+- `cmshopee.db`
+- `chrome_user_data_dir/`
+- `images/`
+- `logs/`
+- `prompts/`、`title_prompt.txt`（用户维护提示词时生成）
+
+这些文件属于用户本地数据，不随新版本程序包覆盖。
+
+## 五、用户后续更新方式
+
+第一版不做自动更新。给用户发新版本时：
+
+1. 让用户先关闭 cmshopee。
+2. 建议用户备份当前整个程序文件夹。
+3. 解压新版 `dist\cmshopee\`。
+4. 只覆盖程序文件，例如 `cmshopee.exe` 和 `_internal/`。
+5. 不删除也不覆盖用户原有的 `config.json`、`config/ai_models.json`、`cmshopee.db`、`chrome_user_data_dir/`、`images/`、`logs/`、`prompts/`、`title_prompt.txt`。
+
+如果用户把整个旧目录删除再放新版，账号、任务记录、图片和登录态也会一起丢失，只能从备份恢复。
+
+## 六、验证清单
+
+打包前后至少执行：
+
+```powershell
+python -m compileall app main.py
+python -m unittest discover -s tests
+powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
+```
+
+打包成功后确认：
+
+- `dist\cmshopee\cmshopee.exe` 存在。
+- `dist\cmshopee\` 中没有第三节列出的本地数据。
+- 在干净目录首次启动时能生成默认配置并进入 GUI。
+
+涉及 Shopee/CDP 的真实更新能力，仍按任务文档要求用测试商品做人工回归；打包任务本身不新增自动绕过登录、验证码或风控的能力。
+