docs(GOV-001): 建立工程治理与追溯规范

2026-08-12 18:18:55 +08:00
parent 7cc2ba06a6
commit efdfb331bb
46 changed files with 1030 additions and 0 deletions
@@ -0,0 +1,5 @@
+# 设计
+
+首屏顺序为：市场结论、驱动与风险、核心指数、市场宽度与量能、板块概览、情绪与资金摘要。分析偏好保存在浏览器本地，页面只显示轻量的当前状态入口。
+
+ETF监控、两融数据、大盘云图和实时消息仍是独立一级菜单，不属于短线和中长线切换。
@@ -0,0 +1,8 @@
+# 实施计划
+
+1. 初始化 Vue 3、Vite、TypeScript和 Dart Sass。
+2. 建立市场快照类型和确定性模拟数据。
+3. 实现终端外壳、数据状态和结论区。
+4. 实现指数、宽度、量能、板块、情绪与资金模块。
+5. 实现分析偏好菜单和依据抽屉。
+6. 完成测试、构建、浏览器验证和视觉对比。
@@ -0,0 +1,11 @@
+id: FEAT-MO-001
+name: 市场综合概览
+slug: market-overview
+status: approved
+owner: project
+created_at: 2026-08-12
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+traceability_note: 开发尚未开始，GitNexus与QA证据将在开发门禁执行时创建
+release: unreleased
@@ -0,0 +1,5 @@
+# 需求
+
+首屏为“市场概览”模块中的综合概览，采用结论优先。市场概览内部通过轻量分析状态入口切换综合、短线和中长线视角，并支持规则、AI、混合与对照分析。
+
+当前切片仅开发 Vue 3 可交互首屏和本地模拟数据，不接用户体系和正式数据链路。
@@ -0,0 +1,8 @@
+# 测试计划
+
+- 结论、驱动和风险在首屏可见。
+- 分析状态可以临时切换并保存默认值。
+- 依据抽屉能够打开和关闭。
+- 时间范围切换更新图表。
+- 加载、部分数据、过期和错误状态具有明确文案。
+- 桌面和窄窗口不出现阻断核心内容的溢出。
@@ -0,0 +1,11 @@
+# 设计
+
+采用仓库级规范、功能级档案和自动化门禁三层结构。
+
+- `AGENTS.md` 为代理和开发者的强制入口。
+- `docs/governance/` 保存长期规范。
+- `docs/features/` 保存每次功能的需求、设计、测试、GitNexus 前后报告、发布和回退。
+- `tools/governance/` 提供一致的开发前和开发后入口。
+- `.githooks/commit-msg` 在本地阻止非中文或不符合格式的提交。
+
+GitNexus 索引不提交，因为它可以重新生成；分析摘要必须提交，因为它是历史决策证据。
@@ -0,0 +1,8 @@
+# GitNexus 开发后基线
+
+- 日期：2026-08-12
+- GitNexus状态：最新。
+- 图谱规模：170 个符号、191 条关系、4 个功能簇、0 条执行流程。
+- 远程仓库：未配置。
+
+图谱已识别治理脚本中的功能编号校验、目录解析和门禁执行关系，并形成 4 个治理相关功能簇。查询“engineering governance feature record”能够定位功能编号校验、必备文件清单、开始/完成门禁及对应文档。仓库尚无业务代码，因此没有业务执行流程属于符合预期的结果。
@@ -0,0 +1,8 @@
+# GitNexus 开发前基线
+
+- 日期：2026-08-12
+- Git 状态：空仓库，尚无提交。
+- GitNexus：20 个节点、16 条关系、0 个功能簇、0 条执行流程。
+- 远程仓库：未配置。
+
+当前只有项目说明、空的前后端目录和市场概览初步计划，不存在可受影响的生产代码符号。
@@ -0,0 +1,10 @@
+# GitNexus 前后比较
+
+| 项目 | 开发前 | 开发后 | 说明 |
+|---|---:|---:|---|
+| 符号 | 20 | 170 | 新增治理脚本、规范和功能档案中的可索引结构 |
+| 关系 | 16 | 191 | 新增脚本导入、调用与文档关联 |
+| 功能簇 | 0 | 4 | 形成治理相关功能簇，尚无业务功能簇 |
+| 执行流程 | 0 | 0 | 尚未开始业务应用代码开发 |
+
+实际变化与开发前计划一致，影响限制在工程治理层。暂存区变更检测识别 46 个文件、118 个符号、0 条受影响流程，风险为低；未发现 API、数据模型、消息契约、部署或界面方面的计划外变化。
@@ -0,0 +1,21 @@
+# 实际变更检测
+
+## 实际范围
+
+- 新增仓库级规范、系统架构、ADR、功能档案和文档索引。
+- 新增功能档案校验、开发前索引和开发后完成门禁脚本。
+- 新增中文提交信息钩子和本地 Git 配置说明。
+- 更新 `AGENTS.md`，保留 GitNexus 自动管理区块，并在其外加入项目强制规则。
+
+## 计划外影响检查
+
+首次执行变更检测时因空仓库没有 `HEAD` 而失败。创建中文空基线提交 `7cc2ba0` 后，使用暂存区范围重新执行：
+
+```text
+npx gitnexus detect-changes --repo a-share-analysis --scope staged
+Changes: 46 files, 118 symbols
+Affected processes: 0
+Risk level: low
+```
+
+没有业务生产代码、HTTP API、数据库结构、RabbitMQ消息、部署配置或用户界面变化。实际范围与计划一致。
@@ -0,0 +1,18 @@
+# 开发前影响计划
+
+## 计划影响
+
+- 新增仓库级规范、功能档案、ADR和治理工具。
+- 更新 `AGENTS.md` 与 `README.md` 的开发入口。
+- 不修改业务生产代码，不改变 API、数据库、RabbitMQ消息和页面行为。
+
+## GitNexus 风险
+
+初始仓库没有业务调用流程和现有生产符号。治理代码完成后，对核心符号 `validateFeatureId` 执行上游影响分析：
+
+- 直接依赖：`tools/governance/start.mjs`、`tools/governance/finish.mjs`。
+- 受影响执行流程：0。
+- 受影响模块：0。
+- GitNexus风险等级：低。
+
+该符号仍需通过行为测试保护，因为错误放宽编号格式会同时削弱开发前和开发后门禁。
@@ -0,0 +1,9 @@
+# 实施计划
+
+1. 初始化本地 Git 与首次 GitNexus 索引。
+2. 建立代码、流程、追溯、Git/Gitea规范。
+3. 建立系统架构与 ADR。
+4. 用测试先行实现功能编号和档案清单校验。
+5. 实现开发前后 GitNexus 门禁脚本。
+6. 建立 GOV-001 与 FEAT-MO-001 功能档案。
+7. 执行测试、脚本检查、GitNexus重建并提交中文基线。
@@ -0,0 +1,17 @@
+id: GOV-001
+name: 工程治理基线
+slug: engineering-governance
+status: verifying
+owner: project
+created_at: 2026-08-12
+requirements: requirements.md
+design: design.md
+implementation_plan: implementation-plan.md
+decisions:
+  - ../../adr/ADR-0001-monorepo-independent-deploy.md
+  - ../../adr/ADR-0002-gitnexus-double-gate.md
+gitnexus_before: gitnexus/before.md
+gitnexus_after: gitnexus/after.md
+gitnexus_comparison: gitnexus/comparison.md
+baseline_commit: 7cc2ba0
+release: unreleased
@@ -0,0 +1,27 @@
+# 测试结果
+
+- 日期：2026-08-12
+- Node.js：v20.20.2
+
+## 已执行
+
+```text
+npm run test:governance
+结果：4 个测试通过，0 个失败。
+
+node --check tools/governance/start.mjs
+结果：通过。
+
+node --check tools/governance/finish.mjs
+结果：通过。
+
+npm run governance:finish -- GOV-001 engineering-governance
+结果：基础门禁通过。
+```
+
+中文提交钩子另外验证规范中文示例通过、英文摘要被拒绝。
+
+```text
+规范中文提交：退出码 0
+英文摘要提交：退出码 1
+```
@@ -0,0 +1,3 @@
+# 视觉 QA
+
+本功能不修改用户界面，因此不适用视觉对比。后续页面功能必须保存同视口参考图和实现图。
@@ -0,0 +1,3 @@
+# 发布说明
+
+建立项目首个工程治理基线，不包含用户可见业务功能。
@@ -0,0 +1,14 @@
+# 需求
+
+## 目标
+
+建立可直接阅读、可比较、可追溯和可回退的工程治理基线。
+
+## 必须满足
+
+- 分别提供代码开发规范和开发流程规范。
+- 关键代码必须包含解释业务口径和设计原因的中文注释。
+- 代码按常规阅读尺度拆分，禁止过度碎片化。
+- 所有提交使用中文 Conventional Commit并关联功能编号。
+- 每次开发前后均刷新 GitNexus并保存可读报告。
+- 当前只使用本地 Git，未来接入用户自建 Gitea，不使用 GitHub。
@@ -0,0 +1,3 @@
+# 回退说明
+
+在本地首个提交建立后，可通过该提交完整读取治理基线。若治理脚本阻塞开发，可先用 Git 恢复到上一标签；不得删除功能档案或改写已共享历史。
@@ -0,0 +1,8 @@
+# 测试计划
+
+- 验证合法和非法功能编号。
+- 验证功能目录只能解析到 `docs/features/`。
+- 验证完成门禁的必备文件清单。
+- 验证中文提交钩子接受规范示例并拒绝英文摘要。
+- 验证 GitNexus 索引在修改后可成功重建。
+- 验证仓库未配置远程地址。