diff --git a/docs/task/13-优化-admin-windows-启动脚本并增加热重载.md b/docs/task/13-优化-admin-windows-启动脚本并增加热重载.md new file mode 100644 index 0000000..b62919b --- /dev/null +++ b/docs/task/13-优化-admin-windows-启动脚本并增加热重载.md @@ -0,0 +1,65 @@ +# 13 优化 Admin Windows 启动脚本并增加热重载 + +- 类型:开发体验优化 +- 父级大工单:#1 +- 所属 MVP / 版本:#2 / MVP +- 状态:已实现,待验收 +- 日期:2026-08-06 +- Gitea 工单:http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/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 全量检查 | 通过 | +| 差异格式检查 | 通过 | + +## 测试 + +执行了: + +```powershell +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 启动脚本增加热重载