---
id: T-558
title: release 发布目录与 zip 使用中文品牌名
phase: 8
deps: [T-540, T-537, T-538]
status: TODO
created: 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 业务流程。

## 执行记录