# 恒诺迁移工具构建与发版说明

本文是 `henlo_migration_wpf10/` 的构建、Velopack 打包、更新服务器部署和客户端自动更新说明。涉及版本、发布或更新的任务必须先完整读取本文；若本文与实际代码冲突，以 `.csproj`、`pack.bat` 和 `App.xaml.cs` 为准，并同步更新本文。

## 权限边界

- 普通 Debug/Release 构建可以用于本地验证。
- 修改版本号、运行 `pack.bat`、删除或覆盖发布产物、上传更新服务器都属于显式发布动作，必须有用户当前任务的明确授权。
- 打包脚本不会上传任何文件；服务器部署是独立的外部写操作，需要另行授权。
- 不要把“项目构建成功”描述成“发版成功”或“自动更新已验证”。

## 版本来源

- 唯一版本来源是 `henlo_migration_wpf10/henlo_migration_wpf10.csproj` 的 `<Version>`。
- 正式发版前必须把版本号单调递增，不要重新打包已存在的版本号。
- 程序显示版本来自程序集元数据，不在脚本或文档中另设版本常量。

## 日常构建

在仓库根目录执行：

```powershell
dotnet restore .\henlo_migration_wpf10\henlo_migration_wpf10.csproj
dotnet build .\henlo_migration_wpf10\henlo_migration_wpf10.csproj -c Debug
```

依赖已经恢复且不希望访问包源时：

```powershell
dotnet build .\henlo_migration_wpf10\henlo_migration_wpf10.csproj -c Debug --no-restore
```

Debug 产物位于 `henlo_migration_wpf10/bin/Debug/net10.0-windows/`，只用于开发验证，不是 Velopack 发布包。项目现有 `CS8632` 和 `NU1701` 警告不等于构建错误，但不得新增编译错误。

## 正式打包流程

唯一正式入口：

```powershell
cd .\henlo_migration_wpf10
.\pack.bat
```

`pack.bat` 当前执行顺序：

1. 从 `.csproj` 读取 `<Version>`。
2. 删除并重建 `publish/`。
3. 执行：

   ```powershell
   dotnet publish henlo_migration_wpf10.csproj -c Release -o publish --self-contained false -r win-x64
   ```

4. 删除 `publish/config.ini`，确保本机数据库配置不会进入产物。
5. 确保 `publish/data/`、`publish/data/from/`、`publish/pre/` 存在。
6. 执行：

   ```powershell
   vpk pack -u henlo_migration -v <Version> -p publish -e "恒诺迁移工具.exe" -o releases --noInst
   ```

7. 保留 `releases/` 中的历史包，供 Velopack 生成差量包；脚本只清理 `publish/`，不会清理 `releases/`。

打包依赖 Windows、对应 .NET SDK、可调用的 `dotnet` 和 `vpk`。不要使用 `_build*`、`_make_pack.bat`、`_write_pack.ps1` 等历史辅助文件作为正式入口。

## 当前发布形态

- 目标平台：Windows x64。
- 发布方式：framework-dependent，`--self-contained false`；目标机器需要匹配的 .NET 10 Desktop Runtime。
- Velopack 参数包含 `--noInst`，因此不生成 Setup 安装器，只生成便携包和更新源文件。
- `Properties/PublishProfiles/FolderProfile.pubxml` 虽配置 `PublishSingleFile=true`，但 `pack.bat` 没有使用该 Profile；正式产物不是单文件，会包含 EXE、DLL 和 runtimeconfig/deps 文件。

## 运行时文件进入发布包的规则

- `.csproj` 只复制 `pre/*.txt|*.fnc|*.prc` 等程序辅助脚本，不复制本机 `config.ini` 或 `data/from/*.txt`；`pack.bat` 还会在打包前再次删除 `publish/config.ini`，并创建空的 `data/from/` 目录。
- `pre/hmig_get_table_bos_31.prc`、`pre/hmig_get_table_bos_field_31.prc` 等运行时辅助过程必须出现在发布输出中。
- 新安装的索引列表为空；程序添加第一条对应配置时会在 `data/from/` 创建 `table.txt`、`bos.txt`、`bos_field.txt`、`prc.txt` 或 `data.txt`。
- 新安装首次运行时会创建值为空的 `config.ini`，由用户在界面配置；不得把真实或样例账号密码放入发布产物。

## Velopack 产物

正常情况下 `releases/` 至少包含：

```text
henlo_migration-win-Portable.zip
henlo_migration-<Version>-full.nupkg
henlo_migration-<Version>-delta.nupkg
RELEASES
releases.win.json
assets.win.json
```

便携 ZIP 内应包含 `.portable`、根启动器、`Update.exe`、`current/` 应用文件以及需要的 `data/`、`pre/` 内容。差量包是否生成取决于 `releases/` 中是否有可用的历史版本。

## 更新服务器部署

客户端更新地址硬编码在 `App.xaml.cs`：

```text
http://zjhenlo.henlo.net:8878/henlo_migration/auto_update/
```

当前没有自动上传脚本。获得上传授权后，应部署并核对：

- 新版本 full nupkg；
- 新版本 delta nupkg（若生成）；
- `RELEASES`；
- `releases.win.json`；
- `assets.win.json`；
- 需要提供便携下载时再上传 `henlo_migration-win-Portable.zip`。

上传后至少验证服务器能直接访问元数据文件和其中引用的包，文件大小及版本号与本地产物一致。不要只上传 nupkg 而遗漏更新后的元数据。

## 客户端自动更新流程

`App.xaml.cs` 当前行为：

1. UI 启动前调用 `VelopackApp.Build().Run()`。
2. 从系统临时目录恢复上次更新前备份的 `config.ini`、`data/`、`pre/`。
3. 创建指向更新服务器的 `UpdateManager`；非 Velopack 环境创建失败时禁用自动更新。
4. 后台静默检查并下载更新；手动“检查更新”使用相同更新源。
5. 用户同意立即重启时，先备份 `config.ini`、`data/`、`pre/`，再调用 `ApplyUpdatesAndRestart()`。
6. 新版本首次启动时恢复备份并删除临时备份目录。

当前限制和未验证项：

- 更新备份范围包含 `config.ini`、`data/` 和 `pre/`；恢复失败时会记录到 `error.log`，发版验收仍需验证用户配置未丢失。
- 用户下载完成后选择“不立即重启”时，代码没有明确实现下次启动自动应用已下载更新的流程。
- 直接运行普通 `publish/` 中的 EXE 时通常不属于 Velopack 安装态，程序会禁用更新或把检查异常写入 `error.log`。
- `--noInst` 生成的是便携模式；便携包的检查、下载、应用和重启更新链路尚未完成实际端到端回归，不能声称自动更新可靠可用。

## 发版验收清单

1. 确认工作区改动和准备发布的提交范围，避免把无关或敏感文件带入。
2. 递增并核对 `.csproj` 版本号。
3. 先执行主项目构建，确保 `0` 个错误。
4. 获得明确授权后运行 `pack.bat`，确认 publish 和 vpk 两阶段都成功。
5. 检查便携 ZIP、full/delta 包、`RELEASES` 和两个 JSON 的版本、大小及时间。
6. 检查发布包中的 `pre/` 和必要运行文件，并确认产物中不存在 `config.ini` 及开发机 `data/from/*.txt`。
7. 在未安装态测试普通 EXE/便携包启动；若任务涉及自动更新，再在对应 Velopack 运行形态下单独验证更新。
8. 只有获得上传授权后才能部署服务器；上传后验证 URL 和包完整性。
9. 交付说明必须区分：构建验证、打包验证、便携运行验证、自动更新验证和服务器部署验证。