code-spec/README.md

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

规则覆盖关系（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: 展示不推荐做法

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