签入版本

DjangoAdmin_FastAPI_NaiveVue/zh/volume2/repository.md

@@ -0,0 +1,95 @@
+# Repository 层
+
+Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。
+
+## 文件位置
+
+```
+src/modules/system/position/repository.py
+```
+
+## 完整代码
+
+```python
+from modules.system.position.models import Position
+from core.base_repository import BaseRepository
+
+
+# ============================================================
+# 岗位仓库类
+# ============================================================
+class PositionRepository(BaseRepository[Position]):
+    """岗位数据仓库，继承基础仓库获得通用 CRUD 能力"""
+    pass
+
+
+# ============================================================
+# 仓库实例
+# ============================================================
+position_repo = PositionRepository(Position)
+```
+
+## 代码解析
+
+### 基类继承
+
+```python
+class PositionRepository(BaseRepository[Position]):
+```
+
+`BaseRepository[Position]` 是泛型基类，传入模型类型后自动获得以下能力：
+
+| 方法 | 说明 |
+|:----|:----|
+| `get_by_id(id)` | 根据 ID 查询单条（自动过滤软删除） |
+| `get_by_ids(ids)` | 根据 ID 列表查询多条 |
+| `get_one(**kwargs)` | 按等值条件查询单条（跳过 None 值） |
+| `get_all(**kwargs)` | 按等值条件查询全部（自动过滤软删除） |
+| `exists_by_field(field, value)` | 判断字段值是否存在 |
+| `count(**kwargs)` | 按条件计数 |
+| `filter(*criterion)` | 原始 SQLAlchemy 条件查询（不自动过滤软删除） |
+| `filter_by(**kwargs)` | 等值条件查询（自动过滤软删除，跳过 None） |
+| `create(**kwargs)` | 创建记录 |
+| `update(id, **kwargs)` | 更新记录 |
+| `paginate(page, limit)` | 分页查询 |
+| `batch_delete(ids)` | 批量软删除 |
+
+### 单例实例
+
+```python
+position_repo = PositionRepository(Position)
+```
+
+每个模块在文件末尾创建一个模块级单例 `xxx_repo`，业务代码通过导入此实例访问数据库，避免重复创建 Repository 对象。
+
+### 何时需要自定义方法
+
+大多数简单 CRUD 模块（如 Position、Level、Category）的 Repository 只需 `pass`。当需要以下场景时，才在子类中添加自定义方法：
+
+- **复杂联表查询**：如 User 需要关联 Dept、Role 查询
+- **特殊聚合查询**：如统计、分组
+- **非标准查询条件**：如区间查询、模糊 + 精确组合
+
+示例（UserRepository 中的自定义方法）：
+
+```python
+class UserRepository(BaseRepository[User]):
+    def get_by_username(self, username: str):
+        """根据用户名查询用户（含角色信息）"""
+        return self.filter(
+            User.username == username,
+            User.is_delete == 0
+        ).first()
+```
+
+## 开发要点
+
+1. **简单模块直接 `pass`**：继承基类即可获得完整 CRUD 能力
+2. **必须创建模块级单例**：`xxx_repo = XxxRepository(XModel)`，供 Service 层调用
+3. **`filter()` 不自动过滤软删除**：需要手动追加 `Model.is_delete == 0` 条件
+4. **`filter_by()` / `get_one()` / `get_all()` 自动过滤软删除**：且跳过 None 值，推荐优先使用
+5. **Repository 层不做响应封装**：返回 SQLAlchemy 查询结果，由 Service 层处理响应
+
+## 总结
+
+Repository 层继承 `BaseRepository` 获得通用 CRUD 能力，等值查询方法（`get_one`/`get_all`/`filter_by`）自动过滤软删除且跳过 None 值，`filter()` 为原始出口需手动追加软删除条件。Repository 层不做响应封装，由 Service 层处理。