yimo-kit 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. yimo/__init__.py +26 -0
  2. yimo/kit/__init__.py +98 -0
  3. yimo/kit/ai/__init__.py +110 -0
  4. yimo/kit/ai/_internal/__init__.py +27 -0
  5. yimo/kit/ai/_internal/failover.py +535 -0
  6. yimo/kit/ai/_internal/pool.py +526 -0
  7. yimo/kit/ai/_internal/rerank_transport.py +137 -0
  8. yimo/kit/ai/_internal/retry_after.py +51 -0
  9. yimo/kit/ai/_internal/sdk_client.py +463 -0
  10. yimo/kit/ai/_internal/service_base.py +115 -0
  11. yimo/kit/ai/_internal/types.py +28 -0
  12. yimo/kit/ai/agent/__init__.py +127 -0
  13. yimo/kit/ai/agent/approval.py +66 -0
  14. yimo/kit/ai/agent/errors.py +128 -0
  15. yimo/kit/ai/agent/loop.py +643 -0
  16. yimo/kit/ai/agent/mcp.py +278 -0
  17. yimo/kit/ai/agent/registry.py +203 -0
  18. yimo/kit/ai/agent/session.py +150 -0
  19. yimo/kit/ai/agent/skill.py +370 -0
  20. yimo/kit/ai/agent/types.py +161 -0
  21. yimo/kit/ai/chat_service.py +724 -0
  22. yimo/kit/ai/decision/__init__.py +57 -0
  23. yimo/kit/ai/decision/decima.py +853 -0
  24. yimo/kit/ai/decision/laya.py +552 -0
  25. yimo/kit/ai/embedding_service.py +198 -0
  26. yimo/kit/ai/exceptions.py +109 -0
  27. yimo/kit/ai/image_service.py +84 -0
  28. yimo/kit/ai/messages.py +105 -0
  29. yimo/kit/ai/model_builder.py +121 -0
  30. yimo/kit/ai/model_client.py +62 -0
  31. yimo/kit/ai/profiles.py +577 -0
  32. yimo/kit/ai/rerank_service.py +136 -0
  33. yimo/kit/ai/runner.py +1127 -0
  34. yimo/kit/common_kit.py +221 -0
  35. yimo/kit/config/__init__.py +44 -0
  36. yimo/kit/config/kit_config.py +210 -0
  37. yimo/kit/config/log_config.py +171 -0
  38. yimo/kit/crawl/__init__.py +71 -0
  39. yimo/kit/crawl/article_io.py +325 -0
  40. yimo/kit/crawl/article_models.py +172 -0
  41. yimo/kit/crawl/deepseek_kit.py +673 -0
  42. yimo/kit/crawl/web_article_kit.py +638 -0
  43. yimo/kit/crawl/wx_article_kit.py +692 -0
  44. yimo/kit/db/__init__.py +101 -0
  45. yimo/kit/db/audit.py +625 -0
  46. yimo/kit/db/base_db_kit.py +1265 -0
  47. yimo/kit/db/crud.py +423 -0
  48. yimo/kit/db/engine.py +235 -0
  49. yimo/kit/db/exceptions.py +45 -0
  50. yimo/kit/db/models/__init__.py +33 -0
  51. yimo/kit/db/models/base.py +56 -0
  52. yimo/kit/db/mysql_kit.py +348 -0
  53. yimo/kit/db/pg_kit.py +442 -0
  54. yimo/kit/db/query.py +338 -0
  55. yimo/kit/db/session.py +85 -0
  56. yimo/kit/db/sqlite_kit.py +462 -0
  57. yimo/kit/db/transaction.py +109 -0
  58. yimo/kit/docs/__init__.py +34 -0
  59. yimo/kit/docs/anydoc_kit.py +490 -0
  60. yimo/kit/docs/docx_kit.py +895 -0
  61. yimo/kit/docs/md2doc_kit.py +1801 -0
  62. yimo/kit/docs/mineru_kit.py +1497 -0
  63. yimo/kit/docs/rc_docparser_kit.py +654 -0
  64. yimo/kit/file_kit.py +518 -0
  65. yimo/kit/license_kit.py +533 -0
  66. yimo/kit/redis_kit.py +392 -0
  67. yimo_kit-0.1.0.dist-info/METADATA +1673 -0
  68. yimo_kit-0.1.0.dist-info/RECORD +70 -0
  69. yimo_kit-0.1.0.dist-info/WHEEL +4 -0
  70. yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,1265 @@
1
+ """
2
+ Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
15
+
16
+ Project: yimo
17
+ Author: 溢墨修心(Yimo)
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ # date: 2026-08-22
23
+ """数据库 Kit 共享基类(DRY 收敛)
24
+
25
+ 三个数据库 Kit(PgKit / MySqlKit / SQLiteKit)在重构前拥有约 400 行几乎
26
+ 逐行相同的代码(连接管理 / ORM / 原生 SQL / 原生表操作 / 事务 / 表操作),
27
+ 仅 DB_TYPE 与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛,子类
28
+ 只声明 DB_TYPE 并覆写 get_table_info(SQLite 另含向量操作)。
29
+
30
+ 2026-10-11:将原本仅 SQLiteKit 具备的 4 个方言无关方法(raw_connection /
31
+ create_raw_table / raw_insert / raw_get_by)上移到本基类,使三个 Kit 在该层
32
+ 的能力与签名完全一致(共享方法 19 → 23)。
33
+
34
+ 设计要点:
35
+ - 所有公开方法保留原签名与语义,外部调用零影响。
36
+ - 使用 PEP 695 方法级泛型 `T: SQLModel` 表达「模型类 → 实例」。
37
+ - 数据参数用 `dict[str, object]`(比 `dict[str, Any]` 严格)。
38
+ - 三层边界不变:本层方法自动提交(内部 session_scope);CRUDBase 不提交;
39
+ transaction() 上下文管理器管理多操作原子性。
40
+ - 类中存在公开方法 `list`,会遮蔽内置 `list` 类型;因此所有返回/参数中
41
+ 的列表类型统一显式写作 `builtins.list[...]`,避免 mypy 将 `list[T]`
42
+ 解析为方法名。
43
+ """
44
+
45
+ import builtins
46
+ import json
47
+ import re
48
+ import threading
49
+ from abc import ABC, abstractmethod
50
+ from collections.abc import Generator
51
+ from contextlib import contextmanager
52
+ from typing import cast
53
+
54
+ from sqlalchemy import JSON, TextClause, bindparam, text
55
+ from sqlalchemy.pool import PoolProxiedConnection
56
+ from sqlmodel import Session, SQLModel
57
+
58
+ from yimo.kit.common_kit import CommonKit
59
+ from yimo.kit.config.log_config import get_default_logger
60
+ from yimo.kit.db.audit import (
61
+ UPDATED_AT,
62
+ AuditConfig,
63
+ candidate_columns,
64
+ deleted_predicate,
65
+ fill_insert_for,
66
+ fill_update,
67
+ fill_update_for,
68
+ table_columns,
69
+ touch_columns,
70
+ )
71
+ from yimo.kit.db.crud import CRUDBase
72
+ from yimo.kit.db.engine import (
73
+ MYSQL,
74
+ close_engine,
75
+ create_tables,
76
+ get_engine,
77
+ list_tables,
78
+ table_exists,
79
+ )
80
+ from yimo.kit.db.exceptions import DBError
81
+ from yimo.kit.db.session import session_scope
82
+
83
+ logger = get_default_logger(__name__)
84
+
85
+ # 字段数据:列名到值的映射(object 覆盖全部 SQLModel 支持类型)
86
+ type FieldData = dict[str, object]
87
+
88
+ # 向量检索的默认距离类型:三库能力集的交集(SQLite 仅支持 L2),
89
+ # 由三个数据库 Kit 的 search_vectors 共用,避免各 Kit 默认值漂移。
90
+ # 默认值不得按后端覆写——否则同一份代码换 import 后会在静默中改变度量语义。
91
+ DEFAULT_DISTANCE_TYPE = "L2"
92
+
93
+ # CRUD 实例缓存:CRUDBase 无状态(仅存 model),按 model 复用避免重复实例化
94
+ # 值类型取宽基类 SQLModel,规避 PEP 695 类型参数上界约束
95
+ _crud_cache: dict[type, CRUDBase[SQLModel, SQLModel, SQLModel]] = {}
96
+ _crud_lock = threading.Lock()
97
+
98
+
99
+ def _get_crud[T: SQLModel](model: type[T]) -> CRUDBase[T, T, T]:
100
+ """按模型获取(并缓存)CRUD 实例"""
101
+ crud = _crud_cache.get(model)
102
+ if crud is None:
103
+ with _crud_lock:
104
+ crud = _crud_cache.get(model)
105
+ if crud is None:
106
+ new_crud: CRUDBase[T, T, T] = CRUDBase(model)
107
+ crud = cast(CRUDBase[SQLModel, SQLModel, SQLModel], new_crud)
108
+ _crud_cache[model] = crud
109
+ return cast(CRUDBase[T, T, T], crud)
110
+
111
+
112
+ def to_vector_literal(vector: builtins.list[float]) -> str:
113
+ """把 float 列表转换为向量文本字面量(如 [0.1, 0.2] → "[0.1,0.2]")
114
+
115
+ 供共享相同文本格式的数据库后端复用:PgKit(pgvector 的 vector 类型)与
116
+ MySqlKit(STRING_TO_VECTOR)。SQLiteKit 走 float32 bytes,不使用本函数。
117
+ """
118
+ return "[" + ",".join(repr(float(value)) for value in vector) + "]"
119
+
120
+
121
+ def vector_insert_placeholders(
122
+ columns: builtins.list[str],
123
+ id_col: str,
124
+ column: str,
125
+ vector_placeholder: str = ":vec",
126
+ ) -> str:
127
+ """生成向量表 INSERT 的占位符串(供三个数据库 Kit 的 build_insert_vectors 共用)
128
+
129
+ 绑定参数名与列名**解耦**:id 列固定为 ``:id``、向量列固定为 ``vector_placeholder``、
130
+ 其余列用 ``:列名``。这样调用方覆写 ``id_col`` / ``column``(自建 DDL 场景)时,
131
+ 参数字典的键不受列名影响。
132
+
133
+ Args:
134
+ columns: 列名列表(按 INSERT 顺序)
135
+ id_col: id 列名 → ``:id``
136
+ column: 向量列名 → ``vector_placeholder``
137
+ vector_placeholder: 向量列的占位符文本(MySQL 传 ``"STRING_TO_VECTOR(:vec)"``)
138
+
139
+ ⚠ 内部符号(不在 ``yimo.kit.db.__all__``):调用方请用
140
+ `BaseDbKit.build_insert_vectors`,无需关心绑定名。
141
+ """
142
+
143
+ def _one(name: str) -> str:
144
+ if name == column:
145
+ return vector_placeholder
146
+ if name == id_col:
147
+ return ":id"
148
+ return f":{name}"
149
+
150
+ return ", ".join(_one(name) for name in columns)
151
+
152
+
153
+ # 向量插入的内部保留绑定名(与 vector_insert_placeholders 的映射一一对应)
154
+ _RESERVED_BIND_NAMES = frozenset({"id", "vec"})
155
+
156
+ # 绑定参数名须为标识符:否则 SQLAlchemy 无法解析 `:name`(列名含空格等会得到
157
+ # "A value is required for bind parameter" 这类无法定位的报错)
158
+ _BIND_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
159
+
160
+
161
+ def _check_identifier(name: str) -> None:
162
+ """校验表名 / 列名为合法标识符(拼接进 SQL 前的白名单)
163
+
164
+ Raises:
165
+ ValueError: 含字母、数字、下划线以外的字符,或以数字开头
166
+ """
167
+ if not _BIND_NAME_RE.match(name):
168
+ raise ValueError(
169
+ f"{name!r} 不是合法标识符(表名/列名仅允许字母、数字、下划线)"
170
+ )
171
+
172
+
173
+ # 写入侧需要特殊处理的序列类型(会被 prepare_statement 当作 IN 展开,须先消除)
174
+ _WRITE_SEQUENCE_TYPES = (list, tuple, set, frozenset)
175
+
176
+
177
+ def _adapt_write_values(
178
+ db_type: str, table_name: str, data: dict[str, object]
179
+ ) -> None:
180
+ """按目标列类型适配写入值(**原地修改** data;惰性探测)
181
+
182
+ 规则(二次评估定稿):
183
+
184
+ - ``dict``:任何驱动都无法直接绑定 → 一律编码为 JSON 文本;
185
+ - ``list`` / ``tuple`` / ``set`` / ``frozenset``:仅当目标列是 JSON 类型时编码;
186
+ 其它列抛 ``ValueError``——这些序列会被 ``prepare_statement`` 当作 ``IN`` 展开,
187
+ 写进 ``VALUES`` 会破坏 SQL 结构(数组 / 向量请用字符串或 ``execute()`` 手写)。
188
+
189
+ 只有 ``data`` 中确实出现上述类型时才探测列(纯标量写入零额外查询)。
190
+ """
191
+ if not any(isinstance(v, (dict, *_WRITE_SEQUENCE_TYPES)) for v in data.values()):
192
+ return
193
+
194
+ columns = table_columns(db_type, table_name)
195
+ for name, value in list(data.items()):
196
+ if isinstance(value, dict):
197
+ data[name] = json.dumps(value, ensure_ascii=False)
198
+ continue
199
+ if isinstance(value, _WRITE_SEQUENCE_TYPES):
200
+ column_type = columns.get(name)
201
+ if column_type is None:
202
+ raise ValueError(
203
+ f"{name!r} 的值是序列,但表 {table_name} 中查不到该列"
204
+ f"(或列探测失败):请确认表已提交建好;"
205
+ f"JSON 列请传 dict / list;向量请用 to_vector_literal(...);"
206
+ f"数组等其它类型请用 execute() 手写 SQL"
207
+ )
208
+ if isinstance(column_type, JSON):
209
+ data[name] = json.dumps(list(value), ensure_ascii=False)
210
+ else:
211
+ raise ValueError(
212
+ f"{name!r} 的值是序列,且目标列不是 JSON 类型:"
213
+ f"JSON 列请传 dict / list;向量请用 to_vector_literal(...);"
214
+ f"数组等其它类型请用 execute() 手写 SQL"
215
+ )
216
+
217
+
218
+ def _check_extra_key(key: str, id_col: str, column: str) -> None:
219
+ """校验 ``extra_data`` 的键可作为绑定参数名(拼装前抛出可操作的 ``ValueError``)
220
+
221
+ 三类问题(均实测):
222
+ ① 保留绑定名 ``id`` / ``vec`` → ``params`` 被覆盖,SQLite 静默写坏数据;
223
+ ② 与 ``id_col`` / ``column`` 重复 → SQLite 接受重复列名并丢弃调用方给的值;
224
+ ③ 不是合法标识符 → 报错无法定位("A value is required for bind parameter")。
225
+ """
226
+ if key in _RESERVED_BIND_NAMES:
227
+ raise ValueError(
228
+ f"extra_data 含保留绑定名 {key!r}:向量插入的内部绑定名固定为 "
229
+ f"'id'(id 列)与 'vec'(向量列),同名业务列会覆盖它们;"
230
+ f"请重命名该键,或改用自定义 SQL(配合 Kit.transaction())"
231
+ )
232
+ if key in (id_col, column):
233
+ raise ValueError(
234
+ f"extra_data 含重复列 {key!r}:该列已由 id_col / column 覆盖"
235
+ )
236
+ if not _BIND_NAME_RE.match(key):
237
+ raise ValueError(
238
+ f"extra_data 的键 {key!r} 不是合法标识符,无法生成绑定参数名"
239
+ )
240
+
241
+
242
+ def normalize_extra_cols(
243
+ extra_cols: dict[str, str] | builtins.list[dict[str, str]] | None,
244
+ ) -> builtins.list[tuple[str, str]]:
245
+ """归一化 ``create_vector_table`` 的额外列定义(两种入参形态)
246
+
247
+ 接受 ``{列名: 方言类型串}``(推荐,与 `create_raw_table` 同形,**键序即 DDL 列序**)
248
+ 或既有 ``[{"name": ..., "type": ...}]``;空值返回空列表。
249
+ 两种形态产出**逐字一致**的 DDL。
250
+ """
251
+ if not extra_cols:
252
+ return []
253
+ if isinstance(extra_cols, dict):
254
+ return [(name, col_type) for name, col_type in extra_cols.items()]
255
+ return [(col["name"], col["type"]) for col in extra_cols]
256
+
257
+
258
+ def generate_snowflake_ids(count: int) -> builtins.list[int]:
259
+ """生成 count 个雪花 ID(int64;当前 18 位,上限 19 位)
260
+
261
+ 供三个数据库 Kit 的向量方法在调用方未提供 id(``ids=None``)时兜底使用:
262
+ id 由**应用侧(kit)生成**而非数据库自增,保证三库语义一致,同时避免
263
+ PostgreSQL 序列不随显式 id 推进的问题(BIGSERIAL → 纯 BIGINT 主键)。
264
+
265
+ ⚠ 雪花 ID 超过 2^53,经 JSON 传给 JavaScript 会丢精度,需按字符串传输。
266
+ """
267
+ return [CommonKit.generate_snowflake_id() for _ in range(count)]
268
+
269
+
270
+ # 可参与 IN 展开的参数类型(按类型白名单判断,绝不用 Iterable:
271
+ # 否则字符串会被逐字符展开)
272
+ _EXPANDING_TYPES = (list, tuple, set, frozenset)
273
+
274
+
275
+ def prepare_statement(
276
+ sql: str, params: FieldData | builtins.list[FieldData] | None = None
277
+ ) -> tuple[TextClause, FieldData | builtins.list[FieldData] | None]:
278
+ """把 SQL 文本 + 参数转为(可直接执行的语句, 参数)
279
+
280
+ 供调用方在**自有事务**(`*Kit.transaction()`)内执行原生 SQL,
281
+ 与 ``query`` / ``execute`` 使用**同一套参数规则**(单一事实源)——
282
+ 单字典形态下后两者等价于 ``session.execute(*prepare_statement(sql, params))``;
283
+ 本函数**不建连接、不改状态、不执行**。
284
+
285
+ 两种参数形态(与 ``execute`` 对称):
286
+
287
+ - **单字典**:值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键按
288
+ SQLAlchemy **expanding** 语义绑定,可直接书写 ``WHERE id IN :ids``
289
+ (三库通用);第二项为归一化后的参数字典;
290
+ - **字典列表**(批量 / executemany):第二项**原样返回该列表**,语句为
291
+ 裸 ``text(sql)``(**不做** ``IN`` 展开——批量与展开参数互斥,与
292
+ ``execute`` 的批量约束一致);经 ``_validate_batch_rows`` 本地预校验
293
+ (各行键集一致、行值为标量)。
294
+
295
+ 典型用法(调用方**无须 import sqlalchemy**)::
296
+
297
+ from yimo.kit.db import SQLiteKit, prepare_statement
298
+
299
+ stmt, bound = prepare_statement(
300
+ "DELETE FROM t WHERE id IN :ids", {"ids": [1, 2, 3]}
301
+ )
302
+ with SQLiteKit.transaction() as session:
303
+ session.execute(stmt, bound) # 第二个值必须一并传入
304
+
305
+ stmt, rows = prepare_statement( # 批量(executemany)
306
+ "INSERT INTO t (a, b) VALUES (:a, :b)", [{"a": 1, "b": 2}]
307
+ )
308
+ with SQLiteKit.transaction() as session:
309
+ session.execute(stmt, rows)
310
+
311
+ 三条实现约束(**单字典形态**,与 ``query`` / ``execute`` 现有语义完全一致):
312
+
313
+ 1. 只对**确实出现在 SQL 文本中**的参数名做 expanding —— 否则传入"未使用的
314
+ 序列参数"会触发 SQLAlchemy 的 ``ArgumentError: This text() construct
315
+ doesn't define a bound parameter …``,该报错对使用方没有意义;
316
+ 2. 按类型白名单判断(见 `_EXPANDING_TYPES`),字符串不会被当作列表;
317
+ 3. ``set`` / ``frozenset`` 归一化为 ``list`` —— SQLAlchemy 的 expanding 只接受
318
+ **可下标序列**(直接传 set 会抛 ``TypeError: 'set' object is not
319
+ subscriptable``);``IN`` 与顺序无关,故归一化不改变语义。
320
+
321
+ Args:
322
+ sql: SQL 语句(使用命名参数 ``:param``)
323
+ params: **单个参数字典**(值为 ``list`` / ``tuple`` / ``set`` / ``frozenset``
324
+ 的键按 ``IN`` 展开,三库通用)或**参数字典的列表**(批量,行值须为标量)
325
+
326
+ Returns:
327
+ ``(语句, 参数)``:执行时**必须**把第二个值一并传给 ``session.execute``;
328
+ ``params`` 为 None 时第二项即 None,为列表时**原样返回该列表**
329
+
330
+ Note:
331
+ ``:name::type`` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 ``text()``
332
+ 识别**(该写法在支持本函数之前同样不可用),请改用 ``CAST(:name AS type)``。
333
+
334
+ Raises:
335
+ ValueError: 列表形态的行键集不一致或行值含序列类型(来自
336
+ ``_validate_batch_rows``,与 ``execute`` 批量形态同一规则)
337
+
338
+ See Also:
339
+ ``query`` / ``execute``:kit 自管事务的原生 SQL 入口(同样支持列表参数)。
340
+ """
341
+ if isinstance(params, builtins.list):
342
+ # 批量形态:语句不做 IN 展开,参数行列表原样返回(由 execute/session
343
+ # 以 executemany 执行);空列表不校验、不报错(构造期无副作用)
344
+ if params:
345
+ _validate_batch_rows(params)
346
+ return text(sql), params
347
+
348
+ statement = text(sql)
349
+ if not params:
350
+ return statement, params
351
+
352
+ normalized: FieldData = {}
353
+ expanding: list[object] = []
354
+ for name, value in params.items():
355
+ if isinstance(value, _EXPANDING_TYPES):
356
+ if isinstance(value, (set, frozenset)):
357
+ value = list(value)
358
+ normalized[name] = value
359
+ # 约束 1:只对确实出现在 SQL 文本中的参数名做 expanding
360
+ if re.search(rf":{re.escape(name)}\b", sql):
361
+ expanding.append(bindparam(name, expanding=True))
362
+ else:
363
+ normalized[name] = value
364
+
365
+ if expanding:
366
+ statement = statement.bindparams(*expanding) # type: ignore[arg-type]
367
+ return statement, normalized
368
+
369
+
370
+ def _validate_batch_rows(rows: builtins.list[FieldData]) -> None:
371
+ """批量执行(executemany)的本地预校验:键集一致 + 不含序列参数
372
+
373
+ 约束来自 DBAPI 的 executemany 语义(实测):
374
+
375
+ 1. 各行字典的**键集必须完全一致** —— 否则 SQLAlchemy 报
376
+ ``StatementError: A value is required for bind parameter 'xxx'``,
377
+ 不指明是哪一行,对使用方没有意义;
378
+ 2. 行值须为**标量** —— 批量与 ``IN`` 展开(expanding)**互斥**:对批量语句
379
+ 做 expanding 标注后按行执行会得到 ``OperationalError: near "?": syntax error``
380
+ 这类驱动级错误(三库通用行为)。
381
+
382
+ 在本地提前给出**可操作的** ``ValueError``(含行号与差异明细),
383
+ 避免把上述两类无意义报错暴露给使用方。
384
+
385
+ Args:
386
+ rows: 批量参数(非空)
387
+
388
+ Raises:
389
+ ValueError: 键集不一致,或行值中含序列类型
390
+ """
391
+ base = set(rows[0])
392
+ for index, row in enumerate(rows):
393
+ keys = set(row)
394
+ if keys != base:
395
+ raise ValueError(
396
+ f"批量参数第 {index} 行的键集与第 0 行不一致:"
397
+ f"缺少 {sorted(base - keys)},多出 {sorted(keys - base)};"
398
+ f"executemany 要求各行键集完全一致"
399
+ )
400
+ for name, value in row.items():
401
+ if isinstance(value, _EXPANDING_TYPES):
402
+ raise ValueError(
403
+ f"批量参数第 {index} 行的 {name!r} 是序列类型:"
404
+ f"批量执行(executemany)与 IN 展开(expanding)互斥;"
405
+ f"如需 IN 语义请改用单个参数字典(execute 的单字典形态),"
406
+ f"或逐行调用 execute"
407
+ )
408
+
409
+
410
+ class BaseDbKit(ABC):
411
+ """数据库工具类共享基类
412
+
413
+ 子类需声明 `DB_TYPE` 并实现 `get_table_info`。所有方法均为类方法,
414
+ 业务代码无需实例化。
415
+ """
416
+
417
+ # 数据库类型标识(postgresql / mysql / sqlite),由子类覆写
418
+ DB_TYPE: str
419
+
420
+ # 向量列的占位符(后端覆写点):MySQL 需经 STRING_TO_VECTOR 转换
421
+ VECTOR_PLACEHOLDER: str = ":vec"
422
+
423
+ # ==================== 向量写入的共享构造(只拼装,不执行) ====================
424
+
425
+ @classmethod
426
+ def _vector_param(cls, vector: builtins.list[float]) -> object:
427
+ """向量 → 绑定参数值(**私有钩子**,子类覆写;基类=文本字面量)
428
+
429
+ PostgreSQL(pgvector)与 MySQL(``STRING_TO_VECTOR``)共用文本字面量;
430
+ `SQLiteKit` 覆写为 float32 小端字节。
431
+ """
432
+ return to_vector_literal(vector)
433
+
434
+ @classmethod
435
+ def build_insert_vectors(
436
+ cls,
437
+ table_name: str,
438
+ vectors: builtins.list[builtins.list[float]],
439
+ ids: builtins.list[int] | None = None,
440
+ extra_data: builtins.list[dict[str, object]] | None = None,
441
+ id_col: str = "id",
442
+ column: str = "embedding",
443
+ ) -> builtins.list[tuple[str, builtins.list[dict[str, object]]]]:
444
+ """构造向量表 INSERT 语句(**只拼装、不执行、不管事务**)
445
+
446
+ 供调用方在**自己的事务**内写入向量行(与其它表行同事务提交)::
447
+
448
+ with SQLiteKit.transaction() as session:
449
+ session.execute(text("INSERT INTO docs_item (...) VALUES (...)"), {...})
450
+ for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors",
451
+ vectors, ids=[...],
452
+ id_col="rowid"):
453
+ session.execute(text(sql), params)
454
+
455
+ Args:
456
+ table_name: 表名
457
+ vectors: 向量列表,每个向量为 float 列表(也接受二维 numpy 数组)
458
+ ids: 可选的 ID 列表(长度需与 vectors 一致);None 时由 Kit 生成雪花 ID
459
+ (生成值可从返回的参数列表读取)
460
+ extra_data: 额外列数据列表(长度需与 vectors 一致)
461
+ id_col: 主键列名(默认 ``id``,供自建 DDL 的表使用)
462
+ column: 向量列名(默认 ``embedding``,供自建 DDL 的表使用)
463
+
464
+ Returns:
465
+ 按**列集分组**的 ``[(SQL, 参数列表), ...]``:同列集的行合并为一条可
466
+ ``executemany`` 的语句(常规同构 ``extra_data`` 只返回 1 条)。SQL 为
467
+ SQLAlchemy ``text()`` 风格(``:id`` / ``:vec`` / ``:列名``)。
468
+
469
+ Raises:
470
+ ValueError: 入参自洽性校验失败——长度/维度不一致、``extra_data`` 键为保留绑定名
471
+ (``id`` / ``vec``)或与 ``id_col`` / ``column`` 重复、键不是合法标识符、
472
+ ``id_col == column``
473
+
474
+ Note:
475
+ - **无副作用**:不建连接、不接触数据库、不改任何状态;对**不存在的表**也正常返回。
476
+ - **执行载体**:SQLite 可直接在 ``raw_connection()``(DBAPI 支持 ``:name``)或
477
+ ``transaction()`` 上执行;**PG / MySQL 的原生 DBAPI 不支持 ``:name``**
478
+ (psycopg2 / pymysql 需 ``%(name)s``),须经 ``Kit.transaction()`` 的 session 执行。
479
+ - ``insert_vectors`` 的执行语义即"本方法 + 自带事务",两者共用同一份拼装逻辑。
480
+ """
481
+ if id_col == column:
482
+ raise ValueError(f"id_col 与 column 不能同名(当前均为 {id_col!r})")
483
+ # 用 len() 而非真值判断:入参可为 list 或二维 numpy 数组
484
+ if len(vectors) == 0:
485
+ return []
486
+ if ids is None:
487
+ ids = generate_snowflake_ids(len(vectors))
488
+ if len(ids) != len(vectors):
489
+ raise ValueError("ids 长度必须与 vectors 一致")
490
+ if extra_data is not None and len(extra_data) != len(vectors):
491
+ raise ValueError("extra_data 长度必须与 vectors 一致")
492
+
493
+ dims = len(vectors[0])
494
+ if any(len(vec) != dims for vec in vectors):
495
+ raise ValueError(
496
+ f"同一批次的向量长度必须一致(首个向量 {dims} 维,存在其它维度的向量)"
497
+ )
498
+
499
+ # 按「列集合」分组:executemany 要求同一语句的参数列表**键集一致**
500
+ groups: dict[tuple[str, ...], builtins.list[dict[str, object]]] = {}
501
+ for i, vector in enumerate(vectors):
502
+ columns: builtins.list[str] = [id_col, column]
503
+ params: dict[str, object] = {"id": ids[i], "vec": cls._vector_param(vector)}
504
+ if extra_data is not None:
505
+ for key, value in extra_data[i].items():
506
+ _check_extra_key(key, id_col, column)
507
+ columns.append(key)
508
+ params[key] = value
509
+ groups.setdefault(tuple(columns), []).append(params)
510
+
511
+ statements: builtins.list[tuple[str, builtins.list[dict[str, object]]]] = []
512
+ for columns_tuple, params_list in groups.items():
513
+ columns_list = list(columns_tuple)
514
+ placeholders = vector_insert_placeholders(
515
+ columns_list, id_col, column, cls.VECTOR_PLACEHOLDER
516
+ )
517
+ statements.append(
518
+ (
519
+ f"INSERT INTO {table_name} ({', '.join(columns_list)}) "
520
+ f"VALUES ({placeholders})",
521
+ params_list,
522
+ )
523
+ )
524
+ return statements
525
+
526
+ # ==================== 连接管理 ====================
527
+
528
+ @classmethod
529
+ def connect(cls) -> bool:
530
+ """初始化数据库连接(延迟创建引擎并验证连通性)
531
+
532
+ Returns:
533
+ True 表示连接成功
534
+ """
535
+ try:
536
+ engine = get_engine(cls.DB_TYPE)
537
+ with engine.connect() as conn:
538
+ conn.execute(text("SELECT 1"))
539
+ logger.info("✅ 数据库连接成功")
540
+ return True
541
+ except Exception as e:
542
+ logger.error(f"❌ 数据库连接失败: {e}")
543
+ return False
544
+
545
+ @classmethod
546
+ def close(cls) -> None:
547
+ """关闭数据库连接"""
548
+ close_engine(cls.DB_TYPE)
549
+ logger.info("🔌 数据库连接已关闭")
550
+
551
+ @classmethod
552
+ def is_connected(cls) -> bool:
553
+ """检查数据库是否可连接"""
554
+ try:
555
+ engine = get_engine(cls.DB_TYPE)
556
+ with engine.connect() as conn:
557
+ conn.execute(text("SELECT 1"))
558
+ return True
559
+ except Exception:
560
+ return False
561
+
562
+ @classmethod
563
+ def raw_connection(cls) -> PoolProxiedConnection:
564
+ """获取原生 DBAPI 连接(引擎侧扩展加载已由 engine.py 自动完成)
565
+
566
+ PostgreSQL 返回 psycopg2 连接、MySQL 返回 pymysql 连接、SQLite 返回
567
+ sqlite3 连接(sqlite-vector 扩展已自动加载)。用于执行驱动特有函数与
568
+ 静态 DDL。
569
+
570
+ ⚠ 调用方负责提交与关闭连接。psycopg2 / pymysql 默认**不开启自动提交**,
571
+ 与 sqlite3 的使用习惯不同:需要落库时必须显式 commit。
572
+ """
573
+ return get_engine(cls.DB_TYPE).raw_connection()
574
+
575
+ # ==================== ORM 操作(自动管理 session) ====================
576
+
577
+ @classmethod
578
+ def create[T: SQLModel](cls, model: type[T], data: FieldData) -> T:
579
+ """创建单条记录
580
+
581
+ Args:
582
+ model: SQLModel 模型类
583
+ data: 字段名到值的映射
584
+
585
+ Returns:
586
+ 创建后的模型实例(含主键)
587
+ """
588
+ with session_scope(cls.DB_TYPE) as session:
589
+ crud = _get_crud(model)
590
+ obj = crud.create(session, data)
591
+ session.expunge(obj) # 脱离 session,使返回值在 session 关闭后仍可用
592
+ return obj
593
+
594
+ @classmethod
595
+ def create_multi[T: SQLModel](
596
+ cls, model: type[T], data_list: builtins.list[FieldData]
597
+ ) -> builtins.list[T]:
598
+ """批量创建记录
599
+
600
+ Args:
601
+ model: SQLModel 模型类
602
+ data_list: 字段字典列表
603
+
604
+ Returns:
605
+ 创建后的模型实例列表
606
+ """
607
+ with session_scope(cls.DB_TYPE) as session:
608
+ crud = _get_crud(model)
609
+ objs = crud.create_multi(
610
+ session, cast(builtins.list[T | FieldData], data_list)
611
+ )
612
+ for obj in objs:
613
+ session.expunge(obj)
614
+ return objs
615
+
616
+ @classmethod
617
+ def get[T: SQLModel](cls, model: type[T], id: object) -> T | None:
618
+ """根据主键获取单条记录
619
+
620
+ Args:
621
+ model: SQLModel 模型类
622
+ id: 主键值
623
+
624
+ Returns:
625
+ 模型实例,不存在时返回 None
626
+ """
627
+ with session_scope(cls.DB_TYPE) as session:
628
+ obj = session.get(model, id)
629
+ if obj:
630
+ session.expunge(obj)
631
+ return obj
632
+
633
+ @classmethod
634
+ def get_by[T: SQLModel](
635
+ cls, model: type[T], field_name: str, field_value: object
636
+ ) -> T | None:
637
+ """根据字段值获取单条记录
638
+
639
+ Args:
640
+ model: SQLModel 模型类
641
+ field_name: 字段名
642
+ field_value: 字段值
643
+
644
+ Returns:
645
+ 模型实例,不存在时返回 None
646
+ """
647
+ with session_scope(cls.DB_TYPE) as session:
648
+ crud = _get_crud(model)
649
+ obj = crud.get_by_field(session, field_name, field_value)
650
+ if obj:
651
+ session.expunge(obj)
652
+ return obj
653
+
654
+ @classmethod
655
+ def list[T: SQLModel](
656
+ cls,
657
+ model: type[T],
658
+ *,
659
+ skip: int = 0,
660
+ limit: int = 100,
661
+ order_by: str | None = None,
662
+ desc: bool = False,
663
+ ) -> builtins.list[T]:
664
+ """获取多条记录(分页 + 排序)
665
+
666
+ Args:
667
+ model: SQLModel 模型类
668
+ skip: 跳过记录数
669
+ limit: 返回记录数上限
670
+ order_by: 排序字段名
671
+ desc: 是否降序排列
672
+
673
+ Returns:
674
+ 模型实例列表
675
+ """
676
+ with session_scope(cls.DB_TYPE) as session:
677
+ crud = _get_crud(model)
678
+ results = crud.get_multi(
679
+ session, skip=skip, limit=limit, order_by=order_by, desc=desc
680
+ )
681
+ for obj in results:
682
+ session.expunge(obj)
683
+ return results
684
+
685
+ @classmethod
686
+ def update[T: SQLModel](cls, model: type[T], id: object, data: FieldData) -> T:
687
+ """更新单条记录
688
+
689
+ Args:
690
+ model: SQLModel 模型类
691
+ id: 主键值
692
+ data: 需要更新的字段字典
693
+
694
+ Returns:
695
+ 更新后的模型实例
696
+ """
697
+ with session_scope(cls.DB_TYPE) as session:
698
+ crud = _get_crud(model)
699
+ obj = crud.get_or_raise(session, id)
700
+ crud.update(session, obj, data)
701
+ session.expunge(obj)
702
+ return obj
703
+
704
+ @classmethod
705
+ def delete[T: SQLModel](cls, model: type[T], id: object) -> bool:
706
+ """删除单条记录
707
+
708
+ Args:
709
+ model: SQLModel 模型类
710
+ id: 主键值
711
+
712
+ Returns:
713
+ True 表示删除成功,False 表示记录不存在
714
+ """
715
+ with session_scope(cls.DB_TYPE) as session:
716
+ crud = _get_crud(model)
717
+ obj = crud.delete(session, id)
718
+ return obj is not None
719
+
720
+ @classmethod
721
+ def upsert[T: SQLModel](
722
+ cls, model: type[T], data: FieldData, conflict_fields: builtins.list[str]
723
+ ) -> T:
724
+ """插入或更新记录
725
+
726
+ 根据 conflict_fields 判断记录是否已存在,存在则更新,不存在则插入。
727
+
728
+ Args:
729
+ model: SQLModel 模型类
730
+ data: 字段字典
731
+ conflict_fields: 用于判断冲突的字段列表
732
+
733
+ Returns:
734
+ 创建或更新后的模型实例
735
+ """
736
+ with session_scope(cls.DB_TYPE) as session:
737
+ crud = _get_crud(model)
738
+ obj = crud.upsert(session, data, conflict_fields)
739
+ session.expunge(obj)
740
+ return obj
741
+
742
+ @classmethod
743
+ def count(cls, model: type[SQLModel]) -> int:
744
+ """获取记录总数
745
+
746
+ Args:
747
+ model: SQLModel 模型类
748
+
749
+ Returns:
750
+ 记录总数
751
+ """
752
+ with session_scope(cls.DB_TYPE) as session:
753
+ crud = _get_crud(model)
754
+ return crud.count(session)
755
+
756
+ # ==================== 原生 SQL 操作 ====================
757
+
758
+ @classmethod
759
+ def query(
760
+ cls, sql: str, params: FieldData | None = None
761
+ ) -> builtins.list[dict[str, object]]:
762
+ """执行原生查询 SQL,返回字典列表
763
+
764
+ Args:
765
+ sql: SQL 查询语句(使用命名参数 :param)
766
+ params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开,
767
+ 可直接书写 ``WHERE id IN :ids``(三库通用)
768
+
769
+ Returns:
770
+ 查询结果列表,每行为一个字典
771
+
772
+ Note:
773
+ ``IN`` **不保证返回顺序**,需要顺序请自行按 id 重排;参数列表过大时
774
+ (如 PG 单语句参数上限 65535)应分批查询。
775
+ """
776
+ statement, bound = prepare_statement(sql, params)
777
+ with session_scope(cls.DB_TYPE, autocommit=False) as session:
778
+ result = session.execute(statement, bound or {})
779
+ rows = result.fetchall()
780
+ columns = result.keys()
781
+ data = [dict(zip(columns, row)) for row in rows]
782
+ logger.info(f"🔍 执行查询 → 返回 {len(data)} 行")
783
+ return data
784
+
785
+ @classmethod
786
+ def execute(
787
+ cls,
788
+ sql: str | TextClause,
789
+ params: FieldData | builtins.list[FieldData] | None = None,
790
+ ) -> int:
791
+ """执行原生更新 SQL(INSERT/UPDATE/DELETE),支持批量(executemany)
792
+
793
+ Args:
794
+ sql: SQL 语句(使用命名参数 ``:param``);也接受已构造好的
795
+ :class:`~sqlalchemy.TextClause`(如 ``build_raw_*`` 的返回值)
796
+ params: 两种形态:
797
+
798
+ - **None / 单个参数字典**:执行一次;值为 ``list`` / ``tuple`` /
799
+ ``set`` / ``frozenset`` 的参数按 ``IN`` 展开
800
+ (如 ``DELETE FROM t WHERE id IN :ids``,三库通用);
801
+ - **参数字典的列表**:批量执行(executemany,同一语句 + N 行参数,
802
+ 一次往返)。⚠ 与 ``IN`` 展开**互斥**(行值须为标量),
803
+ 各行字典的**键集必须完全一致**,**空列表**不触库直接返回 0。
804
+
805
+ Returns:
806
+ 受影响的行数(批量形态为各行累加;部分驱动对 executemany 不上报
807
+ 精确行数时可能为 ``-1``,请以数据为准)
808
+
809
+ Raises:
810
+ ValueError: 批量形态的行参数键集不一致,或行值中含序列类型
811
+ (批量与 ``IN`` 展开互斥)
812
+ """
813
+ if isinstance(params, builtins.list):
814
+ if not isinstance(sql, str):
815
+ raise ValueError("批量执行(executemany)要求传入 SQL 文本")
816
+ return cls._execute_batch(sql, params)
817
+ if isinstance(sql, TextClause):
818
+ statement, bound = sql, params
819
+ else:
820
+ statement, bound = prepare_statement(sql, params)
821
+ with session_scope(cls.DB_TYPE) as session:
822
+ result = session.execute(statement, bound or {})
823
+ affected = getattr(result, "rowcount", 0) or 0
824
+ logger.info(f"✅ 执行更新 → 影响 {affected} 行")
825
+ return affected
826
+
827
+ @classmethod
828
+ def _execute_batch(cls, sql: str, rows: builtins.list[FieldData]) -> int:
829
+ """批量执行(executemany):先本地预校验,再一次往返执行 N 行参数
830
+
831
+ 私有方法(不属于公共面):仅 ``execute`` 的列表形态会进入。
832
+
833
+ Args:
834
+ sql: SQL 语句(使用命名参数 ``:param``;**不传** ``params`` 构造语句,
835
+ 即不做 ``IN`` 展开——批量与展开参数互斥)
836
+ rows: 参数字典列表(非空;键集一致;值须为标量)
837
+
838
+ Returns:
839
+ 受影响的行数(各行累加;驱动不上报时为 ``-1``)
840
+ """
841
+ if not rows:
842
+ # 空列表语义:不触库、不报错,直接返回 0(DBAPI 对 executemany
843
+ # 传空列表会报 "A value is required for bind parameter")
844
+ logger.info("批量执行收到空参数列表 → 不执行任何语句")
845
+ return 0
846
+ _validate_batch_rows(rows)
847
+ statement, _ = prepare_statement(sql)
848
+ with session_scope(cls.DB_TYPE) as session:
849
+ result = session.execute(statement, rows)
850
+ affected = getattr(result, "rowcount", 0) or 0
851
+ logger.info(f"✅ 批量执行 → {len(rows)} 行参数,影响 {affected} 行")
852
+ return affected
853
+
854
+ # ==================== 原生表操作 ====================
855
+
856
+ @classmethod
857
+ def create_raw_table(
858
+ cls, table_name: str, columns: dict[str, str], if_not_exists: bool = True
859
+ ) -> None:
860
+ """根据「列名 → 列定义」字典创建普通表
861
+
862
+ Args:
863
+ table_name: 表名
864
+ columns: 列定义字典,如 {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
865
+ if_not_exists: 是否附加 IF NOT EXISTS(默认 True)
866
+
867
+ ⚠ 列定义须按**目标数据库方言**书写,本方法只做字符串拼接与执行,
868
+ 不做方言翻译:
869
+ PostgreSQL: {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
870
+ MySQL: {"id": "INT AUTO_INCREMENT PRIMARY KEY", "name": "VARCHAR(100)"}
871
+ SQLite: {"id": "INTEGER PRIMARY KEY", "name": "TEXT"}
872
+ """
873
+ column_defs = ", ".join(
874
+ f"{name} {definition}" for name, definition in columns.items()
875
+ )
876
+ if_not_exists_sql = "IF NOT EXISTS " if if_not_exists else ""
877
+ sql = f"CREATE TABLE {if_not_exists_sql}{table_name} ({column_defs})"
878
+ with get_engine(cls.DB_TYPE).connect() as conn:
879
+ conn.execute(text(sql))
880
+ conn.commit()
881
+ logger.info(f"✅ 创建表 {table_name}")
882
+
883
+ @classmethod
884
+ def build_raw_insert(
885
+ cls,
886
+ table_name: str,
887
+ data: dict[str, object],
888
+ *,
889
+ ignore_conflict: bool = False,
890
+ ) -> tuple[TextClause, dict[str, object]]:
891
+ """构造 INSERT 语句(**只拼装、不执行、不管事务**)
892
+
893
+ Args:
894
+ table_name: 表名(仅接受合法标识符)
895
+ data: 列名 → 值 字典(``dict`` / 序列值会按目标列类型编码为 JSON 文本)
896
+ ignore_conflict: True 时忽略唯一冲突——PG / SQLite 生成
897
+ ``ON CONFLICT DO NOTHING``,MySQL 生成 ``INSERT IGNORE``。
898
+ ⚠ MySQL 的 IGNORE 忽略范围更宽(含数据截断告警),三库不严格等价。
899
+
900
+ Returns:
901
+ ``(语句, 参数)``,供自有事务内执行:``session.execute(*build_raw_insert(...))``
902
+
903
+ Raises:
904
+ ValueError: 表名/列名非法、``data`` 为空、序列值但目标列不是 JSON 类型
905
+
906
+ Note:
907
+ 启用审计填充时自动补齐缺失的审计字段(未启用时行为与旧版一致)。
908
+ """
909
+ _check_identifier(table_name)
910
+ for name in data:
911
+ _check_identifier(name)
912
+
913
+ payload = dict(data) # 副本:不污染调用方 dict
914
+ fill_insert_for(cls.DB_TYPE, table_name, payload)
915
+ _adapt_write_values(cls.DB_TYPE, table_name, payload)
916
+ if not payload:
917
+ raise ValueError("build_raw_insert 的 data 不能为空")
918
+
919
+ columns = ", ".join(payload.keys())
920
+ placeholders = ", ".join(f":{name}" for name in payload)
921
+ if ignore_conflict and cls.DB_TYPE == MYSQL:
922
+ sql = f"INSERT IGNORE INTO {table_name} ({columns}) VALUES ({placeholders})"
923
+ else:
924
+ sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
925
+ if ignore_conflict:
926
+ sql = f"{sql} ON CONFLICT DO NOTHING"
927
+
928
+ stmt, bound = prepare_statement(sql, payload)
929
+ return stmt, cast(dict[str, object], bound)
930
+
931
+ @classmethod
932
+ def build_raw_update(
933
+ cls,
934
+ table_name: str,
935
+ data: dict[str, object],
936
+ where: str,
937
+ params: dict[str, object] | None = None,
938
+ ) -> tuple[TextClause, dict[str, object]]:
939
+ """构造 UPDATE 语句(**只拼装、不执行、不管事务**)
940
+
941
+ Args:
942
+ table_name: 表名(仅接受合法标识符)
943
+ data: 列名 → 新值(业务字段;``updated_*`` 由填充器补)
944
+ where: WHERE 子句(不含 ``WHERE`` 关键字)
945
+ params: where 的绑定参数(键名不得与 ``data`` 重复;值为序列时按 ``IN`` 展开)
946
+
947
+ Returns:
948
+ ``(语句, 参数)``:``session.execute(*build_raw_update(...))``
949
+
950
+ Raises:
951
+ ValueError: ``data`` 为空 / ``where`` 为空 / 标识符非法 / 绑定名冲突
952
+
953
+ Note:
954
+ 只刷新审计字段请用 :meth:`build_raw_touch`。
955
+ """
956
+ if not data:
957
+ raise ValueError(
958
+ "build_raw_update 的 data 不能为空;如需只刷新审计字段请用 raw_touch()"
959
+ )
960
+ if not where or not where.strip():
961
+ raise ValueError("build_raw_update 必须提供非空 where 子句")
962
+ _check_identifier(table_name)
963
+ for name in data:
964
+ _check_identifier(name)
965
+
966
+ payload = dict(data) # 副本:不污染调用方 dict
967
+ fill_update_for(cls.DB_TYPE, table_name, payload)
968
+ _adapt_write_values(cls.DB_TYPE, table_name, payload)
969
+ assignments = ", ".join(f"{name} = :{name}" for name in payload)
970
+
971
+ bound = dict(params or {})
972
+ conflict = set(payload) & set(bound)
973
+ if conflict:
974
+ raise ValueError(
975
+ f"data 与 params 的绑定名冲突: {sorted(conflict)};请改用其它参数名"
976
+ )
977
+ bound.update(payload)
978
+ sql = f"UPDATE {table_name} SET {assignments} WHERE {where}"
979
+ stmt, prepared = prepare_statement(sql, bound)
980
+ return stmt, cast(dict[str, object], prepared)
981
+
982
+ @classmethod
983
+ def build_raw_touch(
984
+ cls, table_name: str, where: str, params: dict[str, object] | None = None
985
+ ) -> tuple[TextClause, dict[str, object]]:
986
+ """构造「只刷新更新时间 / 更新人」的 UPDATE(**只拼装、不执行**)
987
+
988
+ Args:
989
+ table_name: 表名(仅接受合法标识符)
990
+ where: WHERE 子句(不含 ``WHERE`` 关键字)
991
+ params: where 的绑定参数
992
+
993
+ Returns:
994
+ ``(语句, 参数)``
995
+
996
+ Raises:
997
+ DBError: 审计填充未启用,或表没有任何 ``updated_at`` 相关列
998
+ ValueError: ``where`` 为空 / 标识符非法 / 绑定名冲突
999
+
1000
+ Note:
1001
+ SET 列取 ``updated_at`` 槽位候选(含内置别名 ``update_time``)与表列的交集;
1002
+ 两套列同时存在时都写。值来自 ``AuditConfig`` 的时钟与用户钩子。
1003
+ """
1004
+ if not where or not where.strip():
1005
+ raise ValueError("build_raw_touch 必须提供非空 where 子句")
1006
+ _check_identifier(table_name)
1007
+ if not AuditConfig.is_enabled():
1008
+ raise DBError(
1009
+ "build_raw_touch 需要审计填充:请先 AuditConfig.enable(...),"
1010
+ "或改用 raw_update 显式给字段"
1011
+ )
1012
+ if not touch_columns(cls.DB_TYPE, table_name):
1013
+ expected = " / ".join(candidate_columns(UPDATED_AT))
1014
+ raise DBError(
1015
+ f"表 {table_name} 没有 {expected} 中的任何一列,无法 touch;"
1016
+ f"请改用 raw_update 显式给字段"
1017
+ )
1018
+
1019
+ payload: dict[str, object] = {}
1020
+ fill_update(payload, table_columns(cls.DB_TYPE, table_name))
1021
+ assignments = ", ".join(f"{name} = :{name}" for name in payload)
1022
+
1023
+ bound = dict(params or {})
1024
+ conflict = set(payload) & set(bound)
1025
+ if conflict:
1026
+ raise ValueError(
1027
+ f"touch 字段与 params 的绑定名冲突: {sorted(conflict)};"
1028
+ f"请改用其它参数名"
1029
+ )
1030
+ bound.update(payload)
1031
+ sql = f"UPDATE {table_name} SET {assignments} WHERE {where}"
1032
+ stmt, prepared = prepare_statement(sql, bound)
1033
+ return stmt, cast(dict[str, object], prepared)
1034
+
1035
+ @classmethod
1036
+ def build_raw_delete(
1037
+ cls, table_name: str, where: str, params: dict[str, object] | None = None
1038
+ ) -> tuple[TextClause, dict[str, object]]:
1039
+ """构造 DELETE 语句(**只拼装、不执行、不管事务**)
1040
+
1041
+ Args:
1042
+ table_name: 表名(仅接受合法标识符)
1043
+ where: WHERE 子句(不含 ``WHERE`` 关键字;**必须非空**)
1044
+ params: where 的绑定参数
1045
+
1046
+ Returns:
1047
+ ``(语句, 参数)``
1048
+
1049
+ Raises:
1050
+ ValueError: ``where`` 为空 / 表名非法
1051
+
1052
+ Note:
1053
+ 复杂关联删除(``DELETE ... USING``、级联多表)请用 ``execute()`` 或
1054
+ ``transaction()`` 内的 ``session.execute`` 手写。
1055
+ """
1056
+ if not where or not where.strip():
1057
+ raise ValueError("build_raw_delete 必须提供非空 where 子句")
1058
+ _check_identifier(table_name)
1059
+ stmt, bound = prepare_statement(
1060
+ f"DELETE FROM {table_name} WHERE {where}", params
1061
+ )
1062
+ return stmt, cast(dict[str, object], bound or {})
1063
+
1064
+ @classmethod
1065
+ def raw_insert(
1066
+ cls, table_name: str, data: dict[str, object], *, ignore_conflict: bool = False
1067
+ ) -> int:
1068
+ """向指定表插入一行数据(键为列名)
1069
+
1070
+ Args:
1071
+ table_name: 表名(仅接受合法标识符)
1072
+ data: 列名 → 值 字典
1073
+ ignore_conflict: True 时忽略唯一冲突(PG / SQLite ``ON CONFLICT DO NOTHING``、
1074
+ MySQL ``INSERT IGNORE``;后者忽略范围更宽)
1075
+
1076
+ Returns:
1077
+ 受影响的行数(冲突被忽略时为 0)
1078
+
1079
+ Note:
1080
+ - 调用 ``AuditConfig.enable()`` 后自动补齐缺失的审计字段;
1081
+ - 事务内使用请改用 :meth:`build_raw_insert`。
1082
+
1083
+ Raises:
1084
+ ValueError: 表名/列名非法、``data`` 为空、序列值但目标列不是 JSON 类型
1085
+ """
1086
+ return cls.execute(
1087
+ *cls.build_raw_insert(table_name, data, ignore_conflict=ignore_conflict)
1088
+ )
1089
+
1090
+ @classmethod
1091
+ def raw_update(
1092
+ cls,
1093
+ table_name: str,
1094
+ data: dict[str, object],
1095
+ where: str,
1096
+ params: dict[str, object] | None = None,
1097
+ ) -> int:
1098
+ """按 where 条件更新数据(自动补 updated_*,需启用自动填充)
1099
+
1100
+ Args:
1101
+ table_name: 表名(仅接受合法标识符)
1102
+ data: 列名 → 新值(业务字段;``updated_*`` 由填充器补)
1103
+ where: WHERE 子句(**不含** ``WHERE`` 关键字,如 ``"id = :id"``)
1104
+ params: where 子句的绑定参数(键名不得与 ``data`` 的键重复)
1105
+
1106
+ Returns:
1107
+ 受影响的行数
1108
+
1109
+ Raises:
1110
+ ValueError: ``data`` 为空 / ``where`` 为空 / 标识符非法 /
1111
+ ``data`` 与 ``params`` 的绑定名冲突
1112
+
1113
+ Note:
1114
+ - 只刷新审计字段请用 :meth:`raw_touch`;
1115
+ - 事务内使用请改用 :meth:`build_raw_update`;
1116
+ - 无 WHERE 的全表更新属危险操作,请显式用 ``execute()`` 书写;
1117
+ - 未启用自动填充时,``data`` 原样写入(不加 ``updated_*``)。
1118
+
1119
+ 用法::
1120
+
1121
+ PgKit.raw_update(
1122
+ "writing_project",
1123
+ {"title": "新标题"},
1124
+ "id = :id AND created_by = :owner",
1125
+ {"id": 123, "owner": "admin"},
1126
+ )
1127
+ """
1128
+ return cls.execute(*cls.build_raw_update(table_name, data, where, params))
1129
+
1130
+ @classmethod
1131
+ def raw_touch(
1132
+ cls, table_name: str, where: str, params: dict[str, object] | None = None
1133
+ ) -> int:
1134
+ """只刷新更新时间 / 更新人(需先启用审计填充)
1135
+
1136
+ Args:
1137
+ table_name: 表名(仅接受合法标识符)
1138
+ where: WHERE 子句(不含 ``WHERE`` 关键字)
1139
+ params: where 的绑定参数
1140
+
1141
+ Returns:
1142
+ 受影响的行数
1143
+
1144
+ Raises:
1145
+ DBError: 审计填充未启用,或表没有任何 ``updated_at`` 相关列
1146
+ ValueError: ``where`` 为空 / 标识符非法 / 绑定名冲突
1147
+
1148
+ Note:
1149
+ 事务内使用请改用 :meth:`build_raw_touch`。
1150
+
1151
+ 用法::
1152
+
1153
+ PgKit.raw_touch("chat_session", "id = :id", {"id": 1})
1154
+ """
1155
+ return cls.execute(*cls.build_raw_touch(table_name, where, params))
1156
+
1157
+ @classmethod
1158
+ def raw_delete(
1159
+ cls, table_name: str, where: str, params: dict[str, object] | None = None
1160
+ ) -> int:
1161
+ """按 where 条件删除数据
1162
+
1163
+ Args:
1164
+ table_name: 表名(仅接受合法标识符)
1165
+ where: WHERE 子句(不含 ``WHERE`` 关键字;**必须非空**)
1166
+ params: where 的绑定参数
1167
+
1168
+ Returns:
1169
+ 受影响的行数
1170
+
1171
+ Raises:
1172
+ ValueError: ``where`` 为空 / 表名非法
1173
+
1174
+ Note:
1175
+ 事务内使用请改用 :meth:`build_raw_delete`;复杂关联删除
1176
+ (``DELETE ... USING``、级联多表)保留手写。
1177
+ """
1178
+ return cls.execute(*cls.build_raw_delete(table_name, where, params))
1179
+
1180
+ @classmethod
1181
+ def raw_get_by(
1182
+ cls, table_name: str, column: str, value: object
1183
+ ) -> dict[str, object] | None:
1184
+ """按单列等值查询一行
1185
+
1186
+ Args:
1187
+ table_name: 表名
1188
+ column: 列名
1189
+ value: 查询值
1190
+
1191
+ Returns:
1192
+ 匹配的第一行(字典);无匹配返回 None
1193
+
1194
+ Note:
1195
+ 开启软删除查询过滤(`AuditConfig.set_soft_delete_filter(True)`)后,
1196
+ 若表存在 deleted 列,会自动追加 ``deleted = 正常值`` 条件;
1197
+ 需读取已删除行时用 ``with AuditConfig.include_deleted():`` 包裹。
1198
+ """
1199
+ where = f"{column} = :value"
1200
+ params: dict[str, object] = {"value": value}
1201
+ predicate = deleted_predicate(cls.DB_TYPE, table_name)
1202
+ if predicate is not None:
1203
+ fragment, extra = predicate
1204
+ where = f"{where} AND {fragment}"
1205
+ params.update(extra)
1206
+
1207
+ rows = cls.query(
1208
+ f"SELECT * FROM {table_name} WHERE {where} LIMIT 1", params
1209
+ )
1210
+ return rows[0] if rows else None
1211
+
1212
+ # ==================== 事务管理 ====================
1213
+
1214
+ @classmethod
1215
+ @contextmanager
1216
+ def transaction(cls) -> Generator[Session, None, None]:
1217
+ """事务上下文管理器
1218
+
1219
+ 正常退出时自动提交,异常时自动回滚。
1220
+ 适用于多个操作需要原子性的场景。
1221
+
1222
+ Yields:
1223
+ SQLModel Session 实例
1224
+
1225
+ 用法::
1226
+
1227
+ with PgKit.transaction() as session:
1228
+ crud = CRUDBase(UserModel)
1229
+ user = crud.create(session, {"name": "test"})
1230
+ """
1231
+ with session_scope(cls.DB_TYPE) as session:
1232
+ yield session
1233
+
1234
+ # ==================== 表操作 ====================
1235
+
1236
+ @classmethod
1237
+ def list_tables(cls) -> builtins.list[str]:
1238
+ """列出数据库中的所有表"""
1239
+ return list_tables(cls.DB_TYPE)
1240
+
1241
+ @classmethod
1242
+ def table_exists(cls, table_name: str) -> bool:
1243
+ """检查表是否存在"""
1244
+ return table_exists(table_name, cls.DB_TYPE)
1245
+
1246
+ @classmethod
1247
+ def create_tables(cls, models: builtins.list[type[SQLModel]]) -> None:
1248
+ """创建数据库表
1249
+
1250
+ Args:
1251
+ models: 需要创建表的 SQLModel 模型类列表
1252
+ """
1253
+ create_tables(models, cls.DB_TYPE)
1254
+
1255
+ @classmethod
1256
+ @abstractmethod
1257
+ def get_table_info(cls, table_name: str) -> builtins.list[dict[str, object]]:
1258
+ """获取表的列信息
1259
+
1260
+ Args:
1261
+ table_name: 表名
1262
+
1263
+ Returns:
1264
+ 列信息字典列表(column_name, data_type, is_nullable 等)
1265
+ """