docs: 完善 README 文档,添加规范索引、接入步骤和使用说明

2026-03-02 10:37:04 +08:00
parent f6f87e0c47
commit fb3962accd
1 changed files with 125 additions and 2 deletions
@@ -1,3 +1,126 @@
-# Review Spec
+# Code Spec

-该仓库是小管家代码规范仓库，规范是基于 Gitea Flows Review Spec 协议编写。
+该仓库是小管家代码规范仓库，规范基于 spaceflow [Review Spec](https://lydanne.github.io/spaceflow/reference/review-spec.html) 协议编写。
+
+
+## 目标
+
+- 统一 JS/TS、NestJS、Mongoose Model、Vue 的代码风格与结构约束。
+- 提供可执行、可审查、可扩展的规则定义（含规则 ID、Good/Bad 示例、覆盖关系）。
+- 为自动化 Review 与人工 Code Review 提供统一判断标准。
+
+## 目录结构
+
+```txt
+.
+├── README.md
+└── references/
+    ├── js&ts.base.md
+    ├── js&ts.file-name.md
+    ├── js&ts.nest.md
+    ├── js&ts.test-code.md
+    ├── js.models.md
+    ├── vue.base.md
+    └── vue.file-name.md
+```
+
+## 接入步骤（`.spaceflowrc`）
+
+1. 在业务仓库根目录创建或修改 `.spaceflowrc`。
+2. 在 `review.references` 中引入本仓库 `references` 地址。
+3. 根据项目需要配置 `includes`、注释策略和重试策略。
+
+```json
+{
+  "review": {
+    "references": ["https://git.bjxgj.com/xgj-pub/code-spec/src/branch/main/references"],
+    "includes": [
+      "**/*.ts",
+      "**/*.js",
+      "!nest-src/errcode.ts",
+      "!nest-src/libs/entity/**",
+      "!**/dist/**",
+      "!**/*.spec.*",
+      "!**/*.config.*"
+    ],
+    "generateDescription": true,
+    "lineComments": true,
+    "verifyFixes": true,
+    "autoUpdatePrTitle": true,
+    "analyzeDeletions": false,
+    "deletionAnalysisMode": "open-code",
+    "concurrency": 1,
+    "retries": 3,
+    "retryDelay": 1000
+  }
+}
+```
+
+> 说明：如果你的 `.spaceflowrc` 已有其他配置，请仅合并 `review` 字段，不要覆盖现有配置。
+
+### MCP 配置（spaceflow）
+
+如果你需要在支持 MCP 的客户端中接入 spaceflow，可加入以下配置：
+
+```json
+{
+  "mcpServers": {
+    "spaceflow": {
+      "args": [
+        "-y",
+        "@spaceflow/cli",
+        "mcp"
+      ],
+      "command": "npx",
+      "disabled": false
+    }
+  }
+}
+```
+
+然后我们就可以使用这样的提示词让AI去拉规则了.
+
+```
+请使用 spaceflow 工具去 review 代码。
+```
+
+## 规范索引
+
+| 规范集 | 规则 ID 前缀 | 作用范围（includes） | 说明 |
+| --- | --- | --- | --- |
+| JS/TS 基础规范 | `JsTs.Base` | 通用 JS/TS 文件 | 命名、复杂度、行数、魔法值等基础约束 |
+| JS/TS 文件命名规范 | `JsTs.FileName` | 通用 JS/TS 文件 | class/interface 与函数文件命名规则 |
+| NestJS 规范 | `JsTs.Nest` | `*.controller.ts` `*.service.ts` `*.module.ts` `*.dto.ts` `*.pipe.ts` `*.guard.ts` `*.interceptor.ts` `*.filter.ts` `*.exception-filter.ts` `*.proxy.ts` `*.model.ts` | 目录结构、分层职责、文件命名与模块组织 |
+| 测试代码规范 | `JsTs.TestCode` | 测试文件（`.test.js` `.test.ts` `.spec.ts`） | 测试文件命名与 `describe/it` 结构约束 |
+| Mongoose Model 规范 | `Js.Model` | `*/models/*.js` | schema 字段、索引、钩子、方法、引用关系等 |
+| Vue 基础规范 | `Vue.Base` | `*.vue` | 自定义组件命名规范 |
+| Vue 文件命名规范 | `Vue.FileName` | `*.vue` | 组件文件命名规范 |
+
+## 规则覆盖关系（override）
+
+当多个规范同时命中同一文件时，按以下覆盖关系处理冲突：
+
+1. `JsTs.Nest` 覆盖 `JsTs.FileName`。
+2. `JsTs.Nest.DtoDefinition` 对 `JsTs.Base.NoMagicStringsAndNumbers` 做规则级覆盖。
+3. `Js.Model` 覆盖 `JsTs.Base`。
+4. `Js.Model.FileName` 覆盖 `JsTs.FileName`。
+
+> 建议：在实现自动化检查时，先按 `includes` 过滤命中文件，再按 `override` 解析最终生效规则。
+
+## 使用建议
+
+1. **按文件类型匹配规范集**：先判断文件路径与后缀，再应用对应规则。
+2. **输出规则 ID**：Review 结果中保留规则 ID（如 `JsTs.Base.FuncLowerCamel`），便于追踪和整改。
+3. **先基础后专项**：优先接入 `JsTs.Base` 与 `JsTs.FileName`，再逐步接入 Nest / Model / Vue / Test 专项规则。
+4. **保持示例驱动**：新增规则时提供清晰的 Good/Bad 示例，降低理解成本。
+
+## 维护约定
+
+新增或修改规则时建议遵循以下格式：
+
+- 一级标题：规范名称 + 规则前缀（如 ``[JsTs.Base]``）
+- 二级标题：单条规则描述 + 完整规则 ID（如 ``[JsTs.Base.ConstUpperCase]``）
+- 元信息：`includes` / `override` / `severity`（如适用）
+- 示例：必须包含 `Good` 与 `Bad`
+
+这样可以保证规则文档在人工阅读和自动化解析两种场景下都保持一致性。