# 09 domainCheck 交付打包说明

## 一、用途

用于在 Windows 或 Linux 上把当前可交付内容整理成一份发布包，便于：

- 发给运维或部署同事
- 存档版本快照
- 迁移到 Linux 服务器前做交付留档

## 二、打包脚本

根目录脚本：

- `package_domain_release.ps1`
- `verify_domain_release.ps1`
- `prepare_final_release.ps1`
- `show_latest_release.ps1`
- `package_domain_release.sh`
- `verify_domain_release.sh`
- `prepare_final_release.sh`
- `show_latest_release.sh`

Windows 执行方式：

```powershell
powershell -ExecutionPolicy Bypass -File .\package_domain_release.ps1
```

Linux / 海外主机执行方式：

```bash
bash ./package_domain_release.sh
```

如需一键完成“打包 + 验包 + 生成最终准备报告”：

```powershell
powershell -ExecutionPolicy Bypass -File .\prepare_final_release.ps1
```

```bash
bash ./prepare_final_release.sh
```

如需快速查看当前最新交付物：

```powershell
powershell -ExecutionPolicy Bypass -File .\show_latest_release.ps1
```

```bash
bash ./show_latest_release.sh
```

注意：

- `show_latest_release.*` 现在不只是“显示最近一次 final report 是否存在”
- 它会额外校验 `final_release_report.json` 是否真的对应当前 `latest_release.*`
- 只有 `final_release_report_matches_latest=true` 时，`final_release_ok=true` 才有意义
- `final_release_gate_decision / blocked_reasons / verify_ok / smoke_test_ok` 用于解释“为什么当前能签 / 不能签”
- Ops Center 里的“直接创建 Release / 一键 Worker 灰度 / 一键 Control 发布”
  - 现在会硬性依赖 `final_release_ok=true`
  - 如果 final report 缺失、过期或门禁未 ready，前端会禁用按钮，后端接口也会拒绝执行

## 三、输出位置

打包后会生成：

- `release/domaincheck_release_时间戳/`
- `release/domaincheck_release_时间戳.zip`
- `release/domaincheck_release_时间戳.tar.gz`
- `release/domaincheck_release_时间戳.sha256.txt`
- `release/latest_release.txt`
- `release/latest_release.json`
- `release/final_release_report.json`

## 四、当前会包含的内容

- `docs/`
- `scripts/`
- `scripts/` 中会同时带上 PowerShell 和 Shell 版发布脚本
- `domain-api/`
  - `app`
  - `deploy`
  - `README.md`
  - `requirements.txt`
  - `.env.example`
- `domain-web/`
  - `src`
  - `deploy`
  - `README.md`
  - `package.json`
  - `package-lock.json`
  - `tsconfig`
  - `vite.config.ts`
  - `.env.example`
  - `.env.production.example`
  - 若存在则带上 `dist`

同时会生成：

- `release_manifest.json`
- `README_RELEASE.txt`
- `smoke_test_report.json`
  - 若打包时本机 Web/API 正常运行，则自动生成并随包带出
- `.sha256.txt`
  - 用于校验 zip 交付包完整性

## 五、建议使用顺序

1. 先阅读 `docs/08_domainCheck_交付说明.md`
2. 查看 `release_manifest.json`
3. 查看 `smoke_test_report.json`
4. 核对 `.sha256.txt`
   或执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\verify_domain_release.ps1
```

```bash
bash ./verify_domain_release.sh
```

5. Windows 联调先跑 `scripts/smoke_test_stack.ps1`
6. Linux 部署前阅读：
   - `docs/05_domainCheck_Linux部署清单.md`
   - `docs/07_domainCheck_WebLinux发布验收清单.md`
   - `domain-api/deploy/linux/README.md`

## 六、说明

当前打包内容偏向“交付部署包”和“源代码归档包”，不包含：

- `node_modules`
- Python 虚拟环境
- 临时运行日志
- 数据库数据本体

这样更适合交付、存档和迁移。

Windows 默认产物为 `.zip`，Linux 默认产物为 `.tar.gz`；两者都会生成同结构的 `release_manifest.json / .sha256.txt / latest_release.*`，便于海外控制面统一管理。

`latest_release.txt / latest_release.json` 用于快速定位“当前最新一份交付包”，避免人工翻目录。

若打包目录本身是 Git 仓库，脚本还会自动写入 `commit_sha / commit_ref`；海外控制面在创建 Release 时可以直接回填提交号，减少人工抄写出错。

`final_release_report.json` 用于记录最近一次“打包 + 验包”的最终状态。

`show_latest_release.*` 读取这个报告时，还会校验：

- `package_name`
- `archive_path` / `zip_path`
- `sha256`

也就是说，即使目录里留着一份旧的 `final_release_report.json`，只要它不是给当前最新包签出的，`final_release_ok` 也不会误报为 `true`。