# Harness 标准作业程序 (SOP)

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

## 流程全景

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

---

## 步骤详解

### Step 1: Init — 环境就绪

```bash
# 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 — 门禁检查

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

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

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

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

---

### Step 5: Cleanup — 状态更新

```bash
# 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 → 当前任务先完成
```

---

## 速查命令

```bash
# 诊断
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 # 功能清单
```