# 代码编纂工作流（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: 时间戳记录 每次执行流程前，首先获取当前时间戳： ```bash 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` **文档模板**: ```markdown # 需求分析 - {timestamp} ## 需求来源 - 提出时间: {timestamp} - 需求类型: [功能新增 / 缺陷修复 / 性能优化 / 代码重构 / 文档更新] ## 原始需求描述 {用户原始需求的完整记录} ## 需求拆解 ### 需求 1: {子需求标题} - **详细描述**: - **优先级**: [P0-阻塞 / P1-高 / P2-中 / P3-低] - **影响范围**: {涉及的文件/模块} - **验收标准**: {明确的完成标准} ### 需求 2: ... ## 约束条件 - 技术约束: {如兼容 React 19、TailwindCSS 4 等} - 业务约束: {如中文界面、深色主题等} - 时间约束: {如有} ## 风险评估 | 风险点 | 影响 | 缓解措施 | |--------|------|----------| | {风险} | {高/中/低} | {措施} | ``` --- ### 阶段 3: 实现方案 **目标**: 制定详细的代码修改计划，确保方案可行且最小侵入。 **输出文件**: `./工程分析/实现方案-{timestamp}.md` **文档模板**: ```markdown # 实现方案 - {timestamp} ## 对应需求 - 需求分析文档: `需求分析-{timestamp}.md` ## 方案概述 {总体技术思路和目标} ## 修改文件清单 ### 文件 1: `{文件路径}` - **修改类型**: [新增 / 修改 / 删除] - **修改内容**: {具体说明} - **关键代码逻辑**: {伪代码或关键实现要点} ### 文件 2: ... ## 新增依赖 | 依赖名 | 版本 | 用途 | |--------|------|------| | {name} | {ver} | {用途} | ## 兼容性分析 - 与现有功能的冲突: {分析} - 回滚策略: {如需回滚，步骤是什么} ## 预估工作量 - 代码编写: {时间} - 测试验证: {时间} - 文档更新: {时间} ``` **审核要求**: - 完成后必须停止，等待用户阅读并确认 - 用户确认后，方可进入下一阶段 - 如用户提出修改意见，更新方案后重新提交审核 --- ### 阶段 4: 测试方案 **目标**: 定义如何验证修改的正确性和稳定性。 **输出文件**: `./工程分析/测试方案-{timestamp}.md` **文档模板**: ```markdown # 测试方案 - {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`（追加模式） **记录格式**: ```markdown ## {timestamp} - {需求简述} ### A. 具体问题 {清晰描述遇到的具体问题} ### B. 产生问题原因 {分析问题产生的根本原因} ### C. 解决问题方案 {详细说明解决步骤和方法} ### D. 后续如何避免问题 {给出可操作的预防措施} ``` **记录时机**: - 执行过程中遇到任何非预期问题，均应记录 - 即使问题未导致阻塞，但有参考价值，也应记录 - 如执行过程完全顺利，可记录 "本次执行顺利，无异常问题" --- ### 阶段 8: Gitea 备份 **目标**: 将修改后的代码安全备份到 Gitea 仓库。 **操作命令**: ```bash # 确认当前分支 git branch # 添加所有变更 git add . # 提交（commit message 格式: "{timestamp} - {修改简述}"） git commit -m "{timestamp} - {修改简述}" # 推送到远程 git push origin main ``` **注意事项**: - 确保 `node_modules/` 和 `dist/` 不在提交范围内（检查 `.gitignore`） - 提交前确认没有遗漏的文档文件（`工程分析/` 目录下的文档必须一并提交） - 推送成功后，向用户汇报备份完成 --- ### 阶段 9: 重新部署 **目标**: 将修改后的代码部署到运行环境。 **部署步骤**: ```bash # 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 助手建立，经用户审核后生效。后续任何流程变更需经双方确认后更新本文档。