code-spec/README.md

# Code 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` | 组件文件命名规范 |

## 规则明细图表

| 规范集 | 规则 ID | 规则说明 | 文档 |
| --- | --- | --- | --- |
| JsTs.Base | `JsTs.Base.ConstUpperCase` | 常量名使用大写加下划线命名（UPPER_CASE），单词间以下划线分隔 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.FuncLowerCamel` | 函数名使用小驼峰命名 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.NoMagicVar` | 禁止使用字面量魔法数字 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.ConstantsDefinition` | 基于 JsTs.Base.NoMagicVar 抽离的静态常量需要放在对应文件里 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.ClassNaming` | class 和 interface 命名使用大驼峰命名 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.VarNaming` | 变量名使用小驼峰或者蛇形命名 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.CodeNotMoreThan700Lines` | 单文件代码不超过 700 行 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.FuncNotMoreThan200Lines` | 单个函数或方法不能超出 200 行 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.ComplexLogic` | 复杂的逻辑判断要添加注释 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.Base | `JsTs.Base.ComplexFunc` | 复杂的函数要添加注释 | [js&ts.base.md](references/js&ts.base.md) |
| JsTs.FileName | `JsTs.FileName.UpperCamel` | class 和 interface 文件使用大驼峰命名 | [js&ts.file-name.md](references/js&ts.file-name.md) |
| JsTs.FileName | `JsTs.FileName.LowerCamel` | 函数文件使用小驼峰命名 | [js&ts.file-name.md](references/js&ts.file-name.md) |
| JsTs.Nest | `JsTs.Nest.DirStructure` | 目录框架规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ControllerDefinition` | 控制器命名规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ServiceDefinition` | 服务命名规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ModuleDefinition` | 模块命名规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.DtoDefinition` | Dto 命名规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ProxyDefinition` | Proxy 编写规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ModelDefinition` | Model 编写规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.BusinessDefinition` | 业务代码编写规范 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.Nest | `JsTs.Nest.ConstantsDefinition` | 基于 JsTs.Base.NoMagicStringsAndNumbers 抽离的静态常量需要放在对应文件里 | [js&ts.nest.md](references/js&ts.nest.md) |
| JsTs.TestCode | `JsTs.TestCode.FileName` | 测试文件命名 | [js&ts.test-code.md](references/js&ts.test-code.md) |
| JsTs.TestCode | `JsTs.TestCode.BlockName` | 测试代码块命名 | [js&ts.test-code.md](references/js&ts.test-code.md) |
| Js.Model | `Js.Model.FileName` | 模型文件命名规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.FieldName` | Schema 字段命名规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.SchemaDefinition` | Schema 定义规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.IndexDefinition` | 索引定义规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.VirtualField` | 虚拟字段规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.Middleware` | 中间件/钩子规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.StaticMethod` | 静态方法规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.InstanceMethod` | 实例方法规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.Reference` | 关联引用规范 | [js.models.md](references/js.models.md) |
| Js.Model | `Js.Model.FieldType` | 必须写明字段的类型 | [js.models.md](references/js.models.md) |
| Vue.Base | `Vue.Base.CustomComponentName` | Vue 自定义组件命名规则 | [vue.base.md](references/vue.base.md) |
| Vue.FileName | `Vue.FileName.UpperCamel` | Vue 组件文件使用大驼峰命名 | [vue.file-name.md](references/vue.file-name.md) |

## 规则覆盖关系（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`（如适用）
- 示例：使用 `### Example:` 分组，`#### Good:` 展示推荐做法，`#### Bad:` 展示不推荐做法

这样可以保证规则文档在人工阅读和自动化解析两种场景下都保持一致性。