116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# 删除规范
|
||
|
||
## 概述
|
||
|
||
项目统一使用软删除机制，通过 `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 delete_positions
|
||
id_list = parse_batch_ids(request)
|
||
return delete_positions(id_list)
|
||
```
|
||
|
||
## 删除流程
|
||
|
||
```
|
||
1. Router 接收请求
|
||
↓
|
||
2. parse_batch_ids(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` 钩子添加业务校验。
|