删除规范

概述

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

软删除约定

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

单条删除

URL 格式

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

Router 示例

@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)

装饰器顺序

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

批量删除

请求格式

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

[1, 2, 3]

Router 示例

@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 层实现

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)

返回值说明

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

权限标识

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

常见错误提示

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

总结

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