1630 lines
42 KiB
Markdown
1630 lines
42 KiB
Markdown
# Git 提交规范
|
||
|
||
> **版本：** v1.3
|
||
> **创建日期：** 2025-11-16
|
||
> **更新日期：** 2026-01-22
|
||
> **适用范围：** 全项目（前端 + 后端 + 文档）
|
||
> **优先级：** ⭐⭐⭐⭐⭐ P0 必须遵守
|
||
|
||
---
|
||
|
||
## 🚨 紧急警告：必须每日提交！
|
||
|
||
> **🔴🔴🔴 血泪教训：DC模块代码全部丢失事件（2025-11-28）🔴🔴🔴**
|
||
|
||
### 事件回顾
|
||
|
||
**时间**：2025-11-27 - 2025-11-28
|
||
**丢失内容**：DC模块完整代码（约2天开发量）
|
||
- ❌ 4个Prisma数据表定义
|
||
- ❌ 4个Service类（HealthCheckService、TemplateService等）
|
||
- ❌ Controller和Routes
|
||
- ❌ 所有TypeScript代码文件
|
||
|
||
**保留内容**：
|
||
- ✅ 设计文档（数据库设计、API设计）
|
||
- ✅ 开发记录（Day2、Day3完成总结）
|
||
- ✅ 空目录结构
|
||
|
||
**丢失原因**：
|
||
- ❌ **代码写完后未提交到Git**
|
||
- ❌ **代码仅存在于Cursor临时缓存中**
|
||
- ❌ **Cursor缓存清理后，代码永久丢失**
|
||
- ❌ **Git中无任何提交记录，无法恢复**
|
||
|
||
### 🔥 强制规则（立即生效）
|
||
|
||
```bash
|
||
# ⭐⭐⭐⭐⭐ 每天下班前必须执行（无例外！）
|
||
git status
|
||
git add .
|
||
git commit -m "feat(module): Complete Day X development"
|
||
git push origin master
|
||
|
||
# ⚠️ 不提交 = 代码随时可能丢失！
|
||
```
|
||
|
||
**提交时机（任选其一，发生时必须提交）：**
|
||
1. ✅ **每天下班前**（最重要！无论代码是否完美）
|
||
2. ✅ **每次长时间离开电脑前**（午休、会议、外出）
|
||
3. ✅ **完成重要功能后**
|
||
4. ✅ **准备关闭Cursor前**
|
||
5. ✅ **电脑出现异常前**（如卡顿、死机征兆）
|
||
|
||
**绝对禁止：**
|
||
- 🔴 **禁止**依赖Cursor自动保存（Cursor不保证持久化）
|
||
- 🔴 **禁止**"稍后再提交"（稍后可能就忘记了）
|
||
- 🔴 **禁止**代码过夜不提交（一夜之间可能丢失）
|
||
- 🔴 **禁止**"代码还没完善不想提交"（不完善也要提交，总比丢失强）
|
||
|
||
### 💡 最佳实践
|
||
|
||
**每日工作流（推荐）：**
|
||
|
||
```bash
|
||
# 早上开始工作
|
||
git pull origin master # 拉取最新代码
|
||
|
||
# 开发过程中...
|
||
# [编写代码、测试功能]
|
||
|
||
# 🔥 每天下班前（强制执行！）
|
||
git status # 查看修改
|
||
git add . # 添加所有修改
|
||
git commit -m "feat(dc): Complete Day 2 - HealthCheck and Template services
|
||
|
||
Summary:
|
||
- Implement HealthCheckService with Excel parsing
|
||
- Implement TemplateService with 3 preset templates
|
||
- Add 4 Prisma models (dc_health_checks, dc_templates, etc.)
|
||
- Update documentation
|
||
|
||
Status: Basic functionality verified, ready for testing"
|
||
|
||
git push origin master # 推送到远程
|
||
|
||
# 现在可以安心下班！代码已安全备份 ✅
|
||
```
|
||
|
||
**🎯 记住：Git是代码的唯一可靠备份！未提交的代码 = 不存在的代码！**
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [远程仓库配置](#远程仓库配置)
|
||
2. [Commit Message 规范](#commit-message-规范)
|
||
3. [提交频率与时机](#提交频率与时机) ⭐ 重要原则
|
||
4. [分支管理策略](#分支管理策略)
|
||
5. [中文编码问题解决](#中文编码问题解决)
|
||
6. [Git 历史重写与维护](#git-历史重写与维护)
|
||
7. [代码审查流程](#代码审查流程)
|
||
8. [常见问题与最佳实践](#常见问题与最佳实践)
|
||
|
||
---
|
||
|
||
## 远程仓库配置
|
||
|
||
### 🌐 Gitee 仓库信息
|
||
|
||
**仓库地址：**
|
||
```
|
||
https://gitee.com/hahafeng117/AIclinicalresearch.git
|
||
```
|
||
|
||
**全局配置：**
|
||
```bash
|
||
git config --global user.name "HaHafeng"
|
||
git config --global user.email "gofeng117@163.com"
|
||
```
|
||
|
||
**中文编码配置：** ⭐ 重要
|
||
```bash
|
||
# 确保 Git 正确处理中文文件名和提交信息
|
||
git config --global core.quotepath false
|
||
git config --global gui.encoding utf-8
|
||
git config --global i18n.commit.encoding utf-8
|
||
git config --global i18n.logoutputencoding utf-8
|
||
```
|
||
|
||
**PowerShell 配置：**
|
||
```powershell
|
||
# 在 PowerShell Profile 中添加（$PROFILE 文件）
|
||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||
$env:LESSCHARSET = 'utf-8'
|
||
```
|
||
|
||
### 克隆仓库
|
||
|
||
```bash
|
||
# 初次克隆
|
||
git clone https://gitee.com/hahafeng117/AIclinicalresearch.git
|
||
|
||
# 查看远程仓库
|
||
git remote -v
|
||
```
|
||
|
||
---
|
||
|
||
## Commit Message 规范
|
||
|
||
### ⚠️ 重要提示：避免中文乱码
|
||
|
||
**强制要求：Commit Message 必须使用英文** ⭐⭐⭐
|
||
|
||
**原因**：
|
||
- Windows PowerShell 环境下，Git commit message 中的中文会出现乱码
|
||
- 中文乱码会导致提交历史难以阅读，影响团队协作
|
||
- 英文 commit message 是国际开源项目的标准实践
|
||
|
||
**✅ 正确示例：**
|
||
```bash
|
||
git commit -m "feat(asl): Implement full-text screening core service"
|
||
git commit -m "fix(frontend): Fix dropdown menu click issue"
|
||
git commit -m "docs: Add development guide for Day 2-3"
|
||
```
|
||
|
||
**❌ 错误示例：**
|
||
```bash
|
||
git commit -m "feat(asl): 实现全文复筛核心服务" # 会出现乱码
|
||
git commit -m "修复下拉菜单问题" # 会出现乱码
|
||
```
|
||
|
||
**例外情况**：
|
||
- 文件名和文件内容可以使用中文（Git 能正确处理 UTF-8 编码的文件）
|
||
- 仅 commit message 必须使用英文
|
||
|
||
---
|
||
|
||
### 📝 格式规范
|
||
|
||
**标准格式：**
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 类型
|
||
|
||
| Type | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `feat` | 新功能 | `feat(asl): 添加标题摘要初筛功能` |
|
||
| `fix` | Bug 修复 | `fix(frontend): 修复下拉菜单点击问题` |
|
||
| `docs` | 文档更新 | `docs: 添加 Git 提交规范文档` |
|
||
| `style` | 代码格式（不影响逻辑） | `style: 格式化代码，统一缩进` |
|
||
| `refactor` | 重构（不改变功能） | `refactor(backend): 重构用户认证逻辑` |
|
||
| `perf` | 性能优化 | `perf: 优化查询性能，添加索引` |
|
||
| `test` | 测试相关 | `test(asl): 添加初筛功能单元测试` |
|
||
| `chore` | 构建/工具相关 | `chore: 更新依赖包版本` |
|
||
| `build` | 构建系统 | `build: 配置 Docker 镜像` |
|
||
| `ci` | CI/CD 配置 | `ci: 添加 GitHub Actions 配置` |
|
||
| `revert` | 回滚提交 | `revert: 回滚提交 abc123` |
|
||
|
||
### Scope 范围
|
||
|
||
**模块级别：**
|
||
- `platform` - 平台基础层
|
||
- `uam` - 用户与权限中心
|
||
- `llm` - LLM 大模型网关
|
||
- `asl` - AI 智能文献
|
||
- `aia` - AI 智能问答
|
||
- `pkb` - 个人知识库
|
||
- `rvw` - 稿件审查系统
|
||
- `ssa` - 智能统计分析
|
||
- `admin` - 运营管理端
|
||
- `frontend` - 前端通用
|
||
- `backend` - 后端通用
|
||
- `docs` - 文档
|
||
|
||
**功能级别：**
|
||
- `(asl/screening)` - 文献初筛
|
||
- `(asl/extraction)` - 数据提取
|
||
- `(backend/auth)` - 用户认证
|
||
- `(frontend/layout)` - 页面布局
|
||
|
||
### Subject 主题
|
||
|
||
**✅ 推荐（英文）：**
|
||
```
|
||
feat(asl): Implement title and abstract screening
|
||
fix(frontend): Fix AgentChatPage conversation data extraction issue
|
||
docs: Add Day 23-24 work summary
|
||
refactor(backend): Optimize database connection pool configuration
|
||
```
|
||
|
||
**❌ 避免：**
|
||
```
|
||
更新代码 # 中文（会乱码）
|
||
fix bug # 没有说明具体问题
|
||
修复了一些问题 # 中文（会乱码）+ 信息不足
|
||
feat: add feature # 没有指明模块和具体功能
|
||
update code # 太笼统
|
||
```
|
||
|
||
**规则：**
|
||
- ⭐ **必须使用英文**（避免中文乱码）
|
||
- ✅ 使用祈使句（"Add" 而不是 "Added"）
|
||
- ✅ 首字母小写
|
||
- ✅ 不要以句号结尾
|
||
- ✅ 简洁明了（≤50字符）
|
||
|
||
### Body 详细描述
|
||
|
||
**可选，用于说明：**
|
||
- Why: 为什么做这个修改？
|
||
- What: 修改了什么？
|
||
- Impact: 有什么影响？
|
||
|
||
**示例（必须使用英文）：**
|
||
```
|
||
feat(asl): Implement title and abstract screening
|
||
|
||
Completed features:
|
||
- Add CSV file import
|
||
- Implement dual-model AI judgment (Qwen + DeepSeek)
|
||
- Add PICO configuration
|
||
- Implement batch processing and progress display
|
||
|
||
Technical details:
|
||
- Use Papa Parse for CSV parsing
|
||
- Integrate Dify API for AI judgment
|
||
- Use Ant Design Upload component
|
||
```
|
||
|
||
### Footer 脚注
|
||
|
||
**可选，用于：**
|
||
- 关闭 Issue：`Closes #123`
|
||
- 不兼容变更：`BREAKING CHANGE: Description`
|
||
- 关联 Issue：`Refs #456`
|
||
|
||
**示例（必须使用英文）：**
|
||
```
|
||
feat(backend): Refactor API routing structure
|
||
|
||
BREAKING CHANGE: API routes changed from /api/xxx to /api/v1/xxx
|
||
All frontend API calls need to be updated
|
||
|
||
Closes #123
|
||
Refs #456
|
||
```
|
||
|
||
### 完整示例
|
||
|
||
**示例 1：新功能（必须使用英文）**
|
||
```
|
||
feat(asl): Implement title and abstract screening
|
||
|
||
Features:
|
||
- Add CSV file import
|
||
- Implement dual-model AI judgment
|
||
- Add PICO configuration
|
||
|
||
Closes #123
|
||
```
|
||
|
||
**示例 2：Bug 修复（必须使用英文）**
|
||
```
|
||
fix(frontend): Fix AgentChatPage conversation data extraction issue
|
||
|
||
Problem: Conversation data not correctly extracted from response
|
||
Solution: Modify data parsing logic to handle nested structures
|
||
|
||
Fixes #234
|
||
```
|
||
|
||
**示例 3：文档更新（必须使用英文）**
|
||
```
|
||
docs: Add Day 23-24 work summary
|
||
|
||
Contents:
|
||
- Knowledge base development summary
|
||
- Issues encountered and solutions
|
||
- Next steps
|
||
```
|
||
|
||
---
|
||
|
||
## 提交频率与时机
|
||
|
||
> **⭐⭐⭐⭐⭐ 核心原则：每天开发完成后必须立即提交！**
|
||
> **⚠️ Cursor环境特别提醒：未提交的代码可能在缓存清理时永久丢失！**
|
||
|
||
### 🎯 基本原则
|
||
|
||
#### **原则 0：每日必提交原则（最高优先级）⭐⭐⭐⭐⭐**
|
||
|
||
**为什么必须每日提交？**
|
||
|
||
1. **防止Cursor缓存丢失**
|
||
- Cursor IDE可能在缓存清理、崩溃、重启后丢失未保存的代码
|
||
- 未提交到Git的代码只存在于临时工作区，风险极高
|
||
- 真实案例：DC模块开发完成，但因未提交，代码全部丢失
|
||
|
||
2. **保护开发成果**
|
||
- 每天的开发工作都有价值，不应因意外丢失
|
||
- Git是代码的唯一可靠备份
|
||
- 提交后即使本地丢失，也可以从远程仓库恢复
|
||
|
||
3. **便于问题追溯**
|
||
- 每日提交可以清晰记录开发进度
|
||
- 出现问题时可以快速回退到前一天的稳定版本
|
||
|
||
**⭐⭐⭐⭐⭐ 强制规则：**
|
||
|
||
```bash
|
||
# 每天下班前（或每天开发结束时）必须执行
|
||
git status # 查看修改的文件
|
||
git add . # 添加所有修改
|
||
git commit -m "feat(module): Complete Day X development
|
||
|
||
Summary:
|
||
- [列出今天完成的主要工作]
|
||
- [列出实现的核心功能]
|
||
- [列出更新的文档]
|
||
|
||
Tested: Basic functionality verified"
|
||
|
||
git push origin master # 推送到远程仓库
|
||
```
|
||
|
||
**执行时机：**
|
||
- ✅ **每天下班前**（最重要！）
|
||
- ✅ **每次长时间离开电脑前**（如午休、会议）
|
||
- ✅ **重要功能完成后**
|
||
- ✅ **准备关闭Cursor前**
|
||
|
||
**特别提醒：**
|
||
- 🔴 **绝对不要**依赖Cursor的自动保存
|
||
- 🔴 **绝对不要**认为"稍后再提交"
|
||
- 🔴 **绝对不要**让代码过夜不提交
|
||
|
||
---
|
||
|
||
#### **原则 1：批量提交，避免碎片化提交**
|
||
|
||
**❌ 错误做法：**
|
||
```bash
|
||
# 每改一个文件就提交一次（过于频繁）
|
||
git commit -m "fix: Fix file A"
|
||
git commit -m "fix: Fix file B"
|
||
git commit -m "fix: Fix file C"
|
||
git commit -m "docs: Update docs"
|
||
# 结果：产生大量碎片化提交，污染 Git 历史
|
||
```
|
||
|
||
**✅ 正确做法（必须使用英文）：**
|
||
```bash
|
||
# 一天工作结束后，统一提交（推荐）
|
||
git add .
|
||
git commit -m "feat(asl): Implement title and abstract screening
|
||
|
||
Features:
|
||
- Implement Excel parsing logic
|
||
- Add LLM async task processing
|
||
- Complete storage service integration
|
||
- Update related documentation
|
||
|
||
Tested: Local verification passed"
|
||
```
|
||
|
||
**推荐提交频率：**
|
||
- ✅ **每天至少一次**（强制要求，保护代码安全）
|
||
- ✅ **完成一个完整功能时**：功能开发+测试验证+文档更新一起提交
|
||
- ✅ **重要里程碑节点**：如模块开发完成、架构升级完成
|
||
- ⚠️ **避免每次小改动就提交**：会产生大量无意义的提交记录（但每日至少提交一次）
|
||
|
||
---
|
||
|
||
#### **原则 2：必须验证测试后才能提交**
|
||
|
||
**⚠️ 严禁提交未经验证的代码！**
|
||
|
||
| 情况 | 是否可以提交 | 说明 |
|
||
|------|------------|------|
|
||
| ❌ 代码写完，未测试 | **禁止提交** | 可能包含语法错误、逻辑错误 |
|
||
| ❌ 测试中发现问题，未修复 | **禁止提交** | 会混乱代码库，影响其他人 |
|
||
| ❌ 功能未完成，只完成一半 | **禁止提交** | 破坏代码完整性 |
|
||
| ✅ 本地测试通过 | **可以提交** | 基本功能验证通过 |
|
||
| ✅ 功能测试+文档完善 | **推荐提交** | 完整的功能交付 |
|
||
| ✅ 完整验收通过 | **最佳提交** | 包含测试、文档、验收 |
|
||
|
||
**正确的工作流程：**
|
||
```
|
||
1. 开发功能
|
||
↓
|
||
2. 本地测试（确保无语法错误、逻辑错误）
|
||
↓
|
||
3. 功能验证（确保功能正常工作）
|
||
↓
|
||
4. 代码检查（Linter、格式化）
|
||
↓
|
||
5. 更新文档（如有必要）
|
||
↓
|
||
6. 等待明确指令
|
||
↓
|
||
7. 统一提交 ✅
|
||
```
|
||
|
||
---
|
||
|
||
#### **原则 3：只在明确授权时提交**
|
||
|
||
**⚠️ AI 助手规则（适用于 Cursor、GitHub Copilot 等）：**
|
||
|
||
| 场景 | AI 行为 | 说明 |
|
||
|------|--------|------|
|
||
| ❌ 用户未明确要求 | **不提交** | 等待用户指令 |
|
||
| ❌ 代码未经测试验证 | **不提交** | 避免混乱代码库 |
|
||
| ✅ 用户明确说"提交git" | **可以提交** | 遵循用户指令 |
|
||
| ✅ 用户说"推送到远程" | **可以提交并推送** | 完成整个流程 |
|
||
|
||
**示例对话：**
|
||
|
||
**❌ 错误：**
|
||
```
|
||
AI: 我已经完成功能开发，现在提交到 git...
|
||
[自动执行 git commit && git push]
|
||
```
|
||
|
||
**✅ 正确：**
|
||
```
|
||
AI: 我已经完成功能开发和本地测试验证。
|
||
代码已准备好提交，等待您的指令。
|
||
|
||
用户: 好的，提交git并推送到远程
|
||
AI: 收到！现在提交...
|
||
[执行 git commit && git push]
|
||
```
|
||
|
||
---
|
||
|
||
### 📋 提交检查清单
|
||
|
||
**在执行 `git commit` 之前，请确认：**
|
||
|
||
- [ ] ✅ **代码已完成**：功能/修复/文档完整实现
|
||
- [ ] ✅ **本地测试通过**：无语法错误、逻辑错误
|
||
- [ ] ✅ **功能验证通过**：实际运行测试，确保功能正常
|
||
- [ ] ✅ **代码风格检查**：通过 Linter 检查
|
||
- [ ] ✅ **文档已更新**：相关文档同步更新（如有必要）
|
||
- [ ] ✅ **Commit 信息规范**：符合 Conventional Commits 规范
|
||
- [ ] ✅ **用户已授权**：用户明确要求提交
|
||
|
||
**只有以上所有项目都打勾，才能执行 `git commit`！**
|
||
|
||
---
|
||
|
||
### 🚫 禁止的行为
|
||
|
||
| 行为 | 后果 | 正确做法 |
|
||
|------|------|---------|
|
||
| 每次小改动就提交 | Git 历史混乱，难以追踪 | 一天工作结束后统一提交 |
|
||
| 提交未测试的代码 | 引入 Bug，影响团队 | 测试验证后再提交 |
|
||
| 提交一半的功能 | 破坏代码完整性 | 完成完整功能后提交 |
|
||
| AI 自动提交 | 未经用户确认，可能混乱 | 等待用户明确指令 |
|
||
| 提交后立即强制推送 | 覆盖远程历史，危险 | 确认无冲突后再推送 |
|
||
|
||
---
|
||
|
||
### ✅ 推荐的提交场景
|
||
|
||
**场景 1：功能开发完成（必须使用英文）**
|
||
```bash
|
||
# Completed ASL module title and abstract screening at end of day
|
||
git add backend/src/modules/asl/
|
||
git add docs/03-业务模块/ASL-AI智能文献/
|
||
git commit -m "feat(asl): Implement title and abstract screening
|
||
|
||
Features:
|
||
- Implement Excel parsing and validation
|
||
- Add LLM async task processing
|
||
- Integrate platform infrastructure (storage/logger/jobQueue)
|
||
- Complete API and database schema
|
||
- Update development documentation
|
||
|
||
Tested: Local tests passed, functionality verified"
|
||
```
|
||
|
||
**场景 2：Bug 修复（必须使用英文）**
|
||
```bash
|
||
# Fixed health check route conflict and verified
|
||
git add backend/src/index.ts backend/src/common/health/
|
||
git commit -m "fix(backend): Fix duplicate health check route registration
|
||
|
||
Problem: /health route registered in multiple places causing conflicts
|
||
Solution: Unified registration in registerHealthRoutes
|
||
|
||
Fixes: FastifyError Method 'GET' already declared for route '/health'
|
||
Tested: Service started successfully, all three endpoints accessible"
|
||
```
|
||
|
||
**场景 3：架构升级（必须使用英文）**
|
||
```bash
|
||
# Completed platform infrastructure implementation and verification
|
||
git add backend/src/common/ backend/src/config/
|
||
git add docs/
|
||
git commit -m "feat(platform): Implement platform infrastructure (8 core modules)
|
||
|
||
Completed:
|
||
- Storage service (LocalAdapter + OSSAdapter reserved)
|
||
- Logging system (Winston + JSON format)
|
||
- Cache service (Memory + Redis reserved)
|
||
- Async tasks (MemoryQueue + DatabaseQueue reserved)
|
||
- Health checks (liveness + readiness)
|
||
- Monitoring metrics (DB/memory/API)
|
||
- Database connection pool (prevent Serverless limit)
|
||
- Environment configuration
|
||
|
||
Design principle: Adapter pattern for zero-code env switching
|
||
Implementation: 2.5 days (20 hours)
|
||
Status: Local dev environment verified
|
||
|
||
Related: #Platform-Infrastructure"
|
||
```
|
||
|
||
---
|
||
|
||
### 💡 最佳实践
|
||
|
||
1. **每天下班前提交一次**
|
||
- 汇总当天所有工作
|
||
- 确保代码已测试验证
|
||
- 写清楚提交信息
|
||
|
||
2. **提交前运行检查**
|
||
```bash
|
||
# 代码风格检查
|
||
npm run lint
|
||
|
||
# 类型检查
|
||
npm run type-check
|
||
|
||
# 测试（如有）
|
||
npm run test
|
||
```
|
||
|
||
3. **提交信息要完整**
|
||
- 写清楚做了什么
|
||
- 为什么这样做
|
||
- 测试验证情况
|
||
- 相关的 Issue 或文档
|
||
|
||
4. **重要改动要备份**
|
||
```bash
|
||
# 重大架构调整前，创建备份分支
|
||
git checkout -b backup/before-refactor
|
||
git checkout develop
|
||
```
|
||
|
||
---
|
||
|
||
## 分支管理策略
|
||
|
||
### 🌿 分支类型
|
||
|
||
```
|
||
master (main)
|
||
├── develop
|
||
├── feature/xxx
|
||
├── fix/xxx
|
||
├── hotfix/xxx
|
||
└── release/xxx
|
||
```
|
||
|
||
### 主分支
|
||
|
||
**master / main**
|
||
- 生产环境分支
|
||
- 永远保持可部署状态
|
||
- 只接受来自 `release` 或 `hotfix` 的合并
|
||
- 每次合并都打 tag（如 `v1.0.0`）
|
||
|
||
**develop**
|
||
- 开发主分支
|
||
- 最新的开发进度
|
||
- 接受来自 `feature` 和 `fix` 的合并
|
||
|
||
### 辅助分支
|
||
|
||
**feature/xxx - 功能分支**
|
||
```bash
|
||
# 创建功能分支
|
||
git checkout -b feature/asl-screening develop
|
||
|
||
# 开发完成后合并到 develop
|
||
git checkout develop
|
||
git merge --no-ff feature/asl-screening
|
||
git branch -d feature/asl-screening
|
||
git push origin develop
|
||
```
|
||
|
||
**fix/xxx - Bug 修复分支**
|
||
```bash
|
||
# 从 develop 创建修复分支
|
||
git checkout -b fix/dropdown-click develop
|
||
|
||
# 修复完成后合并到 develop
|
||
git checkout develop
|
||
git merge --no-ff fix/dropdown-click
|
||
git branch -d fix/dropdown-click
|
||
```
|
||
|
||
**hotfix/xxx - 紧急修复分支**
|
||
```bash
|
||
# 从 master 创建紧急修复分支
|
||
git checkout -b hotfix/critical-bug master
|
||
|
||
# 修复完成后同时合并到 master 和 develop
|
||
git checkout master
|
||
git merge --no-ff hotfix/critical-bug
|
||
git tag -a v1.0.1 -m "Hotfix: 修复严重 bug"
|
||
|
||
git checkout develop
|
||
git merge --no-ff hotfix/critical-bug
|
||
|
||
git branch -d hotfix/critical-bug
|
||
```
|
||
|
||
**release/xxx - 发布分支**
|
||
```bash
|
||
# 从 develop 创建发布分支
|
||
git checkout -b release/v1.0.0 develop
|
||
|
||
# 发布准备完成后合并到 master 和 develop
|
||
git checkout master
|
||
git merge --no-ff release/v1.0.0
|
||
git tag -a v1.0.0 -m "Release v1.0.0"
|
||
|
||
git checkout develop
|
||
git merge --no-ff release/v1.0.0
|
||
|
||
git branch -d release/v1.0.0
|
||
```
|
||
|
||
### 分支命名规范
|
||
|
||
**✅ 推荐：**
|
||
```
|
||
feature/asl-screening # 功能：AI 智能文献初筛
|
||
feature/user-authentication # 功能：用户认证
|
||
fix/dropdown-click # 修复：下拉菜单点击
|
||
fix/api-timeout # 修复：API 超时
|
||
hotfix/security-vulnerability # 紧急修复：安全漏洞
|
||
release/v1.0.0 # 发布：v1.0.0
|
||
```
|
||
|
||
**❌ 避免：**
|
||
```
|
||
feature/new-feature # 太笼统
|
||
fix/bug # 没有说明具体问题
|
||
test # 临时分支，应该有明确目的
|
||
my-branch # 个人分支，应该说明用途
|
||
```
|
||
|
||
---
|
||
|
||
## 中文编码问题解决
|
||
|
||
### ⚠️ 问题描述
|
||
|
||
在 Windows PowerShell 环境下，Git 提交信息中的中文可能会出现乱码，如：
|
||
|
||
```
|
||
124dc35 feat: 娣诲姞鏅鸿兘闂瓟鍔熻兘锛堟棤椤圭洰/鏅鸿兘浣撴蹇电殑绾璇濓級
|
||
```
|
||
|
||
实际应该是：
|
||
```
|
||
124dc35 feat: 添加智能问答功能（无项目/智能体概念的纯对话）
|
||
```
|
||
|
||
### ✅ 预防措施
|
||
|
||
**1. Git 全局配置**
|
||
```bash
|
||
git config --global core.quotepath false
|
||
git config --global gui.encoding utf-8
|
||
git config --global i18n.commit.encoding utf-8
|
||
git config --global i18n.logoutputencoding utf-8
|
||
```
|
||
|
||
**2. PowerShell 配置**
|
||
|
||
编辑 PowerShell Profile：
|
||
```powershell
|
||
# 打开 Profile
|
||
notepad $PROFILE
|
||
|
||
# 添加以下内容
|
||
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
|
||
$env:LESSCHARSET = 'utf-8'
|
||
```
|
||
|
||
**3. 项目配置文件**
|
||
|
||
项目根目录已包含：
|
||
- `.editorconfig` - 统一编辑器编码配置（UTF-8）
|
||
- `.gitattributes` - 统一 Git 文件编码处理
|
||
|
||
**4. 强制要求：必须使用英文提交信息** ⭐⭐⭐ 必须
|
||
|
||
```bash
|
||
# ✅ 正确：必须使用英文
|
||
git commit -m "feat(asl): Add screening feature"
|
||
|
||
# ❌ 错误：禁止使用中文（会出现乱码）
|
||
git commit -m "feat(asl): 添加初筛功能" # 会出现乱码！
|
||
```
|
||
|
||
**原因**：
|
||
- Windows PowerShell 环境下中文会乱码
|
||
- 无论如何配置编码都无法完全避免乱码问题
|
||
- **唯一解决方案：使用英文**
|
||
|
||
### 🔧 修复历史提交中的中文乱码
|
||
|
||
**使用修复脚本：**
|
||
|
||
项目根目录提供了 `fix-git-commit-messages.ps1` 脚本：
|
||
|
||
```powershell
|
||
# 1. 查看脚本说明
|
||
Get-Help .\fix-git-commit-messages.ps1
|
||
|
||
# 2. 运行脚本（交互式）
|
||
.\fix-git-commit-messages.ps1
|
||
|
||
# 3. 运行脚本（跳过确认）
|
||
.\fix-git-commit-messages.ps1 -SkipConfirm
|
||
```
|
||
|
||
**手动修复流程：**
|
||
|
||
1. **创建备份分支**
|
||
```bash
|
||
git branch backup-before-fix
|
||
```
|
||
|
||
2. **准备提交映射表**
|
||
|
||
编辑 `fix-git-commit-messages.ps1` 中的 `$commitMapping` 哈希表：
|
||
```powershell
|
||
$commitMapping = @{
|
||
"124dc35" = "feat: add general chat feature (without project/agent concept)"
|
||
"9618eca" = "fix: AgentChatPage conversation data extraction issue"
|
||
# 添加更多需要修复的提交...
|
||
}
|
||
```
|
||
|
||
3. **执行修复**
|
||
```powershell
|
||
.\fix-git-commit-messages.ps1 -SkipConfirm
|
||
```
|
||
|
||
4. **验证结果**
|
||
```bash
|
||
# 查看修复后的提交历史
|
||
git log --oneline -20
|
||
|
||
# 检查是否还有中文乱码
|
||
git log --all --oneline | Select-String "[\u4e00-\u9fa5]"
|
||
```
|
||
|
||
5. **强制推送到远程**
|
||
```bash
|
||
git push --force origin master
|
||
```
|
||
|
||
6. **清理备份**
|
||
```bash
|
||
# 如果修复成功，删除备份分支
|
||
git branch -D backup-before-fix
|
||
|
||
# 清理临时引用
|
||
git for-each-ref --format="%(refname)" refs/original/ | ForEach-Object { git update-ref -d $_ }
|
||
|
||
# 运行垃圾回收
|
||
git reflog expire --expire=now --all
|
||
git gc --prune=now --aggressive
|
||
```
|
||
|
||
### ⚠️ 注意事项
|
||
|
||
**修复历史提交的风险：**
|
||
- ⚠️ 会改变所有后续提交的 SHA-1 哈希值
|
||
- ⚠️ 需要强制推送（`--force`）到远程仓库
|
||
- ⚠️ 会影响所有协作者的本地仓库
|
||
- ⚠️ 必须通知团队成员重新克隆或重置
|
||
|
||
**建议：**
|
||
- ✅ 在项目早期进行修复
|
||
- ✅ 提前通知所有团队成员
|
||
- ✅ 创建备份分支
|
||
- ✅ 优先使用英文提交信息，避免编码问题
|
||
|
||
---
|
||
|
||
### 🔴🔴🔴 UTF-8 文件内容编码安全（2026-01-16 新增）
|
||
|
||
> **血泪教训：文档批量乱码事件（2026-01-16）**
|
||
>
|
||
> **事件描述：** 2026-01-14 的 AIA V2.0 提交后，大量 Markdown 文档出现乱码
|
||
> - 中文字符被截断显示为 `<EFBFBD>?`
|
||
> - 示例：`"指南" → "指<>?"`、`"团队" → "团<>?"`
|
||
> - 影响范围：docs/ 目录下几乎所有文档
|
||
|
||
#### 问题根本原因
|
||
|
||
**UTF-8 字符编码被破坏：**
|
||
- UTF-8 中文字符通常占 3 个字节
|
||
- 某次操作导致**最后 1-2 个字节被截断**
|
||
- 可能原因：PowerShell 重定向、编辑器编码错误、脚本处理不当
|
||
|
||
**定位过程：**
|
||
```bash
|
||
# 发现问题：文档显示乱码
|
||
cat file.md # 显示 "指<>?" 而非 "指南"
|
||
|
||
# 对比 Git 历史
|
||
git show 4ed67a8:file.md # 正常："指南"
|
||
git show HEAD:file.md # 损坏："指<>?"
|
||
|
||
# 确认损坏时间：2026-01-14 的提交
|
||
```
|
||
|
||
#### 🔥 强制规则（立即生效）
|
||
|
||
**1. 提交前必须检查文件编码**
|
||
```bash
|
||
# ⭐⭐⭐ 提交前必须执行！检查是否有损坏的 UTF-8 字符
|
||
git diff --staged | Select-String "<22>"
|
||
|
||
# 如果发现 "<22>" 字符，说明文件编码已损坏，禁止提交！
|
||
# 必须先修复编码再提交
|
||
```
|
||
|
||
**2. 禁止使用可能破坏编码的操作**
|
||
- 🔴 **禁止**使用 PowerShell 重定向操作处理 UTF-8 文件
|
||
```powershell
|
||
# ❌ 危险操作（会丢失编码信息）
|
||
git show commit:file.md > file.md
|
||
Get-Content file.md > new-file.md
|
||
|
||
# ✅ 安全操作（保持 UTF-8 编码）
|
||
git show commit:file.md | Set-Content file.md -Encoding UTF8
|
||
Get-Content file.md -Encoding UTF8 | Set-Content new-file.md -Encoding UTF8
|
||
```
|
||
|
||
- 🔴 **禁止**使用不支持 UTF-8 的编辑器保存中文文件
|
||
- 🔴 **禁止**使用批量替换工具（如 sed）直接处理 UTF-8 文件
|
||
- 🔴 **禁止**在没有指定 `-Encoding UTF8` 的情况下使用 PowerShell 读写文件
|
||
|
||
**3. 安全的文件操作方式**
|
||
```powershell
|
||
# ✅ 推荐：使用 Git 命令直接恢复（安全）
|
||
git checkout <commit-hash> -- path/to/file.md
|
||
|
||
# ✅ 推荐：使用 IDE（VS Code、Cursor）直接编辑和保存
|
||
# 这些 IDE 默认使用 UTF-8 编码
|
||
|
||
# ✅ 如果必须使用 PowerShell，显式指定编码
|
||
$content = Get-Content file.md -Encoding UTF8
|
||
$content | Set-Content file.md -Encoding UTF8 -NoNewline
|
||
```
|
||
|
||
**4. 提交前验证清单**
|
||
```bash
|
||
# ✅ 步骤 1：检查是否有乱码字符
|
||
git diff --staged | Select-String "<22>"
|
||
|
||
# ✅ 步骤 2：抽查修改的文档文件（确保中文显示正常）
|
||
git diff --staged --name-only -- "*.md" | Select-Object -First 5 | ForEach-Object {
|
||
Write-Host "`n检查文件: $_" -ForegroundColor Yellow
|
||
Get-Content $_ -Encoding UTF8 -First 5
|
||
}
|
||
|
||
# ✅ 步骤 3：如果一切正常，再执行提交
|
||
git commit -m "your message"
|
||
```
|
||
|
||
#### 🔧 修复已损坏文件的方法
|
||
|
||
**方法 1：从 Git 历史恢复（推荐）**
|
||
```bash
|
||
# 1. 查找最后一个正常版本
|
||
git log --oneline -- path/to/damaged-file.md
|
||
|
||
# 2. 恢复文件（使用 checkout，安全）
|
||
git checkout <normal-commit-hash> -- path/to/damaged-file.md
|
||
|
||
# 3. 验证恢复效果
|
||
Get-Content path/to/damaged-file.md -Encoding UTF8 -First 10
|
||
```
|
||
|
||
**方法 2：批量恢复（需谨慎）**
|
||
```bash
|
||
# 1. 先备份有新内容的文档到安全位置
|
||
|
||
# 2. 批量恢复到正常版本
|
||
git checkout <normal-commit-hash> -- docs/
|
||
|
||
# 3. 恢复备份的新文档
|
||
# 手动复制回来
|
||
```
|
||
|
||
#### 💡 预防措施总结
|
||
|
||
| 预防措施 | 说明 | 重要性 |
|
||
|---------|------|--------|
|
||
| **提交前检查** | `git diff --staged \| Select-String "<22>"` | ⭐⭐⭐⭐⭐ |
|
||
| **使用 IDE 编辑** | VS Code/Cursor 默认 UTF-8 | ⭐⭐⭐⭐⭐ |
|
||
| **避免 PS 重定向** | 不使用 `>` 操作符处理 UTF-8 文件 | ⭐⭐⭐⭐⭐ |
|
||
| **显式指定编码** | PowerShell 操作加 `-Encoding UTF8` | ⭐⭐⭐⭐ |
|
||
| **定期抽查** | 每周检查文档编码是否正常 | ⭐⭐⭐ |
|
||
|
||
**🎯 记住：编码损坏后很难修复，预防永远比修复重要！**
|
||
|
||
---
|
||
|
||
## Git 历史重写与维护
|
||
|
||
### 🛠️ 常用命令
|
||
|
||
**修改最后一次提交：**
|
||
```bash
|
||
# 修改提交信息
|
||
git commit --amend -m "new message"
|
||
|
||
# 添加遗漏的文件
|
||
git add forgotten-file.txt
|
||
git commit --amend --no-edit
|
||
```
|
||
|
||
**重置提交：**
|
||
```bash
|
||
# 软重置（保留更改）
|
||
git reset --soft HEAD~1
|
||
|
||
# 混合重置（默认，保留工作区更改）
|
||
git reset HEAD~1
|
||
|
||
# 硬重置（丢弃所有更改）⚠️ 危险
|
||
git reset --hard HEAD~1
|
||
```
|
||
|
||
**交互式变基：**
|
||
```bash
|
||
# 重新排列、合并、编辑最近 3 次提交
|
||
git rebase -i HEAD~3
|
||
|
||
# 变基到 develop 分支
|
||
git rebase develop
|
||
```
|
||
|
||
**拣选提交：**
|
||
```bash
|
||
# 将特定提交应用到当前分支
|
||
git cherry-pick <commit-hash>
|
||
```
|
||
|
||
**过滤历史：**
|
||
```bash
|
||
# 修改所有历史提交的作者信息
|
||
git filter-branch --env-filter '
|
||
if [ "$GIT_COMMITTER_EMAIL" = "old@email.com" ]
|
||
then
|
||
export GIT_COMMITTER_EMAIL="new@email.com"
|
||
export GIT_AUTHOR_EMAIL="new@email.com"
|
||
fi
|
||
' --tag-name-filter cat -- --all
|
||
|
||
# 从所有历史中删除文件（如敏感信息）
|
||
git filter-branch --tree-filter 'rm -f passwords.txt' HEAD
|
||
```
|
||
|
||
### 强制推送规范
|
||
|
||
**⚠️ 危险操作，需谨慎！**
|
||
|
||
**基本强制推送：**
|
||
```bash
|
||
git push --force origin master
|
||
```
|
||
|
||
**更安全的强制推送：** ⭐ 推荐
|
||
```bash
|
||
# 只有当远程分支与本地预期一致时才推送
|
||
git push --force-with-lease origin master
|
||
```
|
||
|
||
**禁止强制推送的分支：**
|
||
- ❌ `master` / `main` （除非修复历史问题）
|
||
- ❌ `develop` （需要团队同意）
|
||
- ✅ `feature/*` （可以，仅影响个人）
|
||
- ✅ `fix/*` （可以，仅影响个人）
|
||
|
||
**强制推送前检查清单：**
|
||
- [ ] 是否已创建备份分支？
|
||
- [ ] 是否已通知团队成员？
|
||
- [ ] 是否确认没有其他人基于当前分支工作？
|
||
- [ ] 是否了解强制推送的后果？
|
||
- [ ] 是否可以使用 `--force-with-lease` 替代 `--force`？
|
||
|
||
### 垃圾回收与清理
|
||
|
||
**清理未追踪文件：**
|
||
```bash
|
||
# 预览将被删除的文件
|
||
git clean -n
|
||
|
||
# 删除未追踪文件
|
||
git clean -f
|
||
|
||
# 删除未追踪文件和目录
|
||
git clean -fd
|
||
|
||
# 包括 .gitignore 中的文件
|
||
git clean -fdx
|
||
```
|
||
|
||
**清理过期引用：**
|
||
```bash
|
||
# 清理过期的 reflog
|
||
git reflog expire --expire=now --all
|
||
|
||
# 运行垃圾回收
|
||
git gc --prune=now
|
||
|
||
# 积极的垃圾回收（更彻底，更慢）
|
||
git gc --prune=now --aggressive
|
||
```
|
||
|
||
**查看仓库大小：**
|
||
```bash
|
||
# 查看 .git 目录大小
|
||
git count-objects -vH
|
||
```
|
||
|
||
---
|
||
|
||
## 代码审查流程
|
||
|
||
### 👥 Pull Request / Merge Request 规范
|
||
|
||
**PR/MR 标题：**
|
||
```
|
||
[类型] 简短描述（≤50字符）
|
||
|
||
示例：
|
||
[Feature] 实现 AI 智能文献标题摘要初筛
|
||
[Fix] 修复下拉菜单点击无响应问题
|
||
[Refactor] 重构用户认证逻辑
|
||
[Docs] 更新 Git 提交规范文档
|
||
```
|
||
|
||
**PR/MR 描述模板：**
|
||
```markdown
|
||
## 📝 变更说明
|
||
简要描述这个 PR 做了什么
|
||
|
||
## 🎯 关联 Issue
|
||
Closes #123
|
||
|
||
## ✨ 主要变更
|
||
- 添加了 XXX 功能
|
||
- 修复了 YYY 问题
|
||
- 重构了 ZZZ 模块
|
||
|
||
## 🧪 测试
|
||
- [ ] 单元测试通过
|
||
- [ ] 集成测试通过
|
||
- [ ] 手动测试完成
|
||
|
||
## 📸 截图（如果适用）
|
||
[添加截图]
|
||
|
||
## ⚠️ 注意事项
|
||
需要注意的特殊情况或依赖
|
||
|
||
## 📋 检查清单
|
||
- [ ] 代码符合项目规范
|
||
- [ ] 添加了必要的测试
|
||
- [ ] 更新了相关文档
|
||
- [ ] 通过了所有 CI 检查
|
||
```
|
||
|
||
### Code Review 检查清单
|
||
|
||
**代码质量：**
|
||
- [ ] 代码逻辑正确，无明显 bug
|
||
- [ ] 符合代码规范（ESLint/Prettier）
|
||
- [ ] 变量、函数命名清晰
|
||
- [ ] 无重复代码（DRY 原则）
|
||
- [ ] 适当的注释和文档
|
||
|
||
**功能完整性：**
|
||
- [ ] 实现了所有需求
|
||
- [ ] 边界条件处理正确
|
||
- [ ] 错误处理完善
|
||
- [ ] 无性能问题
|
||
|
||
**测试：**
|
||
- [ ] 包含单元测试
|
||
- [ ] 测试覆盖率达标
|
||
- [ ] 测试用例合理
|
||
|
||
**安全性：**
|
||
- [ ] 无 SQL 注入风险
|
||
- [ ] 无 XSS 风险
|
||
- [ ] 敏感信息未泄露
|
||
- [ ] 权限检查正确
|
||
|
||
**文档：**
|
||
- [ ] API 文档已更新
|
||
- [ ] README 已更新（如需要）
|
||
- [ ] 数据库变更已记录
|
||
|
||
### Review 响应时间
|
||
|
||
| 优先级 | 响应时间 | 说明 |
|
||
|--------|----------|------|
|
||
| 🔴 紧急 | 2 小时内 | 生产环境 Bug、安全漏洞 |
|
||
| 🟡 高 | 1 天内 | 阻塞其他开发的功能 |
|
||
| 🟢 中 | 2 天内 | 常规功能和修复 |
|
||
| ⚪ 低 | 3 天内 | 优化、重构、文档 |
|
||
|
||
---
|
||
|
||
## 常见问题与最佳实践
|
||
|
||
### 🤔 常见问题
|
||
|
||
**Q1: 提交后发现有错误，如何修改？**
|
||
```bash
|
||
# 修改后重新提交（未推送到远程）
|
||
git add .
|
||
git commit --amend --no-edit
|
||
|
||
# 如果已推送，需要强制推送
|
||
git push --force-with-lease origin feature/xxx
|
||
```
|
||
|
||
**Q2: 如何撤销已推送的提交？**
|
||
```bash
|
||
# 方式 1：创建一个新的 revert 提交（推荐）
|
||
git revert <commit-hash>
|
||
git push origin master
|
||
|
||
# 方式 2：重置后强制推送（危险，不推荐）
|
||
git reset --hard HEAD~1
|
||
git push --force origin master
|
||
```
|
||
|
||
**Q3: 如何解决合并冲突？**
|
||
```bash
|
||
# 1. 拉取最新代码
|
||
git pull origin develop
|
||
|
||
# 2. 手动解决冲突文件
|
||
|
||
# 3. 标记为已解决
|
||
git add <conflicted-files>
|
||
|
||
# 4. 完成合并
|
||
git commit -m "chore: merge develop into feature/xxx"
|
||
```
|
||
|
||
**Q4: 如何查看某个文件的修改历史？**
|
||
```bash
|
||
# 查看文件的提交历史
|
||
git log --follow -- path/to/file
|
||
|
||
# 查看文件的详细修改内容
|
||
git log -p -- path/to/file
|
||
|
||
# 查看每行代码的最后修改信息
|
||
git blame path/to/file
|
||
```
|
||
|
||
**Q5: 如何恢复已删除的文件？**
|
||
```bash
|
||
# 查找删除该文件的提交
|
||
git log --all --full-history -- path/to/file
|
||
|
||
# 恢复文件（从删除前的提交）
|
||
git checkout <commit-hash>^ -- path/to/file
|
||
```
|
||
|
||
**Q6: 如何临时保存未提交的更改？**
|
||
```bash
|
||
# 保存更改
|
||
git stash save "描述信息"
|
||
|
||
# 查看保存的更改
|
||
git stash list
|
||
|
||
# 恢复更改
|
||
git stash pop
|
||
|
||
# 恢复特定的 stash
|
||
git stash apply stash@{0}
|
||
```
|
||
|
||
**Q7: 提交信息写错了怎么办？**
|
||
```bash
|
||
# 修改最后一次提交信息（未推送）
|
||
git commit --amend -m "正确的提交信息"
|
||
|
||
# 如果已推送
|
||
git commit --amend -m "正确的提交信息"
|
||
git push --force-with-lease origin branch-name
|
||
|
||
# 修改更早的提交信息
|
||
git rebase -i HEAD~3 # 修改最近 3 次提交
|
||
# 在编辑器中将 pick 改为 reword
|
||
```
|
||
|
||
### 💡 最佳实践
|
||
|
||
**提交频率：**
|
||
- ✅ **每天至少提交一次**（Cursor环境强制要求）
|
||
- ✅ 每个提交只做一件事
|
||
- ✅ 提交可编译、可运行的代码
|
||
- ⚠️ 可以积累一天的更改，但不要超过一天
|
||
- ❌ **绝对不要**让代码过夜不提交（Cursor环境风险）
|
||
|
||
**提交内容：**
|
||
- ✅ 只提交相关的更改
|
||
- ✅ 使用 `.gitignore` 排除无关文件
|
||
- ✅ **提交 `backend/.env` 环境变量文件**（私有仓库，防止配置丢失）
|
||
- ❌ 不要提交生成的文件（`node_modules/`, `dist/`）
|
||
|
||
> ⚠️ **关于 `.env` 文件的特殊说明（2026-01-22 更新）**
|
||
>
|
||
> **背景**：2026-01-22 发生环境变量文件被意外覆盖事件，导致大量配置丢失。
|
||
>
|
||
> **决策**：鉴于本项目为私有仓库，且团队规模小（2人），为防止配置丢失，
|
||
> 决定将 `backend/.env` 文件纳入 Git 版本管理。
|
||
>
|
||
> **注意事项**：
|
||
> - 🔴 如果仓库将来变为公开，必须立即从 Git 历史中删除 `.env`
|
||
> - 🔴 定期轮换 API 密钥（建议每 90 天）
|
||
> - 🔴 不要将 `.env` 文件分享给非团队成员
|
||
|
||
**分支管理：**
|
||
- ✅ 从最新的 `develop` 创建功能分支
|
||
- ✅ 定期将 `develop` 合并到功能分支
|
||
- ✅ 功能完成后及时合并和删除分支
|
||
- ❌ 不要长期保持功能分支不合并
|
||
|
||
**协作：**
|
||
- ✅ 推送前先拉取（`git pull --rebase`）
|
||
- ✅ 及时响应 Code Review
|
||
- ✅ 主动沟通冲突和问题
|
||
- ❌ 不要直接推送到 `master` 分支
|
||
|
||
### 🔧 有用的 Git 别名
|
||
|
||
在 `~/.gitconfig` 中添加：
|
||
|
||
```ini
|
||
[alias]
|
||
# 状态和日志
|
||
st = status
|
||
co = checkout
|
||
br = branch
|
||
ci = commit
|
||
|
||
# 美化的日志
|
||
lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit
|
||
|
||
# 简洁的状态
|
||
s = status -s
|
||
|
||
# 最近的提交
|
||
last = log -1 HEAD
|
||
|
||
# 撤销最后一次提交（保留更改）
|
||
undo = reset --soft HEAD~1
|
||
|
||
# 查看差异
|
||
d = diff
|
||
dc = diff --cached
|
||
|
||
# 拉取并变基
|
||
up = pull --rebase
|
||
|
||
# 推送当前分支
|
||
push-current = "!git push -u origin $(git rev-parse --abbrev-ref HEAD)"
|
||
```
|
||
|
||
使用示例：
|
||
```bash
|
||
git st # 相当于 git status
|
||
git lg # 美化的日志
|
||
git push-current # 推送当前分支
|
||
```
|
||
|
||
### 📚 推荐阅读
|
||
|
||
**Git 学习资源：**
|
||
- [Pro Git Book（中文版）](https://git-scm.com/book/zh/v2)
|
||
- [Git 官方文档](https://git-scm.com/docs)
|
||
- [Learn Git Branching（交互式教程）](https://learngitbranching.js.org/)
|
||
|
||
**提交规范：**
|
||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||
- [Angular Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
**遇到问题？**
|
||
1. 查看本文档的常见问题部分
|
||
2. 搜索 Git 官方文档
|
||
3. 向团队技术负责人咨询
|
||
4. 在团队群聊中讨论
|
||
|
||
**文档反馈：**
|
||
如果发现文档错误或有改进建议，请：
|
||
1. 提交 Issue
|
||
2. 直接修改并提交 PR
|
||
3. 联系文档维护人
|
||
|
||
---
|
||
|
||
## ⚠️ Cursor IDE 环境专用最佳实践
|
||
|
||
> **⭐⭐⭐⭐⭐ 血泪教训：未提交的代码可能永久丢失！**
|
||
|
||
### 🔴 真实案例：DC模块代码丢失事件
|
||
|
||
**事件回顾（2025-11-27）：**
|
||
|
||
1. **开发过程**：
|
||
- 完成了DC模块Tool B的完整开发
|
||
- 包含4个Prisma表模型（dc_health_checks, dc_templates, dc_extraction_tasks, dc_extraction_items）
|
||
- 包含4个Service（HealthCheckService, TemplateService, DualModelExtractionService, ConflictDetectionService）
|
||
- 包含Controller、Routes等完整代码
|
||
- 完成了LLM集成测试
|
||
|
||
2. **悲剧发生**：
|
||
- 开发完成后未立即提交到Git
|
||
- 代码停留在Cursor的临时缓存中
|
||
- Cursor重启/缓存清理后，代码全部消失
|
||
- 只保留了文档和空目录结构
|
||
|
||
3. **损失评估**：
|
||
- 💔 2-3天的开发工作完全丢失
|
||
- 💔 所有Service实现代码丢失
|
||
- 💔 Prisma模型定义丢失
|
||
- 💔 测试代码丢失
|
||
- ✅ 幸运的是设计文档保留了
|
||
|
||
4. **恢复难度**：
|
||
- ❌ Cursor缓存已清理，无法恢复
|
||
- ❌ Git历史中无任何记录
|
||
- ❌ Windows文件历史无记录
|
||
- ✅ 只能基于设计文档完全重建
|
||
|
||
### 🛡️ 防止代码丢失的强制规则
|
||
|
||
#### **规则1：每天下班前必须提交 ⭐⭐⭐⭐⭐**
|
||
|
||
```bash
|
||
# 每天下班前执行的标准流程
|
||
cd D:\MyCursor\AIclinicalresearch
|
||
|
||
# 1. 查看状态
|
||
git status
|
||
|
||
# 2. 添加所有修改
|
||
git add .
|
||
|
||
# 3. 提交（必须使用英文）
|
||
git commit -m "feat(module): Complete Day X development
|
||
|
||
Summary:
|
||
- [今天完成的主要工作]
|
||
- [实现的核心功能]
|
||
- [更新的文档]
|
||
|
||
Status: Code tested and verified locally"
|
||
|
||
# 4. 推送到远程（关键！）
|
||
git push origin master
|
||
|
||
# 5. 确认推送成功
|
||
git log -1
|
||
```
|
||
|
||
**执行时机：**
|
||
- ✅ 每天下班前（强制）
|
||
- ✅ 午休前
|
||
- ✅ 长时间离开电脑前
|
||
- ✅ 准备关闭Cursor前
|
||
- ✅ 系统更新/重启前
|
||
|
||
#### **规则2：重要功能完成后立即提交**
|
||
|
||
```bash
|
||
# 场景：刚完成一个Service的实现
|
||
git add backend/src/modules/dc/tool-b/services/HealthCheckService.ts
|
||
git commit -m "feat(dc): Implement HealthCheckService
|
||
|
||
Features:
|
||
- Excel parsing logic
|
||
- Empty rate calculation
|
||
- Token estimation
|
||
- Interception strategy
|
||
|
||
Tested: Basic unit tests passed"
|
||
|
||
git push origin master
|
||
```
|
||
|
||
#### **规则3：使用Git状态检查脚本**
|
||
|
||
在项目根目录创建 `check-git-status.ps1`：
|
||
|
||
```powershell
|
||
# check-git-status.ps1
|
||
Write-Host "=== Git Status Check ===" -ForegroundColor Yellow
|
||
cd D:\MyCursor\AIclinicalresearch
|
||
|
||
$status = git status --short
|
||
if ($status) {
|
||
Write-Host "⚠️ You have uncommitted changes!" -ForegroundColor Red
|
||
Write-Host $status
|
||
Write-Host ""
|
||
Write-Host "Please commit your changes before closing Cursor!" -ForegroundColor Red
|
||
Write-Host "Run: git add . && git commit -m 'your message' && git push" -ForegroundColor Yellow
|
||
} else {
|
||
Write-Host "✅ All changes committed!" -ForegroundColor Green
|
||
}
|
||
|
||
Write-Host ""
|
||
Write-Host "Last commit:" -ForegroundColor Cyan
|
||
git log -1 --oneline
|
||
```
|
||
|
||
**使用方法：**
|
||
```bash
|
||
# 关闭Cursor前运行
|
||
.\check-git-status.ps1
|
||
```
|
||
|
||
#### **规则4：设置Cursor关闭提醒**
|
||
|
||
在 `workspace settings.json` 中添加：
|
||
```json
|
||
{
|
||
"git.enableSmartCommit": true,
|
||
"git.confirmSync": false,
|
||
"git.autofetch": true,
|
||
"git.showUnpushedChangesIndicator": true
|
||
}
|
||
```
|
||
|
||
### 🚨 Cursor环境风险点
|
||
|
||
| 风险点 | 说明 | 防范措施 |
|
||
|--------|------|---------|
|
||
| **缓存清理** | Cursor可能清理临时文件 | 每日提交 |
|
||
| **IDE崩溃** | Cursor崩溃可能丢失未保存内容 | 每日提交 + 每小时Ctrl+S |
|
||
| **系统重启** | Windows更新强制重启 | 下班前提交 |
|
||
| **AI生成代码** | AI生成的代码未自动保存 | 生成后立即验证并提交 |
|
||
| **多文件操作** | 批量修改后未保存 | 操作后检查git status |
|
||
|
||
### ✅ 安全的开发流程
|
||
|
||
```
|
||
1. 拉取最新代码
|
||
git pull origin master
|
||
↓
|
||
2. 开始开发
|
||
[编写代码、测试、调试]
|
||
↓
|
||
3. 阶段性保存
|
||
Ctrl+S（每隔15-30分钟）
|
||
↓
|
||
4. 功能完成后验证
|
||
[运行测试、检查功能]
|
||
↓
|
||
5. 立即提交
|
||
git add .
|
||
git commit -m "..."
|
||
git push origin master
|
||
↓
|
||
6. 确认推送成功
|
||
git log -1
|
||
检查Gitee网页是否更新
|
||
```
|
||
|
||
### 📋 每日开发检查清单
|
||
|
||
**开始开发前：**
|
||
- [ ] 拉取最新代码：`git pull`
|
||
- [ ] 检查当前分支：`git branch`
|
||
- [ ] 确认工作区干净：`git status`
|
||
|
||
**开发过程中：**
|
||
- [ ] 每30分钟保存：`Ctrl+S`
|
||
- [ ] 每小时检查状态：`git status`
|
||
- [ ] 重要功能完成后立即提交
|
||
|
||
**下班前（强制）：**
|
||
- [ ] 保存所有文件：`Ctrl+Shift+S`
|
||
- [ ] 查看修改内容：`git status`
|
||
- [ ] 添加修改：`git add .`
|
||
- [ ] 提交代码：`git commit -m "..."`
|
||
- [ ] 推送到远程：`git push origin master`
|
||
- [ ] 确认推送成功：访问Gitee查看
|
||
|
||
**关闭Cursor前：**
|
||
- [ ] 运行检查脚本：`.\check-git-status.ps1`
|
||
- [ ] 确认无未提交修改
|
||
- [ ] 确认最新提交已推送
|
||
|
||
### 🆘 紧急恢复指南
|
||
|
||
**如果代码已丢失，尝试以下方法：**
|
||
|
||
1. **检查Cursor缓存**：
|
||
```bash
|
||
Get-ChildItem "C:\Users\zhibo\.cursor\" -Recurse -Include "*.ts"
|
||
| Sort-Object LastWriteTime -Descending | Select-Object -First 50
|
||
```
|
||
|
||
2. **检查Git对象**：
|
||
```bash
|
||
git fsck --lost-found
|
||
git reflog
|
||
```
|
||
|
||
3. **检查Windows文件历史**：
|
||
- 右键项目文件夹 → 属性 → 以前的版本
|
||
|
||
4. **如果完全无法恢复**：
|
||
- 基于设计文档重建（幸好保留了文档）
|
||
- 吸取教训，强化每日提交习惯
|
||
|
||
### 💡 Cursor环境推荐设置
|
||
|
||
**VS Code / Cursor 设置**：
|
||
```json
|
||
{
|
||
"files.autoSave": "afterDelay",
|
||
"files.autoSaveDelay": 1000,
|
||
"git.enableSmartCommit": true,
|
||
"git.confirmSync": false,
|
||
"git.autofetch": true,
|
||
"git.showUnpushedChangesIndicator": true,
|
||
"editor.formatOnSave": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新：** 2025-11-28
|
||
**维护人：** 技术架构师
|
||
**版本历史：**
|
||
- v1.2 (2025-11-28): **添加Cursor环境专用最佳实践**，基于DC模块代码丢失事件的血泪教训
|
||
- 新增"Cursor IDE环境专用最佳实践"章节
|
||
- 强制要求每日提交
|
||
- 添加代码丢失防范措施
|
||
- 添加每日开发检查清单
|
||
- v1.1 (2025-11-22): **强制要求 Commit Message 使用英文**，避免中文乱码问题
|
||
- 在"Commit Message 规范"开头添加重要提示
|
||
- 更新所有示例为英文版本
|
||
- 将"优先使用英文"改为"必须使用英文"
|
||
- v1.0 (2025-11-16): 初始版本，包含完整的 Git 规范和中文乱码解决方案
|
||
|
||
|
||
|