签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,192 @@
+# Git提交规范
+
+## 概述
+
+ 使用 Conventional Commits 规范管理提交信息，确保提交历史清晰可读，便于自动生成变更日志和语义化版本管理。
+
+:::tip Conventional Commits 格式
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+:::
+
+## 提交类型（type）
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `feat` | 新功能 | `feat(user): 添加用户导入功能` |
+| `fix` | 修复 bug | `fix(auth): 修复 token 过期后未刷新的问题` |
+| `docs` | 文档变更 | `docs: 更新部署文档` |
+| `style` | 代码格式（不影响逻辑） | `style: 格式化代码缩进` |
+| `refactor` | 重构（非新功能非修复） | `refactor(repo): 统一查询方法封装` |
+| `perf` | 性能优化 | `perf(query): 优化分页查询性能` |
+| `test` | 测试相关 | `test(unit): 添加岗位模块单元测试` |
+| `chore` | 构建/工具变更 | `chore: 更新依赖版本` |
+| `ci` | CI/CD 变更 | `ci: 添加 GitHub Actions 配置` |
+| `revert` | 回滚提交 | `revert: 回滚 feat(user) 提交` |
+
+## 范围（scope）
+
+可选，用于说明影响的模块或组件：
+
+```
+feat(user): 用户模块
+fix(auth): 认证模块
+refactor(repo): Repository 层
+feat(api): API 层
+docs(deploy): 部署文档
+```
+
+## 提交信息示例
+
+### 简单提交
+
+```
+feat(position): 添加岗位状态切换接口
+fix(captcha): 修复验证码过期时间计算错误
+docs: 更新 README 安装说明
+```
+
+### 带正文的提交
+
+```
+fix(auth): 修复 token 刷新后旧 token 仍有效的问题
+
+旧 token 在刷新后未加入黑名单，导致短时间内可同时使用新旧两个 token。
+修复方案：刷新时将旧 token 加入 Redis 黑名单。
+
+Closes #123
+```
+
+### 破坏性变更
+
+```
+feat(api)!: 统一响应格式，移除 data.code 字段
+
+BREAKING CHANGE: 响应格式从 {data: {code, data}} 变为 {code, data, msg, ok}
+前端需同步更新响应处理逻辑。
+```
+
+:::warning 破坏性变更
+破坏性变更使用 `!` 后缀标记，并在正文或 footer 中说明 `BREAKING CHANGE`。此类变更需在版本号中体现（主版本号 +1）。
+:::
+
+## 分支策略
+
+| 分支 | 用途 | 命名格式 | 说明 |
+|------|------|---------|------|
+| `main` | 主分支（生产） | `main` | 始终保持可发布状态 |
+| `master` | 开发主分支 | `master` | 日常开发合并目标 |
+| `feature/*` | 功能分支 | `feature/功能名` | 从 master 拉取 |
+| `fix/*` | 修复分支 | `fix/问题描述` | 从 master 拉取 |
+| `hotfix/*` | 紧急修复 | `hotfix/问题描述` | 从 main 拉取 |
+
+### 分支工作流
+
+```
+1. 从 master 创建功能分支
+ git checkout -b feature/position-import master
+
+2. 开发完成后提交
+ git commit -m "feat(position): 添加岗位 Excel 导入功能"
+
+3. 合并到 master
+ git checkout master
+ git merge feature/position-import
+
+4. 推送到远程
+ git push origin master
+
+5. 生产发布时合并到 main
+ git checkout main
+ git merge master
+ git tag v1.2.0
+```
+
+## 版本标签
+
+使用语义化版本号（Semantic Versioning）：
+
+```
+v主版本号.次版本号.修订号
+v1.2.3
+
+主版本号：破坏性变更
+次版本号：新功能（向后兼容）
+修订号：Bug 修复
+```
+
+```bash
+# 创建标签
+git tag -a v1.2.0 -m "feat: 添加岗位导入功能"
+
+# 推送标签
+git push origin v1.2.0
+
+# 查看标签
+git tag -l
+```
+
+## .gitignore 配置
+
+```gitignore
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+venv/
+
+# 环境配置
+.env
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# 上传文件
+uploads/
+
+# 日志
+logs/
+
+# 数据库
+*.sqlite3
+```
+
+:::tip .env 安全
+`.env` 文件包含敏感信息（数据库密码、JWT 密钥等），必须在 `.gitignore` 中排除。各环境的 `.env` 独立管理，不提交到仓库。
+:::
+
+## 常用 Git 命令
+
+```bash
+# 查看提交历史
+git log --oneline -20
+
+# 查看某次提交的变更
+git show <commit-hash>
+
+# 撤销工作区修改
+git checkout -- <file>
+
+# 撤销暂存
+git reset HEAD <file>
+
+# 暂存当前工作
+git stash
+git stash pop
+
+# 查看分支图
+git log --graph --oneline --all
+```
+
+## 总结
+
+Git 提交规范采用 Conventional Commits 格式：`type(scope): subject`。常用类型包括 feat/fix/docs/refactor/test/chore。分支策略：main（生产）、master（开发）、feature/fix/hotfix（临时分支）。版本使用语义化标签（v1.2.0）。`.env` 等敏感文件必须排除在仓库之外。