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

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({