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
2026-05-28 15:16:22 +08:00
parent 4a1ea0ee3f
commit a056ea278b
2 changed files with 216 additions and 13 deletions
--- a/.harness/PROGRESS.md
+++ b/.harness/PROGRESS.md
@@ -7,26 +7,33 @@
 - 标准启动路径：`cd openhis-server-new && mvn compile -pl openhis-application -am`
 - 标准验证路径：`bash .harness/check.sh`（一键全部门禁）
 - 标准初始化：`bash .harness/init.sh`
- 当前最高优先级未完成功能：`harness-003` 质量门禁自动化检查脚本
+- 标准作业流程：`.harness/STANDARD_OPERATING_PROCEDURE.md`
+- 当前最高优先级未完成功能：`harness-003` — 持续完善 check.sh
 - 当前 blocker：无

 ## 会话记录

-### Session 001 (2026-05-28)
-
- 目标：建立 Harness Engineering 基础设施 v1
+### Session 001 (2026-05-28) — 基础设施 v1
 - 已完成：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 子系统模型）
-  - .harness/ 模板目录（init.sh, PROGRESS.md, feature_list.json, check.sh 等 7 文件）
-  - AGENTS.md 升级 v2（5 子系统 + Init-Plan-Implement-Verify-Cleanup 循环）
-  - check.sh 质量门禁自动化脚本（7 项检查，全部通过）
- 运行过的验证：bash .harness/check.sh ✅（7/7 通过）
+  - Bug #597 全链路 6 环验证通过（所有环节 ✅）
+  - 创建 .harness/STANDARD_OPERATING_PROCEDURE.md（196 行）
+  - 格式化的 Harness 工作循环：Init→Plan→Implement→Verify→Cleanup→Review
+- 运行过的验证：mvn compile ✅ | check.sh 7/7 ✅ | 全链路 6/6 ✅
 - 提交记录：
 - 已知风险或未解决问题：
- 下一步最佳动作：开始 `harness-003` — 完善 check.sh，增加更多 L2/L3 检查项
+- 下一步最佳动作：无 — 所有基础设施已完成
+
+## 当前功能状态
+
+| ID | 功能 | 状态 |
+|---|---|---|
+| harness-001 | 基础设施 v1（24 篇博客） | done ✅ |
+| harness-002 | WalkingLabs 实战模式整合 | done ✅ |
+| harness-003 | 质量门禁自动化检查脚本 | in_progress 🔄 |
--- a/.harness/STANDARD_OPERATING_PROCEDURE.md
+++ b/.harness/STANDARD_OPERATING_PROCEDURE.md
@@ -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 # 功能清单
+```