# 删除规范

## 概述

项目统一使用软删除机制，通过 `is_delete` 字段标记记录状态，不物理删除数据。删除操作分为单条删除和批量删除两种方式。

:::tip 软删除约定
- `is_delete = 0`：正常记录（默认值）
- `is_delete = 1`：已删除记录
- 所有查询方法自动过滤 `is_delete = 0`，业务层无需关心
:::

## 单条删除

### URL 格式

```
DELETE /api/v1/{module}/delete/{id}
```

### Router 示例

```python
@position_blue.route('/delete/<int:id>', methods=['DELETE'])
@check_permission('sys:position:delete')
def delete(id):
    """根据ID删除单个岗位"""
    from src.modules.system.position.service import delete_position
    return delete_position(id)
```

:::tip 装饰器顺序
删除接口的装饰器顺序：`@position_blue.route` → `@check_permission`
:::

## 批量删除

### 请求格式

```
DELETE /api/v1/{module}/batchDelete
Content-Type: application/json

[1, 2, 3]
```

### Router 示例

```python
@position_blue.route('/batchDelete', methods=['DELETE'])
@check_permission('sys:position:batchDelete')
def batch_delete():
    """批量删除岗位"""
    from src.modules.system.position.service import batch_delete_positions
    id_list = parse_id_list(request)
    return batch_delete_positions(id_list)
```

## 删除流程

```
1. Router 接收请求
 ↓
2. parse_id_list(request) 解析 ID 数组
 ↓
3. Service.batch_delete(id_list)
 ↓
4. before_delete(ids) 钩子校验
 ↓（拦截则返回 R.failed）
5. repository.batch_delete(ids) 软删除
 ↓
6. 返回 R.ok(msg="本次共删除N条数据")
```

## Repository 层实现

```python
def batch_delete(self, id_list) -> int:
    """按ID软删除，返回实际删除条数"""
    if not id_list:
        return 0

    records = cls.model.query.filter(
        cls.model.id.in_(id_list),
        cls.model.is_delete == 0
    ).all()

    for record in records:
        record.is_delete = 1

    return len(records)
```

:::tip 返回值说明
`batch_delete` 返回实际软删除的条数。如果传入的 ID 中包含已删除或不存在的记录，返回值会小于入参数量。
:::

## 权限标识

| 操作 | 权限标识 | 说明 |
|------|---------|------|
| 单条删除 | `sys:{module}:delete` | 删除单条记录 |
| 批量删除 | `sys:{module}:batchDelete` | 批量删除记录 |

## 常见错误提示

| 提示 | 原因 |
|------|------|
| "记录ID不存在" | 入参为空或格式错误 |
| "记录不存在" | 部分或全部 ID 对应的记录已删除/不存在 |
| "存在用户引用该岗位" | before_delete 钩子拦截 |

## 总结

删除规范统一使用软删除（`is_delete` 标记），支持单条删除和批量删除（JSON 数组）。Repository 层做数据原语，Service 层统一封装响应。自定义 Service 通过 `before_delete` 钩子添加业务校验。