cmautobuy/docs/task/13-优化-admin-windows-启动脚本并增加热重载.md

13 优化 Admin Windows 启动脚本并增加热重载

• 类型：开发体验优化
• 父级大工单：#1
• 所属 MVP / 版本：#2 / MVP
• 状态：已实现，待验收
• 日期：2026-08-06
• Gitea 工单：#13

背景与目标

根目录的 run_admin.bat 原来只执行 go run .，每次修改代码都要手动停止和重新启动。本任务为 Windows 本地开发增加热重载，同时保持项目固定使用 Go 1.23.0。

最终方案

• 使用开发工具 Air，并固定为 github.com/air-verse/air@v1.61.7。
• 这个版本声明需要 Go 1.23，与项目环境一致；不使用要求更高 Go 版本的最新 Air。
• run_admin.bat 从脚本所在目录进入 admin，不依赖终端当前目录。
• 脚本检查 Go、GOPATH 和 Air 版本；Air 缺失或版本不对时自动安装固定版本。
• admin/.air.toml 监听 Go、HTML、CSS 和 JavaScript 文件，忽略数据、测试数据、测试文件和临时目录。
• 开发可执行文件命名为 admin-dev.exe 并放在 admin/ 下，确保程序仍使用 admin/data，同时避免覆盖正式的 admin.exe。
• Air 只用于本地开发，不加入 admin/go.mod 或 admin/go.sum。

改了哪些

• run_admin.bat：增加环境检查、固定版本安装和热重载启动。
• admin/.air.toml：增加 Windows 热重载配置。
• .gitignore：忽略 admin-dev.exe 和 Air 临时目录。
• docs/admin/00-getting-started.md：增加热重载启动说明，并保留单次 go run . 的用法。

验收结果

验收标准	结果
实际运行 run_admin.bat 可以启动 Admin	通过
Air 固定为 v1.61.7，使用 Go 1.23.0 构建	通过
新增 Go 文件后自动构建并重启	通过，构建和运行次数均从 1 增加到 2
Admin 监听 127.0.0.1:8080	通过
热重载时数据目录仍是 admin/data	通过
临时构建文件不会进入 Git	通过
Admin 全量检查	通过
差异格式检查	通过

测试

执行了：

go vet ./...
go build ./...
go test ./...
git diff --check

另外实际启动 Air 和 run_admin.bat，通过临时新增 Go 源文件触发重建。日志确认第二次 building... 和 running...，测试后已停止相关进程并释放 8080 端口。

注意事项

• 第一次运行需要联网下载 Air；下载失败时脚本会提示检查网络和 GOPROXY。
• admin-dev.exe 是本地生成的忽略文件，不要提交。
• Air v1.61.7 使用 bin 配置项；后续升级 Air 前必须先确认新的 Go 版本要求和配置兼容性。

相关提交

• 7a6c647 为 Admin 启动脚本增加热重载