安心验分支协作规范

本项目使用最外层 Git 仓库统一管理 server-api、admin-web、user-app、work-app 和文档。不要在子目录中单独维护分支体系；涉及多端联动的需求应放在同一个功能分支和合并请求中，方便评审、测试、发版和回滚。

releases/ 和 releases_dev/ 下的 zip、apk、校验文件等发布产物只作为本地交付物管理，不纳入 Git 分支管理范围，也不要提交或推送到远程仓库。正式包放 releases/，测试包放 releases_dev/。

本地开发环境和测试服共用测试数据库连接，测试库名为 test_anxinyan。真实的数据库 host、用户名和密码只允许放在被忽略的 server-api/.env 或服务器环境变量中，不写入 README、规范文档、Skill、.env.example 或其他可提交模板。

长期分支

分支	用途	维护规则
`master`	稳定主线，代表已经验证、可发布的状态	禁止日常直接开发；通过合并请求进入
`develop`	多人开发集成分支	日常功能从这里拉分支，完成后合回这里

初始化完成后，本地默认停留在 develop。日常开发不要直接在 master 上提交业务代码。

临时分支

分支模式	用途	来源	合并目标
`feature/<scope>-<name>`	普通需求或优化	`develop`	`develop`
`release/<version-or-date>`	发版冻结和发布修复	`develop`	`master`，再回合 `develop`
`hotfix/<name>`	线上紧急修复	`master`	`master`，再回合 `develop`

scope 建议使用端或模块名，例如 api、admin、user、work、docs、fulfillment、report。示例：

git switch develop
git pull --ff-only
git switch -c feature/admin-report-export

日常开发流程

从 develop 更新最新代码。
创建 feature/<scope>-<name> 分支。
在功能分支提交改动，提交信息使用清晰的 Conventional Commits 风格，例如 feat: add report export。
提交合并请求到 develop，说明涉及的端、业务入口、验证结果和风险点。
合并前保持分支基于最新 develop，优先使用正常 merge 或 rebase，禁止强推公共协作分支。

提交前检查

所有提交前至少完成：

git status -sb
git diff --check
npx gitnexus detect-changes --scope all --repo anxinyan

如果修改了 PHP 后端文件，补充运行相关 PHP 语法检查或项目脚本；如果修改了前端，按影响端运行对应的类型检查或构建。正式包发版前按上线检查清单执行 server-api/tools/release_audit.php、server-api/tools/smoke_check.php 和相关客户端构建；测试包构建前确认各端测试环境配置指向 https://test.api.anxinjianyan.com。

正式包生成后保留在本地 releases/ 目录，测试包生成后保留在本地 releases_dev/ 目录，并按需另行交付；Git 提交中不包含这些产物。

涉及本地或测试服数据库配置时，提交前确认 server-api/.env 仍被 Git 忽略，并检查 README、docs、.claude 和 .env.example 等可提交文件中没有真实数据库密码：

git check-ignore -v server-api/.env

GitNexus 索引协同

Git 分支负责协作路径，GitNexus 负责改动影响面。推荐节奏：

开发前在 develop 上创建 feature/<scope>-<name>。
不熟悉代码时先用 GitNexus query/context 找入口和流程。
修改函数、类或方法前先做 upstream impact analysis。
提交前运行 npx gitnexus detect-changes --scope all --repo anxinyan。
提交、合并、切换分支或 rebase 后，由本地 hook 异步刷新 GitNexus 索引。

团队成员首次 clone 后执行一次：

git config core.hooksPath scripts/git-hooks

自动刷新只执行 npx gitnexus analyze --index-only --name anxinyan .，不会更新 AGENTS.md、CLAUDE.md 或 GitNexus skills。它不替代提交前的 detect-changes 检查。需要临时关闭时，在 Git 命令前加 GITNEXUS_AUTO_REFRESH=0；需要手动刷新时运行：

./scripts/gitnexus-refresh.sh

发版流程

从最新 develop 创建 release/<version-or-date>。
在 release 分支只接受发布必要修复、配置核对和文档更新。
通过上线检查后，将 release 分支合并到 master 并打 tag。
将 master 的发布结果回合到 develop，保证开发线包含发布修复。

Hotfix 流程

从最新 master 创建 hotfix/<name>。
只修改线上故障必需内容，避免夹带普通需求。
验证通过后合并到 master 并发布。
立即将 master 回合到 develop，避免同一问题在后续版本中回退。

Gitea 仓库设置

默认分支设为 master。
保护 master，要求通过合并请求进入。
建议保护 develop；团队早期可以只限制普通成员直接 push。
不提前保护 feature/*、release/*、hotfix/*，按团队规模和协作习惯逐步增加规则。

5.0 KiB Raw Permalink Blame History Unescape Escape