2026-04-19-02-00-33 建立代码编纂工作流：工程分析框架、经验记录迁移、工作流规范制定

2026-04-19 02:04:40 +08:00
parent 1dc3d60248
commit 96b295f919
3 changed files with 900 additions and 0 deletions
--- a/工程分析/工作流规范.md
+++ b/工程分析/工作流规范.md
@@ -0,0 +1,283 @@
+# 代码编纂工作流规范
+
+> 版本：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`