docs: 在 JS/TS 基础规范的魔法数字检查规则中补充数量类型数字无需抽离的说明

README.md

@@ -96,6 +96,46 @@
 | 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）
 
 当多个规范同时命中同一文件时，按以下覆盖关系处理冲突：
@@ -121,6 +161,6 @@
 - 一级标题：规范名称 + 规则前缀（如 ``[JsTs.Base]``）
 - 二级标题：单条规则描述 + 完整规则 ID（如 ``[JsTs.Base.ConstUpperCase]``）
 - 元信息：`includes` / `override` / `severity`（如适用）
-- 示例：必须包含 `Good` 与 `Bad`
+- 示例：使用 `### Example:` 分组，`#### Good:` 展示推荐做法，`#### Bad:` 展示不推荐做法
 
 这样可以保证规则文档在人工阅读和自动化解析两种场景下都保持一致性。

references/js&ts.base.md

@@ -7,23 +7,27 @@
 - 不检查 nodejs 的导包定义，比如 `const fs = require("fs")`
 - 常量检查只需检查 `const` 声明的静态值，但是不包含对象和函数
 
-### Good
+### Example: 常量命名
+
+#### Good: 使用大写加下划线
 
 ```javascript
-const MAX_COUNT = 100;
+const ROLE_ADMIN = 1;
 ```
 
-### Bad
+#### Bad: 使用小驼峰
 
 ```javascript
-const maxCount = 100;
+const roleAdmin = 1;
 ```
 
 ## 函数名使用小驼峰命名 `[JsTs.Base.FuncLowerCamel]`
 
 > - severity `warn`
 
-### Good
+### Example: 函数命名
+
+#### Good: 使用小驼峰
 
 ```javascript
 function getUserInfo() {
@@ -31,7 +35,7 @@ function getUserInfo() {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写
 
 ```javascript
 function getuserinfo() {
@@ -39,61 +43,66 @@ function getuserinfo() {
 }
 ```
 
-## 禁止使用字面量魔法字符串和魔法数字 `[JsTs.Base.NoMagicStringsAndNumbers]`
+## 禁止使用字面量魔法数字 `[JsTs.Base.NoMagicVar]`
 
 > - severity `warn`
 
-- 只检查数字、字符串、正则字面量，不要检查其他（比如 布尔字面量、对象字面量、函数字面量、数组字面量）
+- 仅检查**数字字面量**和**正则字面量**，不检查布尔、对象、函数、数组、字符串字面量
-- 这块只检查含义不明确的字面量，比如 0 1 500 等，像是 'user' 'admin' 'active' 'inactive' 等是合理的
+- 仅检查含义不明确的数字，如 `0`、`1`、`2` 等；
-- 无需检查单词是否完整拼写
+- `throw` / `new Error` 的错误信息无需审查
-- throw 的错误信息无需审查
+- `console.*`（`log` / `error` / `warn` / `info` / `debug` / `trace`）的内容无需审查
-- new Error 的错误信息无需审查
+- 语义自明的数量类数字无需抽取常量，例如：时间戳、毫秒时长、元素数量、尺寸等一眼可理解的值
-- console.log 的打印代码无需审查
-- console.error 的错误信息无需审查
-- console.warn 的错误信息无需审查
-- console.info 的错误信息无需审查
-- console.debug 的错误信息无需审查
-- console.trace 的错误信息无需审查
-- 无需考虑类型是否合理匹配
 
-### Good
+### Example: 魔法数字
+
+#### Good: 使用常量替代魔法数字
 
 ```javascript
-const MAX_COUNT = 100;
+const ROLE_ADMIN = 1;
+
+if (user.role === ROLE_ADMIN) {
+  // ...
+}
 ```
 
-### Bad
+#### Bad: 使用字面量魔法数字
 
 ```javascript
-const maxCount = 100;
+if (user.role === 1) {
-const userStatus = "active";
+  // ...
+}
 ```
 
-## 基于 JsTs.Base.NoMagicStringsAndNumbers 抽离的静态常量需要放在对应文件里 `[JsTs.Base.ConstantsDefinition]`
+## 基于 JsTs.Base.NoMagicVar 抽离的静态常量需要放在对应文件里 `[JsTs.Base.ConstantsDefinition]`
 
-> - severity `warn`
+> - severity `error`
 
 - 需要放在指定模块的 constants 文件里
+- constants 命名规则: user.constants.js 或者 user.constants.ts
 
-### Good
+### Example: 常量定义位置
+
+#### Good: 常量放在对应模块的 constants 文件
 
 ```javascript
 // user.constants.js
-const MAX_COUNT = 100; // 这是 user 模块需要的
+const ROLE_ADMIN = 1; // 这是 user 模块需要的
 ```
 
-### Bad
+#### Bad: 常量放在错误模块的 constants 文件
 
 ```javascript
 // class.constants.js
-const MAX_COUNT = 100; // 这是 user 模块需要的
+const ROLE_ADMIN = 1; // 这是 user 模块需要的
 ```
 
-## class 和 interface 命名使用大驼峰命名 `[JsTs.Base.ClassUpperCamel]`
+## class 和 interface 命名使用大驼峰命名 `[JsTs.Base.ClassNaming]`
 
 > - severity `warn`
 
-### Good
+### Example: 类和接口命名
+
+#### Good: 使用大驼峰
 
 ```javascript
 class UserInfo {
@@ -101,7 +110,7 @@ class UserInfo {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写
 
 ```javascript
 class userinfo {
@@ -109,53 +118,65 @@ class userinfo {
 }
 ```
 
-## 变量名使用小驼峰命名 `[JsTs.Base.VarLowerCamel]`
+## 变量名使用小驼峰或者蛇形命名 `[JsTs.Base.VarNaming]`
 
 > - severity `warn`
 
 - 需要注意的是从 require 导入的变量不受检查
+- 私有属性可以使用 `_` 开头,比如 `this._fromFeatureRecommendEntry`
 
-### Good
+### Example: 变量命名
+
+#### Good: 使用小驼峰或蛇形命名
 
 ```javascript
 let userName = "John";
+let user_name = "John";
 ```
 
-### Bad
+#### Bad: 使用大驼峰
 
 ```javascript
-let username = "John";
+let Username = "John";
 ```
 
 ## 单文件代码不超过 700 行 `[JsTs.Base.CodeNotMoreThan700Lines]`
 
-### Good
+> - includes `added|*`
+
+### Example: 文件行数
+
+#### Good: 代码不超过 700 行
 
 ```javascript
 // 代码不超过 700 行
 ```
 
-### Bad
+#### Bad: 代码超过 700 行
 
 ```javascript
 // 代码超过 700 行
 ```
 
-## 单个函数或方法不能超出 200 行 `[JsTs.Base.FuncNotMoreThan200Lines]`
+## 单个函数或方法不能超出 300 行 `[JsTs.Base.FuncNotMoreThan300Lines]`
 
-### Good
+### Example: 函数行数
+
+#### Good: 函数不超过 300 行
 
 ```javascript
 function getUserInfo() {
-  // ... 小于等于 200
+  // ... 小于等于 300
 }
 ```
 
-### Bad
+#### Bad: 函数超过 300 行
+
+> - includes `added|*`
 
 ```javascript
 function getUserInfo() {
-  // ... 大于 200
+  // ... 大于 300
 }
 ```
 
@@ -163,18 +184,20 @@ function getUserInfo() {
 
 > - severity `warn`
 
-- 逻辑判断的复杂度超过 2 个的要添加注释
+- 逻辑判断的复杂度大于等于 3 个的要添加注释
 
-### Good
+### Example: 复杂逻辑注释
+
+#### Good: 复杂逻辑添加注释
 
 ```javascript
-// 逻辑判断复杂度超过 2 个
+// 逻辑判断复杂度大于等于 3 个
 if (a && b || c) {
   // ...
 }
 ```
 
-### Bad
+#### Bad: 复杂逻辑未添加注释
 
 ```javascript
 if (a && b && c && d) {
@@ -186,7 +209,11 @@ if (a && b && c && d) {
 
 > - severity `warn`
 
-### Good
+### Example: 复杂函数注释
+
+#### Good: 复杂函数添加注释
+
+> - includes `added|*`
 
 ```javascript
 /**
@@ -197,7 +224,9 @@ function complexFunc() {
 }
 ```
 
-### Bad
+#### Bad: 复杂函数未添加注释
+
+> - includes `added|*`
 
 ```javascript
 function complexFunc() {

references/js&ts.file-name.md

@@ -7,7 +7,9 @@
 - 文件名必须与主导类或接口名称完全一致。
 - 适用于定义单一主要实体的文件。
 
-### Good
+### Example: class 和 interface 文件命名
+
+#### Good: 使用大驼峰命名
 
 ```javascript
 // UserInfo.js
@@ -16,7 +18,7 @@ class UserInfo {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写命名
 
 ```javascript
 // userinfo.js
@@ -30,7 +32,9 @@ class userinfo {
 - 适用于导出一个或多个工具函数的文件。
 - 文件名应反映其包含的核心功能。
 
-### Good
+### Example: 函数文件命名
+
+#### Good: 使用小驼峰命名
 
 ```javascript
 // getUserInfo.js
@@ -39,7 +43,7 @@ function getUserInfo() {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写命名
 
 ```javascript
 // getuserinfo.js

references/js&ts.nest.md

@@ -16,7 +16,9 @@
 - 每个模块的目录下可以包含 `interceptor` 目录，用于存放拦截器
 - 每个模块的目录下可以包含 `filter` 目录，用于存放异常过滤器
 
-### Good
+### Example: 目录结构
+
+#### Good: 按模块组织的目录结构
 
 ```txt
 src/
@@ -43,7 +45,7 @@ src/
 └── main.ts          # 应用入口
 ```
 
-### Bad
+#### Bad: 扁平化的目录结构
 
 ```txt
 src/
@@ -63,13 +65,15 @@ src/
 - 文件名必须加 `.controller.ts` 后缀
 - 注解和装饰器上的静态值无需进行魔法值的提炼 `[JsTs.Base.NoMagicStringsAndNumbers]`
 
-### Good
+### Example: 控制器文件命名
+
+#### Good: 使用小写加横线命名
 
 ```txt
 user-extends.controller.ts
 ```
 
-### Bad
+#### Bad: 使用大驼峰命名
 
 ```txt
 userController.ts
@@ -83,13 +87,15 @@ userController.ts
 - 文件名使用小写加横线命名（如 `user-extends.service.ts`）
 - 文件名必须加 `.service.ts` 后缀
 
-### Good
+### Example: 服务文件命名
+
+#### Good: 使用小写加横线命名
 
 ```txt
 user-extends.service.ts
 ```
 
-### Bad
+#### Bad: 使用大驼峰命名
 
 ```txt
 userService.ts
@@ -100,13 +106,15 @@ userService.ts
 - 文件名使用小写加横线命名（如 `user-extends.module.ts`）
 - 文件名必须加 `.module.ts` 后缀
 
-### Good
+### Example: 模块文件命名
+
+#### Good: 使用小写加横线命名
 
 ```txt
 user-extends.module.ts
 ```
 
-### Bad
+#### Bad: 使用大驼峰命名
 
 ```txt
 userModule.ts
@@ -121,13 +129,15 @@ userModule.ts
 - dto 目录下必须包含 `dto.ts` 文件
 - dto 里的类的属性可以使用小驼峰或者下划线命名
 
-### Good
+### Example: Dto 文件命名
+
+#### Good: 使用小写加横线命名
 
 ```txt
 user-extends.dto.ts
 ```
 
-### Bad
+#### Bad: 使用大驼峰命名
 
 ```txt
 userDto.ts
@@ -141,7 +151,9 @@ userDto.ts
 - 内部只能写使用 syncService 调用的逻辑
 - SyncService 只能在 proxy.ts 中使用
 
-### Good
+### Example: Proxy 编写
+
+#### Good: Proxy 只使用 SyncService 调用旧业务
 
 ```typescript
 // user.proxy.ts
@@ -159,7 +171,7 @@ export class UserProxy {
 }
 ```
 
-### Bad
+#### Bad: Proxy 中直接查询数据库
 
 ```typescript
 // user.proxy.ts
@@ -187,7 +199,9 @@ export class UserProxy {
 - 文件名使用小写加横线命名（如 `user.model.ts`）
 - 文件名必须加 `.model.ts` 后缀
 
-### Good
+### Example: Model 编写
+
+#### Good: Model 只使用数据库调用
 
 ```typescript
 // user.model.ts
@@ -206,7 +220,7 @@ export class UserProxy {
 }
 ```
 
-### Bad
+#### Bad: Model 中使用 SyncService 调用旧业务
 
 ```typescript
 // user.model.ts
@@ -229,7 +243,9 @@ export class UserProxy {
 
 - 目前所有的新代码都应该写在 nest 里
 
-### Good
+### Example: 业务代码位置
+
+#### Good: 新代码写在 nest 目录下
 
 ```typescript
 // nest-src/apps/app/src/user/user.controller.ts
@@ -243,7 +259,7 @@ export class UserProxy {
 // nest-src/apps/app/src/user/user.module.ts
 ```
 
-### Bad
+#### Bad: 新代码写在旧目录下
 
 ```typescript
 // proxy/user.js
@@ -256,14 +272,16 @@ export class UserProxy {
 
 - 需要放在指定模块的 constants 文件里
 
-### Good
+### Example: 常量定义位置
+
+#### Good: 常量放在对应模块的 constants 文件
 
 ```typescript
 // user.constants.ts
 const MAX_COUNT = 100; // 这是 user 模块需要的
 ```
 
-### Bad
+#### Bad: 常量放在错误模块的 constants 文件
 
 ```typescript
 // class.constants.ts

references/js&ts.test-code.md

@@ -7,7 +7,9 @@
 - 必须以 `.test.js` 或 `.test.ts`（或 `.spec.ts`）结尾。
 - 前缀部分应与被测试源文件名保持一致。
 
-### Good
+### Example: 测试文件命名
+
+#### Good: 测试文件名与源文件名一致
 
 ```javascript
 // userInfo.js
@@ -17,7 +19,7 @@ describe("UserInfo", () => {
 });
 ```
 
-### Bad
+#### Bad: 测试文件名与源文件名不一致
 
 ```javascript
 // userInfo.js
@@ -32,7 +34,9 @@ describe("userinfo", () => {
 - 测试代码命名结构：`describe(文件名)` -> `describe(函数名/类名.方法名)` -> `it(场景描述)`。
 - 场景描述应使用 "should ..." 格式，描述预期行为。
 
-### Good
+### Example: 测试代码块命名
+
+#### Good: 使用 describe(文件名) -> describe(函数名/类名.方法名) -> it(场景描述)
 
 ```javascript
 // uUerInfo.js
@@ -68,7 +72,7 @@ describe("userInfo", () => {
 });
 ```
 
-### Bad
+#### Bad: 缺少 describe(函数名/类名.方法名) 层级
 
 ```javascript
 // userInfo.js

references/js.models.md

@@ -10,7 +10,9 @@
 - 文件名使用小写加下划线命名（如 `user_extends.js`）,或者使用小写加横线命名（如 `user-extends.js`）
 - 文件名应与模型名称对应
 
-### Good
+### Example: 模型文件命名
+
+#### Good: 使用小写加下划线或横线命名
 
 ```txt
 user.js
@@ -18,7 +20,7 @@ user_extends.js
 user-profile.js
 ```
 
-### Bad
+#### Bad: 使用大驼峰命名
 
 ```txt
 User.js
@@ -33,7 +35,9 @@ UserProfile.js
 - 要补充字段注释
 - 要补充字段类型
 
-### Good
+### Example: Schema 字段命名
+
+#### Good: 字段名使用 snake_case
 
 ```javascript
 const userSchema = new Schema({
@@ -43,7 +47,7 @@ const userSchema = new Schema({
 });
 ```
 
-### Bad
+#### Bad: 字段名使用驼峰命名
 
 ```javascript
 const userSchema = new Schema({
@@ -59,7 +63,9 @@ const userSchema = new Schema({
 - 必要时添加 `required`、`default` 等属性
 - 复杂类型应使用嵌套 Schema 或引用
 
-### Good
+### Example: Schema 定义
+
+#### Good: 完整的字段定义
 
 ```javascript
 const userSchema = new Schema({
@@ -71,7 +77,7 @@ const userSchema = new Schema({
 });
 ```
 
-### Bad
+#### Bad: 缺少 required/default 等属性
 
 ```javascript
 const userSchema = new Schema({
@@ -88,7 +94,9 @@ const userSchema = new Schema({
 - 需要添加注释说明索引用途
 - 不能在 Schema 定义中直接添加索引，添加到索引要注释掉
 
-### Good
+### Example: 索引定义
+
+#### Good: 索引注释掉并添加用途说明
 
 ```javascript
 const orderSchema = new Schema({
@@ -103,7 +111,7 @@ const orderSchema = new Schema({
 // orderSchema.index({ order_no: 1 }, { unique: true });
 ```
 
-### Bad
+#### Bad: 在 Schema 定义中直接添加索引
 
 ```javascript
 const orderSchema = new Schema({
@@ -119,7 +127,9 @@ const orderSchema = new Schema({
 - 虚拟字段应在 Schema 定义后声明
 - 需要添加注释说明虚拟字段用途
 
-### Good
+### Example: 虚拟字段
+
+#### Good: 使用 virtual 定义可计算字段
 
 ```javascript
 const userSchema = new Schema({
@@ -133,7 +143,7 @@ userSchema.virtual("full_name").get(function () {
 });
 ```
 
-### Bad
+#### Bad: 存储可计算的字段
 
 ```javascript
 const userSchema = new Schema({
@@ -149,7 +159,9 @@ const userSchema = new Schema({
 - 需要添加注释说明中间件用途
 - 避免在中间件中执行耗时操作
 
-### Good
+### Example: 中间件/钩子
+
+#### Good: 中间件添加注释说明用途
 
 ```javascript
 const userSchema = new Schema({
@@ -172,7 +184,7 @@ userSchema.pre("save", async function (next) {
 });
 ```
 
-### Bad
+#### Bad: 中间件缺少注释且使用同步方法
 
 ```javascript
 const userSchema = new Schema({
@@ -192,7 +204,9 @@ userSchema.pre("save", function (next) {
 - 静态方法应在 Schema 定义后声明
 - 需要添加注释说明方法用途
 
-### Good
+### Example: 静态方法
+
+#### Good: 静态方法使用小驼峰命名并添加注释
 
 ```javascript
 const userSchema = new Schema({
@@ -211,7 +225,7 @@ userSchema.statics.findActiveUsers = function () {
 };
 ```
 
-### Bad
+#### Bad: 静态方法使用下划线命名且缺少注释
 
 ```javascript
 const userSchema = new Schema({
@@ -231,7 +245,9 @@ userSchema.statics.find_by_email = function (email) {
 - 需要添加注释说明方法用途
 - 实例方法内部使用 `this` 访问文档属性
 
-### Good
+### Example: 实例方法
+
+#### Good: 实例方法使用小驼峰命名并添加注释
 
 ```javascript
 const userSchema = new Schema({
@@ -251,7 +267,7 @@ userSchema.methods.incrementLoginCount = function () {
 };
 ```
 
-### Bad
+#### Bad: 实例方法使用下划线命名且缺少注释
 
 ```javascript
 const userSchema = new Schema({
@@ -270,7 +286,9 @@ userSchema.methods.compare_password = function (candidatePassword) {
 - 必须指定 `ref` 属性
 - 需要添加注释说明关联关系
 
-### Good
+### Example: 关联引用
+
+#### Good: 引用字段使用 _id 后缀并指定 ref
 
 ```javascript
 const orderSchema = new Schema({
@@ -281,7 +299,7 @@ const orderSchema = new Schema({
 });
 ```
 
-### Bad
+#### Bad: 引用字段缺少 ref 且命名不规范
 
 ```javascript
 const orderSchema = new Schema({
@@ -296,7 +314,9 @@ const orderSchema = new Schema({
 - 禁止使用简写形式（如 `field: String`）
 - 不允许使用 Object 等模糊类型
 
-### Good
+### Example: 字段类型定义
+
+#### Good: 字段定义使用对象形式明确指定 type
 
 ```javascript
 const userSchema = new Schema({
@@ -311,7 +331,7 @@ const userSchema = new Schema({
 });
 ```
 
-### Bad
+#### Bad: 使用简写形式或模糊类型
 
 ```javascript
 const userSchema = new Schema({

references/vue.base.md

@@ -6,7 +6,9 @@
 
 必须使用大驼峰命名并且使用的时候也是，并且至少两个单词。
 
-### Good
+### Example: 自定义组件命名
+
+#### Good: 使用大驼峰且至少两个单词
 
 ```vue
 <!-- UserInfo.vue -->
@@ -22,7 +24,7 @@ export default {
 </script>
 ```
 
-### Bad
+#### Bad: 使用全小写或单词不足
 
 ```vue
 <!-- userinfo.vue -->

references/vue.file-name.md

@@ -4,7 +4,9 @@
 
 ## Vue 组件文件使用大驼峰命名 `[Vue.FileName.UpperCamel]`
 
-### Good
+### Example: Vue 组件文件命名
+
+#### Good: 使用大驼峰命名
 
 ```vue
 <!-- UserInfo.vue -->
@@ -20,7 +22,7 @@ export default {
 </script>
 ```
 
-### Bad
+#### Bad: 使用全小写命名
 
 ```vue
 <!-- userinfo.vue -->