# 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 层处理。