# Gold AutoTrade Windows 打包检查清单

适用范围：本机开发只负责 Windows 版本，发布检查只覆盖源码 ZIP、Windows Portable ZIP、Windows 安装包。

## 1. 当前打包规则

### 1.1 源码 ZIP

- 脚本：`build_trial_zip.sh`
- 规则：`git ls-files` 全量收录 + 黑名单排除
- 结论：只要文件已经被 Git 跟踪，通常不会因为“白名单遗漏”漏进源码 ZIP

重点排除项：

- `.github/`
- `.vscode/`
- `.idea/`
- `website/`
- `assets/`
- `gui_react/public/`
- 部分构建脚本与 `.bak`

额外规则：

- `gui_react/dist` 因常在 `.gitignore` 中，会被单独补拷贝
- EA 文件 `bridge/GoldAutoTradeBridgeEA.mq5`、`bridge/PositionReporterEA.mq5` 缺失会直接中止打包

### 1.2 Windows EXE / Portable / Installer

- Spec：`build_backend_windows.spec`
- CI：`.github/workflows/build-windows-exe.yml`
- 规则：`datas + hiddenimports + runtime_hooks`

判断原则：

- 在 `datas` 中整体打包的目录，文件通常会随目录一起进入产物
- 被 `try/except`、延迟导入、动态导入引用的模块，仍可能需要显式写入 `hiddenimports`
- Windows CI 最终产出两类文件：
- `GoldAutoTrade-Trial-vX.Y.Z-Windows-Portable.zip`
- `GoldAutoTrade-Setup-vX.Y.Z.exe`

## 2. 每次改代码后先检查什么

### 2.1 先判断改动属于哪一类

如果你改的是下面这些位置，必须联动检查打包：

- `src/`
- `bridge/`
- `signal_generators/`
- 根目录入口文件，如 `gui_backend.py`、`updater.py`、`help_responder.py`
- `config/`
- `data/`
- `hooks/`
- `installer/`
- `gui_react/`
- `build_backend_windows.spec`
- `.github/workflows/build-windows-exe.yml`

### 2.2 重点判断是否需要补 `hiddenimports`

优先排查以下情况：

- 新增了 `src/*.py`
- 新增了 `bridge/*.py`
- 新增了根目录 `*.py`
- 原本静态导入改成了函数内导入
- 新增了 `try/except import`
- 新增了 `importlib`、字符串拼接模块名、插件式加载

经验规则：

- `src/`、`bridge/` 目录已进入 `datas`，不代表一定不需要 `hiddenimports`
- 只要 PyInstaller 可能“看不见”这个导入链，就补进 `hiddenimports`

## 3. 本项目 Windows 打包必看文件

- `build_backend_windows.spec`
- `.github/workflows/build-windows-exe.yml`
- `build_trial_zip.sh`
- `scripts/verify_build_parity.py`
- `scripts/clean_build.py`

## 4. 最小检查流程

### 4.1 检查新增文件是否已被 Git 跟踪

如果新修复的文件没进 Git，源码 ZIP 一定漏。

```powershell
git ls-files src/flock_compat.py src/symbol_resolver.py bridge/trader_api.py
```

如果你的本次修复涉及别的新增文件，就把路径替换成实际文件。

### 4.2 跑打包预检

```powershell
python scripts/verify_build_parity.py --spec build_backend_windows.spec
```

预期结果：

- `RESULT: PASS`

如果失败，按下面修：

- `MISSING: src.xxx` -> 补到 `build_backend_windows.spec` 的 `hiddenimports`
- `datas source not found` -> 修正路径，或删除失效条目
- 关键文件未覆盖 -> 检查是否在 `datas`、目录整体打包、或入口链路中

### 4.3 检查最近修复是否命中高风险模块

目前与你最近 Windows 打包修复直接相关、应持续关注的模块：

- `src.flock_compat`
- `src.symbol_resolver`
- `bridge.trader_api`
- `src.price_digits`
- `src.symbol_calibrator`
- `src.trading_context`

建议快速核对：

```powershell
git grep -n "symbol_resolver\|trader_api\|flock_compat\|price_digits\|symbol_calibrator\|trading_context"
```

如果这些模块被新入口、懒加载路径或 `try/except import` 引用，就复查 `hiddenimports`。

## 5. 构建顺序

### 5.1 本地清理式构建

优先使用清理脚本，避免旧缓存混进 EXE：

```powershell
python scripts/clean_build.py --distpath dist_check
```

如果要直接跑 PyInstaller：

```powershell
python -m PyInstaller build_backend_windows.spec --distpath dist --workpath build -y
```

### 5.2 CI 构建

Windows 正式产物以 GitHub Actions 为准：

```powershell
gh workflow run build-windows-exe.yml -f version="1.0.5-trial"
```

查看状态：

```powershell
gh run list --workflow build-windows-exe.yml --limit 5
gh run view <RUN_ID>
```

下载产物：

```powershell
gh run download <RUN_ID> --dir dist/ci-artifacts
```

## 6. 构建后验收

### 6.1 EXE 产物

至少确认以下文件存在：

- `dist/GoldAutoTrade/GoldAutoTradeEngine.exe`
- `dist/GoldAutoTrade/VERSION`
- `dist/GoldAutoTrade/app_config.json`
- `dist/GoldAutoTrade/config/risk_governor_rules.json`
- `dist/GoldAutoTrade/config/strategy_rules_v3.json`

可直接检查：

```powershell
Get-Item dist/GoldAutoTrade/GoldAutoTradeEngine.exe
Get-Item dist/GoldAutoTrade/VERSION
Get-Item dist/GoldAutoTrade/app_config.json
Get-Item dist/GoldAutoTrade/config/risk_governor_rules.json
Get-Item dist/GoldAutoTrade/config/strategy_rules_v3.json
```

### 6.2 Portable ZIP / Installer

CI 完成后至少确认：

- Portable ZIP 成功上传
- NSIS Installer 成功生成
- 文件名版本号正确

当前 CI 产物命名：

- `GoldAutoTrade-Trial-vX.Y.Z-Windows-Portable.zip`
- `GoldAutoTrade-Setup-vX.Y.Z.exe`

### 6.3 运行验证

最少做一次本地启动验证：

- EXE 能启动
- `http://127.0.0.1:18790/api/status` 返回 200
- 主界面可打开
- 不出现 `ModuleNotFoundError`

## 7. 常见遗漏模式

- 新增模块已写代码，但没提交 Git -> 源码 ZIP 漏文件
- 新增模块在函数里导入 -> PyInstaller 静态分析不到
- 新增模块放在 `try/except import` -> 需要补 `hiddenimports`
- 改了 `config/` 使用路径，但没检查 `datas` / `bundle_config`
- React 改了但 `gui_react/dist` 不是最新 -> 打出来的是旧前端
- 改了 `spec` 但没重新跑 Windows CI -> 下载到的还是旧 EXE

## 8. 针对你当前项目的结论

按当前仓库状态，Windows 打包白名单里没有发现下面 3 个最新修复项遗漏：

- `src.flock_compat`
- `src.symbol_resolver`
- `bridge.trader_api`

所以你现在的重点不是“白名单还漏了什么”，而是：

- 新修复文件先确认已被 Git 跟踪
- `build_backend_windows.spec` 变更后重新触发 Windows CI
- 下载 CI 产物做一次启动验证
