hzdyjs/docs/变更管理

变更管理中心

📋 变更管理概述

变更管理中心负责记录、跟踪和管理项目开发过程中的所有变更，确保 Cursor AI 辅助开发 的每次代码调整都有完整的记录和追溯能力。

🎯 管理目标

核心价值

• 🔍 完整追溯：记录每次代码变更的原因、内容和影响
• 📊 数据驱动：通过变更数据分析项目进度和质量
• 🤖 AI 辅助：为 Cursor AI 提供历史变更上下文，提升开发效率
• 👥 团队协作：确保团队成员了解项目变更历史

管理原则

• 强制记录：所有代码变更都必须记录
• 及时更新：变更发生后立即记录
• 标准格式：使用统一的记录格式
• 分类管理：按变更类型和影响范围分类

📊 变更分类体系

按变更类型分类

🆕 新功能开发 (Feature)

• 描述：新增业务功能或模块
• 影响范围：通常涉及多个文件和模块
• 文档要求：需要更新 API 文档、用户手册
• 示例：新增用户管理模块、新增报告厅预约功能

🐛 Bug 修复 (Bugfix)

• 描述：修复已知的功能缺陷或错误
• 影响范围：通常限定在特定功能
• 文档要求：更新已有文档，记录修复内容
• 示例：修复登录验证 bug、修复数据查询错误

🔧 重构优化 (Refactor)

• 描述：改进代码结构，不改变外部行为
• 影响范围：内部代码结构调整
• 文档要求：更新技术文档和代码注释
• 示例：优化数据库查询、重构 service 层逻辑

📚 文档更新 (Documentation)

• 描述：更新项目文档、API 文档、用户手册
• 影响范围：文档文件
• 文档要求：记录文档变更内容
• 示例：更新 API 接口文档、完善开发指南

⚙️ 配置调整 (Configuration)

• 描述：修改系统配置、环境配置
• 影响范围：配置文件
• 文档要求：更新部署和配置文档
• 示例：调整数据库连接配置、修改缓存策略

按影响范围分类

🔴 重大变更 (Major)

• 定义：影响系统架构或核心功能的变更
• 批准要求：需要架构师或项目经理审核
• 测试要求：需要完整的回归测试
• 通知范围：全体团队成员

🟡 中等变更 (Minor)

• 定义：影响单个模块或功能的变更
• 批准要求：模块负责人审核
• 测试要求：模块相关功能测试
• 通知范围：相关开发人员

🟢 小变更 (Patch)

• 定义：局部代码调整或小 bug 修复
• 批准要求：开发人员自审
• 测试要求：基本功能验证
• 通知范围：直接相关人员

📝 变更记录标准格式

标准记录模板

## 调整记录 - YYYY-MM-DD HH:mm:ss

**变更 ID**: CHG-YYYYMMDD-001
**变更时间**: YYYY-MM-DD HH:mm:ss
**变更人员**: [开发者姓名/Cursor AI 辅助]
**变更类型**: 🆕 新功能/🐛Bug 修复/🔧 重构优化/📚 文档更新/⚙️ 配置调整
**影响级别**: 🔴 重大变更/🟡 中等变更/🟢 小变更

### 📋 变更概述

**变更目的**: [简述变更原因和目标，1-2 句话]
**影响范围**: [列出受影响的模块、功能或文件]

### 📁 涉及文件

**后端文件**:

-   backend/[具体文件路径 1]
-   backend/[具体文件路径 2]

**前端文件**:

-   web/[具体文件路径 1]
-   web/[具体文件路径 2]

**配置文件**:

-   [配置文件路径]

**文档文件**:

-   docs/[文档文件路径]

### 🔧 变更内容详述

**业务逻辑变更**:

1. [具体业务逻辑的变更说明]
2. [新增或修改的业务规则]

**技术实现变更**:

1. [技术方案的调整说明]
2. [代码结构的优化内容]

**接口变更**:

-   **新增接口**: [新增接口列表]
-   **修改接口**: [修改的接口及变更内容]
-   **废弃接口**: [废弃的接口及替代方案]

**数据库变更**:

-   **新增表**: [新增表及字段说明]
-   **修改表**: [表结构变更内容]
-   **数据迁移**: [数据迁移脚本或说明]

### 🎯 技术决策

**技术选型**: [使用的技术栈和原因]
**设计模式**: [采用的设计模式和考虑]
**性能优化**: [性能优化措施]
**安全考虑**: [安全性相关的处理]

### 📖 文档同步更新

**API 文档**:

-   [ ] 已更新 docs/开发文档/API.md
-   [ ] 已更新模块 API 接口设计文档

**业务文档**:

-   [ ] 已更新业务需求文档
-   [ ] 已更新用户操作手册

**技术文档**:

-   [ ] 已更新数据库设计文档
-   [ ] 已更新架构设计文档

### 🧪 测试验证

**功能测试**:

-   [ ] 单元测试通过
-   [ ] 集成测试通过
-   [ ] 功能验收测试通过

**质量检查**:

-   [ ] 代码规范检查通过
-   [ ] 代码 review 通过
-   [ ] 安全扫描通过

**性能验证**:

-   [ ] 响应时间满足要求
-   [ ] 并发性能测试通过
-   [ ] 内存使用正常

### 🚀 部署说明

**部署环境**: [开发/测试/生产环境]
**部署步骤**:

1. [部署步骤 1]
2. [部署步骤 2]
3. [部署步骤 3]

**回滚方案**: [如有问题的回滚方案]
**监控要点**: [需要重点监控的指标]

### 📝 备注

**已知问题**: [如有已知问题需要说明]
**后续计划**: [后续的改进或扩展计划]
**相关链接**: [相关的 Issue、PR 或文档链接]

---

🔄 变更管理流程

变更申请流程

flowchart TD
    A[需求提出] --> B[变更评估]
    B --> C{影响级别}
    C -->|重大变更| D[架构师审核]
    C -->|中等变更| E[模块负责人审核]
    C -->|小变更| F[开发人员自审]

    D --> G[制定变更计划]
    E --> G
    F --> G

    G --> H[代码开发]
    H --> I[代码审查]
    I --> J[测试验证]
    J --> K[文档更新]
    K --> L[部署发布]
    L --> M[变更记录]
    M --> N[跟踪反馈]

Cursor AI 辅助开发流程

flowchart TD
    A[AI代码生成] --> B[代码审查]
    B --> C[功能测试]
    C --> D{测试通过?}
    D -->|是| E[立即记录变更]
    D -->|否| F[修复问题]
    F --> C

    E --> G[更新相关文档]
    G --> H[提交代码变更]
    H --> I[通知团队成员]

    style E fill:#ff6b6b
    style G fill:#ff6b6b

紧急变更流程

flowchart TD
    A[紧急问题发现] --> B[快速评估]
    B --> C[紧急修复]
    C --> D[最小化测试]
    D --> E[紧急部署]
    E --> F[事后补充记录]
    F --> G[完整测试验证]
    G --> H[文档完善]

📊 变更统计分析

变更统计指标

数量统计

• 总变更数量：记录期间的总变更次数
• 类型分布：各类型变更的数量分布
• 影响级别分布：不同影响级别的变更比例
• 模块分布：各模块的变更频率

质量指标

• Bug 修复率：Bug 修复变更占总变更的比例
• 回滚率：需要回滚的变更比例
• 测试通过率：一次测试通过的变更比例
• 文档同步率：变更后文档同步更新的比例

效率指标

• 平均处理时间：从变更申请到完成的平均时间
• 审核效率：变更审核的平均时间
• AI 辅助比例：Cursor AI 参与的变更比例
• 自动化程度：自动化处理的变更比例

月度变更报告模板

# YYYY 年 MM 月变更管理报告

## 📊 变更概览

-   **总变更数**: XXX 次
-   **新功能**: XX 次 (XX%)
-   **Bug 修复**: XX 次 (XX%)
-   **重构优化**: XX 次 (XX%)
-   **文档更新**: XX 次 (XX%)
-   **配置调整**: XX 次 (XX%)

## 🎯 关键指标

-   **平均处理时间**: X.X 小时
-   **测试通过率**: XX%
-   **文档同步率**: XX%
-   **AI 辅助比例**: XX%

## 📈 趋势分析

[变更趋势的分析和总结]

## 🔍 问题发现

[发现的问题和改进建议]

## 📋 下月计划

[下月的变更管理改进计划]

🔧 变更管理工具

Cursor AI 集成工具

1. 变更记录助手

# Cursor AI 提示词模板
请根据刚才的代码变更，生成标准的变更记录：

变更类型：[新功能/Bug修复/重构优化/文档更新/配置调整]
变更文件：[具体文件列表]
变更内容：[具体变更说明]

请按照项目的变更记录模板格式生成完整记录。

2. 文档同步检查

# 文档同步检查提示
检查以下变更是否需要更新相关文档：

1. API接口变更 → 更新API.md
2. 数据库变更 → 更新数据库设计文档
3. 业务逻辑变更 → 更新业务需求文档
4. 配置变更 → 更新部署文档

请确认需要更新的文档列表。

自动化工具

Git Hook 集成

#!/bin/bash
# pre-commit hook - 提交前检查
echo "检查变更记录..."
if [[ -z $(git diff --cached --name-only | grep "docs/变更管理/code-adjust-record.md") ]]; then
    echo "⚠️  警告：代码变更未更新变更记录！"
    echo "请在 docs/变更管理/code-adjust-record.md 中记录本次变更"
    exit 1
fi

变更通知脚本

#!/bin/bash
# 变更通知脚本
send_change_notification() {
    local change_type=$1
    local change_files=$2
    local change_author=$3

    echo "🔔 变更通知"
    echo "类型：$change_type"
    echo "文件：$change_files"
    echo "作者：$change_author"
    # 发送到团队通知渠道
}

📋 质量控制检查清单

变更前检查

• 变更需求明确，目标清晰
• 影响范围评估完成
• 技术方案确定
• 测试计划制定
• 回滚方案准备

变更中检查

• 代码规范符合标准
• 单元测试编写完成
• 代码审查通过
• 集成测试通过
• 文档同步更新

变更后检查

• 功能验收通过
• 性能指标满足要求
• 无明显副作用
• 变更记录完整
• 团队成员已通知

🚀 持续改进计划

短期目标（1 个月内）

• 完善变更记录模板
• 建立自动化检查机制
• 优化 Cursor AI 集成流程
• 提升团队变更管理意识

中期目标（3 个月内）

• 建立变更影响分析工具
• 实现变更数据可视化
• 建立变更质量评估体系
• 优化变更审核流程

长期目标（6 个月内）

• 实现智能变更建议
• 建立变更风险预警机制
• 完善变更知识库
• 实现变更管理全自动化

---

📖 相关文档

• 代码调整记录：code-adjust-record.md
• 项目总览：项目总览
• 开发文档：开发文档
• 测试文档：测试文档

---

🎯 目标：通过标准化的变更管理，确保项目开发过程可控、可追溯，为 Cursor AI 提供完整的变更上下文，提升开发效率和质量。