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