Git推送规则

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: Git, 提交, 推送, commit, push, 规范, 工作流
---

# 仓库推送规范

本文档定义了项目的 Git 推送规范和自动化流程。

---

## &#128203; 推送规则

### 自动推送触发条件

以下情况**必须**自动推送到 Gitee 仓库：

1. ✅ **代码更新**
   - 新增功能代码
   - 修复 bug
   - 重构代码
   - 优化性能

2. ✅ **文档更新**
   - 更新日志（CHANGELOG）
   - 接口文档
   - 部署文档
   - 用户手册

3. ✅ **用户明确要求**
   - 用户说"推送"、"更新"、"提交"
   - 用户说"推送到码云"
   - 用户说"同步代码"

4. ✅ **关键任务完成**
   - 功能模块完成
   - 测试通过
   - 部署成功
   - 文档更新完成

---

## &#128640; 推送流程

### 标准推送流程

```bash
# 1. 添加所有更改
git add .

# 2. 提交更改（使用规范的提交信息）
git commit -m "feat: 新功能描述"
# 或
git commit -m "fix: 修复问题描述"
# 或
git commit -m "docs: 文档更新描述"

# 3. 推送到 Gitee
git push origin <branch-name>
```

### 推送前检查清单

- [ ] 代码已通过本地构建检查
- [ ] 更新日志（CHANGELOG）已更新
- [ ] 接口文档（如适用）已更新
- [ ] 提交信息符合规范
- [ ] 无敏感信息泄露

---

## &#128221; 提交信息规范

### 提交信息格式

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type 类型

| Type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat: 添加用户登录功能` |
| `fix` | 修复 bug | `fix: 修复数据库连接失败` |
| `docs` | 文档更新 | `docs: 更新部署文档` |
| `style` | 代码格式调整 | `style: 统一代码缩进` |
| `refactor` | 重构 | `refactor: 重构用户服务模块` |
| `test` | 测试 | `test: 添加单元测试` |
| `chore` | 构建/工具配置 | `chore: 更新依赖包` |
| `perf` | 性能优化 | `perf: 优化查询性能` |

### Scope 范围

常见范围：
- `app`: 应用主逻辑
- `api`: API 接口
- `ui`: UI 组件
- `db`: 数据库
- `deploy`: 部署配置
- `docs`: 文档
- `config`: 配置文件

### 示例

```bash
# 功能
git commit -m "feat(api): 添加工资表导出接口"

# 修复
git commit -m "fix(db): 修复薪资计算精度问题"

# 文档
git commit -m "docs(deploy): 更新部署文档，新增 Docker 配置"

# 重构
git commit -m "refactor(ui): 重构表格组件，提升性能"
```

---

## &#128218; 必须推送的文档

### 核心文档

- ✅ `CHANGELOG.md` - 更新日志
- ✅ `README.md` - 项目说明
- ✅ `API.md` - 接口文档（如有）
- ✅ `docs/DEPLOYMENT.md` - 部署文档
- ✅ `docs/API_DOCS.md` - API 文档目录

### 更新日志规范

每次推送必须更新 `CHANGELOG.md`：

```markdown
# 更新日志

## [版本号] - YYYY-MM-DD

### 新增
- [功能描述](issue 链接)

### 修复
- [问题描述](issue 链接)

### 变更
- [变更描述]

### 文档
- [文档更新内容]

---

## [上个版本] - YYYY-MM-DD
...
```

### 接口文档规范

如果新增或修改了 API，必须更新接口文档：

1. **API.md**（单文件方式）
2. **docs/API_DOCS.md**（目录方式）
3. **docs/api/**/*.md**（按模块分类）

每个接口应包含：
- 接口路径
- 请求方法（GET/POST/PUT/DELETE）
- 请求参数
- 响应示例
- 错误码

---

## &#128272; 凭证管理

### Gitee 凭证信息

- **仓库地址**: https://gitee.com/futurebird/machao
- **用户名**: futurebird
- **个人令牌**: 3719f9bb9fc4bf1d8edb0b9a0d066077

### 推送命令

```bash
# 使用 HTTPS + 令牌推送
git push https://futurebird:3719f9bb9fc4bf1d8edb0b9a0d066077@gitee.com/futurebird/oepnmachao.git <branch-name>

# 或配置环境变量后推送
export GITEE_TOKEN="3719f9bb9fc4bf1d8edb0b9a0d066077"
git push https://futurebird:${GITEE_TOKEN}@gitee.com/futurebird/oepnmachao.git <branch-name>
```

### 保存凭证（可选）

```bash
# 保存凭证到 git-credentials（不安全，仅限本地开发环境）
git config --global credential.helper store
git push origin main
# 输入一次后，后续无需再次输入
```

---

## &#128260; 分支管理规范

### 主分支

- `main`: 主分支，生产环境代码
  - 只接收合并请求（Merge Request）
  - 必须通过代码审查
  - 必须通过所有测试

### 开发分支

- `develop`: 开发分支
  - 日常开发使用
  - 可以直接推送
  - 定期合并到 main

- `feature/*`: 功能分支
  - 开发新功能
  - 完成后合并到 develop

- `bugfix/*`: 修复分支
  - 修复 bug
  - 完成后合并到 develop

### 重构分支

- `refactor/*`: 重构分支
  - 大型重构使用
  - 完成后合并到 develop

---

## &#129302; 自动化推送脚本

### 通用推送脚本

创建 `scripts/auto-push.sh`：

```bash
#!/bin/bash

# 自动推送脚本
# 使用方式: ./scripts/auto-push.sh [commit-message] [branch-name]

set -e

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# 配置
GITEE_USERNAME="futurebird"
GITEE_TOKEN="3719f9bb9fc4bf1d8edb0b9a0d066077"
REPO_URL="https://${GITEE_USERNAME}:${GITEE_TOKEN}@gitee.com/futurebird/oepnmachao.git"

# 参数
COMMIT_MSG=${1:-"chore: 自动提交代码更新"}
BRANCH_NAME=${2:-$(git branch --show-current)}

echo -e "${BLUE}========================================${NC}"
echo -e "${BLUE}&#128640; 自动推送到 Gitee${NC}"
echo -e "${BLUE}========================================${NC}"
echo ""

# 1. 检查是否有更改
if [ -z "$(git status --porcelain)" ]; then
    echo -e "${YELLOW}⚠ 没有需要提交的更改${NC}"
    exit 0
fi

# 2. 添加所有更改
echo -e "${YELLOW}&#128230; 添加更改...${NC}"
git add .
echo -e "${GREEN}✓ 更改已添加${NC}"
echo ""

# 3. 提交
echo -e "${YELLOW}&#128221; 提交更改...${NC}"
git commit -m "$COMMIT_MSG"
echo -e "${GREEN}✓ 提交成功: $COMMIT_MSG${NC}"
echo ""

# 4. 推送到 Gitee
echo -e "${YELLOW}&#128228; 推送到 Gitee...${NC}"
git push "$REPO_URL" "$BRANCH_NAME"
echo -e "${GREEN}✓ 推送成功${NC}"
echo ""

# 5. 显示状态
echo -e "${YELLOW}&#128202; 当前状态:${NC}"
git status

echo ""
echo -e "${GREEN}========================================${NC}"
echo -e "${GREEN}&#127881; 推送完成！${NC}"
echo -e "${GREEN}========================================${NC}"
```

### 使用方法

```bash
# 添加执行权限
chmod +x scripts/auto-push.sh

# 使用默认提交信息和当前分支
./scripts/auto-push.sh

# 自定义提交信息
./scripts/auto-push.sh "feat: 添加新功能"

# 指定分支
./scripts/auto-push.sh "fix: 修复问题" develop
```

---

## &#128203; 推送检查清单

### 推送前

- [ ] 代码已通过本地构建
- [ ] 代码已通过测试
- [ ] 更新日志已更新
- [ ] 接口文档已更新（如有 API 变更）
- [ ] 提交信息符合规范
- [ ] 无敏感信息泄露
- [ ] 分支名称正确

### 推送后

- [ ] 在 Gitee 验证推送成功
- [ ] 检查构建状态（如有 CI/CD）
- [ ] 通知团队成员（如需）
- [ ] 更新任务跟踪系统（如需）

---

## &#128680; 禁止推送的内容

### 敏感信息

- ❌ 密码
- ❌ API 密钥
- ❌ 数据库密码
- ❌ 个人令牌
- ❌ 证书文件（.pem, .key）
- ❌ 临时文件
- ❌ 日志文件

### 应忽略的文件

确保 `.gitignore` 包含：

```
# 环境变量
.env
.env.local
.env.*.local

# 依赖
node_modules/

# 构建产物
.next/
dist/
build/

# 日志
*.log
logs/

# 临时文件
*.tmp
*.temp
.DS_Store

# IDE
.vscode/
.idea/
```

---

## &#128202; 推送统计

### 查看推送记录

```bash
# 查看最近 10 次推送
git log --oneline -10

# 查看特定作者的推送
git log --author="username" --oneline

# 查看今天的推送
git log --since="today" --oneline

# 查看本周的推送
git log --since="1 week ago" --oneline
```

### 推送统计

```bash
# 统计提交次数
git rev-list --count HEAD

# 统计作者提交次数
git shortlog -sn

# 查看代码变更统计
git diff --stat HEAD~1
```

---

## &#128260; 同步流程

### 从 Gitee 拉取最新代码

```bash
# 拉取最新代码
git pull origin main

# 或拉取并合并
git fetch origin
git merge origin/main
```

### 解决冲突

```bash
# 1. 拉取最新代码
git pull origin main

# 2. 如果有冲突，查看冲突文件
git status

# 3. 解决冲突
# 编辑冲突文件，保留需要的代码

# 4. 标记冲突已解决
git add <conflicted-file>

# 5. 提交
git commit -m "fix: 解决合并冲突"

# 6. 推送
git push origin main
```

---

## &#128161; 最佳实践

### 1. 频繁推送

- ✅ 小步快跑，频繁提交
- ✅ 每完成一个功能就推送
- ✅ 避免累积大量更改

### 2. 规范提交

- ✅ 使用规范的提交信息
- ✅ 清晰描述变更内容
- ✅ 关联 issue 或 PR

### 3. 文档同步

- ✅ 代码更新时同步更新文档
- ✅ API 变更时更新接口文档
- ✅ 重大变更时更新 CHANGELOG

### 4. 代码审查

- ✅ 推送前进行自审
- ✅ 使用 Pull Request 进行协作
- ✅ 接受团队反馈

---

## &#128222; 问题排查

### 推送失败

```bash
# 1. 检查网络连接
ping gitee.com

# 2. 检查远程地址
git remote -v

# 3. 检查凭证
git config credential.helper

# 4. 重新配置凭证
git remote set-url origin https://futurebird:3719f9bb9fc4bf1d8edb0b9a0d066077@gitee.com/futurebird/oepnmachao.git

# 5. 清理缓存
git credential-cache exit

# 6. 重新推送
git push origin main
```

### 认证失败

```bash
# 检查令牌是否正确
# 访问: https://gitee.com/profile/personal_access_tokens

# 更新令牌
export GITEE_TOKEN="new-token"
git push https://futurebird:${GITEE_TOKEN}@gitee.com/futurebird/oepnmachao.git main
```

---

## &#127919; 总结

### 推送原则

1. **及时推送**：完成功能后立即推送
2. **规范提交**：使用规范的提交信息
3. **文档同步**：代码和文档同步更新
4. **质量保证**：推送前确保代码质量

### 核心要求

- ✅ 每次更新都要推送
- ✅ 更新日志必须同步
- ✅ 接口文档必须同步
- ✅ 提交信息符合规范

---

**仓库地址**: https://gitee.com/futurebird/machao
**文档版本**: v1.0
**最后更新**: 2024-01-XX