Code Spec

该仓库是小管家代码规范仓库，规范基于 spaceflow Review Spec 协议编写。

目标

• 统一 JS/TS、NestJS、Mongoose Model、Vue 的代码风格与结构约束。
• 提供可执行、可审查、可扩展的规则定义（含规则 ID、Good/Bad 示例、覆盖关系）。
• 为自动化 Review 与人工 Code Review 提供统一判断标准。

目录结构

.
├── 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、注释策略和重试策略。

{
  "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，可加入以下配置：

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

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