his/.qoder/rules/IRON_LAWS.md

🔴 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 检查清单

# 编译验证
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): 修复退费金额计算）

提交前检查流程

# 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，无代码提交

正确做法

// ✅ 正确：只加备注，不改状态
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 修复成功

正确做法

// ✅ 正确：基于 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 运行失败但仍标记成功

验证命令

# 检查所有 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 个因状态不对失败，需要逐个检查

批量操作模板

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