签入版本

EasyGoAdmin_Beego_NaiveVue/zh/guide/model.md

@@ -0,0 +1,103 @@
+# 3.3 模型层开发
+
+:::tip 概述
+模型层负责定义数据库表的映射关系，继承 BaseModel 后自动获得软删除和审计字段能力。
+:::
+
+## 模型文件位置
+
+```text
+app/model/Example.php
+```
+
+## 完整代码（来自项目实际代码）
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace app\model;
+
+use app\BaseModel;
+
+/**
+ * 案例演示模型
+ *
+ * 对应数据表 example，继承 BaseModel 获得通用模型能力
+ * （软删除与审计字段自动写入）。
+ *
+ * 说明：本模型只有表映射，未定义关联或辅助方法；
+ * 案例演示的查询过滤、排序、唯一校验等均由 ExampleLogic 配置。
+ */
+class Example extends BaseModel
+{
+    /**
+     * 数据表名
+     *
+     * 显式指定表名，覆盖默认的类名推导规则。
+     * ThinkPHP 默认使用类名的小写下划线形式作为表名，
+     * Example → think_example。如果表名与类名不对应，
+     * 可通过 $name 属性显式指定。
+     *
+     * @var string
+     */
+    protected $name = 'example';
+}
+```
+
+## 继承 BaseModel 后获得的能力
+
+| 能力 | 说明 | 代码示例 |
+|------|------|----------|
+| 软删除 | 全局查询自动过滤 `is_delete=1` | `$list = Example::select();` 自动排除已删除 |
+| 软删除操作 | 设置 `is_delete=1` | `$model->softDelete();` |
+| 批量软删除 | 批量设置 `is_delete=1` | `Example::batchSoftDelete([1,2,3]);` |
+| 审计字段-创建 | 自动填充 `create_user` 和 `create_time` | `Example::create([...])` 时自动填充 |
+| 审计字段-更新 | 自动填充 `update_user` 和 `update_time` | `$model->save([...])` 时自动填充 |
+
+## 查询已删除数据
+
+```php
+// 查询单条（包括已删除）
+$example = Example::withoutGlobalScope(['soft_delete'])->find($id);
+
+// 查询所有（包括已删除）
+$all = Example::withoutGlobalScope(['soft_delete'])->select();
+```
+
+## 简单模型 vs 复杂模型
+
+:::tip 模型层职责
+模型层只负责表映射和关联关系，不包含业务逻辑。所有查询条件、排序、唯一性校验等都由 Logic 层配置。
+:::
+
+### 简单模型（如 Example）
+
+只需声明表名，所有逻辑由 Logic 层配置：
+
+```php
+class Example extends BaseModel
+{
+    protected $name = 'example';
+}
+```
+
+### 复杂模型（如 Role）
+
+包含关联关系：
+
+```php
+class Role extends BaseModel
+{
+    protected $name = 'role';
+
+    /**
+     * 关联菜单（多对多）
+     * 通过 role_menu 中间表关联
+     */
+    public function menus()
+    {
+        return $this->belongsToMany(Menu::class, 'role_menu', 'menu_id', 'role_id');
+    }
+}
+```