his/.harness/STANDARD_OPERATING_PROCEDURE.md

Harness 标准作业程序 (SOP)

所有开发任务、Bug 修复、重构，必须遵循此流程。

流程全景

Init → Plan → Implement → Verify → Cleanup → Review
 │        │        │           │         │         │
 └─ 环境  └─ 全链路 └─ 约束内   └─ 门禁    └─ 状态   └─ 评分
    就绪    分析     修改        检查       更新     评审

---

步骤详解

Step 1: Init — 环境就绪

# 1. 确认在正确的目录
pwd

# 2. 运行初始化
bash .harness/init.sh

# 3. 读取当前进度
cat .harness/PROGRESS.md
cat .harness/feature_list.json

# 4. 查看最近变更
git log --oneline -5
git status --short

检查项：

• 编译通过 (mvn compile)
• 了解当前进行中的功能
• 了解最近提交

---

Step 2: Plan — 全链路分析

对于每个字段/功能的新增或修改，先画出完整数据流：

录入 → 保存 → 查询 → 修改 → 删除 → 关联
 │       │      │      │      │      │
 └前端    └API   └Mapper └回显   └软删除 └上下游
          └Ctrl  └DTO    └再保存         └计费
          └Svc   └前端                     └打印
          └Entity                          └报表
          └DB

检查清单（6 环）：

1. 录入 — 前端有输入入口？（弹窗、行编辑、表单）
2. 保存 — 前端→API→Controller→Service→Entity→DB，每个入口都传了吗？（注意多个 Service 实现类）
3. 查询 — DB→Mapper XML（UNION ALL 子查询统一加）→DTO→前端展示
4. 修改 — 编辑回显→修改保存→正确更新？
5. 删除/停止 — 状态变更会丢失该字段吗？
6. 关联 — 上下游（护士站、药房、计费、打印、报表）需要同步改吗？

输出： update_plan 分解步骤 + 风险评估

---

Step 3: Implement — 约束内修改

约束铁律：

• 一次只做一个功能（single_active_feature = true）
• 只动必要文件，禁止"顺便改进"无关代码
• 遵循 AGENTS.md 中的代码风格规范
• 涉及 Mapper XML 时，UNION ALL 所有子查询统一修改

修改原则：

• 安全 > 架构 > 质量 > 性能
• 增量修改，每步可回滚
• 每个检查点保存进度（update_plan）

---

Step 4: Verify — 门禁检查

# L1: 编译检查
cd openhis-server-new && mvn compile -pl openhis-application -am

# L2: 全链路门禁
bash .harness/check.sh

# L3: 人工审查（输出变更摘要）

输出变更摘要：

修改文件: N 个
新增行数: N
删除行数: N
影响模块: [模块列表]
风险等级: 低/中/高
变更摘要: [一句话描述做了什么]

---

Step 5: Cleanup — 状态更新

# 1. 更新进度
vim .harness/PROGRESS.md
# 添加新会话记录，更新完成状态

# 2. 更新功能清单
vim .harness/feature_list.json
# 标记完成/更新状态

# 3. 运行干净状态检查
cat .harness/clean-state-checklist.md
# 逐项确认

# 4. 提交
git add -A
git commit -m "type(scope): description"
git push origin develop

提交信息格式：

<type>(<scope>): <description>

type: feat | fix | refactor | docs | test | chore
scope: 模块名（如 mapper, service, harness）

---

Step 6: Review — 评审评分

对照 .harness/evaluator-rubric.md 逐项评分：

维度	满分	自评
正确性	2	行为是否符合目标
验证	2	门禁是否全部通过
范围纪律	2	是否超出任务边界
可靠性	2	能否重复执行
可维护性	2	代码是否规范
交接准备度	2	下一轮能否继续

结论： Accept / Revise / Block

---

异常处理

编译失败

失败 → 分析错误 → git restore 撤销 → 从检查点重试
持续失败（3次） → 上报人类

全链路不完整

发现缺环 → 记录到 PROGRESS.md blocker → 补充修复

范围蔓延

发现超出任务 → 创建新 feature → 当前任务先完成

---

速查命令

# 诊断
pwd                           # 确认目录
git status --short            # 查看变更
git log --oneline -5          # 查看历史
git diff --stat HEAD          # 变更统计

# 回滚
git checkout -- <file>        # 撤销单个文件
git reset HEAD~1              # 撤销上次提交（保留修改）

# 验证
bash .harness/init.sh         # 初始化
bash .harness/check.sh        # 全部门禁

# 状态
cat .harness/PROGRESS.md      # 进度
cat .harness/feature_list.json # 功能清单