From fb4383f541bc352ba11b1aa0a800228cb2b8c6a8 Mon Sep 17 00:00:00 2001 From: Citrons <909229731@qq.com> Date: Wed, 12 Aug 2026 18:26:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(GOV-002):=20=E5=A2=9E=E5=8A=A0=20PRD=20?= =?UTF-8?q?=E4=B8=8E=E5=BC=80=E5=8F=91=E5=AE=A1=E6=9F=A5=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 5 +- CHANGELOG.md | 4 + VERSION | 2 +- .../FEAT-MO-001-market-overview/manifest.yaml | 1 + .../FEAT-MO-001-market-overview/prd.md | 94 +++++++++++++++++++ .../manifest.yaml | 3 + .../GOV-001-engineering-governance/prd.md | 26 +++++ .../review/code-review.md | 8 ++ .../review/standards-review.md | 7 ++ .../GOV-002-prd-review-gates/design.md | 5 + .../gitnexus/after.md | 9 ++ .../gitnexus/before.md | 26 +++++ .../gitnexus/comparison.md | 10 ++ .../gitnexus/detected-changes.md | 10 ++ .../gitnexus/impact-plan.md | 8 ++ .../implementation-plan.md | 9 ++ .../GOV-002-prd-review-gates/manifest.yaml | 16 ++++ docs/features/GOV-002-prd-review-gates/prd.md | 26 +++++ .../qa/test-results.md | 14 +++ .../GOV-002-prd-review-gates/qa/visual-qa.md | 3 + .../GOV-002-prd-review-gates/release-notes.md | 3 + .../GOV-002-prd-review-gates/requirements.md | 7 ++ .../review/code-review.md | 28 ++++++ .../review/standards-review.md | 22 +++++ .../GOV-002-prd-review-gates/rollback.md | 3 + .../GOV-002-prd-review-gates/test-plan.md | 6 ++ docs/governance/code-development-standards.md | 13 +++ docs/governance/development-workflow.md | 28 +++--- docs/governance/documentation-traceability.md | 6 ++ docs/governance/prd-standard.md | 34 +++++++ docs/governance/review-standard.md | 37 ++++++++ docs/index.md | 3 + docs/templates/code-review-template.md | 27 ++++++ docs/templates/prd-template.md | 37 ++++++++ docs/templates/standards-review-template.md | 28 ++++++ tools/governance/feature-record.mjs | 19 ++++ tools/governance/feature-record.test.mjs | 21 +++++ tools/governance/finish.mjs | 15 +++ 38 files changed, 609 insertions(+), 14 deletions(-) create mode 100644 docs/features/FEAT-MO-001-market-overview/prd.md create mode 100644 docs/features/GOV-001-engineering-governance/prd.md create mode 100644 docs/features/GOV-001-engineering-governance/review/code-review.md create mode 100644 docs/features/GOV-001-engineering-governance/review/standards-review.md create mode 100644 docs/features/GOV-002-prd-review-gates/design.md create mode 100644 docs/features/GOV-002-prd-review-gates/gitnexus/after.md create mode 100644 docs/features/GOV-002-prd-review-gates/gitnexus/before.md create mode 100644 docs/features/GOV-002-prd-review-gates/gitnexus/comparison.md create mode 100644 docs/features/GOV-002-prd-review-gates/gitnexus/detected-changes.md create mode 100644 docs/features/GOV-002-prd-review-gates/gitnexus/impact-plan.md create mode 100644 docs/features/GOV-002-prd-review-gates/implementation-plan.md create mode 100644 docs/features/GOV-002-prd-review-gates/manifest.yaml create mode 100644 docs/features/GOV-002-prd-review-gates/prd.md create mode 100644 docs/features/GOV-002-prd-review-gates/qa/test-results.md create mode 100644 docs/features/GOV-002-prd-review-gates/qa/visual-qa.md create mode 100644 docs/features/GOV-002-prd-review-gates/release-notes.md create mode 100644 docs/features/GOV-002-prd-review-gates/requirements.md create mode 100644 docs/features/GOV-002-prd-review-gates/review/code-review.md create mode 100644 docs/features/GOV-002-prd-review-gates/review/standards-review.md create mode 100644 docs/features/GOV-002-prd-review-gates/rollback.md create mode 100644 docs/features/GOV-002-prd-review-gates/test-plan.md create mode 100644 docs/governance/prd-standard.md create mode 100644 docs/governance/review-standard.md create mode 100644 docs/templates/code-review-template.md create mode 100644 docs/templates/prd-template.md create mode 100644 docs/templates/standards-review-template.md diff --git a/AGENTS.md b/AGENTS.md index ab3047b..978f5ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,17 +11,18 @@ 1. 修改生产代码前必须执行 `npm run governance:start -- <功能编号> <短名称>`，刷新 GitNexus，并完成开发前影响分析。 2. 修改完成后必须执行测试、构建、视觉验证和 `npm run governance:finish -- <功能编号> <短名称>`，再次刷新 GitNexus并保存前后对比。 -3. 任何功能必须先有 `docs/features/<功能编号>-<短名称>/` 功能档案；没有需求、设计、计划和回退说明不得视为完成。 +3. 任何功能必须先有 `docs/features/<功能编号>-<短名称>/` 功能档案；没有 PRD、需求、设计、计划和回退说明不得视为完成。 4. Git 提交必须使用中文 Conventional Commit，并带功能编号；禁止英文摘要和含糊提交信息。 5. 代码必须为关键业务逻辑、数据口径、异常恢复和架构取舍提供准确的中文注释；禁止无意义逐行注释。 6. 文件按稳定职责拆分，不以追求“原子化”为目的过度拆分。优先保证普通开发者能够连续阅读完整业务流程。 7. 不使用 GitHub。当前只使用本地 Git，远程仓库仅在用户安装 Gitea 后配置。 8. 禁止提交密钥、真实凭据、生产数据、`.env` 和 GitNexus 本地索引。 +9. 开发完成后必须先通过代码 Review 和开发规范符合性 Review，再进入发布；Review 结论和问题处置必须写入功能档案。 # GitNexus — Code Intelligence -This project is indexed by GitNexus as **a-share-analysis** (171 symbols, 192 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. +This project is indexed by GitNexus as **a-share-analysis** (300 symbols, 325 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. diff --git a/CHANGELOG.md b/CHANGELOG.md index f16113c..a2034a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ 本项目采用语义化版本。功能级变化请从 `docs/features/` 按功能编号追溯。 +## 0.0.1 - 2026-08-12 + +- 增加 PRD 与开发后 Review 强制门禁。 + ## 0.0.0 - 2026-08-12 - 建立工程治理、GitNexus 门禁和功能档案体系。 diff --git a/VERSION b/VERSION index 77d6f4c..8acdd82 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.0.0 +0.0.1 diff --git a/docs/features/FEAT-MO-001-market-overview/manifest.yaml b/docs/features/FEAT-MO-001-market-overview/manifest.yaml index bf9d340..4d892aa 100644 --- a/docs/features/FEAT-MO-001-market-overview/manifest.yaml +++ b/docs/features/FEAT-MO-001-market-overview/manifest.yaml @@ -5,6 +5,7 @@ status: approved owner: project created_at: 2026-08-12 requirements: requirements.md +prd: prd.md design: design.md implementation_plan: implementation-plan.md traceability_note: 开发尚未开始，GitNexus与QA证据将在开发门禁执行时创建 diff --git a/docs/features/FEAT-MO-001-market-overview/prd.md b/docs/features/FEAT-MO-001-market-overview/prd.md new file mode 100644 index 0000000..2304d55 --- /dev/null +++ b/docs/features/FEAT-MO-001-market-overview/prd.md @@ -0,0 +1,94 @@ +# 市场综合概览 PRD + +- 功能编号：FEAT-MO-001 +- PRD版本：0.1 +- 状态：approved +- 日期：2026-08-12 + +## 背景与问题 + +现有概念稿能够展示指数、情绪、板块和资金数据，但更接近数据看板，用户难以快速回答“市场当前强弱、量能是否支持、行情由谁驱动、风险在哪里”。 + +## 目标用户与使用场景 + +主要用户为产品所有者，少量朋友可以使用同一只读工具。用户在盘中以分钟级数据观察全市场状态，在收盘后查看冻结的最终总结和历史交易日结果。 + +## 产品目标 + +- 用户进入市场概览后，优先看到一句市场定性以及驱动、风险两列摘要。 +- 用户能够继续核对指数、市场宽度、量能、板块、情绪和资金证据。 +- 用户能够在综合、短线和中长线视角间临时切换，并选择规则、AI、混合或对照分析。 +- 所有实时性、数据日期和分析依据均明确可见。 + +## 非目标 + +- 不做自选股、持仓、笔记、交易计划、社区、荐股、跟单和公开组合。 +- 本切片不接正式行情源、RabbitMQ、MySQL、Redis和付费 AI。 +- 本切片不实现用户、邀请、会员、订阅和支付。 +- ETF监控、两融数据、大盘云图和实时消息仍是独立一级模块。 + +## 用户流程 + +1. 用户进入“市场概览”。 +2. 首先读取市场定性、驱动因素和风险信号。 +3. 通过“查看依据”核对指标来源。 +4. 向下查看指数、宽度、量能、板块、情绪和资金摘要。 +5. 点击轻量分析状态入口，临时切换分析周期和分析引擎。 +6. 点击指数或板块入口进入未来的详情页；首个切片只保留可识别入口。 + +## 功能需求 + +| 编号 | 优先级 | 需求 | 可观察结果 | +|---|---|---|---| +| FR-001 | P0 | 结论优先展示市场定性 | 首屏顶部出现一句结论、市场状态、量能状态和情绪状态 | +| FR-002 | P0 | 展示驱动与风险 | 结论下方并列显示至少三条驱动和三条风险证据 | +| FR-003 | P0 | 展示数据新鲜度 | 页面显示交易状态、数据更新时间和正常/延迟/不完整状态 | +| FR-004 | P0 | 提供分析偏好 | 可选择综合/短线/中长线和规则/AI/混合/对照，并在本地保存默认值 | +| FR-005 | P1 | 展示市场证据模块 | 指数、宽度、量能、板块、情绪和资金摘要可阅读 | +| FR-006 | P1 | 查看结论依据 | 点击入口后展示指标、数值、口径和更新时间 | +| FR-007 | P1 | 支持异常状态 | 加载、空、部分数据、过期和错误状态具有明确文案 | + +## 数据与口径 + +首个切片使用确定性模拟快照。字段仍必须包含交易日期、快照时间、来源状态、完整性和单位，以便以后无结构变更地替换为后端 API。 + +A 股使用红涨绿跌。成交额统一展示为亿元，比例明确使用百分比。历史数据和低频资金数据必须显示实际数据日期，旧数据不得标记为实时。 + +## 状态与异常 + +- 交易中：显示分钟级更新时间。 +- 午间休市或已收盘：显示对应市场状态。 +- 数据延迟：保留最近有效值并标记延迟。 +- 部分数据：只隐藏缺失指标，不让整页失败。 +- AI不可用：规则分析继续可用，并标记降级。 + +## 权限、合规与安全 + +当前为只读访问，不提供交易指令。结论不得包含买入、卖出、目标价和仓位建议。付费 AI 密钥未来只保存在服务端。 + +## 成功指标 + +- 用户能够在 30 秒内说出市场定性、主要驱动和首要风险。 +- 所有结论均能展开查看至少一项数据依据。 +- 页面在目标桌面视口和窄窗口中不阻断核心内容。 + +## 验收标准 + +- Given 页面加载有效快照，When 用户进入市场概览，Then 结论、驱动、风险和更新时间在首屏可见。 +- Given 用户打开分析状态入口，When 切换周期或引擎，Then 页面状态立即更新且可选择设为默认。 +- Given 数据快照被标记为延迟，When 页面渲染，Then 最近有效值保留并明确显示延迟，不能显示“实时”。 +- Given 用户点击查看依据，When 抽屉打开，Then 能看到指标名称、数值、口径和更新时间。 + +## 风险与依赖 + +- 免费数据源稳定性和商业授权需要在正式接入阶段重新评估。 +- AI 分析必须受结构化数据和规则事实约束。 +- 首个视觉版本用于验证信息层级，不作为最终设计冻结版本。 + +## 发布范围与回退触发条件 + +本次仅发布本地 Vue 3 首屏原型。核心交互不可用、结论依据不可追溯或窄屏遮挡核心信息时不得发布；出现回归时回退到上一个本地标签。 + +## 变更记录 + +- 0.1：建立首版 PRD，补充结论优先、分析偏好和异常状态。 diff --git a/docs/features/GOV-001-engineering-governance/manifest.yaml b/docs/features/GOV-001-engineering-governance/manifest.yaml index f0e9ca0..5910ff8 100644 --- a/docs/features/GOV-001-engineering-governance/manifest.yaml +++ b/docs/features/GOV-001-engineering-governance/manifest.yaml @@ -5,6 +5,7 @@ status: released owner: project created_at: 2026-08-12 requirements: requirements.md +prd: prd.md design: design.md implementation_plan: implementation-plan.md decisions: @@ -13,6 +14,8 @@ decisions: 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 baseline_commit: 7cc2ba0 implementation_commit: efdfb33 release: v0.0.0 diff --git a/docs/features/GOV-001-engineering-governance/prd.md b/docs/features/GOV-001-engineering-governance/prd.md new file mode 100644 index 0000000..2ebc22d --- /dev/null +++ b/docs/features/GOV-001-engineering-governance/prd.md @@ -0,0 +1,26 @@ +# 工程治理基线 PRD（追补） + +- 功能编号：GOV-001 +- PRD版本：0.1 +- 状态：retrospective +- 日期：2026-08-12 + +## 背景与目标 + +该治理功能早于 PRD 强制门禁发布。本文件用于追补当时已经确认的产品目标：所有开发步骤可阅读、可比较、可追溯、可回退，并由 GitNexus在开发前后总结影响。 + +## 使用者 + +项目所有者、后续开发者和开发代理。 + +## 核心需求 + +- 分离代码开发规范和开发流程规范。 +- 要求关键代码写有信息价值的中文注释。 +- 禁止过度拆分代码。 +- 使用中文提交。 +- 不使用 GitHub，未来接入自建 Gitea。 + +## 验收结果 + +上述内容已在 `v0.0.0` 建立。GOV-002 将 PRD 和 Review补充为后续功能的强制门禁。 diff --git a/docs/features/GOV-001-engineering-governance/review/code-review.md b/docs/features/GOV-001-engineering-governance/review/code-review.md new file mode 100644 index 0000000..b7c80a7 --- /dev/null +++ b/docs/features/GOV-001-engineering-governance/review/code-review.md @@ -0,0 +1,8 @@ +# 代码 Review（追补） + +- reviewer_type：self +- 审查范围：GOV-001 治理脚本与测试 + +最终结论：passed + +治理脚本具有功能编号、路径和必备材料的行为测试；开发前后命令使用参数数组调用外部进程，未拼接用户输入到 Shell。GOV-002 继续增加 PRD 和 Review材料校验。 diff --git a/docs/features/GOV-001-engineering-governance/review/standards-review.md b/docs/features/GOV-001-engineering-governance/review/standards-review.md new file mode 100644 index 0000000..9ca44f9 --- /dev/null +++ b/docs/features/GOV-001-engineering-governance/review/standards-review.md @@ -0,0 +1,7 @@ +# 开发规范符合性 Review（追补） + +- reviewer_type：self + +最终结论：passed + +GOV-001 已满足当时生效的 GitNexus 双门禁、中文提交、关键中文注释、文档追溯和本地 Git 约束。PRD 与独立 Review要求从 GOV-002 起正式生效，本文件明确标记为追补材料，不伪装成发布前独立审查。 diff --git a/docs/features/GOV-002-prd-review-gates/design.md b/docs/features/GOV-002-prd-review-gates/design.md new file mode 100644 index 0000000..40407a1 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/design.md @@ -0,0 +1,5 @@ +# 设计 + +PRD 与工程需求分离：PRD 定义产品问题、用户、范围和验收；`requirements.md`定义实现约束。Review 分为代码质量和规范符合性两条门禁，两者都必须给出明确状态。 + +为了适合个人项目，允许结构化自审，但必须诚实标记审查者类型；未来经用户授权可使用独立代理或人工审查。 diff --git a/docs/features/GOV-002-prd-review-gates/gitnexus/after.md b/docs/features/GOV-002-prd-review-gates/gitnexus/after.md new file mode 100644 index 0000000..7d06cb0 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/gitnexus/after.md @@ -0,0 +1,9 @@ +# GitNexus 开发后基线 + +- 日期：2026-08-12 +- 索引基线提交：`40f3b2e` +- 当前变更：GOV-002 暂存区 +- 图谱：300 个符号、325 条关系、5 个功能簇、0 条执行流程 +- 状态：最新 + +新增 `getUnpassedReviewFiles` 符号只有 `finish.mjs` 一个直接生产依赖，受影响流程为 0，风险为低。 diff --git a/docs/features/GOV-002-prd-review-gates/gitnexus/before.md b/docs/features/GOV-002-prd-review-gates/gitnexus/before.md new file mode 100644 index 0000000..9b171c7 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/gitnexus/before.md @@ -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`。高风险结果必须先获得用户确认。 diff --git a/docs/features/GOV-002-prd-review-gates/gitnexus/comparison.md b/docs/features/GOV-002-prd-review-gates/gitnexus/comparison.md new file mode 100644 index 0000000..e6f9e54 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/gitnexus/comparison.md @@ -0,0 +1,10 @@ +# GitNexus 前后比较 + +| 项目 | 开发前 | 开发后 | 变化 | +|---|---:|---:|---:| +| 符号 | 171 | 300 | +129 | +| 关系 | 192 | 325 | +133 | +| 功能簇 | 4 | 5 | +1 | +| 执行流程 | 0 | 0 | 0 | + +增长主要来自正式市场概览 PRD、PRD/Review规范、模板和 GOV-002 功能档案。实际暂存变更影响为低，没有计划外业务流程。 diff --git a/docs/features/GOV-002-prd-review-gates/gitnexus/detected-changes.md b/docs/features/GOV-002-prd-review-gates/gitnexus/detected-changes.md new file mode 100644 index 0000000..133f0a2 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/gitnexus/detected-changes.md @@ -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消息或部署配置变化。 diff --git a/docs/features/GOV-002-prd-review-gates/gitnexus/impact-plan.md b/docs/features/GOV-002-prd-review-gates/gitnexus/impact-plan.md new file mode 100644 index 0000000..15670f2 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/gitnexus/impact-plan.md @@ -0,0 +1,8 @@ +# GitNexus 开发前影响计划 + +- 目标符号：`getRequiredFeatureFiles`。 +- 直接依赖：`tools/governance/finish.mjs`。 +- 受影响流程：0。 +- GitNexus风险：低。 + +预期影响是完成门禁新增三份必备材料，不改变开发前索引、业务代码、API、数据库或界面行为。 diff --git a/docs/features/GOV-002-prd-review-gates/implementation-plan.md b/docs/features/GOV-002-prd-review-gates/implementation-plan.md new file mode 100644 index 0000000..d05e9b7 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/implementation-plan.md @@ -0,0 +1,9 @@ +# 实施计划 + +1. 执行开发前 GitNexus 索引、查询和影响分析。 +2. 先修改测试，让缺少 PRD 与 Review清单时失败。 +3. 更新完成门禁清单使测试通过。 +4. 新增 PRD、Review规范和模板。 +5. 更新现有治理文档与市场概览功能档案。 +6. 执行测试、GitNexus开发后分析和两类 Review。 +7. 使用中文提交并建立本地补丁版本标签。 diff --git a/docs/features/GOV-002-prd-review-gates/manifest.yaml b/docs/features/GOV-002-prd-review-gates/manifest.yaml new file mode 100644 index 0000000..45bd6ce --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/manifest.yaml @@ -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 diff --git a/docs/features/GOV-002-prd-review-gates/prd.md b/docs/features/GOV-002-prd-review-gates/prd.md new file mode 100644 index 0000000..15a6023 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/prd.md @@ -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 不通过时的回流路径。 diff --git a/docs/features/GOV-002-prd-review-gates/qa/test-results.md b/docs/features/GOV-002-prd-review-gates/qa/test-results.md new file mode 100644 index 0000000..ac90b4c --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/qa/test-results.md @@ -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 个失败。 diff --git a/docs/features/GOV-002-prd-review-gates/qa/visual-qa.md b/docs/features/GOV-002-prd-review-gates/qa/visual-qa.md new file mode 100644 index 0000000..a863baf --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/qa/visual-qa.md @@ -0,0 +1,3 @@ +# 视觉 QA + +本功能不修改用户界面，视觉 QA 不适用。 diff --git a/docs/features/GOV-002-prd-review-gates/release-notes.md b/docs/features/GOV-002-prd-review-gates/release-notes.md new file mode 100644 index 0000000..71d5eef --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/release-notes.md @@ -0,0 +1,3 @@ +# 发布说明 + +计划发布为 `v0.0.1`：新增 PRD事实来源与开发后双 Review发布门禁，不改变业务功能。 diff --git a/docs/features/GOV-002-prd-review-gates/requirements.md b/docs/features/GOV-002-prd-review-gates/requirements.md new file mode 100644 index 0000000..a0208e5 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/requirements.md @@ -0,0 +1,7 @@ +# 工程需求 + +- 更新功能档案必备文件清单。 +- 为新增清单先写失败测试并完成红—绿验证。 +- 提供 PRD 与两类 Review 的规范和模板。 +- 更新 AGENTS、开发流程、代码规范和追溯目录。 +- 对 GOV-001明确追补状态，对 FEAT-MO-001补充正式 PRD。 diff --git a/docs/features/GOV-002-prd-review-gates/review/code-review.md b/docs/features/GOV-002-prd-review-gates/review/code-review.md new file mode 100644 index 0000000..63a25b0 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/review/code-review.md @@ -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 diff --git a/docs/features/GOV-002-prd-review-gates/review/standards-review.md b/docs/features/GOV-002-prd-review-gates/review/standards-review.md new file mode 100644 index 0000000..7fcd6a7 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/review/standards-review.md @@ -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 diff --git a/docs/features/GOV-002-prd-review-gates/rollback.md b/docs/features/GOV-002-prd-review-gates/rollback.md new file mode 100644 index 0000000..e1fc889 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/rollback.md @@ -0,0 +1,3 @@ +# 回退说明 + +本功能只增加文档和完成门禁清单。若门禁实现异常，使用修复提交恢复；确需回退时检出 `v0.0.0` 可获得升级前治理基线。 diff --git a/docs/features/GOV-002-prd-review-gates/test-plan.md b/docs/features/GOV-002-prd-review-gates/test-plan.md new file mode 100644 index 0000000..53613d7 --- /dev/null +++ b/docs/features/GOV-002-prd-review-gates/test-plan.md @@ -0,0 +1,6 @@ +# 测试计划 + +- 证明旧清单缺少三份材料时测试失败。 +- 证明新清单精确包含 PRD 与两类 Review。 +- 完成门禁在任一材料缺失或为空时失败。 +- 文档占位符、脚本语法、中文提交和远程仓库状态通过检查。 diff --git a/docs/governance/code-development-standards.md b/docs/governance/code-development-standards.md index 5f4f4d1..f419921 100644 --- a/docs/governance/code-development-standards.md +++ b/docs/governance/code-development-standards.md @@ -113,3 +113,16 @@ count += 1; - AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。 - SQL必须参数化；外部输入必须在边界处校验。 - 日志和异常报告必须脱敏。 + +## 12. 代码 Review 要求 + +开发者完成自测不等于 Review 完成。审查者必须从功能 PRD、设计和 Git diff 出发，检查： + +- 业务行为是否真正满足验收标准，是否存在遗漏分支。 +- 类型、数据口径、缓存、消息、事务和异常恢复是否正确。 +- 是否引入安全、性能、并发、幂等或数据一致性风险。 +- 测试是否能捕获真实回归，而非只验证 Mock 或实现细节。 +- 中文注释是否解释关键原因、口径和限制，是否存在失真注释。 +- 文件拆分是否便于常规阅读，是否出现过度抽象或巨型多职责文件。 + +Critical 和 Important 问题必须修复并复审。Minor 问题可以延期，但必须写明理由和后续功能编号。 diff --git a/docs/governance/development-workflow.md b/docs/governance/development-workflow.md index f640bb1..5588ac9 100644 --- a/docs/governance/development-workflow.md +++ b/docs/governance/development-workflow.md @@ -7,7 +7,7 @@ ## 2. 功能状态 ```text -proposed → designing → approved → developing → verifying → released +proposed → prd_review → designing → approved → developing → verifying → reviewing → released ↘ blocked released → superseded ``` @@ -18,18 +18,19 @@ released → superseded 1. 分配功能编号和英文短名称。 2. 建立 `docs/features/<编号>-<短名称>/`。 -3. 填写需求、范围、非目标和验收标准。 -4. 比较可选方案，记录设计与关键决策。 -5. 更新 API、事件和数据结构契约。 -6. 编写测试计划和实施计划。 -7. 确保 Git 工作区基线可识别，执行： +3. 编写 `prd.md`，明确用户问题、目标、范围、非目标、用户流程、指标、风险和验收标准。 +4. PRD 审核通过后，将产品需求转换为可测试的工程需求。 +5. 比较可选方案，记录设计与关键决策。 +6. 更新 API、事件和数据结构契约。 +7. 编写测试计划和实施计划。 +8. 确保 Git 工作区基线可识别，执行： ```bash npm run governance:start -- FEAT-MO-001 market-overview ``` -8. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。 -9. 高风险或关键路径变化必须先向用户说明影响，再进入开发。 +9. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。 +10. 高风险或关键路径变化必须先向用户说明影响，再进入开发。 开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。 @@ -54,9 +55,12 @@ npm run governance:finish -- FEAT-MO-001 market-overview ``` 6. 填写 `gitnexus/after.md`、`detected-changes.md` 和 `comparison.md`。 -7. 更新发布说明、回退说明、变更记录和版本号。 -8. 使用中文 Conventional Commit提交。 -9. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。 +7. 执行代码 Review，将问题、严重程度、修复提交和复审结论写入 `review/code-review.md`。 +8. 逐条执行开发规范符合性 Review，将结果写入 `review/standards-review.md`。 +9. 任一 Review 为 `changes_required` 时，返回开发阶段；修复后重跑相关测试、GitNexus开发后分析和 Review。 +10. 两项 Review 均为 `passed` 后，更新发布说明、回退说明、变更记录和版本号。 +11. 使用中文 Conventional Commit提交。 +12. 提交后执行 `npx gitnexus status`；若状态过期，再运行 `npx gitnexus analyze`。 ## 6. 完成定义 @@ -68,6 +72,8 @@ npm run governance:finish -- FEAT-MO-001 market-overview - 测试和构建有最新成功证据。 - 视觉变化有同视口对比证据。 - GitNexus 开发前后报告和差异说明齐全。 +- 代码 Review 结论为 `passed`，Critical 和 Important 问题已关闭。 +- 开发规范符合性 Review 结论为 `passed`。 - 发布说明和回退方法可执行。 - 中文提交已关联功能编号。 diff --git a/docs/governance/documentation-traceability.md b/docs/governance/documentation-traceability.md index b0f931f..aed7c40 100644 --- a/docs/governance/documentation-traceability.md +++ b/docs/governance/documentation-traceability.md @@ -9,6 +9,7 @@ ```text docs/features/<编号>-<短名称>/ ├── manifest.yaml +├── prd.md ├── requirements.md ├── design.md ├── implementation-plan.md @@ -26,6 +27,9 @@ docs/features/<编号>-<短名称>/ ├── qa/ │ ├── test-results.md │ └── visual-qa.md +├── review/ +│ ├── code-review.md +│ └── standards-review.md ├── release-notes.md └── rollback.md ``` @@ -33,6 +37,8 @@ docs/features/<编号>-<短名称>/ ## 3. 历史保留 - 已发布文档不删除、不覆盖历史结论；修订通过 Git 历史和文档版本说明保留。 +- PRD 是产品目标和验收口径的正式来源；`requirements.md` 是从 PRD 派生的工程约束，二者不能相互替代。 +- Review 文件必须记录审查范围、基线提交、审查提交、发现、处置和最终结论，禁止只写“看过了”。 - 重大方案变化新增 ADR，旧 ADR 标记被替代。 - 规则、提示词、API 和事件契约使用明确版本。 - 截图文件名包含页面、状态、视口和版本，例如 `market-overview-trading-1440x1200-v0.1.0.png`。 diff --git a/docs/governance/prd-standard.md b/docs/governance/prd-standard.md new file mode 100644 index 0000000..4797928 --- /dev/null +++ b/docs/governance/prd-standard.md @@ -0,0 +1,34 @@ +# PRD 编写规范 + +## 1. 定位 + +PRD 是每个业务功能的产品需求事实来源，回答“为谁解决什么问题、为什么做、做到什么程度算完成”。技术设计回答“如何实现”，不能替代 PRD。 + +治理、重构和纯技术任务也需要简化 PRD，用于说明使用者、治理问题、目标和完成标准。 + +## 2. 必备章节 + +每份 `prd.md` 至少包含： + +1. 文档信息：功能编号、版本、状态、作者、日期。 +2. 背景与问题：当前状态、具体问题和证据。 +3. 目标用户与场景：谁在什么时点使用。 +4. 产品目标：用户能够完成什么，产品改善什么。 +5. 非目标：本期明确不解决什么。 +6. 用户流程：入口、关键步骤、结果和异常路径。 +7. 功能需求：编号、优先级、行为与可观察结果。 +8. 数据与口径：来源、时效、单位、缺失和过期处理。 +9. 状态与异常：加载、空、部分数据、错误和降级。 +10. 权限与合规：访问边界、隐私、声明和安全限制。 +11. 成功指标：可以观测和验证的产品指标。 +12. 验收标准：使用 Given/When/Then 或等价可测试描述。 +13. 风险与依赖：外部数据、技术、成本和上线依赖。 +14. 发布范围：本次、后续和回退触发条件。 + +## 3. 编写规则 + +- 需求使用 `FR-001` 等稳定编号，测试和 Review引用该编号。 +- 禁止用“体验更好”“速度较快”等不可验证表达。 +- UI 布局不是需求本身；应先写用户需要识别和完成的行为。 +- PRD 发生实质变化时更新版本和变更记录，并重新确认设计与测试影响。 +- 已发布 PRD 不删除旧结论，废弃需求标记 `superseded` 并说明替代项。 diff --git a/docs/governance/review-standard.md b/docs/governance/review-standard.md new file mode 100644 index 0000000..4919a0e --- /dev/null +++ b/docs/governance/review-standard.md @@ -0,0 +1,37 @@ +# Review 审查规范 + +## 1. 两类 Review + +### 代码 Review + +以 PRD、设计、实施计划、Git diff和测试证据为输入，审查正确性、安全性、性能、数据一致性、契约兼容性和测试充分性。 + +### 开发规范符合性 Review + +逐条检查代码开发规范和流程规范，包括中文注释、命名、文件拆分尺度、日志、错误处理、GitNexus前后门禁、中文提交、文档和回退材料。 + +## 2. 审查角色 + +- 优先由非实现者进行独立 Review。 +- 个人项目没有独立审查者时，可以执行结构化自审，但必须在报告中标明 `reviewer_type: self`，不得伪称独立审查。 +- 使用代理审查时，必须提供功能说明、PRD、设计、基线 SHA 和当前 SHA；只有用户明确授权多代理时才调用独立审查代理。 + +## 3. 严重程度 + +- Critical：可能导致数据错误、安全事故、核心功能不可用或不可恢复，必须修复。 +- Important：会造成明显错误、回归、规范失效或重要测试缺口，必须修复。 +- Minor：不阻塞当前功能，但应记录后续处理或接受理由。 + +## 4. 结论 + +Review 只能使用： + +- `passed`：没有未解决的 Critical 或 Important，证据齐全。 +- `changes_required`：存在必须修改的问题。 +- `blocked`：缺少 PRD、代码、测试、环境或其他必要证据。 + +修复 Review 问题后必须记录修复提交和复审结论。代码变化会使旧的 GitNexus开发后报告失效时，必须重新更新图谱和影响报告。 + +## 5. 发布门禁 + +`review/code-review.md` 和 `review/standards-review.md` 均存在、非空且最终结论为 `passed` 后，功能才允许进入发布状态。 diff --git a/docs/index.md b/docs/index.md index fe03226..8baac4b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,8 @@ - [代码开发规范](governance/code-development-standards.md) - [开发流程规范](governance/development-workflow.md) +- [PRD 编写规范](governance/prd-standard.md) +- [Review 审查规范](governance/review-standard.md) - [文档与追溯规范](governance/documentation-traceability.md) - [Git 与 Gitea 规范](governance/version-control-and-gitea.md) @@ -23,5 +25,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) 功能档案是需求、设计、代码、测试、版本和回退之间的唯一正式关联入口。 diff --git a/docs/templates/code-review-template.md b/docs/templates/code-review-template.md new file mode 100644 index 0000000..40d4819 --- /dev/null +++ b/docs/templates/code-review-template.md @@ -0,0 +1,27 @@ +# 代码 Review + +- 功能编号： +- reviewer_type：self / independent +- reviewer： +- 基线提交： +- 审查提交： +- 日期： + +## 审查范围 + +## PRD 与设计符合性 + +## 发现 + +| 严重程度 | 位置 | 问题 | 影响 | 处理 | +|---|---|---|---|---| + +## 测试缺口 + +## 修复与复审 + +## 最终结论 + +最终结论：blocked + +完成审查后，将上行值改为 `passed`、`changes_required` 或 `blocked`。门禁只接受独占一行的 `最终结论：passed`。 diff --git a/docs/templates/prd-template.md b/docs/templates/prd-template.md new file mode 100644 index 0000000..11ead9c --- /dev/null +++ b/docs/templates/prd-template.md @@ -0,0 +1,37 @@ +# <功能名称> PRD + +- 功能编号： +- PRD版本： +- 状态：draft +- 日期： + +## 背景与问题 + +## 目标用户与使用场景 + +## 产品目标 + +## 非目标 + +## 用户流程 + +## 功能需求 + +| 编号 | 优先级 | 需求 | 可观察结果 | +|---|---|---|---| + +## 数据与口径 + +## 状态与异常 + +## 权限、合规与安全 + +## 成功指标 + +## 验收标准 + +## 风险与依赖 + +## 发布范围与回退触发条件 + +## 变更记录 diff --git a/docs/templates/standards-review-template.md b/docs/templates/standards-review-template.md new file mode 100644 index 0000000..8552932 --- /dev/null +++ b/docs/templates/standards-review-template.md @@ -0,0 +1,28 @@ +# 开发规范符合性 Review + +- 功能编号： +- reviewer_type：self / independent +- reviewer： +- 审查提交： +- 日期： + +## 检查结果 + +- [ ] 必要中文注释准确且没有逐行废话注释。 +- [ ] 文件按稳定职责拆分，适合连续阅读，没有过度碎片化。 +- [ ] 命名、类型、单位和时间语义明确。 +- [ ] 错误处理、日志、脱敏和降级符合规范。 +- [ ] API、事件、规则和提示词按需版本化。 +- [ ] 测试先行证据、构建和视觉验证齐全。 +- [ ] GitNexus开发前后报告和实际变更检测齐全。 +- [ ] PRD、设计、发布说明和回退说明一致。 +- [ ] 提交使用中文 Conventional Commit并关联功能编号。 +- [ ] 未使用 GitHub，未擅自配置或推送远程仓库。 + +## 不符合项与处置 + +## 最终结论 + +最终结论：blocked + +完成审查后，将上行值改为 `passed`、`changes_required` 或 `blocked`。门禁只接受独占一行的 `最终结论：passed`。 diff --git a/tools/governance/feature-record.mjs b/tools/governance/feature-record.mjs index cb4de14..1fb8059 100644 --- a/tools/governance/feature-record.mjs +++ b/tools/governance/feature-record.mjs @@ -4,6 +4,7 @@ const FEATURE_ID_PATTERN = /^(?:FEAT-[A-Z]{2,8}|GOV)-\d{3}$/; const REQUIRED_FEATURE_FILES = Object.freeze([ 'manifest.yaml', + 'prd.md', 'requirements.md', 'design.md', 'implementation-plan.md', @@ -15,10 +16,17 @@ const REQUIRED_FEATURE_FILES = Object.freeze([ 'gitnexus/comparison.md', 'qa/test-results.md', 'qa/visual-qa.md', + 'review/code-review.md', + 'review/standards-review.md', 'release-notes.md', 'rollback.md', ]); +const REVIEW_FILES = Object.freeze([ + 'review/code-review.md', + 'review/standards-review.md', +]); + /** * 功能编号是需求、设计、代码提交、测试结果和发布记录之间的主关联键。 * 严格限制格式可以避免路径穿越、临时名称以及后续无法检索的模糊编号。 @@ -49,3 +57,14 @@ export function getFeatureDirectory(repositoryRoot, featureId, slug) { export function getRequiredFeatureFiles() { return [...REQUIRED_FEATURE_FILES]; } + +/** + * Review 报告不能只靠“文件存在”通过门禁。这里要求报告使用固定的最终结论行， + * 避免 pending、blocked 或 changes_required 被一段其他说明文字意外判定为通过。 + */ +export function getUnpassedReviewFiles(reviewReports) { + return REVIEW_FILES.filter((file) => { + const content = reviewReports.get(file) ?? ''; + return !/^最终结论：passed$/m.test(content); + }); +} diff --git a/tools/governance/feature-record.test.mjs b/tools/governance/feature-record.test.mjs index c017e2c..abc9abb 100644 --- a/tools/governance/feature-record.test.mjs +++ b/tools/governance/feature-record.test.mjs @@ -2,6 +2,7 @@ import assert from 'node:assert/strict'; import test from 'node:test'; import { + getUnpassedReviewFiles, getFeatureDirectory, getRequiredFeatureFiles, validateFeatureId, @@ -28,6 +29,7 @@ test('将功能编号和短名称解析到固定的功能档案目录', () => { test('返回开发完成前必须存在的完整追溯文件清单', () => { assert.deepEqual(getRequiredFeatureFiles(), [ 'manifest.yaml', + 'prd.md', 'requirements.md', 'design.md', 'implementation-plan.md', @@ -39,7 +41,26 @@ test('返回开发完成前必须存在的完整追溯文件清单', () => { 'gitnexus/comparison.md', 'qa/test-results.md', 'qa/visual-qa.md', + 'review/code-review.md', + 'review/standards-review.md', 'release-notes.md', 'rollback.md', ]); }); + +test('只有两份 Review 都明确通过时才允许发布', () => { + const reports = new Map([ + ['review/code-review.md', '# 代码 Review\n\n最终结论：passed\n'], + ['review/standards-review.md', '# 规范 Review\n\n状态：pending\n'], + ]); + + assert.deepEqual(getUnpassedReviewFiles(reports), [ + 'review/standards-review.md', + ]); + + reports.set( + 'review/standards-review.md', + '# 规范 Review\n\n最终结论：passed\n', + ); + assert.deepEqual(getUnpassedReviewFiles(reports), []); +}); diff --git a/tools/governance/finish.mjs b/tools/governance/finish.mjs index 8869dab..3ac89d5 100644 --- a/tools/governance/finish.mjs +++ b/tools/governance/finish.mjs @@ -5,6 +5,7 @@ import path from 'node:path'; import { getFeatureDirectory, getRequiredFeatureFiles, + getUnpassedReviewFiles, validateFeatureId, } from './feature-record.mjs'; @@ -60,6 +61,20 @@ if (missingFiles.length > 0) { throw new Error(`完成门禁未通过，缺少或为空：\n- ${missingFiles.join('\n- ')}`); } +const reviewReports = new Map( + ['review/code-review.md', 'review/standards-review.md'].map((relativeFile) => [ + relativeFile, + readFileSync(path.join(featureDirectory, relativeFile), 'utf8'), + ]), +); +const unpassedReviews = getUnpassedReviewFiles(reviewReports); + +if (unpassedReviews.length > 0) { + throw new Error( + `完成门禁未通过，Review 最终结论不是 passed：\n- ${unpassedReviews.join('\n- ')}`, + ); +} + process.stdout.write( `基础门禁已通过。提交前仍须人工确认 GitNexus 影响报告、业务测试、视觉 QA 和回退说明。\n`, );