# 🔴 AgentForge 铁律（不可违反）

> 所有智能体在处理任何任务时必须遵守。违反任何一条 = 阻断提交。
> 唯一源头文件：修改此文件后所有智能体自动生效。

---

## 一、Bug 状态管理

- **已关闭/已解决的 Bug 禁止处理** — 处理前检查禅道 status，resolved/closed 直接跳过
- **人类提的 Bug 只加备注不改状态** — reporter 是人类账号时，不改 status、不改 assignedTo
- **智能体提的 Bug 可改分配和加备注** — 状态变更等测试通过后由华佗确认
- **每个修复必须有 git commit** — 格式: `fix(#bug_id): 简要描述`
- **🔴 修复完成必须提交** — `git add --all && git commit && git push`，未提交=没修
- **🔴 修复必须合并到 develop** — 工作树 commit ≠ 生效，必须 cherry-pick/merge 到 develop
- **🔴 未合并到 develop 的修复等于没修** — 验收时检查 develop 上是否有该 commit
- **🔴 修复必须编译部署后才算完成** — `mvn package` → `systemctl restart` → 验证启动时间

---

## 二、修复流程

- **一次只修一个 Bug**，不扩大范围
- **修前必须完整获取 Bug 全部信息** — 描述、复现步骤、所有截图/附件、所有备注历史。禁止只看标题就写代码
- **修复前必须读 AGENTS.md**
- **修复后必须验证编译** — `mvn compile` / `vue-tsc --noEmit` 0 error
- **commit 前必须验证** — 编译通过 + 无新增 lint 警告

---

## 三、全链路 6 环分析

涉及数据库字段的 Bug 必须走完整链路：
```
前端/页面 → Controller → Service → Mapper → DB/SQL → 关联模块
 ①录入      ②验证      ③业务     ④持久化    ⑤存储     ⑥联动
```

---

## 四、状态值一致性（来自 Bug #574 教训）

修改任何状态值前，**必须**列出完整链路并逐项检查：
1. 枚举定义（如 `SlotStatus`）的值
2. Service 层设置的状态值是否与枚举一致
3. 查询/列表接口的状态映射是否覆盖所有枚举值
4. 前端 `STATUS_CLASS_MAP` 是否包含新状态
5. 前端过滤条件（`v-if`、`v-for`）是否兼容新状态
6. 池/统计表的聚合 SQL 是否包含新状态值

**禁止**：只改一端不检查其他端。

---

## 五、状态变更影响面分析（来自 Bug #574→575 教训）

改任何状态枚举值前，**必须**执行影响面分析：
1. `rg "原状态枚举名" --type java` 列出所有引用文件
2. 逐个检查：设置值？查询过滤？显示映射？统计聚合？
3. 检查逆向流程：退号、取消、停诊是否兼容新状态
4. 检查 XML mapper 中所有查询过滤条件
5. 检查前端所有 v-if/v-for/disabled 条件

**禁止**：只改正向流程不验逆向流程。

---

## 六、逆向流程验证（来自 Bug #575 教训）

涉及状态流转的 Bug，验证时**必须**覆盖：
- 正向：预约→签到→就诊→完成
- 逆向：退号、取消预约、停诊、退费
- 边界：并发操作、重复操作、异常中断

**禁止**：只测正向流程就标记"修复完成"。

---

## 七、全链路验证（状态流转 Bug 必做）

修复后按以下顺序验证，**编译通过不等于修复完成**：
```
① 数据库：SELECT status FROM table WHERE id = ?  → 确认写入正确
② 后端接口：检查所有 if/switch 分支  → 确认映射正确
③ 前端显示：检查 STATUS_CLASS_MAP  → 确认文本正确
④ 前端交互：检查 v-if/v-for/disabled  → 确认按钮状态正确
⑤ 统计数据：检查聚合 SQL  → 确认统计包含新状态
```

---

## 八、池/统计表同步（来自 Bug #574 反复修复教训）

- **任何状态变更必须同步更新关联统计表**
- 检查清单：
  1. 状态变更后，哪些统计字段需要更新？
  2. 是原子递增/递减，还是全量重算？
  3. 并发安全：用 `SET field = field + 1` 还是先查后改？
  4. 逆向操作（退号/取消）是否正确回滚统计？
- **禁止**：只改状态不改统计，或只改统计不改状态

---

## 九、统计变更必须验证实际值（来自 Bug #575 教训）

- 修改统计逻辑后，**必须查数据库验证实际值**
- `SELECT booked_num, locked_num FROM adm_schedule_pool WHERE id = ?`
- 对比操作前后的值，确认统计正确
- **禁止**：改了统计逻辑不查数据库验证

---

## 十、禁止删除源文件

- **绝对禁止**删除项目中已有的 Java/Vue/SQL 源文件
- 编译错误 → 修复错误，不删除文件
- 重复文件 → 重构合并，不删除文件
- AI 幻觉文件 → 检查 `git ls-tree baseline -- <file>` 确认后再删除
- **唯一例外**：人类明确确认删除

---

## 十一、禁止修改已有公开方法签名

- 不能删除或重命名已有的 public 方法
- 不能修改已有方法的参数列表
- 需要新功能 → 添加重载方法
- 需要改行为 → 修改方法内部实现

---

## 十二、搜索所有相关代码路径

修复前必须用 `rg` 搜索：
```
rg "状态枚举名|相关方法名|相关字段名" --type java --type vue
```
确保不遗漏任何引用路径。

---

## 十三、数据库铁律

- **修前必须查询真实数据库** — 确认表结构、字段约束、索引
- **禁止凭猜测写 SQL** — 先 `\d table_name` 查看表结构
- **修改 SQL 后必须验证** — `EXPLAIN` 或实际查询验证语法
- **NOT NULL 约束必须检查** — INSERT/UPDATE 前先查 `is_nullable`
- **关联表必须查完整** — 涉及 JOIN 查所有关联表结构和外键
- **涉及 SQL 必须先查真实数据库**

---

## 十四、测试铁律

- Playwright 必须 `--workers=1`
- 超时 120 秒，最多重试 3 次
- 测试失败自动重试，超过 3 次通知人工介入
- 测试结果写入禅道备注
- **DB审查失败自动回退** — 路由回原修复智能体

---

## 十五、归档铁律

- **三重写入** — Git + SQLite + Redis
- SQLite 必须使用完整字段
- 禅道备注格式：`[📝 陈琳归档] Bug #xxx`
- 归档报告必须包含：基本信息 + 根因分析 + 修复文件 + 流程时间线

---

## 十六、禅道交互

- 备注使用 resolve+activate workaround
- 不直接调用 comment API（会 404）
- 图片附件必须 OCR 读取

---

## 十七、质量门禁

- L1: 编译通过
- L2: 测试通过
- L3: DB审查通过
- L4: 验收通过
- L5: 归档完成

---

## 过往教训

| Bug | 教训 | 根因 |
|---|---|---|
| #574 | 状态值 BOOKED(1)→应为 CHECKED_IN(3)，前端映射缺失 | 没走完整状态链路 |
| #574 | AI 看到编译错误直接删文件 | 没检查 git baseline |
| #574 | 多次 fallback 修错文件（OrderServiceImpl） | 没用 rg 搜索所有引用 |
| #574 | 签到后 booked_num 未累加 | 只改状态没改统计 |
| #575 | 改了签到状态没检查退号流程 | 只验正向不验逆向 |
| #575 | booked_num 应在预约时累加而非签到时 | 统计变更未验证实际值 |
| — | 修复完成未提交到 develop | 框架未强制验证提交 |
| — | 退号流程只检查 BOOKED(1) 不兼容 CHECKED_IN(3) | 状态变更影响面分析缺失 |

---

## 十八、禁止硬编码业务默认值（来自 Bug #617 教训）

- **禁止**在提交参数中硬编码业务默认值（如 `contractNo: '0000'`）
- 必须使用用户在表单中选择的值，硬编码值仅作为 fallback
- 检查清单：
  1. 表单字段是否有 `v-model` 绑定？
  2. 构建提交参数时是否使用了绑定值？
  3. 提交后是否覆盖了用户选择？
- **禁止**：用户选了医保，提交时却写死为自费

---

## 过往教训（补充）

| Bug | 教训 | 根因 |
|---|---|---|
| #617 | 费用性质硬编码为 '0000'（自费），用户选医保无效 | 构建参数时写死默认值 |

---

## 十九、前端验证铁律

- **提交前必须编译前端** — `npm run build` 或 `npx vite build` 通过才算完成
- **禁止只改 .vue 文件不验证编译** — 改完必须跑一次编译确认无报错
- **SCSS 括号闭合必须检查** — `<style lang="scss" scoped>` 内的所有 `{}` 必须成对闭合
- **SCSS 嵌套层级不超过 4 层** — 过深嵌套说明结构需要重构
- **编译报错必须当场修复** — 看到 error 立即修，不要留到下一步

### SCSS 检查清单

```bash
# 编译验证
cd openhis-ui-vue3 && npm run build

# 如果编译报错，检查 SCSS
grep -n "{" src/views/xxx/index.vue | wc -l  # 开括号数
grep -n "}" src/views/xxx/index.vue | wc -l  # 闭括号数
# 两者必须相等
```

---

## 二十、提交前验证铁律

- **后端**: `mvn compile` 通过 + 无新增 warning
- **前端**: `npm run build` 通过 + 无 SCSS 错误
- **禁止跳过编译直接提交** — 编译失败的代码不允许进仓库
- **提交信息格式**: `type(scope): description`（如 `fix(charge): 修复退费金额计算`）

### 提交前检查流程

```bash
# 1. 后端编译
cd openhis-server-new && mvn compile -pl openhis-application -am

# 2. 前端编译
cd openhis-ui-vue3 && npm run build

# 3. 两个都通过才提交
git add --all && git commit -m "type(scope): description"
```

---

## 二十六、resolve 前必须验证 develop commit（来自 v0.5.1 修复）

- **禁止**仅凭 worktree 未提交变更就 resolve Bug
- resolve 前必须检查 `git log origin/develop --grep="Bug#{id}"` 是否有 commit
- `comment_bug` 用 resolve+activate workaround，activate 失败会导致 bug 卡在 resolved
- `ok_to_commit` 必须要求 `has_fix_commit = true`（develop 上有实际 commit）
- **验证方式**: `git log origin/develop --grep="Bug#{id}" --oneline -1` 有输出才允许 resolve

---

## 二十七、comment_bug 禁止改状态铁律（来自 v0.5.2 修复）

- **禁止**使用 resolve+activate workaround 添加备注 — activate 失败会导致 bug 卡在 resolved
- 添加备注必须使用不改状态的方式：CLI `zentao bug update --comment` 或 API `PUT /bugs/{id}`
- `comment_bug` 函数必须只写 comment，不触发任何状态变更
- **教训**: 36 个 bug 因 activate 失败被误标为 resolved，无代码提交

### 正确做法

```rust
// ✅ 正确：只加备注，不改状态
zentao bug update --id <BUG_ID> --comment "备注内容"

// ❌ 错误：resolve+activate 会改状态
POST /bugs/{id}/resolve  // 改为 resolved
POST /bugs/{id}/activate  // 如果失败，bug 卡在 resolved
```

---

## 二十八、文件快照禁用覆盖判定铁律（来自 v0.5.2 修复）

- **禁止**用主仓库文件快照 diff 覆盖 success 判定
- success 判定必须基于 agent worktree 的实际变更（`count_changed_files` + `has_fix_commit`）
- 主仓库快照仅用于日志记录，不能影响判定结果
- **教训**: 主仓库快照检测到其他 agent 的变更，误判当前 agent 修复成功

### 根因

```
Agent A cherry-pick 到 develop → 主仓库有变更
Agent B 运行 → 主仓库快照检测到 A 的变更 → 误判 B 修复成功
```

### 正确做法

```rust
// ✅ 正确：基于 worktree 判定
let changes = count_worktree_changes(agent_name);  // 检查 worktree
let has_fix = has_recent_fix_commit(agent_name, bug_id);  // 检查 develop commit

// ❌ 错误：基于主仓库判定
let file_diff = snapshot_and_diff(main_repo_dir, &before);  // 检查主仓库
if has_real_changes { r.success = true; }  // 误判
```

---

## 二十九、Worktree 必须存在且为 Git 仓库铁律

- 每个 agent 的 worktree 目录必须存在且包含 `.git` 文件
- 启动 executor 前必须验证 worktree 存在：`test -d /tmp/agentforge-worktrees/{agent}`
- worktree 不存在时必须创建：`git worktree add /tmp/agentforge-worktrees/{agent} -b {agent}`
- **教训**: 4 个 agent（zhangfei, chenlin, huatuo, liubei）无 worktree，codex 运行失败但仍标记成功

### 验证命令

```bash
# 检查所有 agent worktree
for agent in zhaoyun guanyu xunyu zhangfei huatuo chenlin zhugeliang liubei; do
  if [ -d "/tmp/agentforge-worktrees/$agent/.git" ]; then
    echo "✅ $agent: worktree OK"
  else
    echo "❌ $agent: worktree MISSING"
    cd /root/.openclaw/workspace/his-repo
    git worktree add /tmp/agentforge-worktrees/$agent -b $agent
  fi
done
```

---

## 三十、Bug 状态变更必须双重确认铁律

- resolve Bug 前必须检查当前状态：`zentao bug get --id {id} | grep status`
- 只有 `status: active` 的 Bug 才允许 resolve
- resolve 后必须验证状态：`zentao bug get --id {id} | grep status` 确认为 `resolved`
- activate 后必须验证状态：确认恢复为 `active`
- **教训**: 批量操作 36 个 bug 时，1 个因状态不对失败，需要逐个检查

### 批量操作模板

```bash
source /root/.config/zentao/.env
for id in 711 710 709; do
  # 1. 检查当前状态
  status=$(zentao bug get --id "$id" 2>&1 | grep "status:" | awk '{print $2}')
  if [ "$status" != "active" ]; then
    echo "⚠️ Bug #$id: 当前状态=$status，跳过"
    continue
  fi
  # 2. 执行操作
  zentao bug activate --id "$id" --data '{"openedBuild":"6"}'
  # 3. 验证结果
  new_status=$(zentao bug get --id "$id" 2>&1 | grep "status:" | awk '{print $2}')
  echo "Bug #$id: $status → $new_status"
done
```