feat(GOV-002): 增加 PRD 与开发审查门禁

2026-08-12 18:26:31 +08:00
parent 40f3b2ef6f
commit fb4383f541
38 changed files with 609 additions and 14 deletions
@@ -0,0 +1,5 @@
+# 设计
+
+PRD 与工程需求分离：PRD 定义产品问题、用户、范围和验收；`requirements.md`定义实现约束。Review 分为代码质量和规范符合性两条门禁，两者都必须给出明确状态。
+
+为了适合个人项目，允许结构化自审，但必须诚实标记审查者类型；未来经用户授权可使用独立代理或人工审查。
@@ -0,0 +1,9 @@
+# GitNexus 开发后基线
+
+- 日期：2026-08-12
+- 索引基线提交：`40f3b2e`
+- 当前变更：GOV-002 暂存区
+- 图谱：300 个符号、325 条关系、5 个功能簇、0 条执行流程
+- 状态：最新
+
+新增 `getUnpassedReviewFiles` 符号只有 `finish.mjs` 一个直接生产依赖，受影响流程为 0，风险为低。
@@ -0,0 +1,26 @@
+# GitNexus 开发前基线
+
+- 功能编号：GOV-002
+- 记录时间：2026年8月12日 GMT+8 18:20:46
+- 分支：main
+- 基线提交：40f3b2ef6f3b
+
+## 工作区
+
+```text
+(干净)
+```
+
+## GitNexus 状态
+
+```text
+Repository: /Users/citrons/Documents/Codex/2026-08-12/wo-x/a-share-analysis
+Indexed: 8/12/2026, 6:19:51 PM
+Indexed commit: 40f3b2e
+Current commit: 40f3b2e
+Status: ✅ up-to-date
+```
+
+## 后续人工分析
+
+在修改代码前，将 GitNexus query、context、impact 的结论写入 `gitnexus/impact-plan.md`。高风险结果必须先获得用户确认。
@@ -0,0 +1,10 @@
+# GitNexus 前后比较
+
+| 项目 | 开发前 | 开发后 | 变化 |
+|---|---:|---:|---:|
+| 符号 | 171 | 300 | +129 |
+| 关系 | 192 | 325 | +133 |
+| 功能簇 | 4 | 5 | +1 |
+| 执行流程 | 0 | 0 | 0 |
+
+增长主要来自正式市场概览 PRD、PRD/Review规范、模板和 GOV-002 功能档案。实际暂存变更影响为低，没有计划外业务流程。
@@ -0,0 +1,10 @@
+# 实际变更检测
+
+```text
+npx gitnexus detect-changes --repo a-share-analysis --scope staged
+Changes: 38 files, 114 symbols
+Affected processes: 0
+Risk level: low
+```
+
+变更集中在 PRD、Review规范与模板、现有功能档案和治理完成门禁。没有业务页面、API、数据库、RabbitMQ消息或部署配置变化。
@@ -0,0 +1,8 @@
+# GitNexus 开发前影响计划
+
+- 目标符号：`getRequiredFeatureFiles`。
+- 直接依赖：`tools/governance/finish.mjs`。
+- 受影响流程：0。
+- GitNexus风险：低。
+
+预期影响是完成门禁新增三份必备材料，不改变开发前索引、业务代码、API、数据库或界面行为。
@@ -0,0 +1,9 @@
+# 实施计划
+
+1. 执行开发前 GitNexus 索引、查询和影响分析。
+2. 先修改测试，让缺少 PRD 与 Review清单时失败。
+3. 更新完成门禁清单使测试通过。
+4. 新增 PRD、Review规范和模板。
+5. 更新现有治理文档与市场概览功能档案。
+6. 执行测试、GitNexus开发后分析和两类 Review。
+7. 使用中文提交并建立本地补丁版本标签。
@@ -0,0 +1,16 @@
+id: GOV-002
+name: PRD 与 Review 门禁
+slug: prd-review-gates
+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
+release: unreleased
@@ -0,0 +1,26 @@
+# PRD 与 Review 门禁 PRD
+
+- 功能编号：GOV-002
+- PRD版本：0.1
+- 状态：approved
+- 日期：2026-08-12
+
+## 问题
+
+现有档案只有工程需求，没有独立 PRD；开发完成后也没有正式 Review环节，无法证明实现符合产品目标和开发规范。
+
+## 目标
+
+- 每个功能必须有可测试、可版本化的 PRD。
+- 每个功能发布前必须完成代码 Review 和开发规范符合性 Review。
+- 完成门禁自动检查三份材料存在且非空。
+
+## 非目标
+
+本功能不接入外部代码审查平台，不配置 Gitea远程，也不修改业务功能。
+
+## 验收标准
+
+- 完成门禁清单包含 `prd.md`、`review/code-review.md` 和 `review/standards-review.md`。
+- 市场概览具有正式 PRD。
+- 流程文档明确 Review 不通过时的回流路径。
@@ -0,0 +1,14 @@
+# 测试结果
+
+## 测试先行证据
+
+1. 必备文件清单测试先因缺少 `prd.md` 和两类 Review失败。
+2. 更新清单后，4 个原有测试通过。
+3. 新增 Review状态测试先因 `getUnpassedReviewFiles` 不存在而失败。
+4. 实现固定最终结论校验后，5 个测试通过。
+
+## 门禁行为
+
+`pending` Review执行 `npm run governance:finish -- GOV-002 prd-review-gates` 时退出码为 1，并准确列出两份未通过报告。
+
+两份 Review 改为明确 `passed` 后，同一完成门禁执行成功。最终治理测试为 5 个通过、0 个失败。
@@ -0,0 +1,3 @@
+# 视觉 QA
+
+本功能不修改用户界面，视觉 QA 不适用。
@@ -0,0 +1,3 @@
+# 发布说明
+
+计划发布为 `v0.0.1`：新增 PRD事实来源与开发后双 Review发布门禁，不改变业务功能。
@@ -0,0 +1,7 @@
+# 工程需求
+
+- 更新功能档案必备文件清单。
+- 为新增清单先写失败测试并完成红—绿验证。
+- 提供 PRD 与两类 Review 的规范和模板。
+- 更新 AGENTS、开发流程、代码规范和追溯目录。
+- 对 GOV-001明确追补状态，对 FEAT-MO-001补充正式 PRD。
@@ -0,0 +1,28 @@
+# 代码 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 基线提交：`40f3b2e`
+- 审查范围：治理必备文件清单、Review完成门禁、PRD与Review规范
+- 日期：2026-08-12
+
+## PRD 与设计符合性
+
+实现覆盖 PRD 的三项验收：必备清单加入 PRD和两类Review；市场概览新增正式PRD；开发流程加入Review回流和发布门禁。
+
+## 发现与处置
+
+| 严重程度 | 发现 | 处置 |
+|---|---|---|
+| Important | 最初只检查 Review 文件非空，`pending` 报告也可能通过 | 新增 `getUnpassedReviewFiles`，要求两份报告都包含固定最终结论 `passed` |
+| Important | 新门禁行为缺少回归测试 | 先写失败测试，确认缺少导出时失败，再实现并验证通过 |
+| Minor | 当前是实现者自审，不具备独立审查视角 | 诚实标记 `reviewer_type: self`；未来用户授权多代理或有其他开发者时优先独立审查 |
+
+## 验证
+
+- 5 个治理测试通过。
+- `pending` Review 的完成门禁以退出码 1 失败，并列出两份未通过报告。
+- GitNexus 对新增 Review校验的上游影响为 1 个直接依赖、0 个流程，风险为低。
+- 完整暂存区变更检测为 38 个文件、114 个符号、0 条流程，风险为低。
+
+最终结论：passed
@@ -0,0 +1,22 @@
+# 开发规范符合性 Review
+
+- reviewer_type：self
+- reviewer：Codex
+- 日期：2026-08-12
+
+## 检查结果
+
+- [x] 新增公共函数包含解释门禁原因的中文注释。
+- [x] 校验逻辑保留在现有 `feature-record.mjs`，没有为单个判断过度拆分文件。
+- [x] 命名明确区分必备文件和未通过 Review。
+- [x] Review结论采用固定机器可读行，错误信息列出具体文件。
+- [x] 新行为有测试先行的红—绿证据。
+- [x] GitNexus开发前索引、查询、上下文和影响分析已经执行。
+- [x] PRD、工程需求、设计、测试计划和回退说明一致。
+- [x] 未配置 GitHub 或其他远程仓库。
+
+## 不符合项与处置
+
+没有未解决的 Critical 或 Important 不符合项。独立审查缺失属于个人项目当前限制，已经在代码 Review中透明记录。
+
+最终结论：passed
@@ -0,0 +1,3 @@
+# 回退说明
+
+本功能只增加文档和完成门禁清单。若门禁实现异常，使用修复提交恢复；确需回退时检出 `v0.0.0` 可获得升级前治理基线。
@@ -0,0 +1,6 @@
+# 测试计划
+
+- 证明旧清单缺少三份材料时测试失败。
+- 证明新清单精确包含 PRD 与两类 Review。
+- 完成门禁在任一材料缺失或为空时失败。
+- 文档占位符、脚本语法、中文提交和远程仓库状态通过检查。