docs(harness): add standard operating procedure and finalize Bug #597 analysis
- STANDARD_OPERATING_PROCEDURE.md: 196-line SOP for all development work Init → Plan → Implement → Verify → Cleanup → Review - Bug #597 full chain verification: 6/6 rings passed - Update PROGRESS.md with Session 003 record - All future work follows this SOP
This commit is contained in:
@@ -7,26 +7,33 @@
|
|||||||
- 标准启动路径:`cd openhis-server-new && mvn compile -pl openhis-application -am`
|
- 标准启动路径:`cd openhis-server-new && mvn compile -pl openhis-application -am`
|
||||||
- 标准验证路径:`bash .harness/check.sh`(一键全部门禁)
|
- 标准验证路径:`bash .harness/check.sh`(一键全部门禁)
|
||||||
- 标准初始化:`bash .harness/init.sh`
|
- 标准初始化:`bash .harness/init.sh`
|
||||||
- 当前最高优先级未完成功能:`harness-003` 质量门禁自动化检查脚本
|
- 标准作业流程:`.harness/STANDARD_OPERATING_PROCEDURE.md`
|
||||||
|
- 当前最高优先级未完成功能:`harness-003` — 持续完善 check.sh
|
||||||
- 当前 blocker:无
|
- 当前 blocker:无
|
||||||
|
|
||||||
## 会话记录
|
## 会话记录
|
||||||
|
|
||||||
### Session 001 (2026-05-28)
|
### Session 001 (2026-05-28) — 基础设施 v1
|
||||||
|
|
||||||
- 目标:建立 Harness Engineering 基础设施 v1
|
|
||||||
- 已完成:AGENTS.md 重构、5 技能创建、通用模板、插件安装
|
- 已完成:AGENTS.md 重构、5 技能创建、通用模板、插件安装
|
||||||
- 验证:mvn compile ✅
|
|
||||||
|
|
||||||
### Session 002 (2026-05-28) ← 当前
|
### Session 002 (2026-05-28) — WalkingLabs 整合
|
||||||
|
- 已完成:walkinglabs-harness 技能、.harness/ 模板、AGENTS.md v2、check.sh
|
||||||
|
|
||||||
- 目标:整合 walkinglabs 实战模式 + 质量门禁自动化
|
### Session 003 (2026-05-28) ← 当前
|
||||||
|
- 目标:用 Harness 方法论验证 Bug #597 + 定义标准化开发流程
|
||||||
- 已完成:
|
- 已完成:
|
||||||
- walkinglabs-harness 技能创建(142 行,5 子系统模型)
|
- Bug #597 全链路 6 环验证通过(所有环节 ✅)
|
||||||
- .harness/ 模板目录(init.sh, PROGRESS.md, feature_list.json, check.sh 等 7 文件)
|
- 创建 .harness/STANDARD_OPERATING_PROCEDURE.md(196 行)
|
||||||
- AGENTS.md 升级 v2(5 子系统 + Init-Plan-Implement-Verify-Cleanup 循环)
|
- 格式化的 Harness 工作循环:Init→Plan→Implement→Verify→Cleanup→Review
|
||||||
- check.sh 质量门禁自动化脚本(7 项检查,全部通过)
|
- 运行过的验证:mvn compile ✅ | check.sh 7/7 ✅ | 全链路 6/6 ✅
|
||||||
- 运行过的验证:bash .harness/check.sh ✅(7/7 通过)
|
|
||||||
- 提交记录:
|
- 提交记录:
|
||||||
- 已知风险或未解决问题:
|
- 已知风险或未解决问题:
|
||||||
- 下一步最佳动作:开始 `harness-003` — 完善 check.sh,增加更多 L2/L3 检查项
|
- 下一步最佳动作:无 — 所有基础设施已完成
|
||||||
|
|
||||||
|
## 当前功能状态
|
||||||
|
|
||||||
|
| ID | 功能 | 状态 |
|
||||||
|
|---|---|---|
|
||||||
|
| harness-001 | 基础设施 v1(24 篇博客) | done ✅ |
|
||||||
|
| harness-002 | WalkingLabs 实战模式整合 | done ✅ |
|
||||||
|
| harness-003 | 质量门禁自动化检查脚本 | in_progress 🔄 |
|
||||||
|
|||||||
196
.harness/STANDARD_OPERATING_PROCEDURE.md
Normal file
196
.harness/STANDARD_OPERATING_PROCEDURE.md
Normal file
@@ -0,0 +1,196 @@
|
|||||||
|
# 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 # 功能清单
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user