Skip to main content

yang_base/table/table_query/
write.rs

1//! 写入执行:写路径分 insert / update / delete / 批量 upsert 四类
2//! (各自带事务内变体),含插入数据准备(默认值/时间戳/租户注入)与更新数据校验。
3//!
4//! 公共入口按连接池/事务后端运行时分派:MySQL 分支保持原有行为,PostgreSQL 分支
5//! 复用同一套校验与守卫,仅替换底层 `yang_db::postgres::QueryBuilder`。
6
7#![cfg(any(feature = "mysql", feature = "postgres"))]
8
9use super::TableQuery;
10use crate::action::builtin::add::ReturningTarget;
11use crate::database::AnyTransaction;
12use crate::error::BaseError;
13use crate::table::field_config::Audience;
14use serde_json::Value;
15
16/// 将记录转为可写入的列映射。
17///
18/// MySQL 构建复用 `Record::into_columns`(既有内部契约);仅 PostgreSQL 时直接从
19/// `into_map` 收敛,避免依赖 MySQL 专属方法。
20fn record_into_columns(record: crate::table::Record) -> std::collections::HashMap<String, Value> {
21    #[cfg(feature = "mysql")]
22    {
23        record.into_columns()
24    }
25    #[cfg(not(feature = "mysql"))]
26    {
27        record.into_map().into_iter().collect()
28    }
29}
30
31/// 把 RETURNING / `last_insert_id` 得到的主键值收敛为 `u64`(仅整型兼容入口使用)。
32fn json_to_u64(value: &Value) -> Option<u64> {
33    match value {
34        Value::Number(number) => number
35            .as_u64()
36            .or_else(|| number.as_i64().and_then(|value| u64::try_from(value).ok())),
37        Value::String(text) => text.parse().ok(),
38        _ => None,
39    }
40}
41
42/// 批量 upsert 的计划产物:一次性校验通过的待写行集与 ODKU 赋值列。
43///
44/// 只由 [`TableQuery::plan_upsert_batch`] 构造,是「校验已完成、只剩执行」的中间态;
45/// 空批不会产出它(计划返回 `None`)。仅 MySQL 的 ODKU 路径消费该产物。
46#[cfg(feature = "mysql")]
47struct PreparedUpsertBatch {
48    /// 逐行同构的 INSERT 行(已补默认值/时间戳、已剔自增列)。
49    rows: Vec<std::collections::HashMap<String, Value>>,
50    /// ODKU 赋值列(已含 `updated_at`);列序由生成器按 INSERT 列序收敛。
51    tail: Vec<String>,
52}
53
54/// PostgreSQL 批量 upsert 的计划产物:待写行 + 调用方显式提供的列集。
55///
56/// `provided_columns` 用来校验显式 `update_columns`:只能点名调用方真正提供的列,
57/// 框架补出来的默认值 / `created_at` 不算「调用方想更新」。
58#[cfg(feature = "postgres")]
59#[derive(Debug)]
60struct PreparedPgUpsert {
61    rows: Vec<std::collections::HashMap<String, Value>>,
62    provided_columns: std::collections::BTreeSet<String>,
63}
64
65impl TableQuery {
66    /// 执行 INSERT 操作
67    ///
68    /// 插入数据到表中,包括以下步骤:
69    /// 1. 按表定义验证所有字段值
70    /// 2. 检查用户是否有字段的写入权限
71    /// 3. 构建 INSERT SQL 语句
72    /// 4. 执行插入操作
73    ///
74    /// # 返回值
75    ///
76    /// - `Ok(1)`:插入成功
77    /// - `Err(BaseError)`:插入失败
78    pub async fn insert(self, data: crate::table::Record) -> Result<u64, BaseError> {
79        // 填充默认值/时间戳并校验(顺序:写权限→填充默认值→必填/类型校验)
80        let data = self.prepare_and_validate_insert(record_into_columns(data))?;
81        match self.backend()? {
82            #[cfg(feature = "mysql")]
83            yang_db::BackendKind::MySql => {
84                self.compile_db_write_query()?
85                    .insert(&data)
86                    .await
87                    .map_err(BaseError::DatabaseExecuteFailed)?;
88            }
89            #[cfg(feature = "postgres")]
90            yang_db::BackendKind::PostgreSql => {
91                let database = self.pg_database()?;
92                let query = self.register_pg_fields(
93                    self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
94                    data.keys(),
95                )?;
96                // 单行插入用 `insert_batch`(无 RETURNING):主键可以是任意类型,
97                // 不要求整型自增列。
98                query
99                    .insert_batch(std::slice::from_ref(&data))
100                    .await
101                    .map_err(BaseError::DatabaseExecuteFailed)?;
102            }
103            other => {
104                return Err(BaseError::ConfigError(format!(
105                    "TableQuery 不支持当前数据库后端: {other:?}"
106                )));
107            }
108        }
109        Ok(1)
110    }
111
112    /// 在事务中执行 INSERT 操作
113    ///
114    /// 与 [`TableQuery::insert`] 完全一致的写权限校验/默认值填充/时间戳/必填校验
115    /// 流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
116    pub async fn insert_in_tx(
117        self,
118        tx: &mut AnyTransaction,
119        data: crate::table::Record,
120    ) -> Result<u64, BaseError> {
121        let data = self.prepare_and_validate_insert(record_into_columns(data))?;
122        match tx {
123            #[cfg(feature = "mysql")]
124            AnyTransaction::MySql(tx) => {
125                let query = tx.table(&self.table_config.table_ref);
126                self.apply_write_plan(query)?
127                    .insert(&data)
128                    .await
129                    .map_err(BaseError::DatabaseExecuteFailed)?;
130            }
131            #[cfg(feature = "postgres")]
132            AnyTransaction::Postgres(tx) => {
133                let query = tx.table(&self.table_config.table_ref);
134                let query =
135                    self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
136                query
137                    .insert_batch(std::slice::from_ref(&data))
138                    .await
139                    .map_err(BaseError::DatabaseExecuteFailed)?;
140            }
141        }
142        Ok(1)
143    }
144
145    /// 执行 INSERT 并返回 `RETURNING` 结果。
146    ///
147    /// - [`ReturningTarget::Pk`]:只返回主键列,UUID / text / numeric 等非整型主键
148    ///   也能正确回填;
149    /// - [`ReturningTarget::Columns`]:直接 `RETURNING <列...>`(单列/多列均可);
150    /// - [`ReturningTarget::All`]:返回整行。
151    ///
152    /// # MySQL 限制
153    ///
154    /// MySQL 没有 `RETURNING`:只有「目标就是整型主键」的请求能由 `last_insert_id`
155    /// 满足;`All`、多列或非主键列的 `Columns` 返回明确的
156    /// [`BaseError::ConfigError`],绝不用提交的输入伪造返回值。
157    pub async fn insert_returning(
158        self,
159        data: crate::table::Record,
160        target: ReturningTarget<'_>,
161    ) -> Result<crate::table::Record, BaseError> {
162        let data = self.prepare_and_validate_insert(record_into_columns(data))?;
163        match self.backend()? {
164            #[cfg(feature = "mysql")]
165            yang_db::BackendKind::MySql => {
166                let primary_key = self.table_config.primary_key.clone();
167                let allowed = match target {
168                    ReturningTarget::Pk => true,
169                    ReturningTarget::Columns(columns) => {
170                        columns.len() == 1 && columns[0] == primary_key.as_str()
171                    }
172                    ReturningTarget::All => false,
173                };
174                if !allowed {
175                    return Err(Self::mysql_returning_unsupported("非整型主键列或整行"));
176                }
177                let value = self.mysql_insert_returning_pk(&data).await?;
178                Ok(crate::table::Record::new().set(primary_key, value))
179            }
180            #[cfg(feature = "postgres")]
181            yang_db::BackendKind::PostgreSql => self.pg_insert_returning(&data, target).await,
182            other => Err(BaseError::ConfigError(format!(
183                "TableQuery 不支持当前数据库后端: {other:?}"
184            ))),
185        }
186    }
187
188    /// 批量 INSERT 并返回 `RETURNING` 行,保持输入顺序。
189    ///
190    /// PostgreSQL 走驱动的 `insert_batch_returning`:所有分片在同一事务内执行,
191    /// 任一分片失败或解码失败都会整体回滚。MySQL 没有 `RETURNING`,返回明确的
192    /// [`BaseError::ConfigError`],绝不按输入伪造返回值。
193    ///
194    /// 空批返回空向量,不生成语句。
195    #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
196    pub async fn insert_batch_returning(
197        self,
198        data: &[crate::table::Record],
199        target: ReturningTarget<'_>,
200    ) -> Result<Vec<crate::table::Record>, BaseError> {
201        match self.backend()? {
202            #[cfg(feature = "mysql")]
203            yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
204                "insert_batch_returning",
205            )),
206            #[cfg(feature = "postgres")]
207            yang_db::BackendKind::PostgreSql => {
208                let Some(rows) = self.prepare_pg_insert_rows(data)? else {
209                    return Ok(Vec::new());
210                };
211                let database = self.pg_database()?;
212                let query = self.register_pg_fields(
213                    self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
214                    rows[0].keys(),
215                )?;
216                self.apply_pg_returning_target(query, target)?
217                    .insert_batch_returning(&rows)
218                    .await
219                    .map_err(BaseError::DatabaseExecuteFailed)
220            }
221            other => Err(BaseError::ConfigError(format!(
222                "TableQuery 不支持当前数据库后端: {other:?}"
223            ))),
224        }
225    }
226
227    /// 在调用方事务内批量 INSERT 并返回 `RETURNING` 行。
228    ///
229    /// 校验/默认值/类型规则与 [`TableQuery::insert_batch_returning`] 完全一致,
230    /// 只是执行在调用方事务内。MySQL 同样明确返回 [`BaseError::ConfigError`]。
231    #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
232    pub async fn insert_batch_returning_in_tx(
233        self,
234        tx: &mut AnyTransaction,
235        data: &[crate::table::Record],
236        target: ReturningTarget<'_>,
237    ) -> Result<Vec<crate::table::Record>, BaseError> {
238        match tx {
239            #[cfg(feature = "mysql")]
240            AnyTransaction::MySql(_) => Err(Self::mysql_batch_returning_unsupported(
241                "insert_batch_returning_in_tx",
242            )),
243            #[cfg(feature = "postgres")]
244            AnyTransaction::Postgres(tx) => {
245                let Some(rows) = self.prepare_pg_insert_rows(data)? else {
246                    return Ok(Vec::new());
247                };
248                let query = self.register_pg_fields(
249                    self.apply_pg_write_plan(tx.table(&self.table_config.table_ref))?,
250                    rows[0].keys(),
251                )?;
252                self.apply_pg_returning_target(query, target)?
253                    .insert_batch_returning(&rows)
254                    .await
255                    .map_err(BaseError::DatabaseExecuteFailed)
256            }
257        }
258    }
259
260    /// 批量插入准备:逐行复用插入校验(默认值/时间戳/权限),空批返回 `Ok(None)`。
261    ///
262    /// 与驱动的批量 INSERT 一致,要求所有行最终列集相同;异构在触库前明确拒绝。
263    #[cfg(feature = "postgres")]
264    fn prepare_pg_insert_rows(
265        &self,
266        records: &[crate::table::Record],
267    ) -> Result<Option<Vec<std::collections::HashMap<String, Value>>>, BaseError> {
268        let mut rows = Vec::with_capacity(records.len());
269        let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
270        for (index, record) in records.iter().enumerate() {
271            let prepared = self.prepare_and_validate_insert(record_into_columns(record.clone()))?;
272            let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
273            match &base_keys {
274                Some(base) if *base != keys => {
275                    return Err(BaseError::ParamInvalid(
276                        "data".to_string(),
277                        format!(
278                            "批量 insert 第 {} 条记录提供的列集与第 1 条不一致",
279                            index + 1
280                        ),
281                    ));
282                }
283                None => base_keys = Some(keys),
284                _ => {}
285            }
286            rows.push(prepared);
287        }
288        Ok((!rows.is_empty()).then_some(rows))
289    }
290
291    /// 执行 INSERT 并返回真实类型的主键值。
292    ///
293    /// PostgreSQL 走 `INSERT ... RETURNING <主键>`;MySQL 走 `last_insert_id`
294    /// (仅整型主键,非整型返回明确错误)。返回 `(影响行数, 主键 JSON 值)`。
295    pub async fn insert_returning_pk_value(
296        self,
297        data: crate::table::Record,
298    ) -> Result<(u64, Value), BaseError> {
299        let data = self.prepare_and_validate_insert(record_into_columns(data))?;
300        match self.backend()? {
301            #[cfg(feature = "mysql")]
302            yang_db::BackendKind::MySql => {
303                let value = self.mysql_insert_returning_pk(&data).await?;
304                Ok((1, value))
305            }
306            #[cfg(feature = "postgres")]
307            yang_db::BackendKind::PostgreSql => {
308                let primary_key = self.table_config.primary_key.clone();
309                let record = self.pg_insert_returning(&data, ReturningTarget::Pk).await?;
310                let value = record.get(&primary_key).cloned().ok_or_else(|| {
311                    BaseError::ConfigError(
312                        "INSERT ... RETURNING 未返回主键列,无法回填主键".to_string(),
313                    )
314                })?;
315                Ok((1, value))
316            }
317            other => Err(BaseError::ConfigError(format!(
318                "TableQuery 不支持当前数据库后端: {other:?}"
319            ))),
320        }
321    }
322
323    /// 执行 INSERT 操作并返回自增主键(整型兼容入口)
324    ///
325    /// 内部经 [`TableQuery::insert_returning_pk_value`] 取回真实类型主键后再转成
326    /// `u64`;非整型主键在触库前返回明确的 [`BaseError::ParamInvalid`]。需要
327    /// UUID / text / numeric 主键时改用 `insert_returning_pk_value()` 或
328    /// [`TableQuery::insert_returning`]。
329    ///
330    /// # 返回值
331    ///
332    /// - `Ok((1, id))`:插入成功,返回 (影响行数, 主键值)。表无自增列时 `id` 为 0。
333    /// - `Err(BaseError)`:插入失败或主键非整型
334    pub async fn insert_returning_id(
335        self,
336        data: crate::table::Record,
337    ) -> Result<(u64, u64), BaseError> {
338        self.ensure_integer_primary_key()?;
339        let (affected, value) = self.insert_returning_pk_value(data).await?;
340        let id = json_to_u64(&value).ok_or_else(|| {
341            BaseError::ParamInvalid(
342                "primary_key".to_string(),
343                format!(
344                    "insert_returning_id 仅支持整型主键,当前主键值为 {value};\
345                     请改用 insert_returning_pk_value() 或 insert_returning(ReturningTarget::Pk)"
346                ),
347            )
348        })?;
349        Ok((affected, id))
350    }
351
352    /// 在事务中执行 INSERT 并返回自增主键
353    ///
354    /// 与 [`TableQuery::insert_returning_id`] 一致,但在事务内执行;整型主键限制
355    /// 同样适用。
356    pub async fn insert_returning_id_in_tx(
357        self,
358        tx: &mut AnyTransaction,
359        data: crate::table::Record,
360    ) -> Result<(u64, u64), BaseError> {
361        self.ensure_integer_primary_key()?;
362        let data = self.prepare_and_validate_insert(record_into_columns(data))?;
363        match tx {
364            #[cfg(feature = "mysql")]
365            AnyTransaction::MySql(tx) => {
366                let query = tx.table(&self.table_config.table_ref);
367                let id = self
368                    .apply_write_plan(query)?
369                    .insert(&data)
370                    .await
371                    .map_err(BaseError::DatabaseExecuteFailed)?;
372                Ok((1, id))
373            }
374            #[cfg(feature = "postgres")]
375            AnyTransaction::Postgres(tx) => {
376                let primary_key = self.field_ref(&self.table_config.primary_key)?;
377                let query = tx.table(&self.table_config.table_ref);
378                let query =
379                    self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
380                let id = query
381                    .returning(primary_key)
382                    .insert(&data)
383                    .await
384                    .map_err(BaseError::DatabaseExecuteFailed)?;
385                Ok((1, id))
386            }
387        }
388    }
389
390    /// 主键类型守卫:`insert_returning_id` 先把主键转成 `u64`,非整型在触库前拒绝。
391    fn ensure_integer_primary_key(&self) -> Result<(), BaseError> {
392        let primary_key = &self.table_config.primary_key;
393        let config = self.table_config.get_field(primary_key).ok_or_else(|| {
394            BaseError::FieldNotFound(self.table_config.table_name.clone(), primary_key.clone())
395        })?;
396        if matches!(
397            config.field_type,
398            crate::table::FieldType::Integer | crate::table::FieldType::BigInt
399        ) {
400            return Ok(());
401        }
402        Err(BaseError::ParamInvalid(
403            "primary_key".to_string(),
404            format!(
405                "insert_returning_id 仅支持整型主键,当前主键 {}.{primary_key} 为 {:?};\
406                 请改用 insert_returning_pk_value() / insert_returning(ReturningTarget::Pk) \
407                 取回真实类型主键,或 insert() 并在插入后按业务键查询",
408                self.table_config.table_name, config.field_type
409            ),
410        ))
411    }
412
413    /// MySQL 无 `RETURNING` 时的明确错误(不伪造返回值)。
414    #[cfg(feature = "mysql")]
415    fn mysql_returning_unsupported(what: &str) -> BaseError {
416        BaseError::ConfigError(format!(
417            "MySQL 不支持 INSERT ... RETURNING(请求 {what}):只能取回整型主键;\
418             请改用 insert_returning(ReturningTarget::Pk) 或插入后按业务键查询"
419        ))
420    }
421
422    /// MySQL 无 `RETURNING` 时批量写入的明确错误(不伪造返回值)。
423    #[cfg(feature = "mysql")]
424    fn mysql_batch_returning_unsupported(entry: &str) -> BaseError {
425        BaseError::ConfigError(format!(
426            "{entry} 仅支持 PostgreSQL:MySQL 没有 RETURNING,批量写入无法按真实行回填;\
427             请改用 PostgreSQL,或逐条写入后按业务键查询"
428        ))
429    }
430
431    /// MySQL 整型主键回填:调用方显式提供主键时用该值,否则用 `last_insert_id`。
432    #[cfg(feature = "mysql")]
433    async fn mysql_insert_returning_pk(
434        &self,
435        data: &std::collections::HashMap<String, Value>,
436    ) -> Result<Value, BaseError> {
437        self.ensure_integer_primary_key()?;
438        let primary_key = &self.table_config.primary_key;
439        if let Some(value) = data.get(primary_key).filter(|value| !value.is_null()) {
440            if json_to_u64(value).is_none() {
441                return Err(Self::mysql_returning_unsupported("非整型主键值"));
442            }
443            return Ok(value.clone());
444        }
445        let id = self
446            .compile_db_write_query()?
447            .insert(data)
448            .await
449            .map_err(BaseError::DatabaseExecuteFailed)?;
450        Ok(Value::Number(id.into()))
451    }
452
453    /// 把 `ReturningTarget` 应用到 PostgreSQL 查询:主键 / 指定列 / 整行。
454    #[cfg(feature = "postgres")]
455    fn apply_pg_returning_target<'a>(
456        &self,
457        query: yang_db::postgres::QueryBuilder<'a>,
458        target: ReturningTarget<'_>,
459    ) -> Result<yang_db::postgres::QueryBuilder<'a>, BaseError> {
460        match target {
461            ReturningTarget::Pk => {
462                Ok(query.returning(self.field_ref(&self.table_config.primary_key)?))
463            }
464            ReturningTarget::All => Ok(query.returning_all()),
465            ReturningTarget::Columns(columns) => {
466                if columns.is_empty() {
467                    return Err(BaseError::ParamInvalid(
468                        "columns".to_string(),
469                        "ReturningTarget::Columns 至少需要一列".to_string(),
470                    ));
471                }
472                for name in columns {
473                    if !self.table_config.fields.contains_key(*name) {
474                        return Err(BaseError::FieldNotFound(
475                            self.table_config.table_name.clone(),
476                            (*name).to_string(),
477                        ));
478                    }
479                }
480                let refs = self.pg_field_refs(columns)?;
481                Ok(query.returning_columns(&refs))
482            }
483        }
484    }
485
486    /// PostgreSQL `INSERT ... RETURNING`:按目标列取回。
487    #[cfg(feature = "postgres")]
488    async fn pg_insert_returning(
489        &self,
490        data: &std::collections::HashMap<String, Value>,
491        target: ReturningTarget<'_>,
492    ) -> Result<crate::table::Record, BaseError> {
493        let database = self.pg_database()?;
494        let query = self.register_pg_fields(
495            self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
496            data.keys(),
497        )?;
498        self.apply_pg_returning_target(query, target)?
499            .insert_returning(data)
500            .await
501            .map_err(BaseError::DatabaseExecuteFailed)
502    }
503
504    /// PostgreSQL 批量 UPSERT(非事务):多行 `INSERT ... ON CONFLICT (...) DO UPDATE`。
505    ///
506    /// `conflict_columns` 必须显式给出,且必须命中表上的唯一索引/约束——PostgreSQL
507    /// 的 `ON CONFLICT` 不做隐式推断,空切片会在触库前返回
508    /// [`BaseError::ParamInvalid`]。
509    ///
510    /// 冲突时更新的列使用**默认白名单**:插入列 − 冲突列 − 框架保护列(主键、租户
511    /// 字段、`created_at`/`deleted_at`、`source_file`/`company` 等审计归属列)。
512    /// 需要精确控制时用 [`TableQuery::upsert_batch_with_update_columns`]。
513    /// 返回受影响行数;空批返回 `Ok(0)`,不生成语句。
514    ///
515    /// 仅 `postgres` feature 提供。MySQL 继续使用
516    /// [`TableQuery::upsert_batch_in_tx`] 的 `ON DUPLICATE KEY UPDATE` 语义,
517    /// 本方法不改变 MySQL 的既有行为。
518    #[cfg(feature = "postgres")]
519    pub async fn upsert_batch(
520        self,
521        rows: Vec<crate::table::Record>,
522        conflict_columns: &[&str],
523    ) -> Result<u64, BaseError> {
524        let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
525            return Ok(0);
526        };
527        self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, false)
528            .await
529    }
530
531    /// 批量 UPSERT 并返回 `RETURNING` 行(保持输入顺序)。
532    ///
533    /// `conflict_columns` 语义与 [`TableQuery::upsert_batch`] 完全相同:PostgreSQL
534    /// 必须显式给出且命中唯一索引/约束;冲突时按默认白名单更新,返回写入后的行
535    /// (新插入行与冲突更新行都会出现在结果里)。
536    ///
537    /// MySQL 没有 `RETURNING`,明确返回 [`BaseError::ConfigError`]。空批返回空向量。
538    #[cfg_attr(not(feature = "postgres"), allow(unused_variables))]
539    pub async fn upsert_batch_returning(
540        self,
541        rows: Vec<crate::table::Record>,
542        conflict_columns: &[&str],
543        target: ReturningTarget<'_>,
544    ) -> Result<Vec<crate::table::Record>, BaseError> {
545        match self.backend()? {
546            #[cfg(feature = "mysql")]
547            yang_db::BackendKind::MySql => Err(Self::mysql_batch_returning_unsupported(
548                "upsert_batch_returning",
549            )),
550            #[cfg(feature = "postgres")]
551            yang_db::BackendKind::PostgreSql => {
552                let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
553                    return Ok(Vec::new());
554                };
555                let database = self.pg_database()?;
556                let conflicts = self.pg_field_refs(conflict_columns)?;
557                let query = self.register_pg_fields(
558                    database.table(&self.table_config.table_ref),
559                    prepared.rows[0].keys(),
560                )?;
561                let columns = self.resolve_pg_update_columns(&prepared, conflict_columns, None)?;
562                let query = if columns.is_empty() {
563                    query.do_nothing()
564                } else {
565                    let names: Vec<&str> = columns.iter().map(String::as_str).collect();
566                    query.update_columns(&self.pg_field_refs(&names)?)
567                };
568                self.apply_pg_returning_target(query, target)?
569                    .upsert_batch_returning(&prepared.rows, &conflicts)
570                    .await
571                    .map_err(BaseError::DatabaseExecuteFailed)
572            }
573            other => Err(BaseError::ConfigError(format!(
574                "TableQuery 不支持当前数据库后端: {other:?}"
575            ))),
576        }
577    }
578
579    /// PostgreSQL 批量 UPSERT,并显式指定 `DO UPDATE SET` 的更新列白名单。
580    ///
581    /// 更新列必须:存在于表定义、由调用方在待写行里提供、且不包含任何冲突列;
582    /// 另外主键/租户/创建时间/自动列永远不允许出现在赋值列里。配置了 `updated_at`
583    /// 时会被自动追加(语义同逐行 update)。
584    ///
585    /// 仅 `postgres` feature 提供。
586    #[cfg(feature = "postgres")]
587    pub async fn upsert_batch_with_update_columns(
588        self,
589        rows: Vec<crate::table::Record>,
590        conflict_columns: &[&str],
591        update_columns: &[&str],
592    ) -> Result<u64, BaseError> {
593        let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
594            return Ok(0);
595        };
596        self.execute_pg_upsert_batch(
597            prepared,
598            conflict_columns,
599            None,
600            Some(update_columns),
601            false,
602        )
603        .await
604    }
605
606    /// PostgreSQL 批量 UPSERT,冲突行保持原值(`ON CONFLICT (...) DO NOTHING`)。
607    ///
608    /// 与 [`TableQuery::upsert_batch`] 相同的前置处理;返回真正插入的行数。
609    /// 仅 `postgres` feature 提供。
610    #[cfg(feature = "postgres")]
611    pub async fn upsert_batch_do_nothing(
612        self,
613        rows: Vec<crate::table::Record>,
614        conflict_columns: &[&str],
615    ) -> Result<u64, BaseError> {
616        let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
617            return Ok(0);
618        };
619        self.execute_pg_upsert_batch(prepared, conflict_columns, None, None, true)
620            .await
621    }
622
623    /// PostgreSQL 批量 UPSERT,冲突目标带部分唯一索引谓词
624    /// (`ON CONFLICT (cols) WHERE (<predicate>) DO UPDATE ...`)。
625    ///
626    /// 前置校验与默认更新列白名单同 [`TableQuery::upsert_batch`];`predicate` 为
627    /// `yang-db` 的受信 SQL 表达式(拒绝分号 / 注释标记 / NUL)。表声明租户字段时,
628    /// 冲突列仍必须包含该字段。
629    ///
630    /// 仅 `postgres` feature 提供。需要在调用方事务内执行时用
631    /// [`TableQuery::upsert_batch_in_tx_with_conflict_predicate`]。
632    #[cfg(feature = "postgres")]
633    pub async fn upsert_batch_with_conflict_predicate(
634        self,
635        rows: Vec<crate::table::Record>,
636        conflict_columns: &[&str],
637        predicate: Option<&str>,
638    ) -> Result<u64, BaseError> {
639        let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
640            return Ok(0);
641        };
642        self.execute_pg_upsert_batch(prepared, conflict_columns, predicate, None, false)
643            .await
644    }
645
646    /// 在调用方事务内批量 upsert,返回受影响行数。
647    ///
648    /// 第三参数按运行时后端解释:
649    ///
650    /// - **MySQL**:`INSERT ... ON DUPLICATE KEY UPDATE` 的赋值列白名单(既有语义,
651    ///   未改变);
652    /// - **PostgreSQL**:`ON CONFLICT` 的冲突列,必填且必须命中唯一索引/约束。
653    ///   冲突时更新全部非冲突插入列(`yang-db` 默认);调用方不得依赖隐式冲突推断。
654    ///
655    /// 空批返回 `Ok(0)`,不生成语句。MySQL 的校验/默认值/时间戳/ODKU 行为与既有
656    /// 实现完全一致。
657    ///
658    /// # MySQL 调用方义务(框架不兜、也兜不了)
659    ///
660    /// - 冲突键由**表上的唯一索引**决定,本方法无法指定;
661    /// - 本方法**没有 WHERE**。身份列(如 `source_key`)必须由调用方自己从
662    ///   `update_columns` 里排除:把它放进赋值列,跨源命中就会把归属**静默改写**——
663    ///   而逐行路径的 `where_eq(id)+where_eq(owner)` 至少还会撞唯一索引响亮失败。
664    /// - 调用方应在事务前做归属预检,并在同一事务内做写后归属再断言。
665    ///
666    /// # MySQL 返回值
667    ///
668    /// `rows_affected` 之和 ∈ `[N, 2N]`(1=插入,2=更新且值有变;sqlx 带
669    /// `CLIENT_FOUND_ROWS` ⇒「命中但值未变」也计 1)。**不是行数**(要行数用
670    /// `rows.len()`),也**分不出** inserted/updated。
671    ///
672    /// # PostgreSQL 返回值
673    ///
674    /// 插入与更新各计 1 行;`DO NOTHING` 跳过的冲突行不计入。
675    pub async fn upsert_batch_in_tx(
676        self,
677        tx: &mut AnyTransaction,
678        rows: Vec<crate::table::Record>,
679        columns: &[&str],
680    ) -> Result<u64, BaseError> {
681        match tx {
682            #[cfg(feature = "mysql")]
683            AnyTransaction::MySql(tx) => {
684                // 空批 = 写 0 行:没写就没写,不发明语句(生成器也会拒空数据)。
685                let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
686                    return Ok(0);
687                };
688                // 不走 apply_write_plan:写路径计划只挂 WHERE 与软删守卫,而本方法两者都不支持
689                // (plan_upsert_batch 已把带 where / 软删表的调用拒掉),挂上去只会给人
690                // 「守卫已应用」的错觉。
691                tx.table(&self.table_config.table_ref)
692                    .upsert_batch(&batch.rows, &batch.tail)
693                    .await
694                    .map_err(BaseError::DatabaseExecuteFailed)
695            }
696            #[cfg(feature = "postgres")]
697            AnyTransaction::Postgres(tx) => {
698                let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
699                    return Ok(0);
700                };
701                self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, None, None, false)
702                    .await
703            }
704        }
705    }
706
707    /// 在调用方事务内批量 UPSERT,并显式指定 PostgreSQL 的更新列白名单。
708    ///
709    /// 与 [`TableQuery::upsert_batch_with_update_columns`] 的校验/默认值/时间戳
710    /// 规则完全一致,只是执行在调用方事务内。仅 `postgres` feature 提供。
711    #[cfg(feature = "postgres")]
712    pub async fn upsert_batch_in_tx_with_update_columns(
713        self,
714        tx: &mut AnyTransaction,
715        rows: Vec<crate::table::Record>,
716        conflict_columns: &[&str],
717        update_columns: &[&str],
718    ) -> Result<u64, BaseError> {
719        match tx {
720            AnyTransaction::Postgres(tx) => {
721                let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
722                    return Ok(0);
723                };
724                self.execute_pg_upsert_batch_in_tx(
725                    tx,
726                    &prepared,
727                    conflict_columns,
728                    None,
729                    Some(update_columns),
730                    false,
731                )
732                .await
733            }
734            #[cfg(feature = "mysql")]
735            AnyTransaction::MySql(_) => Err(BaseError::ConfigError(
736                "upsert_batch_in_tx_with_update_columns 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx(rows, update_columns) 的 ON DUPLICATE KEY UPDATE 语义"
737                    .to_string(),
738            )),
739        }
740    }
741
742    /// 在调用方事务内执行 PostgreSQL 批量 UPSERT,冲突行保持原值
743    /// (`ON CONFLICT (...) DO NOTHING`)。
744    ///
745    /// 仅 `postgres` feature 提供;MySQL 事务返回明确的
746    /// [`BaseError::ConfigError`](MySQL 的 `DO NOTHING` 等价入口是 ODKU 的空赋值
747    /// 白名单,语义不同,因此不在这里伪装)。
748    #[cfg(feature = "postgres")]
749    pub async fn upsert_batch_do_nothing_in_tx(
750        self,
751        tx: &mut AnyTransaction,
752        rows: Vec<crate::table::Record>,
753        conflict_columns: &[&str],
754    ) -> Result<u64, BaseError> {
755        match tx {
756            AnyTransaction::Postgres(tx) => {
757                let Some(prepared) = self.prepare_pg_upsert_rows(rows, conflict_columns)? else {
758                    return Ok(0);
759                };
760                self.execute_pg_upsert_batch_in_tx(tx, &prepared, conflict_columns, None, None, true)
761                    .await
762            }
763            #[cfg(feature = "mysql")]
764            AnyTransaction::MySql(_) => Err(BaseError::ConfigError(
765                "upsert_batch_do_nothing_in_tx 仅支持 PostgreSQL;MySQL 请使用 upsert_batch_in_tx 的 ON DUPLICATE KEY UPDATE 语义"
766                    .to_string(),
767            )),
768        }
769    }
770
771    /// 在调用方事务内批量 upsert,并为冲突目标指定部分唯一索引谓词
772    /// (`ON CONFLICT (<columns>) WHERE (<predicate>) DO ...`)。
773    ///
774    /// `predicate` 为 `None` 时与原 [`TableQuery::upsert_batch_in_tx`] 完全一致。
775    ///
776    /// - **PostgreSQL**:把谓词透传给 `yang-db` 的
777    ///   `postgres::QueryBuilder::on_conflict_with_predicate`。
778    /// - **MySQL**:`ON DUPLICATE KEY UPDATE` 没有部分索引冲突谓词。传入
779    ///   `Some(_)` 时明确返回 [`BaseError::ConfigError`],绝不静默丢弃谓词。
780    ///
781    /// 表声明租户字段时,冲突列必须包含该字段(PostgreSQL 校验)。
782    pub async fn upsert_batch_in_tx_with_conflict_predicate(
783        self,
784        tx: &mut AnyTransaction,
785        rows: Vec<crate::table::Record>,
786        columns: &[&str],
787        predicate: Option<&str>,
788    ) -> Result<u64, BaseError> {
789        match tx {
790            #[cfg(feature = "mysql")]
791            AnyTransaction::MySql(tx) => {
792                if let Some(predicate) = predicate {
793                    return Err(BaseError::ConfigError(format!(
794                        "MySQL 不支持 ON DUPLICATE KEY UPDATE 的冲突谓词(收到 `{predicate}`);\
795                         请改用 PostgreSQL,或去掉谓词后使用 upsert_batch_in_tx"
796                    )));
797                }
798                let Some(batch) = self.plan_upsert_batch(rows, columns)? else {
799                    return Ok(0);
800                };
801                tx.table(&self.table_config.table_ref)
802                    .upsert_batch(&batch.rows, &batch.tail)
803                    .await
804                    .map_err(BaseError::DatabaseExecuteFailed)
805            }
806            #[cfg(feature = "postgres")]
807            AnyTransaction::Postgres(tx) => {
808                let Some(prepared) = self.prepare_pg_upsert_rows(rows, columns)? else {
809                    return Ok(0);
810                };
811                self.execute_pg_upsert_batch_in_tx(tx, &prepared, columns, predicate, None, false)
812                    .await
813            }
814        }
815    }
816
817    /// PostgreSQL 批量 upsert 的准备:逐行复用插入校验,返回 `Ok(None)` 表示空批。
818    ///
819    /// 与 MySQL 的 [`TableQuery::plan_upsert_batch`] 保持同一失败面(where /
820    /// where_any / 软删守卫无法表达),差别只在冲突列:`ON CONFLICT` 的冲突列
821    /// 必须由调用方显式给出,且每行待写数据都必须包含这些列。
822    #[cfg(feature = "postgres")]
823    fn prepare_pg_upsert_rows(
824        &self,
825        rows: Vec<crate::table::Record>,
826        conflict_columns: &[&str],
827    ) -> Result<Option<PreparedPgUpsert>, BaseError> {
828        let total = rows.len();
829        if total == 0 {
830            return Ok(None);
831        }
832
833        // ON CONFLICT 没有 WHERE:带条件的调用会被静默忽略(写错行远比报错危险)。
834        // `where_any` 在 PG 池上登记为 any_conditions,同样是对行集的条件过滤,
835        // 而所有 PG upsert 执行器都不消费它——只检查 where_conditions 会让该过滤
836        // 条件被静默丢弃,必须一并拒绝。
837        if !self.query_params.where_conditions.is_empty() || !self.any_conditions.is_empty() {
838            return Err(BaseError::ParamInvalid(
839                "where".to_string(),
840                "批量 upsert 不支持 where / where_any 条件:ON CONFLICT 没有 WHERE,条件会被静默忽略"
841                    .to_string(),
842            ));
843        }
844        if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
845            return Err(BaseError::ParamInvalid(
846                "soft_delete_field".to_string(),
847                "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
848                    .to_string(),
849            ));
850        }
851        if conflict_columns.is_empty() {
852            return Err(BaseError::ParamInvalid(
853                "conflict_columns".to_string(),
854                "PostgreSQL 批量 upsert 必须显式指定冲突列(ON CONFLICT 目标)".to_string(),
855            ));
856        }
857        for name in conflict_columns {
858            if !self.table_config.fields.contains_key(*name) {
859                return Err(BaseError::FieldNotFound(
860                    self.table_config.table_name.clone(),
861                    (*name).to_string(),
862                ));
863            }
864        }
865        // 表声明了租户字段时,冲突键必须包含它:否则同一业务唯一键可能命中他租户行,
866        // 默认/显式 update 列就会跨租户改写。
867        if let Some(tenant_field) = self.tenant_key_field() {
868            if !conflict_columns.contains(&tenant_field) {
869                return Err(BaseError::ParamInvalid(
870                    "conflict_columns".to_string(),
871                    format!(
872                        "表 {} 声明了租户字段 `{tenant_field}`,批量 upsert 的冲突列必须包含该字段,否则会跨租户改写",
873                        self.table_config.table_name
874                    ),
875                ));
876            }
877        }
878
879        let mut prepared_rows = Vec::with_capacity(total);
880        let mut base_keys: Option<std::collections::BTreeSet<String>> = None;
881        let mut provided_columns = std::collections::BTreeSet::new();
882        for (index, record) in rows.into_iter().enumerate() {
883            // prepare 之前先抓调用方提供的列:之后补出来的默认值 / created_at
884            // 不能算「调用方想更新」。
885            let provided: std::collections::BTreeSet<String> =
886                record.as_map().keys().cloned().collect();
887            if index == 0 {
888                provided_columns = provided.clone();
889            } else if provided != provided_columns {
890                return Err(BaseError::ParamInvalid(
891                    "rows".to_string(),
892                    format!(
893                        "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
894                        index + 1
895                    ),
896                ));
897            }
898
899            let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
900            let keys: std::collections::BTreeSet<String> = prepared.keys().cloned().collect();
901            match &base_keys {
902                Some(base) if *base != keys => {
903                    return Err(BaseError::ParamInvalid(
904                        "rows".to_string(),
905                        format!(
906                            "批量 upsert 第 {} 条记录提供的列集与第 1 条不一致",
907                            index + 1
908                        ),
909                    ));
910                }
911                None => base_keys = Some(keys),
912                _ => {}
913            }
914            for name in conflict_columns {
915                if !prepared.contains_key(*name) {
916                    return Err(BaseError::ParamInvalid(
917                        "conflict_columns".to_string(),
918                        format!("冲突列 `{name}` 不在第 {} 条待写记录里", index + 1),
919                    ));
920                }
921            }
922            prepared_rows.push(prepared);
923        }
924
925        Ok(Some(PreparedPgUpsert {
926            rows: prepared_rows,
927            provided_columns,
928        }))
929    }
930
931    /// 把列名解析为 `yang-db` 的字段引用。
932    #[cfg(feature = "postgres")]
933    fn pg_field_refs(&self, columns: &[&str]) -> Result<Vec<&yang_db::FieldRef>, BaseError> {
934        columns.iter().map(|name| self.field_ref(name)).collect()
935    }
936
937    /// 返回表定义中声明为 `tenant_key` 的租户隔离字段。
938    #[cfg(feature = "postgres")]
939    fn tenant_key_field(&self) -> Option<&str> {
940        self.table_config
941            .fields
942            .iter()
943            .find_map(|(name, field)| field.tenant_key.then_some(name.as_str()))
944    }
945
946    /// 框架保护的列:主键 / 租户 / 自动列 / 创建时间 / 软删时间,upsert 一律不得覆盖。
947    fn is_framework_owned_column(&self, name: &str) -> bool {
948        if name == self.table_config.primary_key {
949            return true;
950        }
951        if let Some((tenant_field, _)) = &self.tenant_scope {
952            if tenant_field == name {
953                return true;
954            }
955        }
956        if self
957            .table_config
958            .get_field(name)
959            .is_some_and(|field| field.tenant_key || field.auto_increment)
960        {
961            return true;
962        }
963        if let Some(ts) = &self.table_config.timestamp_fields {
964            if ts.created_at.as_deref() == Some(name) || ts.deleted_at.as_deref() == Some(name) {
965                return true;
966            }
967        }
968        matches!(name, "created_at" | "tenant_id")
969    }
970
971    /// 默认 upsert 白名单额外排除的审计/归属列(显式白名单仍可由调用方点名)。
972    #[cfg(feature = "postgres")]
973    fn is_default_upsert_excluded_column(&self, name: &str) -> bool {
974        self.is_framework_owned_column(name) || matches!(name, "source_file" | "company")
975    }
976
977    /// PostgreSQL 默认 upsert 更新列白名单:插入列 − 冲突列 − 框架保护列。
978    ///
979    /// 审计/归属列(`created_at`、`source_file`、`company`、租户、主键)默认不覆盖,
980    /// 避免一次 upsert 把创建时间或归属重置掉。
981    #[cfg(feature = "postgres")]
982    fn default_pg_update_columns(
983        &self,
984        insert_columns: &[String],
985        conflict_columns: &[&str],
986    ) -> Vec<String> {
987        insert_columns
988            .iter()
989            .filter(|name| !conflict_columns.contains(&name.as_str()))
990            .filter(|name| !self.is_default_upsert_excluded_column(name))
991            .cloned()
992            .collect()
993    }
994
995    /// 校验显式更新列并去重:必须存在于表、由调用方提供、且不是冲突列。
996    #[cfg(feature = "postgres")]
997    fn validate_pg_update_columns(
998        &self,
999        provided_columns: &std::collections::BTreeSet<String>,
1000        conflict_columns: &[&str],
1001        update_columns: &[&str],
1002    ) -> Result<Vec<String>, BaseError> {
1003        if update_columns.is_empty() {
1004            return Err(BaseError::ParamInvalid(
1005                "update_columns".to_string(),
1006                "批量 upsert 至少需要一个可更新列".to_string(),
1007            ));
1008        }
1009        let mut columns = Vec::with_capacity(update_columns.len());
1010        for name in update_columns {
1011            if !self.table_config.fields.contains_key(*name) {
1012                return Err(BaseError::FieldNotFound(
1013                    self.table_config.table_name.clone(),
1014                    (*name).to_string(),
1015                ));
1016            }
1017            if conflict_columns.contains(name) {
1018                return Err(BaseError::ParamInvalid(
1019                    "update_columns".to_string(),
1020                    format!("更新列 `{name}` 是冲突列,不能出现在 DO UPDATE SET 里"),
1021                ));
1022            }
1023            if !provided_columns.contains(*name) {
1024                return Err(BaseError::ParamInvalid(
1025                    "update_columns".to_string(),
1026                    format!("更新列 `{name}` 不在调用方提供的待写列里"),
1027                ));
1028            }
1029            if self.is_framework_owned_column(name) {
1030                return Err(BaseError::ParamInvalid(
1031                    "update_columns".to_string(),
1032                    format!("更新列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1033                ));
1034            }
1035            if !columns.iter().any(|existing| existing == name) {
1036                columns.push((*name).to_string());
1037            }
1038        }
1039        // 与逐行 update 一致:配置了 updated_at 时自动追加。
1040        if let Some(updated_at) = self
1041            .table_config
1042            .timestamp_fields
1043            .as_ref()
1044            .and_then(|fields| fields.updated_at.as_ref())
1045            .filter(|name| self.table_config.fields.contains_key(*name))
1046        {
1047            if !columns.iter().any(|existing| existing == updated_at) {
1048                columns.push(updated_at.clone());
1049            }
1050        }
1051        Ok(columns)
1052    }
1053
1054    /// 解析本次 upsert 的 `DO UPDATE SET` 列:显式白名单或默认白名单。
1055    #[cfg(feature = "postgres")]
1056    fn resolve_pg_update_columns(
1057        &self,
1058        prepared: &PreparedPgUpsert,
1059        conflict_columns: &[&str],
1060        update_columns: Option<&[&str]>,
1061    ) -> Result<Vec<String>, BaseError> {
1062        match update_columns {
1063            Some(explicit) => self.validate_pg_update_columns(
1064                &prepared.provided_columns,
1065                conflict_columns,
1066                explicit,
1067            ),
1068            None => {
1069                let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1070                Ok(self.default_pg_update_columns(&insert_columns, conflict_columns))
1071            }
1072        }
1073    }
1074
1075    /// 在连接池上执行已准备的 PostgreSQL 批量 upsert。
1076    #[cfg(feature = "postgres")]
1077    async fn execute_pg_upsert_batch(
1078        self,
1079        prepared: PreparedPgUpsert,
1080        conflict_columns: &[&str],
1081        conflict_predicate: Option<&str>,
1082        update_columns: Option<&[&str]>,
1083        do_nothing: bool,
1084    ) -> Result<u64, BaseError> {
1085        let database = self.pg_database()?;
1086        let conflicts = self.pg_field_refs(conflict_columns)?;
1087        let query = self.register_pg_fields(
1088            database.table(&self.table_config.table_ref),
1089            prepared.rows[0].keys(),
1090        )?;
1091        let query = match conflict_predicate {
1092            Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1093            None => query,
1094        };
1095        let query = if do_nothing {
1096            query.do_nothing()
1097        } else {
1098            let columns =
1099                self.resolve_pg_update_columns(&prepared, conflict_columns, update_columns)?;
1100            if columns.is_empty() {
1101                // 全部插入列都是冲突列/受保护列:冲突行没有可写列,等价 DO NOTHING。
1102                query.do_nothing()
1103            } else {
1104                let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1105                let refs = self.pg_field_refs(&names)?;
1106                query.update_columns(&refs)
1107            }
1108        };
1109        query
1110            .upsert_batch(&prepared.rows, &conflicts)
1111            .await
1112            .map_err(BaseError::DatabaseExecuteFailed)
1113    }
1114
1115    /// 在调用方事务内执行已准备的 PostgreSQL 批量 upsert。
1116    #[cfg(feature = "postgres")]
1117    async fn execute_pg_upsert_batch_in_tx(
1118        &self,
1119        tx: &mut yang_db::postgres::Transaction,
1120        prepared: &PreparedPgUpsert,
1121        conflict_columns: &[&str],
1122        conflict_predicate: Option<&str>,
1123        update_columns: Option<&[&str]>,
1124        do_nothing: bool,
1125    ) -> Result<u64, BaseError> {
1126        let conflicts = self.pg_field_refs(conflict_columns)?;
1127        let query = self.register_pg_fields(
1128            tx.table(&self.table_config.table_ref),
1129            prepared.rows[0].keys(),
1130        )?;
1131        let query = match conflict_predicate {
1132            Some(predicate) => query.on_conflict_with_predicate(&conflicts, predicate),
1133            None => query,
1134        };
1135        let query = if do_nothing {
1136            query.do_nothing()
1137        } else {
1138            let columns =
1139                self.resolve_pg_update_columns(prepared, conflict_columns, update_columns)?;
1140            if columns.is_empty() {
1141                query.do_nothing()
1142            } else {
1143                let names: Vec<&str> = columns.iter().map(String::as_str).collect();
1144                let refs = self.pg_field_refs(&names)?;
1145                query.update_columns(&refs)
1146            }
1147        };
1148        query
1149            .upsert_batch(&prepared.rows, &conflicts)
1150            .await
1151            .map_err(BaseError::DatabaseExecuteFailed)
1152    }
1153
1154    /// 校验并准备一批 MySQL ODKU upsert:`Ok(None)` = 空批(写 0 行),
1155    /// `Ok(Some(_))` = 可执行计划。
1156    ///
1157    /// 失败面顺序即调用方踩坑的顺序:空批 → where → 软删 → 逐行列集 → 赋值列。
1158    #[cfg(feature = "mysql")]
1159    fn plan_upsert_batch(
1160        &self,
1161        rows: Vec<crate::table::Record>,
1162        update_columns: &[&str],
1163    ) -> Result<Option<PreparedUpsertBatch>, BaseError> {
1164        let total = rows.len();
1165        let mut records = rows.into_iter();
1166        // 空批 = 写 0 行:没有第一行可推赋值列,也不发明语句。
1167        let Some(first) = records.next() else {
1168            return Ok(None);
1169        };
1170
1171        // ODKU 没有 WHERE:带条件的调用会被静默忽略(写错行远比报错危险),直接拒绝。
1172        if !self.query_params.where_conditions.is_empty() {
1173            return Err(BaseError::ParamInvalid(
1174                "where".to_string(),
1175                "批量 upsert 不支持 where 条件:ON DUPLICATE KEY UPDATE 没有 WHERE,条件会被静默忽略"
1176                    .to_string(),
1177            ));
1178        }
1179        // 软删守卫是 `deleted_at IS NULL` 这类 WHERE,批量 upsert 表达不了:命中已软删行时
1180        // 会把它们改活,而逐行 update 路径上这会被守卫挡住。
1181        if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
1182            return Err(BaseError::ParamInvalid(
1183                "soft_delete_field".to_string(),
1184                "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
1185                    .to_string(),
1186            ));
1187        }
1188
1189        // 第 1 条记录的两套列集就是全批基准:provided 管「省略即重置」,prepared 管列集
1190        // 异构。先取 provided 再 prepare——prepare 会把默认值与时间戳补进来,之后就分不出
1191        // 「调用方写过这一列」与「框架补的」了。
1192        let first_provided: std::collections::BTreeSet<String> =
1193            first.as_map().keys().cloned().collect();
1194        let first_prepared = self.prepare_and_validate_insert(record_into_columns(first))?;
1195        let first_prepared_keys: std::collections::BTreeSet<String> =
1196            first_prepared.keys().cloned().collect();
1197
1198        let mut prepared_rows = Vec::with_capacity(total);
1199        prepared_rows.push(first_prepared);
1200        for (offset, record) in records.enumerate() {
1201            let provided: std::collections::BTreeSet<String> =
1202                record.as_map().keys().cloned().collect();
1203            let prepared = self.prepare_and_validate_insert(record_into_columns(record))?;
1204            let prepared_keys: std::collections::BTreeSet<String> =
1205                prepared.keys().cloned().collect();
1206            // 第 1 条在循环外已处理,这里从第 2 条起数。
1207            let row_number = offset + 2;
1208            // 某行省略了带默认值的列 ⇒ 批量路径会拿第 1 行的值替它做 ODKU 赋值,等价于
1209            // 「省略即重置」(prepared 两侧都被默认值补齐,只看 prepared 拦不住)。
1210            if provided != first_provided {
1211                return Err(BaseError::ParamInvalid(
1212                    "rows".to_string(),
1213                    format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1214                ));
1215            }
1216            // 列集异构交给生成器只会得到一条更晚、更难归因的 SerializationError。
1217            if prepared_keys != first_prepared_keys {
1218                return Err(BaseError::ParamInvalid(
1219                    "rows".to_string(),
1220                    format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
1221                ));
1222            }
1223            prepared_rows.push(prepared);
1224        }
1225
1226        if update_columns.is_empty() {
1227            return Err(BaseError::ParamInvalid(
1228                "update_columns".to_string(),
1229                "批量 upsert 至少需要一个可更新列(ON DUPLICATE KEY UPDATE 的赋值列)".to_string(),
1230            ));
1231        }
1232        for name in update_columns {
1233            // 要求 ⊆ provided 而不是 ⊆ prepared:prepared 里有框架补出来的默认值与
1234            // created_at,让它们进赋值列就等于「省略即重置」「创建时间被刷新」。
1235            // created_at 不必单独排除:它是 Audience::Nobody,调用方提交会先吃
1236            // FieldPermissionDenied,永远进不了 provided,上一条已把它挡住。
1237            if !first_provided.contains(*name) {
1238                return Err(BaseError::ParamInvalid(
1239                    "update_columns".to_string(),
1240                    format!(
1241                        "赋值列 `{name}` 不在调用方提供的列里(框架补出来的默认值与 created_at 不能当赋值列)"
1242                    ),
1243                ));
1244            }
1245            if self
1246                .table_config
1247                .get_field(name)
1248                .is_some_and(|field| field.auto_increment)
1249            {
1250                return Err(BaseError::ParamInvalid(
1251                    "update_columns".to_string(),
1252                    format!("赋值列 `{name}` 是自增列,不能出现在 ON DUPLICATE KEY UPDATE 里"),
1253                ));
1254            }
1255        }
1256        // 与 PostgreSQL 默认白名单同一套守卫:主键/租户/创建时间/审计归属列
1257        // 一律不许进 ODKU 赋值列。
1258        for name in update_columns {
1259            if self.is_framework_owned_column(name) {
1260                return Err(BaseError::ParamInvalid(
1261                    "update_columns".to_string(),
1262                    format!("赋值列 `{name}` 是主键/租户/创建时间等框架保护列,不能被 upsert 覆盖"),
1263                ));
1264            }
1265        }
1266
1267        // 赋值列 = 调用方白名单(去重)+ updated_at(语义同 with_updated_timestamp:列存在
1268        // 且不在集合里时追加)。列序不在这里排:生成器按 INSERT 列序收敛。
1269        let mut tail: Vec<String> = Vec::with_capacity(update_columns.len() + 1);
1270        for name in update_columns {
1271            if !tail.iter().any(|existing| existing.as_str() == *name) {
1272                tail.push((*name).to_string());
1273            }
1274        }
1275        if let Some(updated_at) = self
1276            .table_config
1277            .timestamp_fields
1278            .as_ref()
1279            .and_then(|fields| fields.updated_at.as_ref())
1280            .filter(|name| self.table_config.fields.contains_key(*name))
1281        {
1282            if !tail.iter().any(|existing| existing == updated_at) {
1283                tail.push(updated_at.clone());
1284            }
1285        }
1286
1287        Ok(Some(PreparedUpsertBatch {
1288            rows: prepared_rows,
1289            tail,
1290        }))
1291    }
1292
1293    /// 填充默认值/时间戳并验证插入数据
1294    ///
1295    /// 处理顺序(修复 required+default 字段被误报 FieldRequired 的问题):
1296    /// 1. 字段与写权限校验:显式提交只读字段时拒绝;null 自增主键视为未提供
1297    /// 2. 规范化数据库生成字段:未提供或为 null 的自增字段交给数据库生成
1298    /// 3. 填充默认值:data 中缺失且配置了 `default_value` 的字段补默认值
1299    /// 4. 填充时间戳:`timestamp_fields` 配置且列存在、调用方未提供时,写入当前时间
1300    /// 5. 必填/类型/验证器校验:在补齐后的数据上执行
1301    pub(crate) fn prepare_and_validate_insert(
1302        &self,
1303        data: std::collections::HashMap<String, Value>,
1304    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1305        let mut prepared = data;
1306
1307        // tenant key 只能由请求上下文注入,业务输入不得覆盖。
1308        if let Some((field, value)) = &self.tenant_scope {
1309            if prepared.contains_key(field) {
1310                return Err(BaseError::PermissionDenied(format!(
1311                    "禁止显式写入租户字段: {field}"
1312                )));
1313            }
1314            prepared.insert(field.clone(), value.clone());
1315        }
1316
1317        // 1. 校验调用方显式提交的字段和写权限。只有 null 自增主键可视为“未提供”,
1318        // 其余只读字段即使提交 null 也必须拒绝,避免绕过字段边界并覆盖数据库默认值。
1319        for (field_name, value) in &prepared {
1320            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1321                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1322            })?;
1323            let omitted_auto_increment = field_config.auto_increment && value.is_null();
1324            let injected_tenant = self
1325                .tenant_scope
1326                .as_ref()
1327                .is_some_and(|(tenant_field, _)| tenant_field == field_name);
1328            if !injected_tenant
1329                && !omitted_auto_increment
1330                && !field_config.permissions.can_write(&self.user_roles_set)
1331            {
1332                return Err(BaseError::FieldPermissionDenied(
1333                    self.table_config.table_name.clone(),
1334                    field_name.clone(),
1335                    "用户无写入权限".to_string(),
1336                ));
1337            }
1338        }
1339
1340        // 2. 数据库生成的自增字段未提供或为 null 时,不进入 INSERT 字段列表。
1341        for (field_name, field_config) in &self.table_config.fields {
1342            if field_config.auto_increment
1343                && prepared
1344                    .get(field_name)
1345                    .map(serde_json::Value::is_null)
1346                    .unwrap_or(true)
1347            {
1348                prepared.remove(field_name);
1349            }
1350        }
1351
1352        // 3. 填充默认值(仅缺失时;显式 null 仍受 nullable/required 约束)
1353        for (field_name, field_config) in &self.table_config.fields {
1354            if field_config.auto_increment {
1355                continue;
1356            }
1357            if let Some(default) = &field_config.default_value {
1358                if !prepared.contains_key(field_name) {
1359                    prepared.insert(field_name.clone(), default.clone());
1360                }
1361            }
1362        }
1363
1364        // 4. 填充创建/更新时间戳(列存在且调用方未提供时)
1365        if let Some(ts) = &self.table_config.timestamp_fields {
1366            let now = chrono::Utc::now().timestamp();
1367            for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
1368                if self.table_config.fields.contains_key(ts_field) {
1369                    let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
1370                    if missing {
1371                        prepared.insert(ts_field.clone(), Value::Number(now.into()));
1372                    }
1373                }
1374            }
1375        }
1376
1377        // 5. 在补齐后的数据上执行必填/类型/验证器校验
1378        for (field_name, field_config) in &self.table_config.fields {
1379            if !field_config.permissions.can_write(&self.user_roles_set) {
1380                continue;
1381            }
1382            if field_config.auto_increment && !prepared.contains_key(field_name) {
1383                continue;
1384            }
1385            let value = prepared.get(field_name).unwrap_or(&Value::Null);
1386            field_config.validate(value, &self.regex_cache)?;
1387        }
1388
1389        Ok(prepared)
1390    }
1391
1392    /// 软删表零 WHERE 写的全表写保护。
1393    ///
1394    /// 未 `with_trashed()` 时,`apply_where_guards` / `apply_pg_where_guards` 会把
1395    /// 软删字段 `IS NULL` 注入 yang-db 的 conditions 列表,使 yang-db 的
1396    /// `conditions.is_empty()` 全表写保护失效——零 WHERE 的 update/delete 会静默
1397    /// 改写/软删整表存活行。框架契约(`error/mod.rs` 的 `MissingWhereClause`:
1398    /// 无 WHERE 的更新/删除始终被拒绝)要求在这里显式判定。
1399    ///
1400    /// 调用位置仅限 update/update_in_tx/delete/delete_in_tx:不能放进
1401    /// `apply_write_plan` / `apply_pg_write_plan`(INSERT 共用,WHERE 天然为空),
1402    /// 也不能放进读写共享的 `apply_*_where_guards`(无过滤读查询合法)。
1403    ///
1404    /// 判空同时计入 `where_conditions` 与 `any_conditions`(PG `where_any` 只在
1405    /// PG 池时登记到后者,否则降级为 `where_in` 写入前者)。租户 `scope_tenant`
1406    /// 与主键定位等框架注入的条件本就写入 `where_conditions`,因此合法的租户
1407    /// 范围批量写不受影响。
1408    ///
1409    /// 只覆盖 `!include_trashed && soft_delete_field.is_some()`:非软删表与
1410    /// `with_trashed()` 的零 WHERE 写保持 yang-db 既有的错误行为,不迁移错误码。
1411    fn ensure_soft_delete_write_has_where(&self, op: &str) -> Result<(), BaseError> {
1412        if self.include_trashed || self.table_config.soft_delete_field.is_none() {
1413            return Ok(());
1414        }
1415        if self.query_params.where_conditions.is_empty() && self.any_conditions.is_empty() {
1416            return Err(BaseError::MissingWhereClause(op.to_string()));
1417        }
1418        Ok(())
1419    }
1420
1421    /// 执行 UPDATE 操作
1422    ///
1423    /// 更新表中的数据,包括以下步骤:
1424    /// 1. 按表定义验证所有字段值
1425    /// 2. 检查用户是否有字段的写入权限
1426    /// 3. 构建 UPDATE SQL 语句
1427    /// 4. 应用已配置的 WHERE 条件
1428    /// 5. 执行更新操作
1429    pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
1430        let data = self.prepare_update_data(record_into_columns(data))?;
1431        // 数据校验/字段权限之后、触库之前:软删守卫会填满 conditions,必须在此
1432        // 按契约拒绝零 WHERE 的整表更新。
1433        self.ensure_soft_delete_write_has_where("UPDATE")?;
1434        match self.backend()? {
1435            #[cfg(feature = "mysql")]
1436            yang_db::BackendKind::MySql => self
1437                .compile_db_write_query()?
1438                .update(&data)
1439                .await
1440                .map_err(BaseError::DatabaseExecuteFailed),
1441            #[cfg(feature = "postgres")]
1442            yang_db::BackendKind::PostgreSql => {
1443                let database = self.pg_database()?;
1444                let query = self.register_pg_fields(
1445                    self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1446                    data.keys(),
1447                )?;
1448                query
1449                    .update(&data)
1450                    .await
1451                    .map_err(BaseError::DatabaseExecuteFailed)
1452            }
1453            other => Err(BaseError::ConfigError(format!(
1454                "TableQuery 不支持当前数据库后端: {other:?}"
1455            ))),
1456        }
1457    }
1458
1459    /// 在事务中执行 UPDATE 操作
1460    ///
1461    /// 与 [`TableQuery::update`] 一致的字段校验/权限/WHERE 守卫/自动 `updated_at`
1462    /// 逻辑,但在事务内执行。
1463    pub async fn update_in_tx(
1464        self,
1465        tx: &mut AnyTransaction,
1466        data: crate::table::Record,
1467    ) -> Result<u64, BaseError> {
1468        let data = self.prepare_update_data(record_into_columns(data))?;
1469        self.ensure_soft_delete_write_has_where("UPDATE")?;
1470        match tx {
1471            #[cfg(feature = "mysql")]
1472            AnyTransaction::MySql(tx) => {
1473                let query = tx.table(&self.table_config.table_ref);
1474                self.apply_write_plan(query)?
1475                    .update(&data)
1476                    .await
1477                    .map_err(BaseError::DatabaseExecuteFailed)
1478            }
1479            #[cfg(feature = "postgres")]
1480            AnyTransaction::Postgres(tx) => {
1481                let query = tx.table(&self.table_config.table_ref);
1482                let query =
1483                    self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1484                query
1485                    .update(&data)
1486                    .await
1487                    .map_err(BaseError::DatabaseExecuteFailed)
1488            }
1489        }
1490    }
1491
1492    fn prepare_update_data(
1493        &self,
1494        data: std::collections::HashMap<String, Value>,
1495    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1496        self.validate_update_data(&data)?;
1497        self.with_updated_timestamp(data)
1498    }
1499
1500    fn with_updated_timestamp(
1501        &self,
1502        mut data: std::collections::HashMap<String, Value>,
1503    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1504        if data.is_empty() {
1505            return Err(BaseError::ParamInvalid(
1506                "data".to_string(),
1507                "无可更新字段".to_string(),
1508            ));
1509        }
1510        if let Some(updated_at) = self
1511            .table_config
1512            .timestamp_fields
1513            .as_ref()
1514            .and_then(|fields| fields.updated_at.as_ref())
1515            .filter(|name| self.table_config.fields.contains_key(*name))
1516        {
1517            data.insert(
1518                updated_at.clone(),
1519                Value::Number(chrono::Utc::now().timestamp().into()),
1520            );
1521        }
1522        Ok(data)
1523    }
1524
1525    /// 验证更新数据
1526    #[cfg(test)]
1527    pub fn validate_update_data(
1528        &self,
1529        data: &std::collections::HashMap<String, Value>,
1530    ) -> Result<(), BaseError> {
1531        self.validate_update_data_impl(data)
1532    }
1533
1534    /// 验证更新数据(内部实现)
1535    #[cfg(not(test))]
1536    fn validate_update_data(
1537        &self,
1538        data: &std::collections::HashMap<String, Value>,
1539    ) -> Result<(), BaseError> {
1540        self.validate_update_data_impl(data)
1541    }
1542
1543    /// 验证更新数据的实际实现
1544    fn validate_update_data_impl(
1545        &self,
1546        data: &std::collections::HashMap<String, Value>,
1547    ) -> Result<(), BaseError> {
1548        if data.is_empty() {
1549            return Err(BaseError::ParamInvalid(
1550                "data".to_string(),
1551                "至少需要一个更新字段".to_string(),
1552            ));
1553        }
1554        self.validate_update_fields(data, None)
1555    }
1556
1557    /// 校验待写字段的存在性/写权限/类型;`skip` 命中的列由框架自行写入,不参与校验。
1558    fn validate_update_fields(
1559        &self,
1560        data: &std::collections::HashMap<String, Value>,
1561        skip: Option<&str>,
1562    ) -> Result<(), BaseError> {
1563        // 只验证提供的字段(与 INSERT 不同,UPDATE 不需要验证所有字段)
1564        for (field_name, value) in data {
1565            if skip.is_some_and(|name| name == field_name) {
1566                continue;
1567            }
1568            if self
1569                .tenant_scope
1570                .as_ref()
1571                .is_some_and(|(tenant_field, _)| tenant_field == field_name)
1572            {
1573                return Err(BaseError::PermissionDenied(format!(
1574                    "禁止修改租户字段: {field_name}"
1575                )));
1576            }
1577            // 1. 检查字段是否存在于表配置中
1578            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
1579                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
1580            })?;
1581
1582            // 2. 检查用户是否有写入权限
1583            if !field_config.permissions.can_write(&self.user_roles_set) {
1584                return Err(BaseError::FieldPermissionDenied(
1585                    self.table_config.table_name.clone(),
1586                    field_name.clone(),
1587                    "用户无写入权限".to_string(),
1588                ));
1589            }
1590
1591            // 3. 验证显式提供的字段值。部分更新不要求提交其它必填字段,但若本字段
1592            // 被显式设为 null,仍执行 required 约束。
1593            field_config.validate(value, &self.regex_cache)?;
1594        }
1595
1596        Ok(())
1597    }
1598
1599    /// 准备软删除写入的标记数据。
1600    ///
1601    /// 软删标记本身由框架写入,因此与逐行 update 共用同一字段校验路径,但写权限
1602    /// 仍保持默认 `Nobody`(纯框架托管)的软删列不参与 can_write 判定;开发者
1603    /// 显式把软删列声明为角色可写/全员可写时,仍按声明校验。
1604    fn prepare_soft_delete_data(
1605        &self,
1606        data: std::collections::HashMap<String, Value>,
1607    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
1608        let framework_managed = self.table_config.soft_delete_field.as_ref().filter(|name| {
1609            self.table_config
1610                .get_field(name)
1611                .is_some_and(|field| matches!(field.permissions.writable, Audience::Nobody))
1612        });
1613        self.validate_update_fields(&data, framework_managed.map(String::as_str))?;
1614        self.with_updated_timestamp(data)
1615    }
1616
1617    /// 批量 upsert 的**计划**(不连库、不执行)——测试专用。
1618    ///
1619    /// 只把 [`TableQuery::plan_upsert_batch`] 的产物摊平成 `(待写行集, 赋值列)`,让无库
1620    /// 用例能断言「哪些列进了 INSERT、哪些列进了 ODKU 尾巴」;生产路径不经过这里。
1621    // 摊平元组比再发明一个测试专用结构体更省;clippy 只嫌它长。
1622    #[allow(clippy::type_complexity)]
1623    #[cfg(all(test, feature = "mysql"))]
1624    pub fn upsert_batch_plan_for_test(
1625        &self,
1626        rows: Vec<crate::table::Record>,
1627        update_columns: &[&str],
1628    ) -> Result<Option<(Vec<std::collections::HashMap<String, Value>>, Vec<String>)>, BaseError>
1629    {
1630        Ok(self
1631            .plan_upsert_batch(rows, update_columns)?
1632            .map(|batch| (batch.rows, batch.tail)))
1633    }
1634
1635    /// 执行 DELETE 操作
1636    ///
1637    /// 删除表中的数据,支持软删除和物理删除两种模式:
1638    /// 1. 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
1639    /// 2. 如果未配置软删除字段,执行物理删除
1640    /// 3. 应用已配置的 WHERE 条件
1641    pub async fn delete(self) -> Result<u64, BaseError> {
1642        if let Some(soft_delete_field) = self.table_config.soft_delete_field.clone() {
1643            let data = self.prepare_soft_delete_data(std::collections::HashMap::from([(
1644                soft_delete_field,
1645                Value::Number(chrono::Utc::now().timestamp().into()),
1646            )]))?;
1647            // 软删走 UPDATE 标记:守卫注入的 `deleted_at IS NULL` 会让 yang-db 误判
1648            // 「已有 WHERE」,零 WHERE 的 delete 会静默软删整表存活行。
1649            self.ensure_soft_delete_write_has_where("DELETE")?;
1650            return self.execute_soft_delete(data).await;
1651        }
1652        self.execute_physical_delete().await
1653    }
1654
1655    /// 软删除执行:两种后端都走 UPDATE 标记。
1656    async fn execute_soft_delete(
1657        self,
1658        data: std::collections::HashMap<String, Value>,
1659    ) -> Result<u64, BaseError> {
1660        match self.backend()? {
1661            #[cfg(feature = "mysql")]
1662            yang_db::BackendKind::MySql => self
1663                .compile_db_write_query()?
1664                .update(&data)
1665                .await
1666                .map_err(BaseError::DatabaseExecuteFailed),
1667            #[cfg(feature = "postgres")]
1668            yang_db::BackendKind::PostgreSql => {
1669                let database = self.pg_database()?;
1670                let query = self.register_pg_fields(
1671                    self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?,
1672                    data.keys(),
1673                )?;
1674                query
1675                    .update(&data)
1676                    .await
1677                    .map_err(BaseError::DatabaseExecuteFailed)
1678            }
1679            other => Err(BaseError::ConfigError(format!(
1680                "TableQuery 不支持当前数据库后端: {other:?}"
1681            ))),
1682        }
1683    }
1684
1685    /// 物理删除执行。
1686    async fn execute_physical_delete(self) -> Result<u64, BaseError> {
1687        match self.backend()? {
1688            #[cfg(feature = "mysql")]
1689            yang_db::BackendKind::MySql => self
1690                .compile_db_write_query()?
1691                .delete()
1692                .await
1693                .map_err(BaseError::DatabaseExecuteFailed),
1694            #[cfg(feature = "postgres")]
1695            yang_db::BackendKind::PostgreSql => {
1696                let database = self.pg_database()?;
1697                self.apply_pg_write_plan(database.table(&self.table_config.table_ref))?
1698                    .delete()
1699                    .await
1700                    .map_err(BaseError::DatabaseExecuteFailed)
1701            }
1702            other => Err(BaseError::ConfigError(format!(
1703                "TableQuery 不支持当前数据库后端: {other:?}"
1704            ))),
1705        }
1706    }
1707
1708    /// 在事务中执行 DELETE 操作
1709    ///
1710    /// 与 [`TableQuery::delete`] 一致:配置了软删除字段时走 UPDATE 标记(同样在
1711    /// 事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
1712    pub async fn delete_in_tx(self, tx: &mut AnyTransaction) -> Result<u64, BaseError> {
1713        // 软删标记与逐行 update 走同一字段校验路径(含 can_write),再进入事务分支。
1714        let soft_delete_data = self
1715            .table_config
1716            .soft_delete_field
1717            .clone()
1718            .map(|field| {
1719                self.prepare_soft_delete_data(std::collections::HashMap::from([(
1720                    field,
1721                    Value::Number(chrono::Utc::now().timestamp().into()),
1722                )]))
1723            })
1724            .transpose()?;
1725        // 与 delete() 同一守卫:软删标记在事务内同样是 UPDATE,零 WHERE 必须拒绝。
1726        self.ensure_soft_delete_write_has_where("DELETE")?;
1727        match tx {
1728            #[cfg(feature = "mysql")]
1729            AnyTransaction::MySql(tx) => {
1730                let query = tx.table(&self.table_config.table_ref);
1731                if let Some(data) = soft_delete_data {
1732                    return self
1733                        .apply_write_plan(query)?
1734                        .update(&data)
1735                        .await
1736                        .map_err(BaseError::DatabaseExecuteFailed);
1737                }
1738                self.apply_write_plan(query)?
1739                    .delete()
1740                    .await
1741                    .map_err(BaseError::DatabaseExecuteFailed)
1742            }
1743            #[cfg(feature = "postgres")]
1744            AnyTransaction::Postgres(tx) => {
1745                let query = tx.table(&self.table_config.table_ref);
1746                if let Some(data) = soft_delete_data {
1747                    let query =
1748                        self.register_pg_fields(self.apply_pg_write_plan(query)?, data.keys())?;
1749                    return query
1750                        .update(&data)
1751                        .await
1752                        .map_err(BaseError::DatabaseExecuteFailed);
1753                }
1754                self.apply_pg_write_plan(query)?
1755                    .delete()
1756                    .await
1757                    .map_err(BaseError::DatabaseExecuteFailed)
1758            }
1759        }
1760    }
1761}
1762
1763#[cfg(all(test, feature = "postgres"))]
1764mod pg_tests {
1765    use super::*;
1766    use crate::table::{Field, Record, Table};
1767    use std::sync::Arc;
1768
1769    fn lazy_query(table: Table) -> TableQuery {
1770        let definition = table.build().expect("测试表定义应有效");
1771        TableQuery::new(
1772            definition.shared_config(),
1773            Arc::from(Vec::<String>::new()),
1774            None,
1775        )
1776    }
1777
1778    /// `where_any` 在 PG 池上登记到 `any_conditions`;批量 upsert 的 ON CONFLICT
1779    /// 无法表达行过滤,必须与 `where_conditions` 一样被拒绝,不能静默丢弃。
1780    /// (RED:修复前只检查 `where_conditions`,该过滤条件会被丢弃并写成功。)
1781    #[test]
1782    fn pg_upsert_rejects_where_any_conditions() {
1783        let mut query = lazy_query(Table::new("pg_upsert_where_any").fields([
1784            Field::id("id"),
1785            Field::string("option_key", 64).required(),
1786            Field::string("label", 64).required(),
1787        ]));
1788        query
1789            .any_conditions
1790            .push(("option_key".to_string(), vec![serde_json::json!("opt_a")]));
1791        let rows = vec![Record::new().set("option_key", "opt_a").set("label", "x")];
1792
1793        let error = query
1794            .prepare_pg_upsert_rows(rows, &["option_key"])
1795            .expect_err("where_any 条件不得在批量 upsert 中被静默忽略");
1796        match error {
1797            BaseError::ParamInvalid(field, message) => {
1798                assert_eq!(field, "where");
1799                assert!(
1800                    message.contains("where_any"),
1801                    "错误信息应点名 where_any: {message}"
1802                );
1803            }
1804            other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1805        }
1806    }
1807
1808    /// PostgreSQL 的 insert_returning_id 依赖 RETURNING 整型主键;字符串主键必须
1809    /// 明确报错并给出可执行指引,不能静默委托给底层返回含糊错误。
1810    #[test]
1811    fn insert_returning_id_rejects_non_integer_primary_key() {
1812        let query = lazy_query(Table::new("pg_string_pk").fields([
1813            Field::string("code", 32).primary_key().required(),
1814            Field::string("name", 32).required(),
1815        ]));
1816
1817        let error = query
1818            .ensure_integer_primary_key()
1819            .expect_err("字符串主键必须被拒绝");
1820        match error {
1821            BaseError::ParamInvalid(field, message) => {
1822                assert_eq!(field, "primary_key");
1823                assert!(
1824                    message.contains("insert_returning_id"),
1825                    "错误信息应指引到 insert_returning_id: {message}"
1826                );
1827                assert!(
1828                    message.contains("insert()"),
1829                    "错误信息应给出替代入口: {message}"
1830                );
1831            }
1832            other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1833        }
1834    }
1835
1836    /// 整型主键(Integer / BigInt)必须放行。
1837    #[test]
1838    fn insert_returning_id_accepts_integer_primary_key() {
1839        let query = lazy_query(
1840            Table::new("pg_int_pk").fields([Field::id("id"), Field::string("name", 32).required()]),
1841        );
1842
1843        query.ensure_integer_primary_key().expect("整型主键应放行");
1844    }
1845
1846    /// 表声明了租户字段时,`ON CONFLICT` 的显式冲突列必须包含它,否则可能命中
1847    /// 他租户行并被 DO UPDATE 改写。
1848    #[test]
1849    fn pg_upsert_requires_tenant_key_in_conflict_columns() {
1850        let query = lazy_query(Table::new("pg_upsert_tenant_conflict").fields([
1851            Field::id("id"),
1852            Field::bigint("tenant_id").tenant_key(),
1853            Field::string("option_key", 64).required(),
1854            Field::string("label", 64).required(),
1855        ]));
1856        let rows = vec![Record::new()
1857            .set("tenant_id", 1_i64)
1858            .set("option_key", "opt_a")
1859            .set("label", "x")];
1860
1861        let error = query
1862            .prepare_pg_upsert_rows(rows, &["option_key"])
1863            .expect_err("缺少租户冲突列必须拒绝");
1864        match error {
1865            BaseError::ParamInvalid(field, message) => {
1866                assert_eq!(field, "conflict_columns");
1867                assert!(
1868                    message.contains("tenant_id"),
1869                    "错误信息应点名租户字段: {message}"
1870                );
1871            }
1872            other => panic!("应返回 ParamInvalid,实际: {other:?}"),
1873        }
1874    }
1875
1876    /// 冲突列包含租户字段时放行,且默认更新列白名单必须排除租户列。
1877    #[test]
1878    fn pg_default_update_columns_exclude_tenant_key() {
1879        let query = lazy_query(Table::new("pg_upsert_tenant_whitelist").fields([
1880            Field::id("id"),
1881            Field::bigint("tenant_id").tenant_key(),
1882            Field::string("option_key", 64).required(),
1883            Field::string("label", 64).required(),
1884        ]));
1885        let rows = vec![Record::new()
1886            .set("tenant_id", 1_i64)
1887            .set("option_key", "opt_a")
1888            .set("label", "x")];
1889        let prepared = query
1890            .prepare_pg_upsert_rows(rows, &["tenant_id", "option_key"])
1891            .expect("含租户冲突列应通过校验")
1892            .expect("非空批应产出计划");
1893        let insert_columns: Vec<String> = prepared.rows[0].keys().cloned().collect();
1894        let update_columns =
1895            query.default_pg_update_columns(&insert_columns, &["tenant_id", "option_key"]);
1896
1897        assert!(
1898            !update_columns.contains(&"tenant_id".to_string()),
1899            "默认白名单不得包含租户列: {update_columns:?}"
1900        );
1901        assert!(
1902            update_columns.contains(&"label".to_string()),
1903            "非保护业务列应在默认白名单内: {update_columns:?}"
1904        );
1905    }
1906}
1907
1908#[cfg(all(test, feature = "mysql"))]
1909mod batch_returning_mysql_tests {
1910    use super::*;
1911    use crate::database::AnyPool;
1912    use crate::table::{Field, Record, Table};
1913    use std::sync::Arc;
1914
1915    fn lazy_mysql_query(table: Table) -> TableQuery {
1916        let definition = table.build().expect("测试表定义应有效");
1917        let pool = sqlx::mysql::MySqlPoolOptions::new()
1918            .connect_lazy("mysql://root@127.0.0.1:3306/test")
1919            .expect("懒连接池构造不应触发网络连接");
1920        TableQuery::new(
1921            definition.shared_config(),
1922            Arc::from(Vec::<String>::new()),
1923            Some(AnyPool::MySql(Arc::new(pool))),
1924        )
1925    }
1926
1927    /// MySQL 没有 `RETURNING`:批量 insert 必须明确返回 ConfigError,绝不降级为
1928    /// 「按输入伪造返回值」。
1929    #[tokio::test]
1930    async fn insert_batch_returning_rejects_mysql() {
1931        let query = lazy_mysql_query(
1932            Table::new("tq_batch_returning_mysql")
1933                .fields([Field::id("id"), Field::string("label", 32).required()]),
1934        );
1935
1936        let error = query
1937            .insert_batch_returning(&[Record::new().set("label", "x")], ReturningTarget::Pk)
1938            .await
1939            .expect_err("MySQL 批量 RETURNING 必须被拒绝");
1940        assert!(
1941            matches!(
1942                error,
1943                BaseError::ConfigError(ref message) if message.contains("insert_batch_returning")
1944            ),
1945            "应返回 ConfigError 并点名入口,实际: {error:?}"
1946        );
1947    }
1948
1949    /// 批量 upsert 的 RETURNING 同样在 MySQL 上明确拒绝。
1950    #[tokio::test]
1951    async fn upsert_batch_returning_rejects_mysql() {
1952        let query = lazy_mysql_query(Table::new("tq_batch_upsert_returning_mysql").fields([
1953            Field::id("id"),
1954            Field::string("option_key", 32).required(),
1955            Field::string("label", 32).required(),
1956        ]));
1957
1958        let error = query
1959            .upsert_batch_returning(
1960                vec![Record::new().set("option_key", "k").set("label", "x")],
1961                &["option_key"],
1962                ReturningTarget::Pk,
1963            )
1964            .await
1965            .expect_err("MySQL 批量 upsert RETURNING 必须被拒绝");
1966        assert!(
1967            matches!(
1968                error,
1969                BaseError::ConfigError(ref message) if message.contains("upsert_batch_returning")
1970            ),
1971            "应返回 ConfigError 并点名入口,实际: {error:?}"
1972        );
1973    }
1974}
1975
1976#[cfg(test)]
1977mod delete_permission_tests {
1978    use super::*;
1979    use crate::table::{Field, Record, Table};
1980    use std::sync::Arc;
1981
1982    fn query_for(table: Table, roles: &[&str]) -> TableQuery {
1983        let definition = table.build().expect("测试表定义应有效");
1984        TableQuery::new(
1985            definition.shared_config(),
1986            Arc::from(
1987                roles
1988                    .iter()
1989                    .map(|role| (*role).to_string())
1990                    .collect::<Vec<String>>(),
1991            ),
1992            None,
1993        )
1994    }
1995
1996    /// 软删写入必须走与逐行 update 相同的字段写权限校验:显式声明了写角色的
1997    /// 软删列,对无该角色的用户必须返回权限错误。
1998    #[tokio::test]
1999    async fn soft_delete_respects_explicit_soft_delete_write_audience() {
2000        let query = query_for(
2001            Table::new("tq_soft_delete_guard").fields([
2002                Field::id("id"),
2003                Field::soft_delete("deleted_at").writable_by(["admin"]),
2004            ]),
2005            &["user"],
2006        );
2007
2008        let error = query
2009            .delete()
2010            .await
2011            .expect_err("无写权限的软删列必须被拒绝");
2012        assert!(
2013            matches!(
2014                error,
2015                BaseError::FieldPermissionDenied(_, ref field, _) if field == "deleted_at"
2016            ),
2017            "应返回 deleted_at 的 FieldPermissionDenied,实际: {error:?}"
2018        );
2019    }
2020
2021    /// 默认 `Field::soft_delete`(写权限 Nobody,仅框架可写)是框架托管列:
2022    /// 守卫应放行并继续执行,而不是被自己的删除标记挡住。补上 WHERE 越过零
2023    /// WHERE 全表写保护后,无连接池应停在初始化错误。
2024    #[tokio::test]
2025    async fn framework_managed_soft_delete_passes_field_permission_guard() {
2026        let query = query_for(
2027            Table::new("tq_soft_delete_framework")
2028                .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2029            &["user"],
2030        )
2031        .where_eq("id", serde_json::json!(1))
2032        .expect("主键条件应有效");
2033
2034        let error = query
2035            .delete()
2036            .await
2037            .expect_err("无连接池应在守卫通过后才报错");
2038        assert!(
2039            matches!(error, BaseError::DatabaseNotInitialized),
2040            "默认软删列不应触发字段权限错误,实际: {error:?}"
2041        );
2042    }
2043
2044    /// 软删表零 WHERE 的 update 必须被拒绝。
2045    ///
2046    /// RED:修复前软删守卫会把 `deleted_at IS NULL` 注入 conditions,yang-db 的
2047    /// `conditions.is_empty()` 全表写保护被绕过——有池时会静默更新整表存活行,
2048    /// 无池时只能观察到 `DatabaseNotInitialized`。修复后应在触库前返回契约规定的
2049    /// `MissingWhereClause`。
2050    #[tokio::test]
2051    async fn soft_delete_update_without_where_is_rejected() {
2052        let query = query_for(
2053            Table::new("tq_soft_delete_zero_where_update").fields([
2054                Field::id("id"),
2055                Field::string("name", 32),
2056                Field::soft_delete("deleted_at"),
2057            ]),
2058            &["admin"],
2059        );
2060
2061        let error = query
2062            .update(Record::new().set("name", "x"))
2063            .await
2064            .expect_err("软删表零 WHERE 更新必须被拒绝");
2065        assert!(
2066            matches!(error, BaseError::MissingWhereClause(ref op) if op == "UPDATE"),
2067            "应返回 UPDATE 的 MissingWhereClause,实际: {error:?}"
2068        );
2069    }
2070
2071    /// 软删表零 WHERE 的 delete 必须被拒绝(RED 同 update:修复前会静默软删整表)。
2072    #[tokio::test]
2073    async fn soft_delete_delete_without_where_is_rejected() {
2074        let query = query_for(
2075            Table::new("tq_soft_delete_zero_where_delete").fields([
2076                Field::id("id"),
2077                Field::string("name", 32),
2078                Field::soft_delete("deleted_at"),
2079            ]),
2080            &["user"],
2081        );
2082
2083        let error = query
2084            .delete()
2085            .await
2086            .expect_err("软删表零 WHERE 删除必须被拒绝");
2087        assert!(
2088            matches!(error, BaseError::MissingWhereClause(ref op) if op == "DELETE"),
2089            "应返回 DELETE 的 MissingWhereClause,实际: {error:?}"
2090        );
2091    }
2092
2093    /// 守卫范围必须精确:只拦「软删表 + 未 with_trashed + 完全零 WHERE」。
2094    /// 非软删表、with_trashed、where_any(any_conditions)与租户注入都必须放行,
2095    /// 保持既有成功路径与错误面不变。
2096    #[test]
2097    fn soft_delete_zero_where_guard_scope() {
2098        // 非软删表:不拦截,保持 yang-db 既有错误行为。
2099        let query = query_for(
2100            Table::new("tq_zero_where_plain").fields([Field::id("id")]),
2101            &["user"],
2102        );
2103        query
2104            .ensure_soft_delete_write_has_where("UPDATE")
2105            .expect("非软删表不应触发守卫");
2106
2107        // with_trashed:不拦截。
2108        let query = query_for(
2109            Table::new("tq_zero_where_trashed")
2110                .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2111            &["user"],
2112        )
2113        .with_trashed();
2114        query
2115            .ensure_soft_delete_write_has_where("UPDATE")
2116            .expect("with_trashed 不应触发守卫");
2117
2118        // where_any-only(PG any_conditions):不拦截。
2119        let mut query = query_for(
2120            Table::new("tq_zero_where_any")
2121                .fields([Field::id("id"), Field::soft_delete("deleted_at")]),
2122            &["user"],
2123        );
2124        query
2125            .any_conditions
2126            .push(("id".to_string(), vec![serde_json::json!(1)]));
2127        query
2128            .ensure_soft_delete_write_has_where("DELETE")
2129            .expect("where_any 条件应被视为已有 WHERE");
2130
2131        // scope_tenant 注入租户条件:合法的租户范围批量写不拦截。
2132        let query = query_for(
2133            Table::new("tq_zero_where_tenant").fields([
2134                Field::id("id"),
2135                Field::bigint("tenant_id").tenant_key(),
2136                Field::soft_delete("deleted_at"),
2137            ]),
2138            &["user"],
2139        )
2140        .scope_tenant("tenant_id", serde_json::json!(7))
2141        .expect("租户条件注入应成功");
2142        query
2143            .ensure_soft_delete_write_has_where("UPDATE")
2144            .expect("租户注入条件应被视为已有 WHERE");
2145    }
2146}