admin/Pre_Seg_Server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
061f4ed25b27f5e1b7d88fa2869299987adbf74e
Pre_Seg_Server/工程分析/代码编纂工作流.md

13 KiB
Raw Blame History

代码编纂工作流（Code Compilation Workflow）

本文档定义了所有项目修改需求的标准执行流程。自 2026-04-28 起生效，后续所有项目修改必须严格按此流程执行。

流程概览

┌─────────────────────────────────────────────────────────────────────────────┐
│  阶段 0: 记录时间戳                                                          │
│  记录当前时间: {Year}-{Mon}-{Day}-{Hour}-{Min}-{Sec}                        │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 1: 工程分析                                                            │
│  阅读或创建 "./工程分析" 文件夹，确保项目整体分析文档存在且最新               │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 2: 需求分析                                                            │
│  将用户提出的需求整理写入 "./工程分析/需求分析-{timestamp}.md"               │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 3: 实现方案（需人工审核）                                              │
│  编写 "./工程分析/实现方案-{timestamp}.md"，完成后提交用户确认               │
│  ⚠️ 未经用户审核确认，不得进入下一阶段                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 4: 测试方案（需人工审核）                                              │
│  编写 "./工程分析/测试方案-{timestamp}.md"，完成后提交用户确认               │
│  ⚠️ 未经用户审核确认，不得进入下一阶段                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 5: 执行前准备                                                          │
│  阅读 "./工程分析/经验记录.md"，避免重复犯错                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 6: 方案执行                                                            │
│  按审核通过的实现方案执行代码修改                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 7: 经验沉淀                                                            │
│  在 "./工程分析/经验记录.md" 中按四段式记录关键问题                           │
│  A. 具体问题  B. 产生原因  C. 解决方案  D. 后续如何避免                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 8: Gitea 备份                                                          │
│  提交代码到 Gitea 仓库，commit 格式: "{timestamp} - {修改简述}"             │
├─────────────────────────────────────────────────────────────────────────────┤
│  阶段 9: 项目重新部署                                                        │
│  重新构建并部署本项目                                                        │
└─────────────────────────────────────────────────────────────────────────────┘

各阶段详细规范

阶段 0: 时间戳记录

每次执行流程前，首先获取当前时间戳：

date "+%Y-%m-%d-%H-%M-%S"
# 输出格式示例: 2026-04-28-22-55-15

此时间戳将贯穿整个流程，用于统一命名所有相关文档。

阶段 1: 工程分析

目标: 确保对项目现状有全面理解。

行动项:

  1. 确认 ./工程分析/ 目录存在
  2. 阅读 项目整体分析.md，确认其内容是否反映当前项目状态
  3. 如项目结构发生显著变化，更新 项目整体分析.md
  4. 阅读 AGENTS.md（项目根目录）获取最新技术栈信息

阶段 2: 需求分析

目标: 将用户原始需求转化为结构化、可执行的需求文档。

输出文件: ./工程分析/需求分析-{timestamp}.md

文档模板:

# 需求分析 - {timestamp}

## 需求来源
- 提出时间: {timestamp}
- 需求类型: [功能新增 / 缺陷修复 / 性能优化 / 代码重构 / 文档更新]

## 原始需求描述
{用户原始需求的完整记录}

## 需求拆解

### 需求 1: {子需求标题}
- **详细描述**: 
- **优先级**: [P0-阻塞 / P1-高 / P2-中 / P3-低]
- **影响范围**: {涉及的文件/模块}
- **验收标准**: {明确的完成标准}

### 需求 2: ...

## 约束条件
- 技术约束: {如兼容 React 19、TailwindCSS 4 等}
- 业务约束: {如中文界面、深色主题等}
- 时间约束: {如有}

## 风险评估
| 风险点 | 影响 | 缓解措施 |
|--------|------|----------|
| {风险} | {高/中/低} | {措施} |

阶段 3: 实现方案

目标: 制定详细的代码修改计划，确保方案可行且最小侵入。

输出文件: ./工程分析/实现方案-{timestamp}.md

文档模板:

# 实现方案 - {timestamp}

## 对应需求
- 需求分析文档: `需求分析-{timestamp}.md`

## 方案概述
{总体技术思路和目标}

## 修改文件清单

### 文件 1: `{文件路径}`
- **修改类型**: [新增 / 修改 / 删除]
- **修改内容**: {具体说明}
- **关键代码逻辑**: {伪代码或关键实现要点}

### 文件 2: ...

## 新增依赖
| 依赖名 | 版本 | 用途 |
|--------|------|------|
| {name} | {ver} | {用途} |

## 兼容性分析
- 与现有功能的冲突: {分析}
- 回滚策略: {如需回滚，步骤是什么}

## 预估工作量
- 代码编写: {时间}
- 测试验证: {时间}
- 文档更新: {时间}

审核要求:

  • 完成后必须停止，等待用户阅读并确认
  • 用户确认后，方可进入下一阶段
  • 如用户提出修改意见，更新方案后重新提交审核

阶段 4: 测试方案

目标: 定义如何验证修改的正确性和稳定性。

输出文件: ./工程分析/测试方案-{timestamp}.md

文档模板:

# 测试方案 - {timestamp}

## 对应实现方案
- 实现方案文档: `实现方案-{timestamp}.md`

## 测试范围
- {说明哪些功能需要测试}

## 测试用例

### 用例 1: {用例标题}
- **前置条件**: 
- **操作步骤**: 
- **预期结果**: 
- **通过标准**: 

### 用例 2: ...

## 回归测试
- [ ] 现有功能 A 不受影响
- [ ] 现有功能 B 不受影响
- [ ] 构建无错误 (`npm run build`)
- [ ] 类型检查无错误 (`npm run lint`)

## 测试环境
- 浏览器: {Chrome / Firefox / Edge}
- 分辨率: {1920x1080 等}
- 测试数据: {说明}

审核要求:

  • 完成后必须停止，等待用户阅读并确认
  • 用户确认后，方可进入下一阶段

阶段 5: 执行前准备

目标: 避免重复犯错，吸取历史经验。

行动项:

  1. 阅读 ./工程分析/经验记录.md
  2. 检查是否有与当前需求相关的历史经验
  3. 如有相关经验，在实现方案中标注注意事项

阶段 6: 方案执行

目标: 按审核通过的方案执行代码修改。

执行原则:

  1. 最小修改原则: 只修改方案中列出的文件，不做计划外的改动
  2. 逐步验证原则: 每完成一个文件的修改，进行局部验证
  3. 保持风格一致: 严格遵循 AGENTS.md 中的代码风格约定
  4. 中文界面原则: 所有新增 UI 文本必须使用中文

执行步骤:

  1. 按文件清单逐个修改
  2. 每次修改后运行类型检查: npm run lint
  3. 全部修改完成后运行构建: npm run build
  4. 根据测试方案执行测试用例

阶段 7: 经验沉淀

目标: 将本次执行过程中遇到的问题和解决方案沉淀为组织知识。

输出文件: ./工程分析/经验记录.md（追加模式）

记录格式:

## {timestamp} - {需求简述}

### A. 具体问题
{清晰描述遇到的具体问题}

### B. 产生问题原因
{分析问题产生的根本原因}

### C. 解决问题方案
{详细说明解决步骤和方法}

### D. 后续如何避免问题
{给出可操作的预防措施}

记录时机:

  • 执行过程中遇到任何非预期问题，均应记录
  • 即使问题未导致阻塞，但有参考价值，也应记录
  • 如执行过程完全顺利，可记录 "本次执行顺利，无异常问题"

阶段 8: Gitea 备份

目标: 将修改后的代码安全备份到 Gitea 仓库。

操作命令:

# 确认当前分支
git branch

# 添加所有变更
git add .

# 提交（commit message 格式: "{timestamp} - {修改简述}"）
git commit -m "{timestamp} - {修改简述}"

# 推送到远程
git push origin main

注意事项:

  • 确保 node_modules/ 和 dist/ 不在提交范围内（检查 .gitignore）
  • 提交前确认没有遗漏的文档文件（工程分析/ 目录下的文档必须一并提交）
  • 推送成功后，向用户汇报备份完成

阶段 9: 重新部署

目标: 将修改后的代码部署到运行环境。

部署步骤:

# 1. 安装依赖（如有新增）
npm install

# 2. 生产构建
npm run build

# 3. 生产模式启动
npm start

验证:

  • 确认服务在端口 3000 正常启动
  • 访问 http://localhost:3000 验证应用可正常访问
  • 验证修改的功能是否生效

文档命名规范

文档类型 命名格式 示例
需求分析 需求分析-{YYYY-MM-DD-HH-MM-SS}.md 需求分析-2026-04-28-22-55-15.md
实现方案 实现方案-{YYYY-MM-DD-HH-MM-SS}.md 实现方案-2026-04-28-22-55-15.md
测试方案 测试方案-{YYYY-MM-DD-HH-MM-SS}.md 测试方案-2026-04-28-22-55-15.md
经验记录 经验记录.md（唯一文件，持续追加） 经验记录.md
项目分析 项目整体分析.md（唯一文件） 项目整体分析.md

流程执行检查表

每次执行流程时，使用以下检查表确保无遗漏：

  • 阶段 0: 已记录时间戳 {timestamp}
  • 阶段 1: 已阅读/更新 项目整体分析.md
  • 阶段 2: 已创建 需求分析-{timestamp}.md
  • 阶段 3: 已创建 实现方案-{timestamp}.md 并通过用户审核
  • 阶段 4: 已创建 测试方案-{timestamp}.md 并通过用户审核
  • 阶段 5: 已阅读 经验记录.md
  • 阶段 6: 已按方案执行所有修改
  • 阶段 7: 已更新 经验记录.md
  • 阶段 8: 已完成 Gitea 备份提交
  • 阶段 9: 已重新部署项目

特殊情况处理

紧急修复（Hotfix）

如遇到生产环境紧急缺陷需要立即修复，可简化流程：

  1. 仍然记录时间戳
  2. 创建简版需求分析（说明紧急性）
  3. 口头/即时通讯确认方案（跳过书面方案审核）
  4. 执行修复
  5. 事后补全: 24 小时内补全实现方案和测试方案文档
  6. 更新经验记录并提交备份

纯文档修改

如需求仅涉及文档更新（如修改 README）：

  1. 可跳过测试方案阶段
  2. 执行修改后直接备份

多次小修改合并

如同一时间段内有多个相关小需求：

  1. 可共用同一个时间戳
  2. 在需求分析中列出所有需求项
  3. 方案文档中分节说明各需求的实现

本工作流由 AI 助手建立，经用户审核后生效。后续任何流程变更需经双方确认后更新本文档。

Reference in New Issue View Git Blame Copy Permalink