Mdeical_Sur_Report/工程分析/工作流规范.md

代码编纂工作流规范

版本：V1.0 适用范围：本项目所有代码修改、功能迭代、Bug 修复、重构任务 生效日期：2026-04-19

---

一、工作流总览

┌─────────────────────────────────────────────────────────────────────┐
│  0. 记录开始时间戳                                                    │
│  1. 阅读工程整体分析 + 经验记录                                       │
│  2. 需求分析 → 写入 需求分析-{时间}.md → 【用户审核】                 │
│  3. 实现方案 → 写入 实现方案-{时间}.md → 【用户审核】                 │
│  4. 测试方案 → 写入 测试方案-{时间}.md → 【用户审核】                 │
│  5. 执行前再次阅读 经验记录.md（防止踩坑）                            │
│     执行修改                                                          │
│     执行后向 经验记录.md 追加新踩坑记录（四段式）                      │
│  6. Git 提交 → Gitea 推送 → 提醒用户                                  │
│  7. npm 重新构建 + 部署                                               │
└─────────────────────────────────────────────────────────────────────┘

---

二、步骤详解

步骤 0：记录开始时间戳

每次接收到修改需求时，首先获取当前时间，格式为：

{Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}

示例：2026-04-19-02-00-33

该时间戳贯穿整个工作流，用于命名所有相关文档。

---

步骤 1：阅读工程分析文档

必做事项：

• 阅读 工程整体分析.md，确认当前架构、技术栈、高风险区域
• 阅读 经验记录.md，回顾与本次需求相关的历史踩坑记录
• 若 工程分析 文件夹或上述文档不存在，立即创建

---

步骤 2：需求分析

输出文件：需求分析-{时间戳}.md

必须包含的内容：

1. 需求背景：用户原始需求的转述
2. 需求拆解：将大需求拆分为可执行的原子任务
3. 影响范围：列出需要修改的文件清单（基于工程整体分析中的高风险区域判断）
4. 优先级排序：P0（阻塞）/ P1（重要）/ P2（优化）
5. 验收标准：明确"做到什么程度算完成"

流转规则：

• 文档写完后，必须停止执行，等待用户二次人工审核确认
• 用户确认后，方可进入步骤 3

---

步骤 3：实现方案

输出文件：实现方案-{时间戳}.md

必须包含的内容：

1. 方案概述：整体技术思路（1-3 句话）
2. 详细步骤：按文件/模块逐条列出修改点，每条包含：
   • 目标文件路径
   • 具体修改内容（新增/删除/修改的代码逻辑）
   • 与现有逻辑的兼容策略（如何处理旧数据、默认值、降级）
3. 依赖关系：哪些修改有先后顺序，哪些可以并行
4. 风险预案：如果方案失败，回滚策略是什么

流转规则：

• 文档写完后，必须停止执行，等待用户二次人工审核确认
• 用户确认后，方可进入步骤 4

---

步骤 4：测试方案

输出文件：测试方案-{时间戳}.md

必须包含的内容：

1. 测试范围：哪些功能需要验证
2. 测试步骤：手动的操作路径（因本项目无自动化测试）
3. 预期结果：每一步的正确输出是什么
4. 边界场景：异常输入、空值、大数据量、快速切换路由等
5. 回滚检查：验证失败后如何恢复到修改前状态

流转规则：

• 文档写完后，必须停止执行，等待用户二次人工审核确认
• 用户确认后，方可进入步骤 5

---

步骤 5：执行修改 + 经验沉淀

执行前：

• 最后一次阅读 经验记录.md，确认本次修改不会触发已知坑点
• 若发现新的潜在风险，在实现方案文档中补充后再执行

执行中：

• 严格按照实现方案的步骤执行，不擅自扩大修改范围
• 若遇到方案外的意外问题，暂停执行，记录问题，与用户沟通后再继续

执行后：

• 按测试方案逐项验证
• 向 经验记录.md 追加新记录（仅当实际遇到问题时），格式如下：

## 记录 N：{问题标题}

**A. 具体问题**
{问题描述}

**B. 产生问题原因**
{根因分析}

**C. 解决问题方案**
{具体修复步骤}

**D. 后续如何避免问题**
{给未来自己的警告}

---

步骤 6：Git 备份

提交规范：

git add -A
git commit -m "{时间戳} {修改简要描述}"
git push origin main

必须包含的信息：

• 时间戳（与需求分析文档一致）
• 本次修改的简要描述（1-2 句话）

完成后：

• 明确提醒用户已完成 Gitea 备份

---

步骤 7：重新部署

标准部署脚本：

# 1. 停止旧服务
Stop-Process -Id (Get-NetTCPConnection -LocalPort 4173 -ErrorAction SilentlyContinue).OwningProcess -Force -ErrorAction SilentlyContinue

# 2. 重新构建
npm run build

# 3. 以独立进程启动预览服务（避免后台任务超时杀死）
Start-Process -FilePath "powershell.exe" -ArgumentList "-Command","cd '$PWD'; npm run preview -- --host" -WindowStyle Hidden

# 4. 验证
Start-Sleep -Seconds 3
Invoke-WebRequest -Uri http://127.0.0.1:4173/ -UseBasicParsing -TimeoutSec 5

注意：

• 严禁使用 Shell(run_in_background=true) 运行 npm run preview，因为任务超时机制（默认 60s）会强制终止 preview 进程，导致服务中断（参见经验记录-21）。
• 必须使用 Start-Process 创建独立的 Windows 进程。

---

三、禁忌清单（严格执行）

编号	禁忌行为	后果	正确做法
1	跳过需求分析文档直接写代码	需求理解偏差，返工	必须先写文档，等用户确认
2	跳过实现方案文档直接改代码	架构混乱，影响范围失控	必须先写文档，等用户确认
3	跳过测试方案文档直接上线	遗漏边界场景，线上故障	必须先写文档，等用户确认
4	使用 Shell(run_in_background=true) 运行 npm run preview	60s 后服务被强制杀死	使用 Start-Process 启动独立进程
5	修改后不更新 经验记录.md	重复踩坑	每次遇到新问题必须追加记录
6	contentEditable 插入多行缩进 HTML	浏览器解析出额外文本节点，破坏排版	必须压缩为紧凑单行 HTML
7	直接 target.remove() 删除 DOM 节点	撤销栈失效，WebKit 误删父级 <p>	使用 Range.selectNode + execCommand('delete')
8	将 useRef 作为自动保存唯一数据源	StrictMode 下首次卸载覆盖有效 draft	自动保存函数从最新 React state 读取
9	异步循环中用 await setTimeout 阻塞	抽帧/UI 更新被串行延迟	使用裸 setTimeout 推入事件队列
10	用 body { padding } 控制打印边距	第二页及后续页边距失效	使用 @page { margin }

---

四、文档模板

需求分析模板

# 需求分析 — {时间戳}

## 1. 需求背景
{用户原始需求}

## 2. 需求拆解
- [ ] 任务 1：{描述}
- [ ] 任务 2：{描述}

## 3. 影响范围
| 文件 | 修改类型 | 风险等级 |
|------|----------|----------|
| {路径} | 新增/修改/删除 | 高/中/低 |

## 4. 优先级
- P0：{阻塞项}
- P1：{重要项}
- P2：{优化项}

## 5. 验收标准
- {标准 1}
- {标准 2}

实现方案模板

# 实现方案 — {时间戳}

## 1. 方案概述
{整体思路}

## 2. 详细步骤

### 步骤 1：{模块/文件}
**目标文件**：`{路径}`
**修改内容**：{详细描述}
**兼容策略**：{如何处理旧数据/默认值}

### 步骤 2：{模块/文件}
...

## 3. 依赖关系
- {步骤 A} 必须在 {步骤 B} 之前执行
- {步骤 C} 和 {步骤 D} 可并行

## 4. 风险预案
- 若 {某步骤} 失败，回滚方式为 {...}

测试方案模板

# 测试方案 — {时间戳}

## 1. 测试范围
{需要验证的功能点}

## 2. 测试步骤与预期结果

### 场景 1：{正常流程}
1. 操作：{步骤}
   预期：{结果}
2. 操作：{步骤}
   预期：{结果}

### 场景 2：{边界/异常}
...

## 3. 回滚检查
- 若测试失败，执行 `{命令}` 恢复到修改前状态

---

五、附录：项目快速参考

• 开发：npm run dev（端口 3000）
• 构建：npm run build
• 预览：npm run preview -- --host（端口 4173）
• 类型检查：npm run lint
• Gitea 仓库：http://192.168.31.5:5002/admin/Mdeical_Sur_Report.git
• 当前分支：main