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
@@ -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证据将在开发门禁执行时创建
@@ -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，补充结论优先、分析偏好和异常状态。
@@ -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
@@ -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补充为后续功能的强制门禁。
@@ -0,0 +1,8 @@
+# 代码 Review（追补）
+
+- reviewer_type：self
+- 审查范围：GOV-001 治理脚本与测试
+
+最终结论：passed
+
+治理脚本具有功能编号、路径和必备材料的行为测试；开发前后命令使用参数数组调用外部进程，未拼接用户输入到 Shell。GOV-002 继续增加 PRD 和 Review材料校验。
@@ -0,0 +1,7 @@
+# 开发规范符合性 Review（追补）
+
+- reviewer_type：self
+
+最终结论：passed
+
+GOV-001 已满足当时生效的 GitNexus 双门禁、中文提交、关键中文注释、文档追溯和本地 Git 约束。PRD 与独立 Review要求从 GOV-002 起正式生效，本文件明确标记为追补材料，不伪装成发布前独立审查。
@@ -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。
+- 完成门禁在任一材料缺失或为空时失败。
+- 文档占位符、脚本语法、中文提交和远程仓库状态通过检查。