# 代码编纂工作流规范

> 版本：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` 追加新记录（仅当实际遇到问题时），格式如下：

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

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

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

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

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

---

### 步骤 6：Git 备份

**提交规范**：
```bash
git add -A
git commit -m "{时间戳} {修改简要描述}"
git push origin main
```

**必须包含的信息**：
- 时间戳（与需求分析文档一致）
- 本次修改的简要描述（1-2 句话）

**完成后**：
- 明确提醒用户已完成 Gitea 备份

---

### 步骤 7：重新部署

**标准部署脚本**：
```powershell
# 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 }` |

---

## 四、文档模板

### 需求分析模板

```markdown
# 需求分析 — {时间戳}

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

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

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

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

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

### 实现方案模板

```markdown
# 实现方案 — {时间戳}

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

## 2. 详细步骤

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

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

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

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

### 测试方案模板

```markdown
# 测试方案 — {时间戳}

## 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`