docs(GOV-004): 明确提交后强制推送设计

2026-08-12 18:36:23 +08:00
parent 4b390d9989
commit 757d8ab6a5
2 changed files with 104 additions and 0 deletions
@@ -0,0 +1,78 @@
+# 提交后强制推送 Gitea 设计规格
+
+- 功能编号：GOV-004
+- 规格版本：0.1
+- 状态：approved_for_review
+- 日期：2026-08-12
+
+## 背景与目标
+
+本地提交如果没有同步到远程，无法实现跨设备备份、Gitea 审阅和可靠的版本追溯。本功能把推送从“需要逐次授权的可选动作”改成项目开发流程的固定完成条件。
+
+目标是：每次本地提交在验证通过后立即同步当前分支；创建版本标签后同步该标签；任何推送失败都会阻止任务被报告为完成。
+
+## 方案比较
+
+### 方案 A：按变化精确推送（采用）
+
+- 普通提交执行 `git push origin <当前分支>`。
+- 创建新标签后执行 `git push origin <标签名>`。
+- 优点：只同步本次明确产生的引用，行为可预测，不会意外发布其他本地标签。
+- 代价：分支和标签需要分别执行推送。
+
+### 方案 B：每次提交推送分支及全部标签
+
+- 执行 `git push origin <当前分支> --tags`。
+- 优点：命令较少。
+- 缺点：可能把尚未准备发布的历史或实验标签一并推送，不采用。
+
+### 方案 C：仅发布时批量推送
+
+- 多个本地提交积累到版本发布时再统一同步。
+- 优点：减少远程交互次数。
+- 缺点：提交期间缺少远程备份，也不符合“提交后需要推送”的要求，不采用。
+
+## 强制流程
+
+1. 完成测试、构建、Review、GitNexus 变更检测和敏感信息检查。
+2. 创建符合中文 Conventional Commit 的本地提交。
+3. 获取当前分支名，执行 `git push origin <当前分支>`。
+4. 如果本次创建了标签，再执行 `git push origin <标签名>`。
+5. 使用 `git status -sb` 或远程引用检查，确认本地分支与远程分支一致。
+6. 把提交 SHA、推送目标、推送结果和标签结果写入功能档案。
+7. 只有分支及本次新建标签全部推送成功后，任务才可以标记完成。
+
+## 失败处理
+
+- 认证、网络、分支保护或服务器错误发生时，保留本地提交和标签，不删除、不改写历史。
+- 将任务状态标为“推送失败/未完成”，记录失败命令、时间和不包含凭据的错误摘要。
+- 修复原因后重复同一个精确推送命令；禁止使用 `--force`、`--force-with-lease` 或绕过保护规则。
+- 远程出现未知提交导致非快进失败时，先获取并检查差异，不自动 rebase、merge 或覆盖远程。
+- 密码和令牌继续由 macOS Keychain 管理，禁止写入文档、脚本、远程 URL、命令参数和 Git 历史。
+
+## 配置与作用域
+
+- 唯一允许的推送远程是当前项目 `.git/config` 中的 `origin`。
+- 推送前必须验证 `origin` 仍为 `https://git.foximao.com/FoXiMao/a-share-analysis.git`。
+- 禁止修改 Git 全局配置，禁止影响其他项目，禁止新增 GitHub 远程。
+- 本规则适用于业务代码、治理文档、规格、Review 修正和版本封存等所有提交。
+
+## 文档变更范围
+
+- `AGENTS.md`：把提交后推送改为代理强制要求。
+- `docs/governance/development-workflow.md`：把推送加入开发后流程和完成定义。
+- `docs/governance/version-control-and-gitea.md`：记录标准命令、失败处理和验证方法。
+- `README.md`：简述项目提交会同步到 Gitea。
+- `docs/features/GOV-004-mandatory-gitea-push/`：保存 PRD、需求、实施计划、测试、Review、GitNexus 前后对比、发布和回退证据。
+
+GOV-003 是当时“只接入、不推送”的历史决策记录，保持原文不变；GOV-004 作为后续决策明确取代其推送授权规则，保证历史可追溯。
+
+## 验收标准
+
+- 所有现行入口规范不再包含“默认不推送”或“逐次取得用户授权”的冲突要求。
+- 规范明确普通提交推当前分支、新标签单独推送、失败不算完成、禁止强推。
+- `main` 的本地历史同步到 `origin/main`。
+- 已有版本标签 `v0.0.0`、`v0.0.1`、`v0.0.2` 同步到远程。
+- GOV-004 的提交和后续封存标签也按相同规则同步。
+- 全局 Git 配置保持不变，敏感信息扫描无发现。
+- 治理测试、完成门禁和 GitNexus 前后检测通过。