---
name: pre-merge-build-fix
description: >
  每次提交时询问是否执行构建检查；执行后端+前端全量构建并自动修复的闭环流程。
  触发短语：构建检查、build-fix、上线前构建、pre-merge build、
  build check、fix build errors。
---

# 合并前构建修复（闭环）

## 概览
在合并上线分支前，执行后端+前端全量构建；若失败，自动修复并立刻重试构建，循环直到通过或达到最大尝试次数。

## 触发场景
- **每次提交代码时**主动询问是否需要执行构建检查
- 用户可选择：
  - 执行全量构建并自动修复（推荐合并上线前）
  - 跳过本次构建检查
- 明确要求"构建检查""build-fix""上线前构建"时也会触发

## 项目约定（必须遵守）
- **构建入口唯一**：使用 `bash scripts/deploy/deploy.sh <env> build`
- **环境映射**：
  - 本地开发 → `dev`
  - `develop`/`staging` 分支 → `uat`
  - `production` 分支 → `production`
- **L1 本地优先只 build 改动侧**：根据 `git diff` 判断改动范围——动了 `backend/` 才 build backend，动了 `frontend/` 才 build frontend，节省时间；用 `--backend` / `--frontend` 参数控制
- **L2 CI 阶段必须全量 build**：CI 跑 `quality-gates.yml` 时不区分改动侧，前后端都构建作为"环境一致性兜底"
- **报告落地**：输出到 `logs/`（建议 `logs/build-fix/`）
- **闭环不中断**：失败后必须立即修复并重跑 build，不允许"先攒一堆再 build"
- **最大尝试次数**：每模块默认 **10 次**（backend 10 次 + frontend 10 次）

## 标准工作流（顺序执行）

### 1) 用户确认与预检查
- **询问用户**是否需要执行构建检查（在提交时触发）
  - 用户可选择"是"或"跳过"
  - 若用户选择跳过，直接结束流程
- 确认当前分支与环境映射：
  - 本地开发：`bash scripts/deploy/deploy.sh test build`
  - `develop` / `staging` 分支：`bash scripts/deploy/deploy.sh uat build`
  - `production` 分支：`bash scripts/deploy/deploy.sh production build`
- 若环境文件缺失导致构建失败（`.env`/`.env.uat`/`.env.pro`），**停止并告知用户**

### 2) 构建闭环（核心）

**判断本次构建范围**（L1 本地阶段必走）：

```bash
git diff --name-only HEAD~1  # 或对照 base branch
```

- 仅 `backend/**` 改动 → 只 build backend（`--backend`）
- 仅 `frontend/**` 改动 → 只 build frontend（`--frontend`）
- 两边都改 → 全量 build
- 仅 docs / scripts → 跳过 build

对应模块执行以下循环：

循环逻辑：
1. 执行构建命令（统一入口）
2. 若失败：
   - 提取"最高优先级阻塞错误"
   - 生成最小修复
   - 立刻重跑构建
3. 直到：
   - 构建成功 ✅
   - 或达到最大尝试次数 ❌
   - 或触发停机条件 ❌

> 例外：CI 阶段不判断改动侧，始终全量 build（`quality-gates.yml` 自动调度）。

### 3) 产出物（最终交付）
- 构建修复报告（必交付）
  - 固定路径：`logs/build-fix/build-fix-YYYY-MM-DD-HHMM.md`
  - 内容必须包含：
    - 使用的构建命令与环境
    - 每次失败的核心错误摘要
    - 每次修复的文件清单（最小差异说明）
    - 最终结果（成功/失败）
- 若涉及代码改动，**不自动提交**；需要用户明确要求才提交

## 自动修复优先级（建议）
优先自动修复（低风险）：
- import/路径错误、缺失导出
- 明确的类型错误（空值保护、类型标注）
- 明确的构建脚本参数或配置缺失

谨慎修复（需保持最小 diff）：
- 依赖版本调整（优先 patch/minor）
- lint 引起的构建失败（避免大范围格式化）

## 停机条件（必须停止并交给人工）
- 需要业务决策或契约变更
- 需要大规模重构
- 测试失败且与文档/契约冲突
- 环境不可用或无法复现

## 失败仍需交付
即使最终构建失败，也必须产出完整报告，标明失败原因与下一步建议。

## 报告模板（必须使用）
将以下模板原样落地到 `logs/build-fix/`：

```markdown
# 构建修复报告

日期：YYYY-MM-DD
环境：uat / production
合并方向：develop -> staging / staging -> production
构建入口：bash scripts/deploy/deploy.sh <env> build
最大尝试次数：backend=10, frontend=10

## 构建结果
- backend：成功 / 失败（尝试次数：N）
- frontend：成功 / 失败（尝试次数：N）

## 失败摘要（按尝试顺序）
1. [backend|frontend] 失败原因：
   - 错误摘要：
   - 关键日志（可简短）：
2. ...

## 修复记录（按尝试顺序）
1. [backend|frontend] 修复内容：
   - 文件清单：
   - 说明：
2. ...

## 结论
- 最终状态：成功 / 失败
- 需人工介入事项（如有）：
```