docs(GOV-003): 配置项目专用 Gitea 远程仓库

2026-08-12 18:33:09 +08:00
parent 7c7190998b
commit b69023e3f8
24 changed files with 336 additions and 11 deletions
@@ -0,0 +1,17 @@
+# 设计
+
+## 配置边界
+
+Git 仓库级配置存放在本项目 `.git/config`，天然不被提交，也不会作用于同一台机器上的其他项目。远程 URL 只包含协议、主机、所有者与仓库名，不嵌入用户名密码。
+
+## 凭据处理
+
+选择 macOS 原生 `osxkeychain` 凭据助手，避免明文凭据。设置 `credential.useHttpPath=true`，使 `git.foximao.com` 下不同仓库可以按 URL 路径隔离凭据；项目账号作为非敏感标识保存在本地仓库配置和治理文档中。
+
+## 授权边界
+
+远程接入分为两种权限：只读检查属于本次配置验证；推送会改变外部状态，需要用户另行明确授权。因此本次只执行非交互 `ls-remote`，不推送 `main` 或标签。
+
+## 文档边界
+
+文档记录可复现配置，但只引用密码的安全管理规则，不记录密码本身。这样既满足项目可追溯性，也避免秘密随克隆、备份和历史版本扩散。
@@ -0,0 +1,9 @@
+# GitNexus 开发后结果
+
+- 执行：`npx gitnexus analyze`。
+- 索引结果：349 个节点、375 条关系、5 个集群、0 条执行流程。
+- 增量分析：6 个已修改文件、14 个新增文件、0 个删除文件。
+- 索引提交：`7c71909`；工作区文档变化已纳入增量索引。
+- 状态：up-to-date。
+
+本功能没有修改生产代码、函数调用关系或业务流程。新增节点主要来自 GOV-003 功能档案和版本控制文档标题。
@@ -0,0 +1,26 @@
+# GitNexus 开发前基线
+
+- 功能编号：GOV-003
+- 记录时间：2026年8月12日 GMT+8 18:28:00
+- 分支：main
+- 基线提交：7c7190998b6d
+
+## 工作区
+
+```text
+(干净)
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/12/2026, 6:27:10 PM
+Indexed commit: 7c71909
+Current commit: 7c71909
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
@@ -0,0 +1,10 @@
+# GitNexus 前后对比
+
+| 项目 | 开发前 | 开发后 | 变化 |
+|---|---:|---:|---:|
+| 节点 | 301 | 349 | +48 |
+| 关系 | 326 | 375 | +49 |
+| 集群 | 5 | 5 | 0 |
+| 执行流程 | 0 | 0 | 0 |
+
+节点和关系增长来自 Gitea 治理说明及完整功能档案；没有新增或改变业务执行流程。变更检测风险为低，与开发前影响预估一致。
@@ -0,0 +1,8 @@
+# GitNexus 变更检测
+
+- 命令：`npx gitnexus detect-changes --repo a-share-analysis --scope all`。
+- 最终暂存区识别范围：24 个文件、51 个文档符号。
+- 受影响流程：0。
+- 风险等级：低。
+
+初次对未暂存变化检测到 7 个既有文件、14 个符号；完整暂存后，GOV-003 新建档案也被纳入检测，最终扩大为 24 个文件、51 个符号。纯文本版本文件和 Changelog 另外通过 `git status`、`git diff --stat` 和完整必备文件门禁核对。
@@ -0,0 +1,8 @@
+# GitNexus 开发前影响分析
+
+- 查询主题：`Gitea local remote version control configuration`。
+- 主要关联：`docs/governance/version-control-and-gitea.md`、`docs/index.md`、`VERSION`、`AGENTS.md` 和 `README.md`。
+- 符号影响检查：`getRequiredFeatureFiles` 只有 1 个直接上游依赖 `finish.mjs`，不参与执行流程，风险为低。
+- 实际变化以文档和 Git 仓库级配置为主，不修改生产代码、API、数据库或前端页面。
+- 预计影响：版本控制入口说明、开发代理约束、版本号和 GOV-003 功能档案。
+- 风险控制：不修改全局配置、不保存密码、不执行推送；修改后重新索引并执行变更检测。
@@ -0,0 +1,10 @@
+# 实施计划
+
+1. 执行开发前 GitNexus 更新、查询和影响分析。
+2. 核对当前远程、本地配置和全局配置基线。
+3. 添加 `origin`，使用 `--local` 设置凭据隔离和默认推送目标。
+4. 通过非交互 `git ls-remote origin` 验证只读连通性。
+5. 更新版本控制规范、代理约束、README、文档索引与版本记录。
+6. 保存 PRD、设计、测试、GitNexus 前后对比和回退说明。
+7. 执行治理测试、敏感信息检查、配置边界检查和双 Review。
+8. 以中文提交封存，并建立本地 `v0.0.2` 标签；不推送。
@@ -0,0 +1,17 @@
+id: GOV-003
+name: 项目专用 Gitea 远程仓库
+slug: gitea-local-remote
+status: verifying
+owner: project
+created_at: 2026-08-12
+prd: prd.md
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+code_review: review/code-review.md
+standards_review: review/standards-review.md
+implementation_commit: pending
+release: v0.0.2
@@ -0,0 +1,37 @@
+# 项目专用 Gitea 远程仓库 PRD
+
+- 功能编号：GOV-003
+- PRD 版本：0.1
+- 状态：approved
+- 日期：2026-08-12
+
+## 问题
+
+项目已有可追溯的本地 Git 基线，但尚未关联用户自建 Gitea。接入过程中必须避免把项目凭据扩散到其他仓库，或把密码写入可提交文件和 Git 历史。
+
+## 目标
+
+- 将当前项目的 `origin` 指向指定 Gitea 仓库。
+- 所有 Git 设置只作用于当前项目，不修改全局配置。
+- 使用系统钥匙串保存未来交互式认证产生的凭据，并按仓库路径隔离。
+- 在治理文档中记录地址、账号、配置、验证和回退方法。
+
+## 非目标
+
+- 本次不向远程推送任何提交或标签。
+- 不在项目内保存密码或访问令牌。
+- 不配置 Gitea Actions、Webhook、分支保护或持续集成服务端规则。
+- 不修改其他项目的 Git 配置。
+
+## 用户流程
+
+项目维护者可以从文档确认唯一远程地址和项目账号；代理和开发者使用项目级配置进行读取。首次获得明确推送授权后，维护者在交互式终端完成认证，凭据由 macOS Keychain 管理。
+
+## 验收标准
+
+- `git remote -v` 的 fetch/push 均为指定仓库。
+- 项目级凭据助手为 `osxkeychain`，`credential.useHttpPath` 为 `true`。
+- 全局凭据助手与默认推送目标保持修改前状态。
+- 无密码进入文档、远程 URL、Git 配置或 Git 历史。
+- `git ls-remote origin` 可以建立只读连接。
+- PRD、设计、测试、Review 和回退档案完整。
@@ -0,0 +1,20 @@
+# 测试结果
+
+## 结果摘要
+
+- `npm run test:governance`：5 个测试通过，0 个失败。
+- `GIT_TERMINAL_PROMPT=0 git ls-remote origin`：退出码 0；远程是空仓库，返回引用为空。
+- fetch 与 push URL：均精确匹配指定 Gitea 仓库。
+- 项目级配置：`osxkeychain`、路径隔离、账号和默认推送目标全部匹配设计。
+- 全局边界：全局 `credential.helper` 和 `remote.pushDefault` 仍未设置。
+- 凭据模式扫描：未发现带用户名密码的 URL、密码赋值或令牌赋值。
+- `git diff --check`：通过。
+
+## 诊断与修正
+
+1. 测试计划最初写成不存在的 `npm test`，执行时因缺少脚本失败；检查 `package.json` 后修正为项目实际提供的 `npm run test:governance`，复测通过。
+2. GitNexus 变更检测最初未指定仓库；本机存在多个索引时工具拒绝猜测。增加 `--repo a-share-analysis` 后成功；最终暂存区结果为 24 个文件、51 个符号、0 条流程，风险为低。
+
+## 完成门禁
+
+双 Review 完成后执行 `npm run governance:finish -- GOV-003 gitea-local-remote`，退出码为 0。门禁确认完整功能档案和两份固定 `passed` Review 均已就绪。
@@ -0,0 +1,3 @@
+# 视觉验证
+
+本功能只修改 Git 仓库级配置和治理文档，不改变界面、样式或交互，因此视觉验证不适用。
@@ -0,0 +1,8 @@
+# 发布说明
+
+## v0.0.2
+
+- 为当前项目配置指定 Gitea `origin`，不影响其他项目。
+- 使用 macOS Keychain 与仓库路径隔离策略管理未来认证凭据。
+- 增加远程接入、授权边界、验证和回退文档。
+- 本版本只建立远程连接，不推送本地提交或标签。
@@ -0,0 +1,9 @@
+# 工程需求
+
+- 远程名固定为 `origin`，地址固定为 `https://git.foximao.com/FoXiMao/a-share-analysis.git`。
+- 使用 `git config --local` 写入凭据助手、路径隔离、账号和默认推送目标。
+- 不调用 `git config --global`，验证前后全局相关配置一致。
+- 不将密码传给 Shell 命令，也不把密码写入仓库文件或 `.git/config`。
+- 使用非交互、只读的 `git ls-remote origin` 检查网络与仓库可达性。
+- 未取得单独明确授权时，不运行 `git push`。
+- 更新根目录入口、治理规范、文档索引、版本和完整功能档案。
@@ -0,0 +1,31 @@
+# 配置与文档 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 基线提交：`7c71909`
+- 实现提交：`pending`
+- 审查范围：项目级 Gitea 远程、凭据隔离、治理文档和回退方案
+- 日期：2026-08-12
+
+## PRD 与设计符合性
+
+实现满足六项验收标准：远程 URL 正确；凭据设置仅位于 `.git/config`；全局配置未变化；密码没有进入文档、配置或历史；只读连通性成功；功能档案完整。
+
+## 发现与处置
+
+| 严重程度 | 发现 | 处置 |
+|---|---|---|
+| Important | 用户提供了密码，但写入文档或命令会形成长期泄露面 | 文档只保存基础地址、账号和仓库 URL；密码不落盘，由 Keychain 在未来交互认证时接管 |
+| Important | 使用全局凭据配置会影响其他项目 | 全部使用 `git config --local`，并验证相关全局项保持未设置 |
+| Minor | 初始测试计划引用了不存在的 `npm test` | 改用仓库实际的 `npm run test:governance` 并复测 5/5 通过 |
+| Minor | GitNexus 多仓库环境无法自动选择索引 | 显式增加 `--repo a-share-analysis`，变更检测成功 |
+
+## 验证
+
+- 远程只读连接、fetch/push URL 和四项本地配置断言全部通过。
+- 全局配置边界断言通过。
+- 凭据模式扫描与 `git diff --check` 通过。
+- GitNexus 最终暂存区检测 24 个文件、51 个符号、0 条流程，风险为低。
+- 没有执行 `git push`，未改变 Gitea 远程仓库内容。
+
+最终结论：passed
@@ -0,0 +1,24 @@
+# 开发规范符合性 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 实现提交：`pending`
+- 日期：2026-08-12
+
+## 检查结果
+
+- [x] 开发前执行治理启动命令并保存 GitNexus 基线。
+- [x] PRD、工程需求、设计、实施计划、测试计划和回退说明一致。
+- [x] 修改仅涉及项目级 Git 配置和治理文档，没有过度拆分生产代码。
+- [x] 基础地址、账号和仓库 URL 可追溯，密码和令牌未进入仓库。
+- [x] Git 全局配置没有修改，不影响其他项目。
+- [x] 未配置 GitHub，唯一远程为用户指定 Gitea。
+- [x] 没有未经授权推送外部状态。
+- [x] 治理测试、配置断言、敏感信息扫描和 GitNexus 变更检测通过。
+- [x] 本功能无界面变化，视觉验证已合理标记为不适用。
+
+## 不符合项与处置
+
+没有未解决的 Critical 或 Important 不符合项。两项执行期错误均属于测试命令选择问题，已修正文档并以成功复测关闭。
+
+最终结论：passed
@@ -0,0 +1,13 @@
+# 回退说明
+
+本功能的运行时影响仅限当前项目 `.git/config`。如需解除接入，在本项目根目录执行：
+
+```bash
+git remote remove origin
+git config --local --unset credential.helper
+git config --local --unset credential.useHttpPath
+git config --local --unset credential.username
+git config --local --unset remote.pushDefault
+```
+
+若 Keychain 已在后续交互式认证中保存凭据，再使用“钥匙串访问”按 `git.foximao.com` 删除对应项。文档和版本记录通过新的中文修复提交回退；不得改写已共享历史。本次未执行推送，因此远程不存在需要回滚的外部提交。
@@ -0,0 +1,9 @@
+# 测试计划
+
+- 检查 `origin` 的 fetch/push URL 精确匹配指定仓库。
+- 检查四项 Git 配置来自 `--local` 作用域。
+- 检查全局凭据助手和默认推送目标仍保持未设置。
+- 使用 `GIT_TERMINAL_PROMPT=0 git ls-remote origin` 验证远程只读连通性。
+- 搜索仓库文件、暂存区 diff 和远程 URL，确认不存在密码或凭据 URL。
+- 运行 `npm run test:governance` 和 `npm run governance:finish -- GOV-003 gitea-local-remote`。
+- 本功能不改变页面，视觉验证标记为不适用并说明原因。
@@ -61,6 +61,7 @@ npm run governance:finish -- FEAT-MO-001 market-overview
 10. 两项 Review 均为 `passed` 后，更新发布说明、回退说明、变更记录和版本号。
 11. 使用中文 Conventional Commit提交。
 12. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。
+13. 本地提交和标签完成后仍不得自动推送；只有用户明确要求时，才向项目专用 Gitea `origin` 推送。

 ## 6. 完成定义

@@ -2,7 +2,17 @@

 ## 1. 当前策略

-当前只使用本地 Git，不配置 GitHub、不创建 GitHub Actions，也不向任何第三方远程仓库推送。用户安装 Gitea 后，再显式配置 `origin`。
+本项目使用本地 Git 和用户自建 Gitea，不使用 GitHub，也不创建 GitHub Actions。
+
+| 配置项 | 值 |
+|---|---|
+| Gitea 基础地址 | `https://git.foximao.com/` |
+| 项目账号 | `FoXiMao` |
+| 唯一远程仓库 | `https://git.foximao.com/FoXiMao/a-share-analysis.git` |
+| 远程名 | `origin` |
+| 配置作用域 | 当前项目 `.git/config` |
+
+密码不属于项目文档。它不得出现在仓库文件、Git 历史、远程 URL、脚本或命令参数中；首次认证时由 Git 凭据助手请求，并交由 macOS Keychain 保存。

 ## 2. 分支与提交

@@ -18,18 +28,59 @@
 git config core.hooksPath .githooks
 ```

-## 3. Gitea 接入
+## 3. Gitea 项目级接入

-Gitea 安装并创建空仓库后，由用户确认地址，再执行：
+在本项目根目录执行以下项目级配置：
+
+```bash
+git remote add origin https://git.foximao.com/FoXiMao/a-share-analysis.git
+git config --local credential.helper osxkeychain
+git config --local credential.useHttpPath true
+git config --local credential.username FoXiMao
+git config --local remote.pushDefault origin
+```
+
+`credential.useHttpPath=true` 让同一 Gitea 域名下不同仓库按路径区分凭据；所有设置使用 `--local`，只写入本项目不可提交的 `.git/config`。禁止使用 `git config --global` 配置本项目账号、凭据助手或默认推送目标。
+
+只读连通性检查：
+
+```bash
+GIT_TERMINAL_PROMPT=0 git ls-remote origin
+```
+
+首次需要写权限时，由用户在交互式终端执行推送并输入凭据：

 ```bash
-git remote add origin <用户提供的Gitea仓库地址>
 git push -u origin main
 ```

-建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。未得到用户提供的地址和授权前，任何代理不得自行添加远程或推送。
+添加远程和验证连通性不代表授权自动推送。代理只有在用户明确要求推送时才能执行。建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。

-## 4. 版本与标签
+## 4. 配置检查与移除
+
+检查当前项目和全局配置的边界：
+
+```bash
+git remote -v
+git config --local --get credential.helper
+git config --local --get credential.useHttpPath
+git config --global --get-all credential.helper
+git config --global --get remote.pushDefault
+```
+
+如需解除本项目 Gitea 接入，执行：
+
+```bash
+git remote remove origin
+git config --local --unset credential.helper
+git config --local --unset credential.useHttpPath
+git config --local --unset credential.username
+git config --local --unset remote.pushDefault
+```
+
+上述操作只影响本项目。Keychain 中已保存的凭据需要在“钥匙串访问”中按 `git.foximao.com` 单独删除。
+
+## 5. 版本与标签

 发布使用带注释标签，例如：

@@ -26,5 +26,6 @@
 - [GOV-001：工程治理基线](features/GOV-001-engineering-governance/manifest.yaml)
 - [FEAT-MO-001：市场综合概览](features/FEAT-MO-001-market-overview/manifest.yaml)
 - [GOV-002：PRD 与 Review 门禁](features/GOV-002-prd-review-gates/manifest.yaml)
+- [GOV-003：项目专用 Gitea 远程仓库](features/GOV-003-gitea-local-remote/manifest.yaml)

 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。