docs: add branch workflow management rules

docs/development/branch-workflow.md

@@ -0,0 +1,73 @@
+# 安心验分支协作规范
+
+本项目使用最外层 Git 仓库统一管理 `server-api`、`admin-web`、`user-app`、`work-app` 和文档。不要在子目录中单独维护分支体系；涉及多端联动的需求应放在同一个功能分支和合并请求中，方便评审、测试、发版和回滚。
+
+`releases/` 下的 zip、apk、校验文件等发布产物只作为本地交付物管理，不纳入 Git 分支管理范围，也不要提交或推送到远程仓库。
+
+## 长期分支
+
+| 分支 | 用途 | 维护规则 |
+| --- | --- | --- |
+| `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`。示例：
+
+```bash
+git switch develop
+git pull --ff-only
+git switch -c feature/admin-report-export
+```
+
+## 日常开发流程
+
+1. 从 `develop` 更新最新代码。
+2. 创建 `feature/<scope>-<name>` 分支。
+3. 在功能分支提交改动，提交信息使用清晰的 Conventional Commits 风格，例如 `feat: add report export`。
+4. 提交合并请求到 `develop`，说明涉及的端、业务入口、验证结果和风险点。
+5. 合并前保持分支基于最新 `develop`，优先使用正常 merge 或 rebase，禁止强推公共协作分支。
+
+## 提交前检查
+
+所有提交前至少完成：
+
+```bash
+git status -sb
+git diff --check
+npx gitnexus detect-changes --scope all
+```
+
+如果修改了 PHP 后端文件，补充运行相关 PHP 语法检查或项目脚本；如果修改了前端，按影响端运行对应的类型检查或构建。发版前按上线检查清单执行 `server-api/tools/release_audit.php`、`server-api/tools/smoke_check.php` 和相关客户端构建。
+
+发布包生成后保留在本地 `releases/` 目录并按需另行交付；Git 提交中不包含 release 包。
+
+## 发版流程
+
+1. 从最新 `develop` 创建 `release/<version-or-date>`。
+2. 在 release 分支只接受发布必要修复、配置核对和文档更新。
+3. 通过上线检查后，将 release 分支合并到 `master` 并打 tag。
+4. 将 `master` 的发布结果回合到 `develop`，保证开发线包含发布修复。
+
+## Hotfix 流程
+
+1. 从最新 `master` 创建 `hotfix/<name>`。
+2. 只修改线上故障必需内容，避免夹带普通需求。
+3. 验证通过后合并到 `master` 并发布。
+4. 立即将 `master` 回合到 `develop`，避免同一问题在后续版本中回退。
+
+## Gitea 仓库设置
+
+- 默认分支设为 `master`。
+- 保护 `master`，要求通过合并请求进入。
+- 建议保护 `develop`；团队早期可以只限制普通成员直接 push。
+- 不提前保护 `feature/*`、`release/*`、`hotfix/*`，按团队规模和协作习惯逐步增加规则。