Files

HaHafeng 9c96f75c52 feat(storage): integrate Alibaba Cloud OSS for file persistence - Add OSSAdapter and LocalAdapter with StorageFactory pattern - Integrate PKB module with OSS upload - Rename difyDocumentId to storageKey - Create 4 OSS buckets and development specification

2026-01-22 22:02:20 +08:00

42 KiB

Raw Permalink Blame History

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中无任何提交记录，无法恢复

🔥 强制规则（立即生效）

# ⭐⭐⭐⭐⭐ 每天下班前必须执行（无例外！）
git status
git add .
git commit -m "feat(module): Complete Day X development"
git push origin master

# ⚠️ 不提交 = 代码随时可能丢失！

提交时机（任选其一，发生时必须提交）：

✅ 每天下班前（最重要！无论代码是否完美）
✅ 每次长时间离开电脑前（午休、会议、外出）
✅ 完成重要功能后
✅ 准备关闭Cursor前
✅ 电脑出现异常前（如卡顿、死机征兆）

绝对禁止：

🔴 禁止依赖Cursor自动保存（Cursor不保证持久化）
🔴 禁止"稍后再提交"（稍后可能就忘记了）
🔴 禁止代码过夜不提交（一夜之间可能丢失）
🔴 禁止"代码还没完善不想提交"（不完善也要提交，总比丢失强）

💡 最佳实践

每日工作流（推荐）：

# 早上开始工作
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是代码的唯一可靠备份！未提交的代码 = 不存在的代码！

远程仓库配置

🌐 Gitee 仓库信息

仓库地址：

https://gitee.com/hahafeng117/AIclinicalresearch.git

全局配置：

git config --global user.name "HaHafeng"
git config --global user.email "gofeng117@163.com"

中文编码配置： ⭐ 重要

# 确保 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 Profile 中添加（$PROFILE 文件）
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:LESSCHARSET = 'utf-8'

克隆仓库

# 初次克隆
git clone https://gitee.com/hahafeng117/AIclinicalresearch.git

# 查看远程仓库
git remote -v

Commit Message 规范

⚠️ 重要提示：避免中文乱码

强制要求：Commit Message 必须使用英文 ⭐⭐⭐

原因：

Windows PowerShell 环境下，Git commit message 中的中文会出现乱码
中文乱码会导致提交历史难以阅读，影响团队协作
英文 commit message 是国际开源项目的标准实践

✅ 正确示例：

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"

❌ 错误示例：

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：每日必提交原则（最高优先级）⭐⭐⭐⭐⭐

为什么必须每日提交？

防止Cursor缓存丢失
- Cursor IDE可能在缓存清理、崩溃、重启后丢失未保存的代码
- 未提交到Git的代码只存在于临时工作区，风险极高
- 真实案例：DC模块开发完成，但因未提交，代码全部丢失
保护开发成果
- 每天的开发工作都有价值，不应因意外丢失
- Git是代码的唯一可靠备份
- 提交后即使本地丢失，也可以从远程仓库恢复
便于问题追溯
- 每日提交可以清晰记录开发进度
- 出现问题时可以快速回退到前一天的稳定版本

⭐⭐⭐⭐⭐ 强制规则：

# 每天下班前（或每天开发结束时）必须执行
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：批量提交，避免碎片化提交

❌ 错误做法：

# 每改一个文件就提交一次（过于频繁）
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 历史

✅ 正确做法（必须使用英文）：

# 一天工作结束后，统一提交（推荐）
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：功能开发完成（必须使用英文）

# 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 修复（必须使用英文）

# 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：架构升级（必须使用英文）

# 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"

💡 最佳实践

每天下班前提交一次
- 汇总当天所有工作
- 确保代码已测试验证
- 写清楚提交信息

提交前运行检查

# 代码风格检查
npm run lint

# 类型检查
npm run type-check

# 测试（如有）
npm run test

提交信息要完整
- 写清楚做了什么
- 为什么这样做
- 测试验证情况
- 相关的 Issue 或文档

重要改动要备份

# 重大架构调整前，创建备份分支
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 - 功能分支

# 创建功能分支
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 修复分支

# 从 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 - 紧急修复分支

# 从 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 - 发布分支

# 从 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 全局配置

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：

# 打开 Profile
notepad $PROFILE

# 添加以下内容
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:LESSCHARSET = 'utf-8'

3. 项目配置文件

项目根目录已包含：

.editorconfig - 统一编辑器编码配置（UTF-8）
.gitattributes - 统一 Git 文件编码处理

4. 强制要求：必须使用英文提交信息 ⭐⭐⭐ 必须

# ✅ 正确：必须使用英文
git commit -m "feat(asl): Add screening feature"

# ❌ 错误：禁止使用中文（会出现乱码）
git commit -m "feat(asl): 添加初筛功能"  # 会出现乱码！

原因：

Windows PowerShell 环境下中文会乱码
无论如何配置编码都无法完全避免乱码问题
唯一解决方案：使用英文

🔧 修复历史提交中的中文乱码

使用修复脚本：

项目根目录提供了 fix-git-commit-messages.ps1 脚本：

# 1. 查看脚本说明
Get-Help .\fix-git-commit-messages.ps1

# 2. 运行脚本（交互式）
.\fix-git-commit-messages.ps1

# 3. 运行脚本（跳过确认）
.\fix-git-commit-messages.ps1 -SkipConfirm

手动修复流程：

创建备份分支

git branch backup-before-fix

准备提交映射表

编辑 fix-git-commit-messages.ps1 中的 $commitMapping 哈希表：

$commitMapping = @{
    "124dc35" = "feat: add general chat feature (without project/agent concept)"
    "9618eca" = "fix: AgentChatPage conversation data extraction issue"
    # 添加更多需要修复的提交...
}

执行修复

.\fix-git-commit-messages.ps1 -SkipConfirm

验证结果

# 查看修复后的提交历史
git log --oneline -20

# 检查是否还有中文乱码
git log --all --oneline | Select-String "[\u4e00-\u9fa5]"

强制推送到远程

git push --force origin master

清理备份

# 如果修复成功，删除备份分支
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 重定向、编辑器编码错误、脚本处理不当

定位过程：

# 发现问题：文档显示乱码
cat file.md  # 显示 "指<>?" 而非 "指南"

# 对比 Git 历史
git show 4ed67a8:file.md  # 正常："指南"
git show HEAD:file.md     # 损坏："指<>?"

# 确认损坏时间：2026-01-14 的提交

🔥 强制规则（立即生效）

1. 提交前必须检查文件编码

# ⭐⭐⭐ 提交前必须执行！检查是否有损坏的 UTF-8 字符
git diff --staged | Select-String "<22>"

# 如果发现 "<22>" 字符，说明文件编码已损坏，禁止提交！
# 必须先修复编码再提交

2. 禁止使用可能破坏编码的操作

🔴 禁止使用 PowerShell 重定向操作处理 UTF-8 文件

# ❌ 危险操作（会丢失编码信息）
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. 安全的文件操作方式

# ✅ 推荐：使用 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. 提交前验证清单

# ✅ 步骤 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 历史恢复（推荐）

# 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：批量恢复（需谨慎）

# 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 历史重写与维护

🛠️ 常用命令

修改最后一次提交：

# 修改提交信息
git commit --amend -m "new message"

# 添加遗漏的文件
git add forgotten-file.txt
git commit --amend --no-edit

重置提交：

# 软重置（保留更改）
git reset --soft HEAD~1

# 混合重置（默认，保留工作区更改）
git reset HEAD~1

# 硬重置（丢弃所有更改）⚠️ 危险
git reset --hard HEAD~1

交互式变基：

# 重新排列、合并、编辑最近 3 次提交
git rebase -i HEAD~3

# 变基到 develop 分支
git rebase develop

拣选提交：

# 将特定提交应用到当前分支
git cherry-pick <commit-hash>

过滤历史：

# 修改所有历史提交的作者信息
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

强制推送规范

⚠️ 危险操作，需谨慎！

基本强制推送：

git push --force origin master

更安全的强制推送： ⭐ 推荐

# 只有当远程分支与本地预期一致时才推送
git push --force-with-lease origin master

禁止强制推送的分支：

❌ master / main （除非修复历史问题）
❌ develop （需要团队同意）
✅ feature/* （可以，仅影响个人）
✅ fix/* （可以，仅影响个人）

强制推送前检查清单：

是否已创建备份分支？
是否已通知团队成员？
是否确认没有其他人基于当前分支工作？
是否了解强制推送的后果？
是否可以使用 --force-with-lease 替代 --force？

垃圾回收与清理

清理未追踪文件：

# 预览将被删除的文件
git clean -n

# 删除未追踪文件
git clean -f

# 删除未追踪文件和目录
git clean -fd

# 包括 .gitignore 中的文件
git clean -fdx

清理过期引用：

# 清理过期的 reflog
git reflog expire --expire=now --all

# 运行垃圾回收
git gc --prune=now

# 积极的垃圾回收（更彻底，更慢）
git gc --prune=now --aggressive

查看仓库大小：

# 查看 .git 目录大小
git count-objects -vH

代码审查流程

👥 Pull Request / Merge Request 规范

PR/MR 标题：

[类型] 简短描述（≤50字符）

示例：
[Feature] 实现 AI 智能文献标题摘要初筛
[Fix] 修复下拉菜单点击无响应问题
[Refactor] 重构用户认证逻辑
[Docs] 更新 Git 提交规范文档

PR/MR 描述模板：

## 📝 变更说明
简要描述这个 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: 提交后发现有错误，如何修改？

# 修改后重新提交（未推送到远程）
git add .
git commit --amend --no-edit

# 如果已推送，需要强制推送
git push --force-with-lease origin feature/xxx

Q2: 如何撤销已推送的提交？

# 方式 1：创建一个新的 revert 提交（推荐）
git revert <commit-hash>
git push origin master

# 方式 2：重置后强制推送（危险，不推荐）
git reset --hard HEAD~1
git push --force origin master

Q3: 如何解决合并冲突？

# 1. 拉取最新代码
git pull origin develop

# 2. 手动解决冲突文件

# 3. 标记为已解决
git add <conflicted-files>

# 4. 完成合并
git commit -m "chore: merge develop into feature/xxx"

Q4: 如何查看某个文件的修改历史？

# 查看文件的提交历史
git log --follow -- path/to/file

# 查看文件的详细修改内容
git log -p -- path/to/file

# 查看每行代码的最后修改信息
git blame path/to/file

Q5: 如何恢复已删除的文件？

# 查找删除该文件的提交
git log --all --full-history -- path/to/file

# 恢复文件（从删除前的提交）
git checkout <commit-hash>^ -- path/to/file

Q6: 如何临时保存未提交的更改？

# 保存更改
git stash save "描述信息"

# 查看保存的更改
git stash list

# 恢复更改
git stash pop

# 恢复特定的 stash
git stash apply stash@{0}

Q7: 提交信息写错了怎么办？

# 修改最后一次提交信息（未推送）
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 中添加：

[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)"

使用示例：

git st           # 相当于 git status
git lg           # 美化的日志
git push-current # 推送当前分支

📚 推荐阅读

Git 学习资源：

提交规范：

📞 获取帮助

遇到问题？

查看本文档的常见问题部分
搜索 Git 官方文档
向团队技术负责人咨询
在团队群聊中讨论

文档反馈： 如果发现文档错误或有改进建议，请：

提交 Issue
直接修改并提交 PR
联系文档维护人

⚠️ Cursor IDE 环境专用最佳实践

⭐⭐⭐⭐⭐ 血泪教训：未提交的代码可能永久丢失！

🔴 真实案例：DC模块代码丢失事件

事件回顾（2025-11-27）：

开发过程：
- 完成了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集成测试
悲剧发生：
- 开发完成后未立即提交到Git
- 代码停留在Cursor的临时缓存中
- Cursor重启/缓存清理后，代码全部消失
- 只保留了文档和空目录结构
损失评估：
- 💔 2-3天的开发工作完全丢失
- 💔 所有Service实现代码丢失
- 💔 Prisma模型定义丢失
- 💔 测试代码丢失
- ✅ 幸运的是设计文档保留了
恢复难度：
- ❌ Cursor缓存已清理，无法恢复
- ❌ Git历史中无任何记录
- ❌ Windows文件历史无记录
- ✅ 只能基于设计文档完全重建

🛡️ 防止代码丢失的强制规则

规则1：每天下班前必须提交 ⭐⭐⭐⭐⭐

# 每天下班前执行的标准流程
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：重要功能完成后立即提交

# 场景：刚完成一个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：

# 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

使用方法：

# 关闭Cursor前运行
.\check-git-status.ps1

规则4：设置Cursor关闭提醒

在 workspace settings.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
确认无未提交修改
确认最新提交已推送

🆘 紧急恢复指南

如果代码已丢失，尝试以下方法：

检查Cursor缓存：

Get-ChildItem "C:\Users\zhibo\.cursor\" -Recurse -Include "*.ts" 
  | Sort-Object LastWriteTime -Descending | Select-Object -First 50

检查Git对象：

git fsck --lost-found
git reflog

检查Windows文件历史：
- 右键项目文件夹 → 属性 → 以前的版本
如果完全无法恢复：
- 基于设计文档重建（幸好保留了文档）
- 吸取教训，强化每日提交习惯

💡 Cursor环境推荐设置

VS Code / Cursor 设置：

{
  "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 规范和中文乱码解决方案

42 KiB Raw Permalink Blame History Unescape Escape

Git 提交规范

🚨 紧急警告：必须每日提交！

事件回顾

🔥 强制规则（立即生效）

💡 最佳实践

📋 目录

远程仓库配置

🌐 Gitee 仓库信息

克隆仓库

Commit Message 规范

⚠️ 重要提示：避免中文乱码

📝 格式规范

Type 类型

Scope 范围

Subject 主题

Body 详细描述

Footer 脚注

完整示例

提交频率与时机

🎯 基本原则

原则 0：每日必提交原则（最高优先级）⭐⭐⭐⭐⭐

原则 1：批量提交，避免碎片化提交

原则 2：必须验证测试后才能提交

原则 3：只在明确授权时提交

📋 提交检查清单

🚫 禁止的行为

✅ 推荐的提交场景

💡 最佳实践

分支管理策略

🌿 分支类型

主分支

辅助分支

分支命名规范

中文编码问题解决

⚠️ 问题描述

✅ 预防措施

🔧 修复历史提交中的中文乱码

⚠️ 注意事项

🔴🔴🔴 UTF-8 文件内容编码安全（2026-01-16 新增）

问题根本原因

🔥 强制规则（立即生效）

🔧 修复已损坏文件的方法

💡 预防措施总结

Git 历史重写与维护

🛠️ 常用命令

强制推送规范

垃圾回收与清理

代码审查流程

👥 Pull Request / Merge Request 规范

Code Review 检查清单

Review 响应时间

常见问题与最佳实践

🤔 常见问题

💡 最佳实践

🔧 有用的 Git 别名

📚 推荐阅读

📞 获取帮助

⚠️ Cursor IDE 环境专用最佳实践

🔴 真实案例：DC模块代码丢失事件

🛡️ 防止代码丢失的强制规则

规则1：每天下班前必须提交 ⭐⭐⭐⭐⭐

规则2：重要功能完成后立即提交

规则3：使用Git状态检查脚本

规则4：设置Cursor关闭提醒

🚨 Cursor环境风险点

✅ 安全的开发流程

📋 每日开发检查清单

🆘 紧急恢复指南

💡 Cursor环境推荐设置

42 KiB

Raw Permalink Blame History