zhaoyun
a056ea278b
- 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
197 lines
4.6 KiB
Markdown
197 lines
4.6 KiB
Markdown
# 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 # 功能清单
|
||
```
|