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

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

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

@@ -23,12 +23,13 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 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.2}/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.2/kit/db/audit.py

@@ -0,0 +1,382 @@
+"""
+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, Mapping, MutableMapping
+from datetime import UTC, datetime
+
+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__)
+
+# 审计字段（与 kit/db/models/base.py::AuditMixin 命名一致）
+CREATED_AT = "created_at"
+CREATED_BY = "created_by"
+UPDATED_AT = "updated_at"
+UPDATED_BY = "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)
+
+# 列探测缓存：(db_type, 表名) -> {列名: SQLAlchemy 类型对象}
+# 仅缓存**探测成功**的结果；失败不缓存，表稍后创建可自愈
+_columns_cache: dict[tuple[str, str], dict[str, TypeEngine]] = {}
+_columns_lock = threading.Lock()
+
+
+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 _deleted_default(column_type: TypeEngine) -> object:
+    """删除标记的正常值：字符串列（VARCHAR/CHAR/TEXT）填 "0"，整数列填 0
+
+    字符串列写整数在 PostgreSQL（``character varying``）与 MySQL 严格模式下
+    会直接报类型错误，故按列类型区分。
+    """
+    if isinstance(column_type, String):
+        return "0"
+    return 0
+
+
+class AuditConfig:
+    """审计字段自动填充的进程级配置（默认关闭）
+
+    进程级类属性 + 线程锁；``enable`` / ``disable`` 属启动期一次性调用，
+    不做运行期热切换承诺。模块导入零副作用。
+    """
+
+    _lock = threading.RLock()
+    _enabled = False
+    _user_resolver: Callable[[], object] | None = None
+    _clock: Callable[[], datetime] = _default_clock
+    _listening = False
+
+    @classmethod
+    def enable(
+        cls,
+        *,
+        user_resolver: Callable[[], object] | None = None,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        """启用自动填充（幂等）
+
+        Args:
+            user_resolver: 返回当前操作人的钩子（str 或 int，与列类型一致）。
+                返回 None / 空串时跳过 ``*_by`` 填充；抛异常时记 warning 并跳过，
+                不影响写入。
+            clock: 取时间钩子，默认 ``datetime.now(UTC)``（测试可注入冻结时钟）。
+
+        Note:
+            事件监听挂在父类 :class:`sqlalchemy.orm.Session` 上，因此
+            ``session_scope`` 新建的 Session 与应用自建的原生 Session 都会触发。
+        """
+        with cls._lock:
+            if user_resolver is not None:
+                cls._user_resolver = user_resolver
+            if clock is not None:
+                cls._clock = clock
+            if not cls._listening:
+                event.listen(Session, "before_flush", _on_before_flush)
+                cls._listening = True
+            cls._enabled = True
+        logger.info("✅ 审计字段与删除标记自动填充已启用")
+
+    @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()
+        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
+        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]:
+    """表「列名 → 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
+
+
+# ==================== dict 路径填充（Core DML / 原生构建器） ====================
+
+
+def _put(
+    data: MutableMapping[str, object],
+    columns: Mapping[str, TypeEngine],
+    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]) -> None:
+    """INSERT 半区：created_* 与 updated_* 同值填补，deleted 补正常值
+
+    Args:
+        data: 待写入的列名 → 值（**原地修改**，调用方应传入副本）
+        columns: 表列名 → 类型对象（为空表示表无审计列，不填）
+    """
+    if not AuditConfig.is_enabled():
+        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:
+    """UPDATE 半区：只动 updated_*（不碰 created_*，也不碰 deleted）
+
+    Args:
+        data: 待更新的列名 → 值（**原地修改**，调用方应传入副本）
+        columns: 表列名 → 类型对象
+    """
+    if not AuditConfig.is_enabled():
+        return
+    now = AuditConfig.now()
+    user = AuditConfig.current_user()
+    _put(data, columns, UPDATED_AT, now)
+    _put(data, columns, 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]:
+    """对象映射到的「表列名 → 类型对象」（无 ``__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)
+    pairs: list[tuple[str, object]] = (
+        [(CREATED_AT, now), (UPDATED_AT, now), (CREATED_BY, user), (UPDATED_BY, user)]
+        if insert
+        else [(UPDATED_AT, now), (UPDATED_BY, user)]
+    )
+    if insert and DELETED in columns:
+        pairs.append((DELETED, _deleted_default(columns[DELETED])))
+
+    state = sa_inspect(obj)
+    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.2}/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 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(

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

@@ -36,10 +36,12 @@ 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, fill_insert, fill_update
 from kit.db.exceptions import DBError, NotFoundError
 
 logger = get_default_logger(__name__)
@@ -79,6 +81,13 @@ class CRUDBase[
         """模型对应的 Table（避免 SQLModel 泛型无 __table__ 的类型缺陷）"""
         return cast(Table, getattr(self.model, "__table__"))
 
+    def _column_names(self) -> dict[str, TypeEngine]:
+        """模型映射表的「列名 → SQLAlchemy 类型对象」（读元数据，零 DB 查询）
+
+        供审计字段自动填充判断「表中是否存在该列」，以及 ``deleted`` 的取值类型。
+        """
+        return {column.name: column.type for column in self._table().columns}
+
     # ==================== 查询方法 ====================
 
     def get(self, session: Session, id: Any) -> ModelType | None:
@@ -219,12 +228,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)
@@ -294,7 +308,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 +316,26 @@ class CRUDBase[
         if not conflict_fields:
             raise DBError("upsert 必须提供 conflict_fields")
 
-        # 更新集：排除冲突字段与主键（避免覆盖主键/冲突键）
+        columns = self._column_names()
+
+        # 更新集：排除冲突字段、主键，以及**只在 INSERT 填充**的 created_*
+        # （若把 created_* 带进 set_，每次冲突更新都会把创建时间刷成 now）
         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 (CREATED_AT, CREATED_BY)
         }
         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":