docs: 统一规范文档示例格式,使用三级标题 Example 和四级标题 Good/Bad 展示代码示例

README.md

@@ -121,6 +121,6 @@
 - 一级标题：规范名称 + 规则前缀（如 ``[JsTs.Base]``）
 - 二级标题：单条规则描述 + 完整规则 ID（如 ``[JsTs.Base.ConstUpperCase]``）
 - 元信息：`includes` / `override` / `severity`（如适用）
-- 示例：必须包含 `Good` 与 `Bad`
+- 示例：使用 `### Example:` 分组，`#### Good:` 展示推荐做法，`#### Bad:` 展示不推荐做法
 
 这样可以保证规则文档在人工阅读和自动化解析两种场景下都保持一致性。

references/js&ts.base.md

@@ -7,13 +7,15 @@
 - 不检查 nodejs 的导包定义，比如 `const fs = require("fs")`
 - 常量检查只需检查 `const` 声明的静态值，但是不包含对象和函数
 
-### Good
+### Example: 常量命名
+
+#### Good: 使用大写加下划线
 
 ```javascript
 const MAX_COUNT = 100;
 ```
 
-### Bad
+#### Bad: 使用小驼峰
 
 ```javascript
 const maxCount = 100;
@@ -23,7 +25,9 @@ const maxCount = 100;
 
 > - severity `warn`
 
-### Good
+### Example: 函数命名
+
+#### Good: 使用小驼峰
 
 ```javascript
 function getUserInfo() {
@@ -31,7 +35,7 @@ function getUserInfo() {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写
 
 ```javascript
 function getuserinfo() {
@@ -57,7 +61,9 @@ function getuserinfo() {
 - 无需考虑类型是否合理匹配
 - 你需要自行的判断这个字面量的值开发是否可以理解，比如说参数的时间戳、毫秒时长、数量等这些如果一看就是可以理解也无需抽出常量
 
-### Good
+### Example: 魔法数字
+
+#### Good: 使用常量替代魔法数字
 
 ```javascript
 const ADMIN = 1;
@@ -67,7 +73,7 @@ if (user.role === ADMIN) {
 }
 ```
 
-### Bad
+#### Bad: 使用字面量魔法数字
 
 ```javascript
 if (user.role === 1) {
@@ -82,14 +88,16 @@ if (user.role === 1) {
 - 需要放在指定模块的 constants 文件里
 - constants 命名规则: user.constants.js 或者 constants.js 或者 user.constants.ts 或者 constants.ts
 
-### Good
+### Example: 常量定义位置
+
+#### Good: 常量放在对应模块的 constants 文件
 
 ```javascript
 // user.constants.js
 const MAX_COUNT = 100; // 这是 user 模块需要的
 ```
 
-### Bad
+#### Bad: 常量放在错误模块的 constants 文件
 
 ```javascript
 // class.constants.js
@@ -100,7 +108,9 @@ const MAX_COUNT = 100; // 这是 user 模块需要的
 
 > - severity `warn`
 
-### Good
+### Example: 类和接口命名
+
+#### Good: 使用大驼峰
 
 ```javascript
 class UserInfo {
@@ -108,7 +118,7 @@ class UserInfo {
 }
 ```
 
-### Bad
+#### Bad: 使用全小写
 
 ```javascript
 class userinfo {
@@ -122,14 +132,16 @@ class userinfo {
 
 - 需要注意的是从 require 导入的变量不受检查
 
-### Good
+### Example: 变量命名
+
+#### Good: 使用小驼峰或蛇形命名
 
 ```javascript
 let userName = "John";
 let user_name = "John";
 ```
 
-### Bad
+#### Bad: 使用大驼峰
 
 ```javascript
 let Username = "John";
@@ -137,13 +149,15 @@ let Username = "John";
 
 ## 单文件代码不超过 700 行 `[JsTs.Base.CodeNotMoreThan700Lines]`
 
-### Good
+### Example: 文件行数
+
+#### Good: 代码不超过 700 行
 
 ```javascript
 // 代码不超过 700 行
 ```
 
-### Bad
+#### Bad: 代码超过 700 行
 
 ```javascript
 // 代码超过 700 行
@@ -151,7 +165,9 @@ let Username = "John";
 
 ## 单个函数或方法不能超出 200 行 `[JsTs.Base.FuncNotMoreThan200Lines]`
 
-### Good
+### Example: 函数行数
+
+#### Good: 函数不超过 200 行
 
 ```javascript
 function getUserInfo() {
@@ -159,7 +175,7 @@ function getUserInfo() {
 }
 ```
 
-### Bad
+#### Bad: 函数超过 200 行
 
 ```javascript
 function getUserInfo() {
@@ -173,7 +189,9 @@ function getUserInfo() {
 
 - 逻辑判断的复杂度超过 2 个的要添加注释
 
-### Good
+### Example: 复杂逻辑注释
+
+#### Good: 复杂逻辑添加注释
 
 ```javascript
 // 逻辑判断复杂度超过 2 个
@@ -182,7 +200,7 @@ if (a && b || c) {
 }
 ```
 
-### Bad
+#### Bad: 复杂逻辑未添加注释
 
 ```javascript
 if (a && b && c && d) {
@@ -194,7 +212,9 @@ if (a && b && c && d) {
 
 > - severity `warn`
 
-### Good
+### Example: 复杂函数注释
+
+#### Good: 复杂函数添加注释
 
 ```javascript
 /**
@@ -205,7 +225,7 @@ function complexFunc() {
 }
 ```
 
-### Bad
+#### Bad: 复杂函数未添加注释
 
 ```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 -->