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,115 @@
+# 代码开发规范
+
+## 1. 目标
+
+本规范保证代码对普通开发者可连续阅读、对关键业务可解释、对历史版本可维护。规范适用于 Vue 3 前端、NestJS 后端、调度器、RabbitMQ Worker、数据适配器、规则引擎和 AI 分析模块。
+
+## 2. 技术基线
+
+- 前端：Vue 3、Vite、TypeScript、Dart Sass、Naive UI。
+- 后端：NestJS、TypeScript。
+- 数据库：MySQL；缓存：Redis；消息队列：RabbitMQ。
+- 图表：Lightweight Charts负责K线和分时，ECharts负责热力图、分布和资金趋势。
+- AI：由服务端调用兼容 OpenAI 格式的付费 API，密钥不得下发浏览器。
+
+依赖版本必须由锁文件固定。引入新依赖前应说明用途、替代方案、体积或运行成本以及退出方案。
+
+## 3. 文件组织与拆分尺度
+
+代码按业务能力组织，而不是把每个函数、类型和常量拆成独立文件。
+
+### 应当拆分
+
+- 文件同时承担两个可独立变化的业务职责。
+- 模块形成稳定复用边界，且确实被多个调用方使用。
+- 单个文件已经难以在一次正常阅读中理解完整流程。
+- 外部系统适配、持久化、消息传输与纯业务计算需要隔离测试。
+
+### 不应拆分
+
+- 只为减少行数创建单函数文件。
+- 将同一业务流程拆成大量需要来回跳转的薄包装。
+- 为尚未出现的复用场景提前抽象。
+- 为形式上的“分层”添加不产生业务价值的转发层。
+
+Vue 页面可以包含与页面强绑定的小型展示逻辑；当子区域拥有独立状态、独立测试价值或被复用时再提取组件。NestJS 模块应让入口、服务和领域计算的调用关系容易跟读。
+
+## 4. 命名与语言
+
+- 文件、变量、函数、类型和数据库字段使用清晰英文命名。
+- 产品文案、业务日志、错误说明、代码注释和提交摘要优先使用中文。
+- 禁止 `data1`、`temp2`、`handleThing` 等缺乏语义的命名。
+- A 股领域词汇使用统一词典，例如 `limitUpCount`、`brokenBoardRate`、`marketBreadth`。
+- 时间字段必须体现语义，例如 `tradeDate`、`snapshotAt`、`sourceUpdatedAt`，不得统称 `time`。
+
+## 5. 注释规范
+
+代码必须写详细但有信息价值的中文注释。注释解释“为什么、口径、限制和风险”，不复述语法。
+
+### 必须注释
+
+- 对外导出的公共接口、类型和关键函数。
+- 涨跌停、复权、停牌、午间休市等 A 股特殊规则。
+- 指标公式、阈值来源、单位、数据日期和缺失值处理。
+- RabbitMQ 的幂等、重试、死信和消息顺序假设。
+- Redis 与 MySQL 一致性边界和缓存失效策略。
+- AI 输入裁剪、事实约束、降级和成本控制逻辑。
+- 看似可以简化但因兼容性或历史原因必须保留的实现。
+- 异常恢复、降级策略和安全边界。
+
+### 禁止注释
+
+```ts
+// 将 count 加一
+count += 1;
+```
+
+此类注释没有提供代码之外的信息。代码变更时，注释必须同步更新；失真的注释视为缺陷。
+
+## 6. 类型与数据契约
+
+- 禁止无理由使用 `any`；外部输入先以 `unknown` 接收并校验。
+- HTTP API 使用版本化 OpenAPI 契约。
+- RabbitMQ 事件包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
+- 金额、成交额和比率必须明确单位，避免同一字段混用元、万元、亿元或百分比小数。
+- 数据来源、采集时间、交易日期、完整性和口径版本必须可追溯。
+
+## 7. 错误处理与日志
+
+- 不吞异常，不使用空 `catch`。
+- 对外错误不泄露密钥、内部地址和原始上游响应。
+- 日志使用结构化字段，至少包含 `traceId`、任务类型、交易日期和数据源。
+- 免费数据源失败时保留最后有效快照，并明确标记陈旧，禁止伪装实时数据。
+- AI 失败不得影响规则分析和基础行情展示。
+
+## 8. 前端规范
+
+- 页面不得直接访问第三方行情源、Redis、RabbitMQ 或 AI 服务。
+- 全局服务器状态使用 TanStack Vue Query，本地界面偏好使用 Pinia或轻量组合式函数。
+- Sass token集中管理颜色、间距、圆角、字号和断点。
+- A 股默认红涨绿跌，但状态必须同时提供文字或形状，不能只依赖颜色。
+- 图表必须标注单位、时间范围、数据日期和更新时间。
+- 所有核心交互覆盖加载、空、部分数据、错误和过期状态。
+
+## 9. 后端与任务规范
+
+- API、Scheduler和Worker作为独立进程维护，不在请求期间临时抓取全市场数据。
+- Scheduler只决定何时投递；RabbitMQ负责任务传输；Worker负责执行；MySQL负责事实记录；Redis负责当前快照和短期状态。
+- 消费者必须幂等，消息确认只能发生在持久化或可验证处理完成后。
+- 免费数据源通过 Adapter 统一为内部模型，上层不得依赖供应商原始字段。
+
+## 10. 测试要求
+
+- 功能和缺陷修复遵循测试先行：先看到测试因缺少行为而失败，再实现最小代码。
+- 纯规则和指标计算使用单元测试，期望值必须手工推导。
+- 数据源 Adapter 使用契约测试和固定样本。
+- HTTP 与 RabbitMQ 使用契约测试。
+- 关键页面使用 Playwright流程测试和视觉截图对比。
+- 合并前必须通过类型检查、测试、构建和适用的视觉验证。
+
+## 11. 安全要求
+
+- 禁止提交 `.env`、API Key、密码、真实账号和生产数据。
+- AI 密钥、数据源凭证和支付凭证仅存在服务端密钥管理中。
+- SQL必须参数化；外部输入必须在边界处校验。
+- 日志和异常报告必须脱敏。
@@ -0,0 +1,98 @@
+# 开发流程规范
+
+## 1. 总原则
+
+每个步骤必须留痕、可以直接阅读、可以比较、可以关联到 Git 提交并有明确回退方法。功能开发以功能编号为主键，禁止先写代码、后补需求和设计。
+
+## 2. 功能状态
+
+```text
+proposed → designing → approved → developing → verifying → released
+                                      ↘ blocked
+released → superseded
+```
+
+状态只能在证据齐全时前进。`released` 必须对应 Git 提交和版本；被替代的设计保留原文并标记 `superseded`，不得删除历史原因。
+
+## 3. 开发前流程
+
+1. 分配功能编号和英文短名称。
+2. 建立 `docs/features/<编号>-<短名称>/`。
+3. 填写需求、范围、非目标和验收标准。
+4. 比较可选方案，记录设计与关键决策。
+5. 更新 API、事件和数据结构契约。
+6. 编写测试计划和实施计划。
+7. 确保 Git 工作区基线可识别，执行：
+
+```bash
+npm run governance:start -- FEAT-MO-001 market-overview
+```
+
+8. 运行 GitNexus 查询、上下文和影响分析，将结果写入 `gitnexus/impact-plan.md`。
+9. 高风险或关键路径变化必须先向用户说明影响，再进入开发。
+
+开发前必须至少回答：修改什么、为什么修改、影响谁、如何验证、失败后如何回退。
+
+## 4. 开发过程
+
+- 使用短期功能分支；当前仓库基线建立阶段经用户明确确认后可直接在 `main` 工作。
+- 每个可观察行为先写失败测试，再实现最小代码并重构。
+- 需求或设计发生变化时，先更新功能档案并记录原因，再改代码。
+- 每个阶段保存必要截图和测试结果，禁止只在聊天中保留决定。
+- 发现缺陷时先记录复现步骤和失败测试，禁止无证据猜测式修复。
+
+## 5. 开发后流程
+
+1. 完成类型检查、单元测试、契约测试、构建和页面流程测试。
+2. 对界面变化保存参考图、实现图和同视口对比结果。
+3. 查看 Git diff，确认没有计划外文件和密钥。
+4. 执行 GitNexus 变更检测；若 MCP 工具不可用，记录限制并至少保存 Git diff 与重新索引结果。
+5. 再次运行：
+
+```bash
+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`。
+
+## 6. 完成定义
+
+下列任一项缺失，功能不得标记完成：
+
+- 需求和设计已确认。
+- 实施计划与实际变化一致。
+- 代码符合开发规范并包含必要中文注释。
+- 测试和构建有最新成功证据。
+- 视觉变化有同视口对比证据。
+- GitNexus 开发前后报告和差异说明齐全。
+- 发布说明和回退方法可执行。
+- 中文提交已关联功能编号。
+
+## 7. 提交流程
+
+提交格式：
+
+```text
+<类型>(<功能编号>): <中文摘要>
+```
+
+示例：
+
+```text
+feat(FEAT-MO-001): 新增市场概览结论区
+fix(FEAT-MO-001): 修正成交额同比计算口径
+docs(GOV-001): 建立工程治理与追溯规范
+```
+
+一次提交应表达一个完整意图，但不为了追求小提交把同一功能切成无法独立理解的碎片。
+
+## 8. 发布与回退
+
+- 使用语义化版本和带注释 Git Tag。
+- 发布产物必须对应确定提交，不从浮动分支临时构建。
+- 应用优先通过部署上一不可变镜像回退。
+- 数据库采用可兼容迁移和前向修复，破坏性回滚需先备份和演练。
+- 规则、提示词和消息契约发布后不得原地覆盖，只能新增版本。
@@ -0,0 +1,43 @@
+# 文档与追溯规范
+
+## 1. 追溯主键
+
+每个业务变化必须有唯一功能编号。功能编号贯穿需求、设计、ADR、代码提交、测试、截图、GitNexus 报告、发布和回退。
+
+## 2. 功能档案必备内容
+
+```text
+docs/features/<编号>-<短名称>/
+├── manifest.yaml
+├── requirements.md
+├── design.md
+├── implementation-plan.md
+├── test-plan.md
+├── gitnexus/
+│   ├── before.md
+│   ├── impact-plan.md
+│   ├── detected-changes.md
+│   ├── after.md
+│   └── comparison.md
+├── screenshots/
+│   ├── reference/
+│   ├── iterations/
+│   └── released/
+├── qa/
+│   ├── test-results.md
+│   └── visual-qa.md
+├── release-notes.md
+└── rollback.md
+```
+
+## 3. 历史保留
+
+- 已发布文档不删除、不覆盖历史结论；修订通过 Git 历史和文档版本说明保留。
+- 重大方案变化新增 ADR，旧 ADR 标记被替代。
+- 规则、提示词、API 和事件契约使用明确版本。
+- 截图文件名包含页面、状态、视口和版本，例如 `market-overview-trading-1440x1200-v0.1.0.png`。
+- `.gitnexus/` 不提交；可读的 GitNexus 摘要和比较报告必须提交。
+
+## 4. 可阅读性
+
+文档先写结论，再写背景、方案和证据。禁止使用“见聊天记录”“以后再说”“大概如此”作为正式设计依据。链接使用仓库相对路径，保证在本地与 Gitea 中均可阅读。
@@ -0,0 +1,40 @@
+# Git 与 Gitea 规范
+
+## 1. 当前策略
+
+当前只使用本地 Git，不配置 GitHub、不创建 GitHub Actions，也不向任何第三方远程仓库推送。用户安装 Gitea 后，再显式配置 `origin`。
+
+## 2. 分支与提交
+
+- `main` 始终保持可验证和可回退。
+- 普通功能使用 `feature/<功能编号>-<短名称>`。
+- 修复使用 `fix/<功能编号>-<短名称>`。
+- 提交必须符合中文 Conventional Commit，仓库通过 `.githooks/commit-msg`检查。
+- 禁止强推共享 `main`，禁止使用破坏历史的回退方式处理已共享版本。
+
+首次克隆后执行：
+
+```bash
+git config core.hooksPath .githooks
+```
+
+## 3. Gitea 接入
+
+Gitea 安装并创建空仓库后，由用户确认地址，再执行：
+
+```bash
+git remote add origin <用户提供的Gitea仓库地址>
+git push -u origin main
+```
+
+建议在 Gitea 中保护 `main`：禁止强推、要求状态检查通过、要求变更说明关联功能编号。未得到用户提供的地址和授权前，任何代理不得自行添加远程或推送。
+
+## 4. 版本与标签
+
+发布使用带注释标签，例如：
+
+```bash
+git tag -a v0.1.0 -m "发布市场综合概览 v0.1.0"
+```
+
+标签必须指向通过验证的提交。应用回退优先选择既有标签和不可变构建产物，而不是重新拼装旧版本。