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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.5.1
+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.1 → sdpy_kit-0.5.3}/kit/__init__.py

@@ -23,12 +23,13 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 from kit.db import (
     MYSQL,
     POSTGRESQL,
     SQLITE,
+    AuditConfig,
     CRUDBase,
     DEFAULT_DISTANCE_TYPE,
     DBError,
@@ -84,6 +85,8 @@ __all__ = [
     "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
+    # 审计字段与删除标记的自动填充（默认关闭，enable 后生效）
+    "AuditConfig",
     # 事务
     "transactional",
     # 原生 SQL 语句构造（公共）

{sdpy_kit-0.5.1 → sdpy_kit-0.5.3}/kit/db/__init__.py

@@ -29,6 +29,7 @@ Author: Clark Chang
 - SQLModel 混入类（models/base.py）
 """
 
+from kit.db.audit import AuditConfig
 from kit.db.base_db_kit import (
     DEFAULT_DISTANCE_TYPE,
     generate_snowflake_ids,
@@ -86,6 +87,8 @@ __all__ = [
     "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
+    # 审计字段与删除标记的自动填充（默认关闭，enable 后生效）
+    "AuditConfig",
     # 事务
     "transactional",
     # 原生 SQL 语句构造（公共）

sdpy_kit-0.5.3/kit/db/audit.py

@@ -0,0 +1,555 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-10-20
+"""审计字段与删除标记的自动填充（仿 MyBatis-Plus MetaObjectHandler）
+
+填充字段（固定，不做别名映射）：
+
+- ``created_at`` / ``created_by`` / ``updated_at`` / ``updated_by``（审计四件套）
+- ``deleted``（逻辑删除标记：``0`` 正常 / ``1`` 删除）
+
+判定规则（唯一）：**表中存在该列** 且 **本次写入数据中该字段为空** → 填充。
+"空" 指 ``None`` / 空串 / 纯空白串（``0`` 与 ``False`` 不算空）。
+调用方显式给了非空值一律保留，**不存在覆盖语义**。
+
+填充矩阵：
+
+========  ============  ======================  ==========
+动作      created_*     updated_*               deleted
+========  ============  ======================  ==========
+INSERT    空才填        空才填（与 created_* 同值）  空才填 0
+UPDATE    不参与        空才填                   不参与
+========  ============  ======================  ==========
+
+"当前值" 指**本次写入的数据**，不是数据库已存值：
+
+- dict 路径（``raw_insert`` / ``raw_update`` / ``CRUDBase.update_multi`` / ``upsert``）：
+  看 ``data`` 中该键的值；
+- ORM 路径（``before_flush``）：看本次 flush 是否显式给该属性赋值（属性变更历史）。
+
+因此业务没传 ``updated_at`` 时，每次更新都会刷新它。
+
+三条落点：
+
+1. ORM flush（``session.add`` / 属性修改 + flush）→ ``before_flush`` 事件；
+2. Core DML（``CRUDBase.update_multi`` / ``upsert``）→ 方法内填 dict；
+3. 原生构建器（``raw_insert`` / ``raw_update``）→ 构建 SQL 前填 dict。
+
+``execute()`` 手写 SQL 与批量 executemany **不填充**（不做 SQL 文本改写）。
+
+默认不启用：未调用 :meth:`AuditConfig.enable` 时，kit 所有写入口行为与本模块
+引入前完全一致（含 ``raw_insert`` 的 SQL 文本）。
+
+用法::
+
+    from kit.db import AuditConfig
+
+    AuditConfig.enable(user_resolver=get_current_userid)  # 应用启动时调用一次
+"""
+
+import threading
+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
+from sqlalchemy.orm import Session
+from sqlalchemy.types import TypeEngine
+
+from kit.config.log_config import get_default_logger
+from kit.db.engine import get_engine
+
+logger = get_default_logger(__name__)
+
+# 字段「槽位 → 默认列名」：槽位是内部语义键（也是默认列名），
+# 实际列名可用 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)
+
+# 填充器实际关注的槽位（审计四件套 + 删除标记）
+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[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 同口径）"""
+    return datetime.now(UTC)
+
+
+def _is_empty(value: object) -> bool:
+    """是否为「空」：None / 空串 / 纯空白串（0 与 False 不算空）"""
+    if value is None:
+        return True
+    return isinstance(value, str) and not value.strip()
+
+
+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__``）。
+    """
+    return "0" if _is_string_type(column_type) else 0
+
+
+class AuditConfig:
+    """审计字段自动填充的进程级配置（默认关闭）
+
+    进程级类属性 + 线程锁；``enable`` / ``disable`` 属启动期一次性调用，
+    不做运行期热切换承诺。模块导入零副作用。
+    """
+
+    _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(
+        cls,
+        *,
+        user_resolver: Callable[[], object] | None = None,
+        clock: Callable[[], datetime] | None = None,
+        fields: Mapping[str, str] | None = None,
+        soft_delete_filter: bool | None = None,
+    ) -> None:
+        """启用自动填充（幂等）
+
+        Args:
+            user_resolver: 返回当前操作人的钩子（str 或 int，与列类型一致）。
+                返回 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  # pyright: ignore[reportAttributeAccessIssue]
+            if clock is not None:
+                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 可沿用）"""
+        with cls._lock:
+            cls._enabled = False
+            if cls._listening:
+                event.remove(Session, "before_flush", _on_before_flush)
+                cls._listening = False
+        logger.info("🔌 审计字段与删除标记自动填充已关闭")
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """当前是否启用"""
+        return cls._enabled
+
+    @classmethod
+    def now(cls) -> datetime:
+        """当前时间（UTC aware；clock 异常时记 warning 并回退 UTC now）"""
+        try:
+            return cls._clock()  # pyright: ignore[reportAttributeAccessIssue]
+        except Exception as e:
+            logger.warning(f"⚠️ 审计时钟调用失败，回退 UTC now: {e}")
+            return datetime.now(UTC)
+
+    @classmethod
+    def current_user(cls) -> object | None:
+        """当前操作人（resolver 未注册或异常时返回 None）"""
+        resolver = cls._user_resolver  # pyright: ignore[reportAttributeAccessIssue]
+        if resolver is None:
+            return None
+        try:
+            return resolver()
+        except Exception as e:
+            logger.warning(f"⚠️ user_resolver 调用失败，跳过 *_by 填充: {e}")
+            return None
+
+    @classmethod
+    def clear_columns_cache(cls, *tables: str) -> None:
+        """清空列探测缓存（表结构变更后调用；不传参清空全部）
+
+        Args:
+            tables: 表名（可多个）；不传则清空全部缓存
+        """
+        with _columns_lock:
+            if not tables:
+                _columns_cache.clear()
+                return
+            targets = set(tables)
+            for key in [k for k in _columns_cache if k[1] in targets]:
+                del _columns_cache[key]
+
+
+# ==================== 列探测（原生路径） ====================
+
+
+def table_columns(db_type: str, table_name: str) -> dict[str, TypeEngine[Any]]:
+    """表「列名 → SQLAlchemy 类型对象」映射（仅缓存探测成功的结果）
+
+    Args:
+        db_type: 数据库类型（postgresql / mysql / sqlite）
+        table_name: 表名（非限定名，按当前 search_path / database 解析）
+
+    Returns:
+        列名到类型对象的映射；表不存在或探测失败时返回**空字典**（= 不填充），
+        且不写入缓存（下次调用重新探测，表稍后创建可自愈）
+
+    Note:
+        保留类型对象而非类型名：``deleted`` 的取值需要 ``isinstance`` 判定
+        （``String`` 家族 → ``"0"``，其余 → ``0``）。
+    """
+    key = (db_type, table_name)
+    with _columns_lock:
+        cached = _columns_cache.get(key)
+    if cached is not None:
+        return cached
+
+    try:
+        inspector = sa_inspect(get_engine(db_type))
+        columns = {col["name"]: col["type"] for col in inspector.get_columns(table_name)}
+    except NoSuchTableError:
+        logger.debug(f"表 {table_name} 不存在，跳过审计字段填充")
+        return {}
+    except Exception as e:
+        logger.warning(f"⚠️ 列探测失败（{db_type}:{table_name}），跳过填充: {e}")
+        return {}
+
+    with _columns_lock:
+        _columns_cache[key] = columns
+    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[Any]],
+    name: str,
+    value: object,
+) -> None:
+    """按唯一规则写一个字段：有列 + 填充值非空 + 当前值为空"""
+    if name not in columns or _is_empty(value):
+        return
+    if not _is_empty(data.get(name)):
+        return
+    data[name] = value
+
+
+def fill_insert(
+    data: MutableMapping[str, object], columns: Mapping[str, TypeEngine[Any]]
+) -> None:
+    """INSERT 半区：created_* 与 updated_* 同值填补，deleted 补正常值
+
+    Args:
+        data: 待写入的列名 → 值（**原地修改**，调用方应传入副本）
+        columns: 表列名 → 类型对象（为空表示表无审计列，不填）
+    """
+    if not AuditConfig.is_enabled():
+        return
+    now = AuditConfig.now()
+    user = AuditConfig.current_user()
+    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:
+        data: 待更新的列名 → 值（**原地修改**，调用方应传入副本）
+        columns: 表列名 → 类型对象
+    """
+    if not AuditConfig.is_enabled():
+        return
+    now = AuditConfig.now()
+    user = AuditConfig.current_user()
+    names = AuditConfig._fields
+    _put(data, columns, names[UPDATED_AT], now)
+    _put(data, columns, names[UPDATED_BY], user)
+
+
+def fill_insert_for(
+    db_type: str, table_name: str, data: MutableMapping[str, object]
+) -> None:
+    """原生路径的 INSERT 入口：**先判启用再探测**（未启用时零额外查询）"""
+    if not AuditConfig.is_enabled():
+        return
+    fill_insert(data, table_columns(db_type, table_name))
+
+
+def fill_update_for(
+    db_type: str, table_name: str, data: MutableMapping[str, object]
+) -> None:
+    """原生路径的 UPDATE 入口：**先判启用再探测**（未启用时零额外查询）"""
+    if not AuditConfig.is_enabled():
+        return
+    fill_update(data, table_columns(db_type, table_name))
+
+
+# ==================== ORM 路径填充（before_flush） ====================
+
+
+def _object_columns(obj: object) -> dict[str, TypeEngine[Any]]:
+    """对象映射到的「表列名 → 类型对象」（无 ``__table__`` 时返回空字典）"""
+    table = getattr(obj, "__table__", None)
+    if table is None:
+        return {}
+    return {column.name: column.type for column in table.columns}
+
+
+def _fill_obj(
+    obj: object, *, now: datetime, user: object | None, insert: bool
+) -> None:
+    """按矩阵填充单个 ORM 对象（列不存在 / 已有非空值 → 跳过）"""
+    columns = _object_columns(obj)
+    names = AuditConfig._fields
+    pairs: list[tuple[str, object]] = (
+        [
+            (names[CREATED_AT], now),
+            (names[UPDATED_AT], now),
+            (names[CREATED_BY], user),
+            (names[UPDATED_BY], user),
+        ]
+        if insert
+        else [(names[UPDATED_AT], now), (names[UPDATED_BY], user)]
+    )
+    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
+        if name not in state.attrs:
+            continue
+        current = getattr(obj, name, None)
+        if insert:
+            # INSERT：属性当前值非空 → 调用方已指定
+            if not _is_empty(current):
+                continue
+        elif state.attrs[name].history.has_changes() and not _is_empty(current):
+            # UPDATE：本次显式赋了非空值 → 保留；未赋值 / 赋空 → 填充
+            continue
+        setattr(obj, name, value)
+
+
+def _on_before_flush(
+    session: Session, flush_context: object, instances: object
+) -> None:
+    """``before_flush`` 钩子：INSERT 走 new 集合，UPDATE 走 dirty 集合
+
+    时间与用户在一次 flush 内只取一次，同批对象取值一致。
+    """
+    if not AuditConfig.is_enabled():
+        return
+    now = AuditConfig.now()
+    user = AuditConfig.current_user()
+    for obj in session.new:
+        _fill_obj(obj, now=now, user=user, insert=True)
+    for obj in session.dirty:
+        if session.is_modified(obj, include_collections=False):
+            _fill_obj(obj, now=now, user=user, insert=False)

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

@@ -56,6 +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 deleted_predicate, fill_insert_for, fill_update_for
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
     close_engine,
@@ -144,6 +145,18 @@ _RESERVED_BIND_NAMES = frozenset({"id", "vec"})
 _BIND_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
 
 
+def _check_identifier(name: str) -> None:
+    """校验表名 / 列名为合法标识符（拼接进 SQL 前的白名单）
+
+    Raises:
+        ValueError: 含字母、数字、下划线以外的字符，或以数字开头
+    """
+    if not _BIND_NAME_RE.match(name):
+        raise ValueError(
+            f"{name!r} 不是合法标识符（表名/列名仅允许字母、数字、下划线）"
+        )
+
+
 def _check_extra_key(key: str, id_col: str, column: str) -> None:
     """校验 ``extra_data`` 的键可作为绑定参数名（拼装前抛出可操作的 ``ValueError``）
 
@@ -806,16 +819,87 @@ class BaseDbKit(ABC):
         """向指定表插入一行数据（键为列名）
 
         Args:
-            table_name: 表名
+            table_name: 表名（仅接受合法标识符）
             data: 列名 → 值 字典
 
         Returns:
             受影响的行数
+
+        Note:
+            调用 ``AuditConfig.enable()`` 后，若表存在 ``created_at`` / ``created_by``
+            / ``updated_at`` / ``updated_by`` / ``deleted`` 列，且 ``data`` 中该键缺失
+            或为空，则自动补齐；显式非空值一律保留。未启用时行为与引入前完全一致。
+
+        Raises:
+            ValueError: 表名不是合法标识符
         """
-        columns = ", ".join(data.keys())
-        placeholders = ", ".join(f":{name}" for name in data)
+        _check_identifier(table_name)
+        payload = dict(data)  # 副本：不污染调用方 dict
+        fill_insert_for(cls.DB_TYPE, table_name, payload)
+        columns = ", ".join(payload.keys())
+        placeholders = ", ".join(f":{name}" for name in payload)
         sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
-        return cls.execute(sql, dict(data))
+        return cls.execute(sql, payload)
+
+    @classmethod
+    def raw_update(
+        cls,
+        table_name: str,
+        data: dict[str, object],
+        where: str,
+        params: dict[str, object] | None = None,
+    ) -> int:
+        """按 where 条件更新数据（自动补 updated_*，需启用自动填充）
+
+        Args:
+            table_name: 表名（仅接受合法标识符）
+            data: 列名 → 新值（业务字段；``updated_*`` 由填充器补）
+            where: WHERE 子句（**不含** ``WHERE`` 关键字，如 ``"id = :id"``）
+            params: where 子句的绑定参数（键名不得与 ``data`` 的键重复）
+
+        Returns:
+            受影响的行数
+
+        Raises:
+            ValueError: ``data`` 为空 / ``where`` 为空 / 标识符非法 /
+                ``data`` 与 ``params`` 的绑定名冲突
+
+        Note:
+            - 无 WHERE 的全表更新属危险操作，请显式用 ``execute()`` 书写。
+            - ``where`` 中出现的 ``:name`` 必须由 ``params`` 提供，否则由
+              SQLAlchemy 抛 ``A value is required for bind parameter``。
+            - 未启用自动填充时，``data`` 原样写入（不加 ``updated_*``）。
+
+        用法::
+
+            PgKit.raw_update(
+                "writing_project",
+                {"title": "新标题"},
+                "id = :id AND created_by = :owner",
+                {"id": 123, "owner": "admin"},
+            )
+        """
+        if not data:
+            raise ValueError("raw_update 的 data 不能为空")
+        if not where or not where.strip():
+            raise ValueError("raw_update 必须提供非空 where 子句")
+        _check_identifier(table_name)
+        for name in data:
+            _check_identifier(name)
+
+        payload = dict(data)  # 副本：不污染调用方 dict
+        fill_update_for(cls.DB_TYPE, table_name, payload)
+        assignments = ", ".join(f"{name} = :{name}" for name in payload)
+
+        bound = dict(params or {})
+        conflict = set(payload) & set(bound)
+        if conflict:
+            raise ValueError(
+                f"data 与 params 的绑定名冲突: {sorted(conflict)}；请改用其它参数名"
+            )
+        bound.update(payload)
+        sql = f"UPDATE {table_name} SET {assignments} WHERE {where}"
+        return cls.execute(sql, bound)
 
     @classmethod
     def raw_get_by(
@@ -830,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.1 → sdpy_kit-0.5.3}/kit/db/crud.py

@@ -36,10 +36,20 @@ from sqlalchemy import Column, Table, delete, func, update
 from sqlalchemy.dialects import mysql as mysql_dialect
 from sqlalchemy.dialects import postgresql as pg_dialect
 from sqlalchemy.dialects import sqlite as sqlite_dialect
+from sqlalchemy.types import TypeEngine
 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,
+    DELETED,
+    AuditConfig,
+    fill_insert,
+    fill_update,
+    normal_value,
+)
 from kit.db.exceptions import DBError, NotFoundError
 
 logger = get_default_logger(__name__)
@@ -67,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 字段的类型缺陷）"""
@@ -79,20 +117,30 @@ class CRUDBase[
         """模型对应的 Table（避免 SQLModel 泛型无 __table__ 的类型缺陷）"""
         return cast(Table, getattr(self.model, "__table__"))
 
+    def _column_names(self) -> dict[str, TypeEngine[Any]]:
+        """模型映射表的「列名 → SQLAlchemy 类型对象」（读元数据，零 DB 查询）
+
+        供审计字段自动填充判断「表中是否存在该列」，以及 ``deleted`` 的取值类型。
+        """
+        return {column.name: column.type for column in self._table().columns}
+
     # ==================== 查询方法 ====================
 
     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"
             )
@@ -219,12 +267,17 @@ class CRUDBase[
         ids: list[Any],
         obj_in: UpdateSchemaType | dict[str, Any],
     ) -> int:
-        """批量更新记录（单条 UPDATE SQL，不 commit）"""
-        update_data = (
+        """批量更新记录（单条 UPDATE SQL，不 commit）
+
+        启用审计填充时自动补 ``updated_at`` / ``updated_by``
+        （不碰 ``created_*`` 与 ``deleted``）。
+        """
+        update_data = dict(
             obj_in
             if isinstance(obj_in, dict)
             else obj_in.model_dump(exclude_unset=True)
         )
+        fill_update(update_data, self._column_names())
         id_col = self._id_col()
         statement = update(self.model).where(id_col.in_(ids)).values(**update_data)
         result = session.execute(statement)
@@ -257,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} 是否存在 → "
@@ -294,7 +352,7 @@ class CRUDBase[
             obj_in: 创建/更新数据
             conflict_fields: 用于判断冲突的字段列表（需为唯一约束）
         """
-        data = (
+        data = dict(
             obj_in
             if isinstance(obj_in, dict)
             else obj_in.model_dump(exclude_unset=True)
@@ -302,17 +360,28 @@ class CRUDBase[
         if not conflict_fields:
             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
+            if k not in conflict_fields
+            and k not in pk_cols
+            and k not in insert_only
         }
         if not update_cols:
             # 无更新字段时退化为空更新（保持合法 SQL）
             update_cols = {conflict_fields[0]: data[conflict_fields[0]]}
 
+        # INSERT 半区补 created_*/updated_*/deleted；UPDATE 半区补 updated_*
+        fill_insert(data, columns)
+        fill_update(update_cols, columns)
+
         # 各数据库方言的 INSERT ... ON CONFLICT / ON DUPLICATE KEY（原子单语句）
         dialect = session.get_bind().dialect.name
         if dialect == "postgresql":
@@ -336,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)
         )