# Repository 层

Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。

## 文件位置

```
src/modules/position/repository.py
```

## 完整代码

```python
# +======================================================================
# | 模块: 岗位数据访问层
# | 说明: 定义岗位仓储，继承 BaseRepository 获得通用 CRUD 与软删除能力
# +======================================================================
"""岗位数据访问。"""

from core.base_repository import BaseRepository
from modules.position.models import Position


# ======================================================================
# 岗位仓储
# ======================================================================
class PositionRepository(BaseRepository):
    """岗位仓储。"""

    # ============================================================
    # 绑定的模型类
    # ============================================================
    model = Position
```

## 代码解析

### 基类继承

```python
class PositionRepository(BaseRepository(Position]):
```

`BaseRepository(Position]` 是泛型基类，传入模型类型后自动获得以下能力：

| 方法 | 说明 |
|:----|:----|
| `get_by_id(id)` | 根据 ID 查询单条（自动过滤软删除） |
| `get_by_ids(ids)` | 根据 ID 列表查询多条 |
| `get_one(**kwargs)` | 按等值条件查询单条（跳过 None 值） |
| `all()` | 按等值条件查询全部（自动过滤软删除） |
| `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)` | 批量软删除 |

### Service 层使用方式

Repository 不需要手动创建单例。Service 层通过 `repo_cls = PositionRepository` 声明关联的 Repository 类，`BaseService.__init__` 会自动实例化：

```python
# service.py 中的使用方式
class PositionService(BaseService):
    model = Position
    repo_cls = PositionRepository  # 传入类，基类自动实例化
```

### 何时需要自定义方法

大多数简单 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. **简单模块只需声明 `model`**：继承基类即可获得完整 CRUD 能力
2. **Service 层通过 `repo_cls` 关联 Repository 类**：基类自动实例化，无需手动创建单例
3. **`filter()` 不自动过滤软删除**：需要手动追加 `Model.is_delete == 0` 条件
4. **`filter_by()` / `get_one()` / `all()` 自动过滤软删除**：且跳过 None 值，推荐优先使用
5. **Repository 层不做响应封装**：返回 SQLAlchemy 查询结果，由 Service 层处理响应

## 总结

Repository 层继承 `BaseRepository` 获得通用 CRUD 能力，等值查询方法（`get_one`/`get_all`/`filter_by`）自动过滤软删除且跳过 None 值，`filter()` 为原始出口需手动追加软删除条件。Repository 层不做响应封装，由 Service 层处理。