cmshoppe/docs/tasks/T-558.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-558	release 发布目录与 zip 使用中文品牌名	8	T-540 T-537 T-538	DONE	2026-07-08

问题 / 背景

T-540 已经把版本号收口到 app/version.py，并让构建脚本统一生成 release\cmshopee-<APP_VERSION>\ 和 release\cmshopee-<APP_VERSION>-portable.zip。这对开发和内部识别足够清晰，但交付给普通用户时仍暴露英文技术代号 cmshopee，不如产品品牌「蝦皮圈優化助手」直观。

正式 release 层应该面向用户展示品牌名，例如当前版本为 0.1.0 时，生成：

• release\蝦皮圈優化助手0.1.0\
• release\蝦皮圈優化助手0.1.0.zip

从全栈工程角度看，这只应影响发布目录名和压缩包文件名。PyInstaller 中间产物 dist\cmshopee\、可执行文件 cmshopee.exe、cmshopee.spec、cmshopee.db、配置键和内部标识符仍保持英文技术代号，避免影响启动、数据迁移、更新覆盖和现有测试。

方案

1. 构建脚本 release 命名

   • scripts\build_exe.ps1 继续读取 APP_NAME、APP_CODE_NAME、APP_VERSION。
   • dist\cmshopee\ 仍作为 PyInstaller 中间产物。
   • 面向用户的 $releaseName 改为 "$appName$appVersion"，不加 v、不加连字符、不加 portable。
   • $releaseDir 改为 release\<APP_NAME><APP_VERSION>\。
   • $portableZip 改为 release\<APP_NAME><APP_VERSION>.zip。

2. 文档同步

   • 更新 docs/packaging.md，明确正式分发入口为 release\蝦皮圈優化助手<APP_VERSION>.zip。
   • 更新 docs/03-tech-stack.md 和相关排障文字，避免继续把旧英文 release 名作为正式发包名。
   • 保留说明：dist\cmshopee\cmshopee.exe 仍是程序内部/中间产物名，用户无需直接理解。

3. 测试同步

   • 更新 tests/test_packaging.py，断言构建脚本使用 $appName$appVersion 组装 release 名，zip 为 $releaseName.zip。
   • 保留对 py -3.10、version.txt、README.txt、_internal、用户数据排除的测试。

验收要点

• 运行 scripts\build_exe.ps1 后，正式 release 目录命名为 release\蝦皮圈優化助手<APP_VERSION>\。
• zip 文件命名为 release\蝦皮圈優化助手<APP_VERSION>.zip。
• dist\cmshopee\cmshopee.exe 和 _internal\ 结构不变。
• 发布目录内仍包含 cmshopee.exe、_internal\、version.txt、README.txt。
• 发布目录和 zip 仍不得包含 data\、DB、配置、图片、日志、Chrome 登录态或运营 Excel。
• python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests、git diff --check 通过。

边界（不改什么）

不改 APP_NAME、APP_CODE_NAME、APP_VERSION 的含义；不改 cmshopee.exe、cmshopee.spec、cmshopee.db、data\ 目录、配置键、DB schema、启动版本检查接口、自动更新逻辑、AI/Excel/Shopee/CDP 业务流程。

执行记录

• 2026-07-08：scripts\build_exe.ps1 的正式 release 命名改为 $appName$appVersion，生成目录 release\蝦皮圈優化助手<APP_VERSION>\，zip 改为 release\蝦皮圈優化助手<APP_VERSION>.zip；dist\cmshopee\cmshopee.exe 与 _internal\ onedir 中间产物保持不变。
• 2026-07-08：同步更新 docs/packaging.md、docs/03-tech-stack.md、docs/troubleshooting.md，明确正式发包名使用中文品牌名，用户更新仍覆盖程序文件和 _internal\ 并保留 data\。
• 2026-07-08：更新 tests/test_packaging.py，断言构建脚本使用 $appName$appVersion 和 $releaseName.zip，并防止旧的 $appCodeName-$appVersion / -portable.zip 命名回归。
• 2026-07-08：实跑打包时发现 Windows Compress-Archive 可能在 PyInstaller 刚复制 _internal\base_library.zip 后遇到短暂文件占用；已为压缩发布包步骤增加 5 次短重试，避免最后一步偶发失败。
• 验证通过：python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests、powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1、git diff --check。
• 打包实测输出：release\蝦皮圈優化助手0.1.1\ 和 release\蝦皮圈優化助手0.1.1.zip；发布目录包含 _internal、cmshopee.exe、README.txt、version.txt，未发现 data、配置、DB、图片、日志或登录态目录。