sdpy-kit 0.5.2__tar.gz → 0.5.3__tar.gz

{sdpy_kit-0.5.2 → sdpy_kit-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.5.2
+Version: 0.5.3
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT

{sdpy_kit-0.5.2 → sdpy_kit-0.5.3}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.5.2 → sdpy_kit-0.5.3}/kit/db/audit.py

@@ -65,8 +65,11 @@ UPDATE    不参与        空才填                   不参与
 """
 
 import threading
-from collections.abc import Callable, Mapping, MutableMapping
+from collections.abc import Callable, Generator, Mapping, MutableMapping
+from contextlib import contextmanager
+from contextvars import ContextVar
 from datetime import UTC, datetime
+from typing import Any, ClassVar
 
 from sqlalchemy import String, event, inspect as sa_inspect
 from sqlalchemy.exc import NoSuchTableError
@@ -78,24 +81,33 @@ from kit.db.engine import get_engine
 
 logger = get_default_logger(__name__)
 
-# 审计字段（与 kit/db/models/base.py::AuditMixin 命名一致）
-CREATED_AT = "created_at"
-CREATED_BY = "created_by"
-UPDATED_AT = "updated_at"
-UPDATED_BY = "updated_by"
+# 字段「槽位 → 默认列名」：槽位是内部语义键（也是默认列名），
+# 实际列名可用 AuditConfig.set_fields() 覆盖（如把 created_at 换成 create_time）
+CREATED_AT, CREATED_BY, UPDATED_AT, UPDATED_BY, DELETED = (
+    "created_at",
+    "created_by",
+    "updated_at",
+    "updated_by",
+    "deleted",
+)
+
+# 审计四件套槽位（created_at / created_by / updated_at / updated_by）
 AUDIT_FIELDS: tuple[str, ...] = (CREATED_AT, CREATED_BY, UPDATED_AT, UPDATED_BY)
 
-# 逻辑删除标记：0 正常 / 1 删除
-DELETED = "deleted"
-
-# 填充器实际关注的列（审计四件套 + 删除标记）
+# 填充器实际关注的槽位（审计四件套 + 删除标记）
 FILL_FIELDS: tuple[str, ...] = (*AUDIT_FIELDS, DELETED)
 
+# 槽位 → 默认列名（默认同名；set_fields 只覆盖发生变化的槽位）
+DEFAULT_FIELDS: dict[str, str] = {slot: slot for slot in FILL_FIELDS}
+
 # 列探测缓存：(db_type, 表名) -> {列名: SQLAlchemy 类型对象}
 # 仅缓存**探测成功**的结果；失败不缓存，表稍后创建可自愈
-_columns_cache: dict[tuple[str, str], dict[str, TypeEngine]] = {}
+_columns_cache: dict[tuple[str, str], dict[str, TypeEngine[Any]]] = {}
 _columns_lock = threading.Lock()
 
+# 「查已删除」上下文开关：进入 AuditConfig.include_deleted() 后临时关闭过滤
+_include_deleted: ContextVar[bool] = ContextVar("audit_include_deleted", default=False)
+
 
 def _default_clock() -> datetime:
     """默认时钟：UTC aware（与 models/base.py::_utcnow 同口径）"""
@@ -109,15 +121,38 @@ def _is_empty(value: object) -> bool:
     return isinstance(value, str) and not value.strip()
 
 
-def _deleted_default(column_type: TypeEngine) -> object:
-    """删除标记的正常值：字符串列（VARCHAR/CHAR/TEXT）填 "0"，整数列填 0
+def _is_string_type(column_type: TypeEngine[Any]) -> bool:
+    """是否为字符串列（兼容 SQLModel 的 ``AutoString`` 这类 ``TypeDecorator``）
+
+    三级判定（任一命中即视为字符串）：
+    1. ``isinstance(type, String)`` —— 原生 ``VARCHAR`` / ``CHAR`` / ``TEXT``；
+    2. ``python_type is str`` —— 多数类型装饰器；
+    3. ``impl`` 是 ``String`` 或其子类 —— SQLModel 的 ``AutoString``
+       （``TypeDecorator``，前两级都判定不到）。
+    """
+    if isinstance(column_type, String):
+        return True
+    try:
+        if column_type.python_type is str:
+            return True
+    except (AttributeError, NotImplementedError):
+        pass
+    impl = getattr(column_type, "impl", None)
+    if isinstance(impl, String):
+        return True
+    return isinstance(impl, type) and issubclass(impl, String)
+
+
+def normal_value(column_type: TypeEngine[Any]) -> object:
+    """删除标记的「正常」值：字符串列（VARCHAR/CHAR/TEXT）为 ``"0"``，整数列为 ``0``
 
+    写入填充与查询过滤共用同一个值，避免两侧口径不一致。
     字符串列写整数在 PostgreSQL（``character varying``）与 MySQL 严格模式下
     会直接报类型错误，故按列类型区分。
+
+    ⚠ 内部符号（不进 ``kit.db.__all__``）。
     """
-    if isinstance(column_type, String):
-        return "0"
-    return 0
+    return "0" if _is_string_type(column_type) else 0
 
 
 class AuditConfig:
@@ -127,11 +162,13 @@ class AuditConfig:
     不做运行期热切换承诺。模块导入零副作用。
     """
 
-    _lock = threading.RLock()
-    _enabled = False
-    _user_resolver: Callable[[], object] | None = None
-    _clock: Callable[[], datetime] = _default_clock
-    _listening = False
+    _lock: ClassVar[Any] = threading.RLock()
+    _enabled: ClassVar[bool] = False
+    _user_resolver: ClassVar[Callable[[], object] | None] = None
+    _clock: ClassVar[Callable[[], datetime]] = _default_clock
+    _fields: ClassVar[dict[str, str]] = dict(DEFAULT_FIELDS)
+    _soft_delete_filter: ClassVar[bool] = False
+    _listening: ClassVar[bool] = False
 
     @classmethod
     def enable(
@@ -139,6 +176,8 @@ class AuditConfig:
         *,
         user_resolver: Callable[[], object] | None = None,
         clock: Callable[[], datetime] | None = None,
+        fields: Mapping[str, str] | None = None,
+        soft_delete_filter: bool | None = None,
     ) -> None:
         """启用自动填充（幂等）
 
@@ -147,22 +186,112 @@ class AuditConfig:
                 返回 None / 空串时跳过 ``*_by`` 填充；抛异常时记 warning 并跳过，
                 不影响写入。
             clock: 取时间钩子，默认 ``datetime.now(UTC)``（测试可注入冻结时钟）。
+            fields: 自定义字段名（槽位 → 实际列名），只给需要改的项，如
+                ``{"created_at": "create_time", "deleted": "del_flag"}``；
+                透传给 :meth:`set_fields`。
+            soft_delete_filter: 是否让查询方法自动追加「deleted = 正常值」条件
+                （None = 保持当前设置；默认关闭）。
 
         Note:
             事件监听挂在父类 :class:`sqlalchemy.orm.Session` 上，因此
             ``session_scope`` 新建的 Session 与应用自建的原生 Session 都会触发。
         """
         with cls._lock:
+            if fields is not None:
+                cls.set_fields(fields)
+            if soft_delete_filter is not None:
+                cls._soft_delete_filter = soft_delete_filter
+            # ClassVar 上的 Callable 赋值：pyright 会误判为方法绑定，运行时正确
             if user_resolver is not None:
-                cls._user_resolver = user_resolver
+                cls._user_resolver = user_resolver  # pyright: ignore[reportAttributeAccessIssue]
             if clock is not None:
-                cls._clock = clock
+                cls._clock = clock  # pyright: ignore[reportAttributeAccessIssue]
             if not cls._listening:
                 event.listen(Session, "before_flush", _on_before_flush)
                 cls._listening = True
             cls._enabled = True
         logger.info("✅ 审计字段与删除标记自动填充已启用")
 
+    @classmethod
+    def fields(cls) -> dict[str, str]:
+        """当前「槽位 → 实际列名」映射（副本，可安全修改）"""
+        return dict(cls._fields)
+
+    @classmethod
+    def set_fields(cls, fields: Mapping[str, str] | None = None) -> None:
+        """配置字段名（不传 / 传 None 恢复默认）
+
+        Args:
+            fields: 槽位 → 实际列名，只给需要改的槽位。可用槽位：
+                ``created_at`` / ``created_by`` / ``updated_at`` / ``updated_by`` /
+                ``deleted``
+
+        Raises:
+            ValueError: 出现未知槽位（防手误，例如把 ``created_at`` 写成 ``create_at``）
+
+        用法::
+
+            AuditConfig.set_fields(
+                {"created_at": "create_time", "deleted": "del_flag"}
+            )
+        """
+        merged = dict(DEFAULT_FIELDS)
+        if fields:
+            unknown = set(fields) - set(DEFAULT_FIELDS)
+            if unknown:
+                raise ValueError(
+                    f"未知的字段槽位: {sorted(unknown)}；"
+                    f"可用槽位: {sorted(DEFAULT_FIELDS)}"
+                )
+            merged.update(fields)
+        with cls._lock:
+            cls._fields = merged
+
+    @classmethod
+    def set_soft_delete_filter(cls, enabled: bool) -> None:
+        """开关「查询自动过滤软删除记录」（默认关闭）
+
+        Args:
+            enabled: True 时，kit 的查询方法对**有 deleted 列的表/模型**追加
+                ``deleted = 正常值`` 条件（整数字段为 ``0``，字符串字段为 ``"0"``）。
+
+        Note:
+            - 只影响**查询**：`CRUDBase` 的 get / get_or_raise / get_multi /
+              get_by_field / get_multi_by_field / count / exists，以及 `raw_get_by`；
+            - 写方法（create / update / update_multi / delete / upsert / raw_*）
+              不追加该条件；
+            - `query()` 手写 SQL **不处理**（与 `execute()` 同一条原则）；
+            - 需要读取已删除记录时用 :meth:`include_deleted` 上下文。
+        """
+        with cls._lock:
+            cls._soft_delete_filter = enabled
+        logger.info(f"🔎 软删除查询过滤已{'开启' if enabled else '关闭'}")
+
+    @classmethod
+    def filter_deleted(cls) -> bool:
+        """当前查询是否应追加「deleted = 正常值」条件
+
+        综合两件事：过滤开关已开启，且当前不在 :meth:`include_deleted` 上下文中。
+        """
+        return cls._soft_delete_filter and not _include_deleted.get()
+
+    @classmethod
+    @contextmanager
+    def include_deleted(cls) -> Generator[None, None, None]:
+        """临时查询已删除记录的上下文（仅本上下文内关闭过滤）
+
+        用法::
+
+            with AuditConfig.include_deleted():
+                rows = PgKit.query(...)      # 手写 SQL 本就不受过滤影响
+                obj = PgKit.get(Model, 1)    # 能查到 deleted=1 的记录
+        """
+        token = _include_deleted.set(True)
+        try:
+            yield
+        finally:
+            _include_deleted.reset(token)
+
     @classmethod
     def disable(cls) -> None:
         """关闭自动填充（保留 user_resolver / clock 配置，再次 enable 可沿用）"""
@@ -182,7 +311,7 @@ class AuditConfig:
     def now(cls) -> datetime:
         """当前时间（UTC aware；clock 异常时记 warning 并回退 UTC now）"""
         try:
-            return cls._clock()
+            return cls._clock()  # pyright: ignore[reportAttributeAccessIssue]
         except Exception as e:
             logger.warning(f"⚠️ 审计时钟调用失败，回退 UTC now: {e}")
             return datetime.now(UTC)
@@ -190,7 +319,7 @@ class AuditConfig:
     @classmethod
     def current_user(cls) -> object | None:
         """当前操作人（resolver 未注册或异常时返回 None）"""
-        resolver = cls._user_resolver
+        resolver = cls._user_resolver  # pyright: ignore[reportAttributeAccessIssue]
         if resolver is None:
             return None
         try:
@@ -218,7 +347,7 @@ class AuditConfig:
 # ==================== 列探测（原生路径） ====================
 
 
-def table_columns(db_type: str, table_name: str) -> dict[str, TypeEngine]:
+def table_columns(db_type: str, table_name: str) -> dict[str, TypeEngine[Any]]:
     """表「列名 → SQLAlchemy 类型对象」映射（仅缓存探测成功的结果）
 
     Args:
@@ -254,12 +383,40 @@ def table_columns(db_type: str, table_name: str) -> dict[str, TypeEngine]:
     return columns
 
 
+def deleted_predicate(
+    db_type: str, table_name: str
+) -> tuple[str, dict[str, object]] | None:
+    """软删除过滤条件（SQL 片段 + 绑定参数）；不适用时返回 None
+
+    适用条件：过滤开关已开启、当前不在 :meth:`AuditConfig.include_deleted` 上下文、
+    表中存在 deleted 列。
+
+    Returns:
+        ``("deleted = :_audit_deleted", {"_audit_deleted": 0})``；字符串列的值是
+        ``"0"``。条件不适用时返回 None（调用方据此不加条件）。
+
+    Note:
+        严格等值，不对 ``NULL`` 做特殊处理——本工具类只提供底层约定，
+        不为业务历史数据兜底。
+
+    ⚠ 内部符号：只供 kit 自建 SQL 的**查询**方法（如 ``raw_get_by``）使用，
+    写方法不得调用。
+    """
+    if not AuditConfig.filter_deleted():
+        return None
+    name = AuditConfig.fields()[DELETED]
+    columns = table_columns(db_type, table_name)
+    if name not in columns:
+        return None
+    return f"{name} = :_audit_deleted", {"_audit_deleted": normal_value(columns[name])}
+
+
 # ==================== dict 路径填充（Core DML / 原生构建器） ====================
 
 
 def _put(
     data: MutableMapping[str, object],
-    columns: Mapping[str, TypeEngine],
+    columns: Mapping[str, TypeEngine[Any]],
     name: str,
     value: object,
 ) -> None:
@@ -271,7 +428,9 @@ def _put(
     data[name] = value
 
 
-def fill_insert(data: MutableMapping[str, object], columns: Mapping[str, TypeEngine]) -> None:
+def fill_insert(
+    data: MutableMapping[str, object], columns: Mapping[str, TypeEngine[Any]]
+) -> None:
     """INSERT 半区：created_* 与 updated_* 同值填补，deleted 补正常值
 
     Args:
@@ -282,15 +441,19 @@ def fill_insert(data: MutableMapping[str, object], columns: Mapping[str, TypeEng
         return
     now = AuditConfig.now()
     user = AuditConfig.current_user()
-    _put(data, columns, CREATED_AT, now)
-    _put(data, columns, UPDATED_AT, now)
-    _put(data, columns, CREATED_BY, user)
-    _put(data, columns, UPDATED_BY, user)
-    if DELETED in columns:
-        _put(data, columns, DELETED, _deleted_default(columns[DELETED]))
-
-
-def fill_update(data: MutableMapping[str, object], columns: Mapping[str, TypeEngine]) -> None:
+    names = AuditConfig._fields
+    _put(data, columns, names[CREATED_AT], now)
+    _put(data, columns, names[UPDATED_AT], now)
+    _put(data, columns, names[CREATED_BY], user)
+    _put(data, columns, names[UPDATED_BY], user)
+    deleted_col = names[DELETED]
+    if deleted_col in columns:
+        _put(data, columns, deleted_col, normal_value(columns[deleted_col]))
+
+
+def fill_update(
+    data: MutableMapping[str, object], columns: Mapping[str, TypeEngine[Any]]
+) -> None:
     """UPDATE 半区：只动 updated_*（不碰 created_*，也不碰 deleted）
 
     Args:
@@ -301,8 +464,9 @@ def fill_update(data: MutableMapping[str, object], columns: Mapping[str, TypeEng
         return
     now = AuditConfig.now()
     user = AuditConfig.current_user()
-    _put(data, columns, UPDATED_AT, now)
-    _put(data, columns, UPDATED_BY, user)
+    names = AuditConfig._fields
+    _put(data, columns, names[UPDATED_AT], now)
+    _put(data, columns, names[UPDATED_BY], user)
 
 
 def fill_insert_for(
@@ -326,7 +490,7 @@ def fill_update_for(
 # ==================== ORM 路径填充（before_flush） ====================
 
 
-def _object_columns(obj: object) -> dict[str, TypeEngine]:
+def _object_columns(obj: object) -> dict[str, TypeEngine[Any]]:
     """对象映射到的「表列名 → 类型对象」（无 ``__table__`` 时返回空字典）"""
     table = getattr(obj, "__table__", None)
     if table is None:
@@ -339,15 +503,24 @@ def _fill_obj(
 ) -> None:
     """按矩阵填充单个 ORM 对象（列不存在 / 已有非空值 → 跳过）"""
     columns = _object_columns(obj)
+    names = AuditConfig._fields
     pairs: list[tuple[str, object]] = (
-        [(CREATED_AT, now), (UPDATED_AT, now), (CREATED_BY, user), (UPDATED_BY, user)]
+        [
+            (names[CREATED_AT], now),
+            (names[UPDATED_AT], now),
+            (names[CREATED_BY], user),
+            (names[UPDATED_BY], user),
+        ]
         if insert
-        else [(UPDATED_AT, now), (UPDATED_BY, user)]
+        else [(names[UPDATED_AT], now), (names[UPDATED_BY], user)]
     )
-    if insert and DELETED in columns:
-        pairs.append((DELETED, _deleted_default(columns[DELETED])))
+    deleted_col = names[DELETED]
+    if insert and deleted_col in columns:
+        pairs.append((deleted_col, normal_value(columns[deleted_col])))
 
     state = sa_inspect(obj)
+    if state is None:  # 理论上实例一定有状态，防御性判断
+        return
     for name, value in pairs:
         if name not in columns or _is_empty(value) or not hasattr(obj, name):
             continue

{sdpy_kit-0.5.2 → sdpy_kit-0.5.3}/kit/db/base_db_kit.py

@@ -56,7 +56,7 @@ from sqlmodel import Session, SQLModel
 
 from kit.common_kit import CommonKit
 from kit.config.log_config import get_default_logger
-from kit.db.audit import fill_insert_for, fill_update_for
+from kit.db.audit import deleted_predicate, fill_insert_for, fill_update_for
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
     close_engine,
@@ -914,10 +914,22 @@ class BaseDbKit(ABC):
 
         Returns:
             匹配的第一行（字典）；无匹配返回 None
+
+        Note:
+            开启软删除查询过滤（`AuditConfig.set_soft_delete_filter(True)`）后，
+            若表存在 deleted 列，会自动追加 ``deleted = 正常值`` 条件；
+            需读取已删除行时用 ``with AuditConfig.include_deleted():`` 包裹。
         """
+        where = f"{column} = :value"
+        params: dict[str, object] = {"value": value}
+        predicate = deleted_predicate(cls.DB_TYPE, table_name)
+        if predicate is not None:
+            fragment, extra = predicate
+            where = f"{where} AND {fragment}"
+            params.update(extra)
+
         rows = cls.query(
-            f"SELECT * FROM {table_name} WHERE {column} = :value LIMIT 1",
-            {"value": value},
+            f"SELECT * FROM {table_name} WHERE {where} LIMIT 1", params
         )
         return rows[0] if rows else None
 

{sdpy_kit-0.5.2 → sdpy_kit-0.5.3}/kit/db/crud.py

@@ -41,7 +41,15 @@ from sqlmodel import Session, SQLModel, select
 from sqlmodel.sql._expression_select_cls import SelectOfScalar
 
 from kit.config.log_config import get_default_logger
-from kit.db.audit import CREATED_AT, CREATED_BY, fill_insert, fill_update
+from kit.db.audit import (
+    CREATED_AT,
+    CREATED_BY,
+    DELETED,
+    AuditConfig,
+    fill_insert,
+    fill_update,
+    normal_value,
+)
 from kit.db.exceptions import DBError, NotFoundError
 
 logger = get_default_logger(__name__)
@@ -69,9 +77,37 @@ class CRUDBase[
     def __init__(self, model: type[ModelType]):
         self.model = model
 
-    def _select_all(self) -> SelectOfScalar[ModelType]:
-        """返回 sqlmodel.select 的标量查询（SQLModel 类型桥接）"""
-        return cast(SelectOfScalar[ModelType], select(self.model))
+    def _select_all(self, *, include_deleted: bool = False) -> SelectOfScalar[ModelType]:
+        """返回 sqlmodel.select 的标量查询（SQLModel 类型桥接）
+
+        Args:
+            include_deleted: 是否跳过软删除过滤（默认 False；仅过滤开关开启时有效）
+        """
+        statement = cast(SelectOfScalar[ModelType], select(self.model))
+        condition = self._deleted_condition(include_deleted=include_deleted)
+        return statement.where(condition) if condition is not None else statement
+
+    def _deleted_condition(self, *, include_deleted: bool = False) -> Any:
+        """软删除过滤条件（过滤关闭 / 模型无 deleted 列时返回 None）
+
+        严格等值：``deleted = 正常值``（整数列 ``0``、字符串列 ``"0"``）。
+        ``NULL`` 不视为未删除——本工具类只做底层约定，不为业务历史数据兜底。
+        """
+        if include_deleted or not AuditConfig.filter_deleted():
+            return None
+        column = getattr(self.model, AuditConfig.fields()[DELETED], None)
+        if column is None:
+            return None
+        return column == normal_value(column.type)
+
+    def _is_visible(self, obj: ModelType) -> bool:
+        """对象是否未被软删除（过滤关闭 / 模型无该字段时恒为 True）"""
+        if not AuditConfig.filter_deleted():
+            return True
+        column = getattr(self.model, AuditConfig.fields()[DELETED], None)
+        if column is None:
+            return True
+        return getattr(obj, column.key, None) == normal_value(column.type)
 
     def _id_col(self) -> Column[Any]:
         """约定的主键列（避免 SQLModel 泛型无 id 字段的类型缺陷）"""
@@ -81,7 +117,7 @@ class CRUDBase[
         """模型对应的 Table（避免 SQLModel 泛型无 __table__ 的类型缺陷）"""
         return cast(Table, getattr(self.model, "__table__"))
 
-    def _column_names(self) -> dict[str, TypeEngine]:
+    def _column_names(self) -> dict[str, TypeEngine[Any]]:
         """模型映射表的「列名 → SQLAlchemy 类型对象」（读元数据，零 DB 查询）
 
         供审计字段自动填充判断「表中是否存在该列」，以及 ``deleted`` 的取值类型。
@@ -91,17 +127,20 @@ class CRUDBase[
     # ==================== 查询方法 ====================
 
     def get(self, session: Session, id: Any) -> ModelType | None:
-        """根据主键获取单条记录"""
+        """根据主键获取单条记录（开启软删除过滤时隐藏已删除记录）"""
         obj = session.get(self.model, id)
+        if obj is not None and not self._is_visible(obj):
+            logger.info(f"🔍 查询 {self.model.__name__} id={id} → 已软删除（过滤隐藏）")
+            return None
         logger.info(
             f"🔍 查询 {self.model.__name__} id={id} → {'命中' if obj else '未找到'}"
         )
         return obj
 
     def get_or_raise(self, session: Session, id: Any) -> ModelType:
-        """根据主键获取记录，不存在时抛出 NotFoundError"""
+        """根据主键获取记录，不存在（或已软删除）时抛出 NotFoundError"""
         obj = session.get(self.model, id)
-        if obj is None:
+        if obj is None or not self._is_visible(obj):
             logger.warning(
                 f"❌ {self.model.__name__} id={id} 不存在，抛出 NotFoundError"
             )
@@ -271,19 +310,24 @@ class CRUDBase[
     # ==================== 聚合查询 ====================
 
     def count(self, session: Session) -> int:
-        """获取记录总数"""
-        total = session.exec(select(func.count()).select_from(self.model)).one()
+        """获取记录总数（开启软删除过滤时不计已删除记录）"""
+        statement = select(func.count()).select_from(self.model)
+        condition = self._deleted_condition()
+        if condition is not None:
+            statement = statement.where(condition)
+        total = session.exec(statement).one()
         logger.info(f"🔍 统计 {self.model.__name__} 记录总数 → {total}")
         return total
 
     def exists(self, session: Session, id: Any) -> bool:
         """检查记录是否存在（仅查询主键列，不载入整对象）"""
         id_col = self._id_col()
+        statement = select(id_col).where(id_col == id)
+        condition = self._deleted_condition()
+        if condition is not None:
+            statement = statement.where(condition)
         found = (
-            session.exec(
-                cast(SelectOfScalar[object], select(id_col).where(id_col == id))
-            ).first()
-            is not None
+            session.exec(cast(SelectOfScalar[object], statement)).first() is not None
         )
         logger.info(
             f"🔍 检查 {self.model.__name__} id={id} 是否存在 → "
@@ -317,16 +361,18 @@ class CRUDBase[
             raise DBError("upsert 必须提供 conflict_fields")
 
         columns = self._column_names()
+        names = AuditConfig.fields()
 
         # 更新集：排除冲突字段、主键，以及**只在 INSERT 填充**的 created_*
         # （若把 created_* 带进 set_，每次冲突更新都会把创建时间刷成 now）
+        insert_only = (names[CREATED_AT], names[CREATED_BY])
         pk_cols = {c.name for c in self._table().primary_key.columns}
         update_cols = {
             k: v
             for k, v in data.items()
             if k not in conflict_fields
             and k not in pk_cols
-            and k not in (CREATED_AT, CREATED_BY)
+            and k not in insert_only
         }
         if not update_cols:
             # 无更新字段时退化为空更新（保持合法 SQL）
@@ -359,12 +405,13 @@ class CRUDBase[
         else:
             raise DBError(f"不支持的数据库类型: {dialect}")
 
-        # 按冲突字段回查返回实例（populate_existing 强制刷新，避免身份映射返回旧值）
+        # 按冲突字段回查返回实例（populate_existing 强制刷新，避免身份映射返回旧值）；
+        # 回查**必须跳过软删除过滤**：冲突行可能已被软删除，否则会误报回查失败
         conditions = [
             getattr(self.model, field) == data.get(field) for field in conflict_fields
         ]
         re_stmt = (
-            self._select_all()
+            self._select_all(include_deleted=True)
             .where(*conditions)
             .execution_options(populate_existing=True)
         )