# deploy-test-env — reference

## Scope
- 本地「审阅 → 提交前 fetch+pull（冲突即停）→（可选 go test）→ 提交 → push 同名分支 → `local_build.sh` → 更新测试环境 → 报告」的单一闭环。
- **不替代** **dev-task-flow**（设计/接口文档/开发报告）或 **self-test-flow**（联调步骤与落库校验报告）。

## Hard Rules（与 SKILL 门禁一致）
- Fail fast：任意一步失败立即停止。
- Never run destructive git commands.
- Never stage or commit secret-like files such as `.env`, `*.pem`, `*.key`, `credentials.json`.
- Never commit unrelated changes outside the requested scope.
- Before running long tasks, check existing terminals to avoid duplicate background processes.

## 阶段 1 — 审阅改动（阻断即停）
- `git status --short`、`git rev-parse --abbrev-ref HEAD`。
- `git diff`；若已有暂存则 `git diff --staged`。
- **应停止并 FAIL 的典型情况**（非穷尽）：明显编译/逻辑错误、删除关键逻辑无说明、包含密钥或令牌、大范围无关格式化、危险变更且用户未确认。
- 审阅通过则 `PASS` 并简要列出改动摘要（模块/意图）。

## 阶段 2 — 提交前同步（必做）
- `git fetch --all --prune`。
- `git rev-parse --abbrev-ref HEAD` 确认当前分支；`git pull` 与上游（`origin` 同名跟踪分支）对齐。
- **冲突即停**：若 `pull` 失败且工作区出现未合并项（`git status` 含 *both modified* / *Unmerged paths* 等），或命令明确报冲突，**立即停止** `FAIL`，不自动解决、不继续后续阶段。
- 无上游时：先与用户确认是否 `git push -u origin <branch>` 再拉取，或按仓库约定处理；无法安全对齐则 `FAIL`。

## 阶段 3 — 单测（按需）
- 用户明确要求跑单元测试时：`go test ./...`，或先跑与改动包相关的测试以节省时间。
- 失败时给出失败包/用例与可操作的修复线索。
- 用户未要求：本阶段 `PASS（跳过）`。
- 若用户要做联调自测（NSQ/HTTP、MySQL/ClickHouse、测试报告），按 **self-test-flow**，**不要**与本阶段 `go test` 混为一谈。

## 阶段 4 — 提交代码
- 再次检视：`git status --short`、`git diff`、`git diff --staged`。
- 仅暂存与本次提交/部署相关的文件；禁止暂存敏感文件。
- 提交信息应说明意图与原因，而非只列文件名。
- **Heredoc 提交**：
  - `git commit -m "$(cat <<'EOF'`
  - `<message>`
  - `EOF`
  - `)"`
- 提交后：`git status`，汇报 commit hash。
- **无待提交改动**：输出「工作区干净/无新提交」，阶段 4 记为 `PASS（跳过提交）`，进入阶段 5。

## 阶段 5 — 推送同名分支
- 当前分支名：`branch=$(git rev-parse --abbrev-ref HEAD)`。
- `git push origin "$branch"`（与本地分支同名的远端分支）。
- 成功或远端已包含本地提交（nothing to push / up-to-date）记 `PASS`；认证失败、非 fast-forward 等记 `FAIL` 并停止（不强推）。

## 阶段 6 — `local_build.sh`
- 在仓库根目录：`bash ./local_build.sh <model>`。
- 需已配置镜像仓库密码：环境变量 **`HARBOR_PASSWORD`**，或根目录 **`local_build.env`**（已 `.gitignore`，勿提交）。
- **model**：`cmd/` 下入口目录，如 `saas`、`virus`、`task`、`threat`、`container`、`leakfix`。
- 未指定时：根据改动路径推断；无法唯一推断则询问用户。
- 脚本含 `go build`、组装 `build/`、`docker build` 与 `push` 等，需 Docker、sudo、网络与镜像仓库可用；若环境不适合推送，与用户确认后可用 `go build ./...` 等仅编译验证，或调整脚本后再跑全流程。

## 阶段 7 — 更新测试环境（必做）
- 目标：将阶段 6 产物实际更新到测试环境，不能仅停留在“镜像已推送”。
- 按团队既有发布链路执行（发布平台 / Jenkins / 部署脚本 等）；使用哪个链路以仓库或团队约定为准。
- 执行前确认目标环境与目标模块（如 `task`）一致，避免误发到非目标环境。
- 发布命令或流水线失败立即 `FAIL` 并停止；禁止“跳过更新环境但宣称完成”。

## 阶段 8 — 报告结果
- 分支名、当前 `HEAD` 短 hash（若阶段 4 有新提交则强调该 hash）。
- 镜像仓库地址与 tag（以 `local_build.sh` 与实际输出为准）。
- 测试环境更新结果（环境名、模块、版本/镜像 tag、关键日志）。
- 各阶段 `PASS`/`FAIL`/跳过 汇总一行。

## Output Contract
- 每个大步报告 `PASS` 或 `FAIL`。
- `FAIL` 时包含：命令、关键错误行、下一步纠正建议。
- 全流程成功时包含：分支名、commit hash、改动摘要、镜像信息（若阶段 6 执行）。
