Skip to main content

yang_base/table/table_query/
write.rs

1//! 写入执行(`mysql` feature):写路径分 insert / update / delete / 批量 upsert 四类
2//! (各自带事务内变体),含插入数据准备(默认值/时间戳/租户注入)与更新数据校验。
3
4#![cfg(feature = "mysql")]
5
6use super::TableQuery;
7use crate::error::BaseError;
8use serde_json::Value;
9
10/// 批量 upsert 的计划产物:一次性校验通过的待写行集与 ODKU 赋值列。
11///
12/// 只由 [`TableQuery::plan_upsert_batch`] 构造,是「校验已完成、只剩执行」的中间态;
13/// 空批不会产出它(计划返回 `None`)。
14struct PreparedUpsertBatch {
15    /// 逐行同构的 INSERT 行(已补默认值/时间戳、已剔自增列)。
16    rows: Vec<std::collections::HashMap<String, Value>>,
17    /// ODKU 赋值列(已含 `updated_at`);列序由生成器按 INSERT 列序收敛。
18    tail: Vec<String>,
19}
20
21impl TableQuery {
22    /// 执行 INSERT 操作
23    ///
24    /// 插入数据到表中,包括以下步骤:
25    /// 1. 按表定义验证所有字段值
26    /// 2. 检查用户是否有字段的写入权限
27    /// 3. 构建 INSERT SQL 语句
28    /// 4. 执行插入操作
29    /// 5. 返回影响行数
30    ///
31    /// # 参数
32    ///
33    /// - `data`:要插入的 [`crate::table::Record`]
34    ///
35    /// # 返回值
36    ///
37    /// - `Ok(u64)`:插入成功,返回影响行数(通常为 1)
38    /// - `Err(BaseError)`:插入失败,返回错误
39    ///
40    /// # 错误
41    ///
42    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
43    /// - `BaseError::FieldRequired`:必填字段缺失
44    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
45    /// - `BaseError::ValidationFailed`:字段值验证失败
46    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
47    ///
48    /// # 示例
49    ///
50    /// ```rust,ignore
51    /// use yang_base::table::Record;
52    ///
53    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
54    /// let data = Record::new()
55    ///     .set("name", "张三")
56    ///     .set("email", "zhangsan@example.com");
57    ///
58    /// // 执行插入
59    /// let affected = query.insert(data).await?;
60    /// println!("插入成功,影响行数: {}", affected);
61    /// # Ok(())
62    /// # }
63    /// ```
64    pub async fn insert(self, data: crate::table::Record) -> Result<u64, BaseError> {
65        // 填充默认值/时间戳并校验(顺序:写权限→填充默认值→必填/类型校验)
66        let data = self.prepare_and_validate_insert(data.into_columns())?;
67        self.compile_db_write_query()?
68            .insert(&data)
69            .await
70            .map_err(BaseError::DatabaseExecuteFailed)?;
71        Ok(1)
72    }
73
74    /// 在事务中执行 INSERT 操作
75    ///
76    /// 与 [`TableQuery::insert`] 完全一致的写权限校验/默认值填充/时间戳/必填校验
77    /// 流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
78    ///
79    /// # 错误
80    ///
81    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
82    /// - 其余同 [`TableQuery::insert`]
83    pub async fn insert_in_tx(
84        self,
85        tx: &mut yang_db::Transaction,
86        data: crate::table::Record,
87    ) -> Result<u64, BaseError> {
88        let data = self.prepare_and_validate_insert(data.into_columns())?;
89        let query = tx.table(&self.table_config.table_ref);
90        self.apply_write_plan(query)?
91            .insert(&data)
92            .await
93            .map_err(BaseError::DatabaseExecuteFailed)?;
94        Ok(1)
95    }
96
97    /// 执行 INSERT 操作并返回自增主键
98    ///
99    /// 与 [`TableQuery::insert`] 完全一致的校验与拼 SQL 流程,但额外返回本次
100    /// INSERT 产生的自增主键值(`last_insert_id`),便于调用方拿到新建记录 ID。
101    ///
102    /// # 参数
103    ///
104    /// - `data`:要插入的数据
105    ///
106    /// # 返回值
107    ///
108    /// - `Ok((affected, id))`:插入成功,返回 (影响行数, 自增主键值)。
109    ///   表无自增列时 `id` 为 0。
110    /// - `Err(BaseError)`:插入失败
111    ///
112    /// # 错误
113    ///
114    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
115    /// - `BaseError::FieldRequired`:必填字段缺失
116    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
117    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
118    pub async fn insert_returning_id(
119        self,
120        data: crate::table::Record,
121    ) -> Result<(u64, u64), BaseError> {
122        let data = self.prepare_and_validate_insert(data.into_columns())?;
123        let id = self
124            .compile_db_write_query()?
125            .insert(&data)
126            .await
127            .map_err(BaseError::DatabaseExecuteFailed)?;
128        Ok((1, id))
129    }
130
131    /// 在事务中执行 INSERT 并返回自增主键
132    ///
133    /// 与 [`TableQuery::insert_returning_id`] 一致,但在事务内执行。批量写入或
134    /// 「插入父行→用其主键插入子行」等需要拿到新 ID 再继续的原子场景使用。
135    pub async fn insert_returning_id_in_tx(
136        self,
137        tx: &mut yang_db::Transaction,
138        data: crate::table::Record,
139    ) -> Result<(u64, u64), BaseError> {
140        let data = self.prepare_and_validate_insert(data.into_columns())?;
141        let query = tx.table(&self.table_config.table_ref);
142        let id = self
143            .apply_write_plan(query)?
144            .insert(&data)
145            .await
146            .map_err(BaseError::DatabaseExecuteFailed)?;
147        Ok((1, id))
148    }
149
150    /// 在调用方事务内批量 upsert(`INSERT ... ON DUPLICATE KEY UPDATE`)。
151    ///
152    /// - INSERT 列集与值 = [`TableQuery::prepare_and_validate_insert`] 的输出(写权限 /
153    ///   自增剔除 / 缺省补 `default_value` / 补 `created_at`+`updated_at` / 必填校验),
154    ///   与单行插入**共用同一个函数**;
155    /// - UPDATE 分支只写 `update_columns ∪ {updated_at}`。框架补出来的默认值与
156    ///   `created_at` **都不在**赋值列里,这正是「省略即保持原值」与「创建时间不被刷新」
157    ///   的落点。
158    ///
159    /// # 调用方义务(框架不兜、也兜不了)
160    ///
161    /// - 冲突键由**表上的唯一索引**决定,本方法无法指定;
162    /// - 本方法**没有 WHERE**。身份列(如 `source_key`)必须由调用方自己从
163    ///   `update_columns` 里排除:把它放进赋值列,跨源命中就会把归属**静默改写**——
164    ///   而逐行路径的 `where_eq(id)+where_eq(owner)` 至少还会撞唯一索引响亮失败。
165    /// - 调用方应在事务前做归属预检,并在同一事务内做写后归属再断言。
166    ///
167    /// # 错误
168    ///
169    /// - `BaseError::ParamInvalid`:带 where / 软删表未 `with_trashed` / 行集不一致 /
170    ///   赋值列为空或不在提供列内 / 赋值列是自增列
171    /// - `BaseError::FieldPermissionDenied`:显式提交 `not_writable` 列(`created_at` 等),
172    ///   沿用 prepare 的错误
173    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
174    ///
175    /// # 返回值
176    ///
177    /// `rows_affected` 之和 ∈ `[N, 2N]`(1=插入,2=更新且值有变;sqlx 带
178    /// `CLIENT_FOUND_ROWS` ⇒「命中但值未变」也计 1)。**不是行数**(要行数用
179    /// `rows.len()`),也**分不出 inserted/updated**。
180    pub async fn upsert_batch_in_tx(
181        self,
182        tx: &mut yang_db::Transaction,
183        rows: Vec<crate::table::Record>,
184        update_columns: &[&str],
185    ) -> Result<u64, BaseError> {
186        // 空批 = 写 0 行:没写就没写,不发明语句(生成器也会拒空数据)。
187        let Some(batch) = self.plan_upsert_batch(rows, update_columns)? else {
188            return Ok(0);
189        };
190        // 不走 apply_write_plan:写路径计划只挂 WHERE 与软删守卫,而本方法两者都不支持
191        // (plan_upsert_batch 已把带 where / 软删表的调用拒掉),挂上去只会给人
192        // 「守卫已应用」的错觉。
193        let affected = tx
194            .table(&self.table_config.table_ref)
195            .upsert_batch(&batch.rows, &batch.tail)
196            .await
197            .map_err(BaseError::DatabaseExecuteFailed)?;
198        Ok(affected)
199    }
200
201    /// 校验并准备一批 upsert:`Ok(None)` = 空批(写 0 行),`Ok(Some(_))` = 可执行计划。
202    ///
203    /// 失败面顺序即调用方踩坑的顺序:空批 → where → 软删 → 逐行列集 → 赋值列。
204    fn plan_upsert_batch(
205        &self,
206        rows: Vec<crate::table::Record>,
207        update_columns: &[&str],
208    ) -> Result<Option<PreparedUpsertBatch>, BaseError> {
209        let total = rows.len();
210        let mut records = rows.into_iter();
211        // 空批 = 写 0 行:没有第一行可推赋值列,也不发明语句。
212        let Some(first) = records.next() else {
213            return Ok(None);
214        };
215
216        // ODKU 没有 WHERE:带条件的调用会被静默忽略(写错行远比报错危险),直接拒绝。
217        if !self.query_params.where_conditions.is_empty() {
218            return Err(BaseError::ParamInvalid(
219                "where".to_string(),
220                "批量 upsert 不支持 where 条件:ON DUPLICATE KEY UPDATE 没有 WHERE,条件会被静默忽略"
221                    .to_string(),
222            ));
223        }
224        // 软删守卫是 `deleted_at IS NULL` 这类 WHERE,批量 upsert 表达不了:命中已软删行时
225        // 会把它们改活,而逐行 update 路径上这会被守卫挡住。
226        if self.table_config.soft_delete_field.is_some() && !self.include_trashed {
227            return Err(BaseError::ParamInvalid(
228                "soft_delete_field".to_string(),
229                "该表配置了软删字段,而批量 upsert 无法表达软删守卫;要么改用 update_in_tx,要么先 with_trashed()"
230                    .to_string(),
231            ));
232        }
233
234        // 第 1 条记录的两套列集就是全批基准:provided 管「省略即重置」,prepared 管列集
235        // 异构。先取 provided 再 prepare——prepare 会把默认值与时间戳补进来,之后就分不出
236        // 「调用方写过这一列」与「框架补的」了。
237        let first_provided: std::collections::BTreeSet<String> =
238            first.as_map().keys().cloned().collect();
239        let first_prepared = self.prepare_and_validate_insert(first.into_columns())?;
240        let first_prepared_keys: std::collections::BTreeSet<String> =
241            first_prepared.keys().cloned().collect();
242
243        let mut prepared_rows = Vec::with_capacity(total);
244        prepared_rows.push(first_prepared);
245        for (offset, record) in records.enumerate() {
246            let provided: std::collections::BTreeSet<String> =
247                record.as_map().keys().cloned().collect();
248            let prepared = self.prepare_and_validate_insert(record.into_columns())?;
249            let prepared_keys: std::collections::BTreeSet<String> =
250                prepared.keys().cloned().collect();
251            // 第 1 条在循环外已处理,这里从第 2 条起数。
252            let row_number = offset + 2;
253            // 某行省略了带默认值的列 ⇒ 批量路径会拿第 1 行的值替它做 ODKU 赋值,等价于
254            // 「省略即重置」(prepared 两侧都被默认值补齐,只看 prepared 拦不住)。
255            if provided != first_provided {
256                return Err(BaseError::ParamInvalid(
257                    "rows".to_string(),
258                    format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
259                ));
260            }
261            // 列集异构交给生成器只会得到一条更晚、更难归因的 SerializationError。
262            if prepared_keys != first_prepared_keys {
263                return Err(BaseError::ParamInvalid(
264                    "rows".to_string(),
265                    format!("批量 upsert 第 {row_number} 条记录提供的列集与第 1 条不一致"),
266                ));
267            }
268            prepared_rows.push(prepared);
269        }
270
271        if update_columns.is_empty() {
272            return Err(BaseError::ParamInvalid(
273                "update_columns".to_string(),
274                "批量 upsert 至少需要一个可更新列(ON DUPLICATE KEY UPDATE 的赋值列)".to_string(),
275            ));
276        }
277        for name in update_columns {
278            // 要求 ⊆ provided 而不是 ⊆ prepared:prepared 里有框架补出来的默认值与
279            // created_at,让它们进赋值列就等于「省略即重置」「创建时间被刷新」。
280            // created_at 不必单独排除:它是 Audience::Nobody,调用方提交会先吃
281            // FieldPermissionDenied,永远进不了 provided,上一条已把它挡住。
282            if !first_provided.contains(*name) {
283                return Err(BaseError::ParamInvalid(
284                    "update_columns".to_string(),
285                    format!(
286                        "赋值列 `{name}` 不在调用方提供的列里(框架补出来的默认值与 created_at 不能当赋值列)"
287                    ),
288                ));
289            }
290            if self
291                .table_config
292                .get_field(name)
293                .is_some_and(|field| field.auto_increment)
294            {
295                return Err(BaseError::ParamInvalid(
296                    "update_columns".to_string(),
297                    format!("赋值列 `{name}` 是自增列,不能出现在 ON DUPLICATE KEY UPDATE 里"),
298                ));
299            }
300        }
301
302        // 赋值列 = 调用方白名单(去重)+ updated_at(语义同 with_updated_timestamp:列存在
303        // 且不在集合里时追加)。列序不在这里排:生成器按 INSERT 列序收敛。
304        let mut tail: Vec<String> = Vec::with_capacity(update_columns.len() + 1);
305        for name in update_columns {
306            if !tail.iter().any(|existing| existing.as_str() == *name) {
307                tail.push((*name).to_string());
308            }
309        }
310        if let Some(updated_at) = self
311            .table_config
312            .timestamp_fields
313            .as_ref()
314            .and_then(|fields| fields.updated_at.as_ref())
315            .filter(|name| self.table_config.fields.contains_key(*name))
316        {
317            if !tail.iter().any(|existing| existing == updated_at) {
318                tail.push(updated_at.clone());
319            }
320        }
321
322        Ok(Some(PreparedUpsertBatch {
323            rows: prepared_rows,
324            tail,
325        }))
326    }
327
328    /// 填充默认值/时间戳并验证插入数据
329    ///
330    /// 处理顺序(修复 required+default 字段被误报 FieldRequired 的问题):
331    /// 1. 字段与写权限校验:显式提交只读字段时拒绝;null 自增主键视为未提供
332    /// 2. 规范化数据库生成字段:未提供或为 null 的自增字段交给数据库生成
333    /// 3. 填充默认值:data 中缺失且配置了 `default_value` 的字段补默认值
334    /// 4. 填充时间戳:`timestamp_fields` 配置且列存在、调用方未提供时,写入当前时间
335    /// 5. 必填/类型/验证器校验:在补齐后的数据上执行
336    ///
337    /// # 参数
338    ///
339    /// - `data`:调用方提供的原始插入数据
340    ///
341    /// # 返回值
342    ///
343    /// - `Ok(HashMap)`:补齐默认值与时间戳后的最终插入数据
344    /// - `Err(BaseError)`:权限或校验失败
345    pub(crate) fn prepare_and_validate_insert(
346        &self,
347        data: std::collections::HashMap<String, Value>,
348    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
349        let mut prepared = data;
350
351        // tenant key 只能由请求上下文注入,业务输入不得覆盖。
352        if let Some((field, value)) = &self.tenant_scope {
353            if prepared.contains_key(field) {
354                return Err(BaseError::PermissionDenied(format!(
355                    "禁止显式写入租户字段: {field}"
356                )));
357            }
358            prepared.insert(field.clone(), value.clone());
359        }
360
361        // 1. 校验调用方显式提交的字段和写权限。只有 null 自增主键可视为“未提供”,
362        // 其余只读字段即使提交 null 也必须拒绝,避免绕过字段边界并覆盖数据库默认值。
363        for (field_name, value) in &prepared {
364            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
365                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
366            })?;
367            let omitted_auto_increment = field_config.auto_increment && value.is_null();
368            let injected_tenant = self
369                .tenant_scope
370                .as_ref()
371                .is_some_and(|(tenant_field, _)| tenant_field == field_name);
372            if !injected_tenant
373                && !omitted_auto_increment
374                && !field_config.permissions.can_write(&self.user_roles_set)
375            {
376                return Err(BaseError::FieldPermissionDenied(
377                    self.table_config.table_name.clone(),
378                    field_name.clone(),
379                    "用户无写入权限".to_string(),
380                ));
381            }
382        }
383
384        // 2. 数据库生成的自增字段未提供或为 null 时,不进入 INSERT 字段列表。
385        for (field_name, field_config) in &self.table_config.fields {
386            if field_config.auto_increment
387                && prepared
388                    .get(field_name)
389                    .map(serde_json::Value::is_null)
390                    .unwrap_or(true)
391            {
392                prepared.remove(field_name);
393            }
394        }
395
396        // 3. 填充默认值(仅缺失时;显式 null 仍受 nullable/required 约束)
397        for (field_name, field_config) in &self.table_config.fields {
398            if field_config.auto_increment {
399                continue;
400            }
401            if let Some(default) = &field_config.default_value {
402                if !prepared.contains_key(field_name) {
403                    prepared.insert(field_name.clone(), default.clone());
404                }
405            }
406        }
407
408        // 4. 填充创建/更新时间戳(列存在且调用方未提供时)
409        if let Some(ts) = &self.table_config.timestamp_fields {
410            let now = chrono::Utc::now().timestamp();
411            for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
412                if self.table_config.fields.contains_key(ts_field) {
413                    let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
414                    if missing {
415                        prepared.insert(ts_field.clone(), Value::Number(now.into()));
416                    }
417                }
418            }
419        }
420
421        // 5. 在补齐后的数据上执行必填/类型/验证器校验
422        for (field_name, field_config) in &self.table_config.fields {
423            if !field_config.permissions.can_write(&self.user_roles_set) {
424                continue;
425            }
426            if field_config.auto_increment && !prepared.contains_key(field_name) {
427                continue;
428            }
429            let value = prepared.get(field_name).unwrap_or(&Value::Null);
430            field_config.validate(value, &self.regex_cache)?;
431        }
432
433        Ok(prepared)
434    }
435
436    /// 执行 UPDATE 操作
437    ///
438    /// 更新表中的数据,包括以下步骤:
439    /// 1. 按表定义验证所有字段值
440    /// 2. 检查用户是否有字段的写入权限
441    /// 3. 构建 UPDATE SQL 语句
442    /// 4. 应用已配置的 WHERE 条件
443    /// 5. 执行更新操作
444    /// 6. 返回影响行数
445    ///
446    /// # 参数
447    ///
448    /// - `data`:要更新的 [`crate::table::Record`]
449    ///
450    /// # 返回值
451    ///
452    /// - `Ok(u64)`:更新成功,返回影响行数
453    /// - `Err(BaseError)`:更新失败,返回错误
454    ///
455    /// # 错误
456    ///
457    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
458    /// - `BaseError::FieldNotFound`:字段不存在
459    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
460    /// - `BaseError::ValidationFailed`:字段值验证失败
461    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
462    ///
463    /// # 示例
464    ///
465    /// ```rust,ignore
466    /// use yang_base::table::Record;
467    /// use serde_json::json;
468    ///
469    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
470    /// let data = Record::new()
471    ///     .set("name", "李四")
472    ///     .set("email", "lisi@example.com");
473    ///
474    /// // 执行更新(需要先设置 WHERE 条件)
475    /// let affected = query
476    ///     .where_eq("id", json!(1))?
477    ///     .update(data)
478    ///     .await?;
479    /// println!("更新成功,影响行数: {}", affected);
480    /// # Ok(())
481    /// # }
482    /// ```
483    pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
484        let data = self.prepare_update_data(data.into_columns())?;
485        self.compile_db_write_query()?
486            .update(&data)
487            .await
488            .map_err(BaseError::DatabaseExecuteFailed)
489    }
490
491    /// 在事务中执行 UPDATE 操作
492    ///
493    /// 与 [`TableQuery::update`] 一致的字段校验/权限/WHERE 守卫/自动 `updated_at`
494    /// 逻辑,但在事务内执行。
495    ///
496    /// # 错误
497    ///
498    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
499    /// - 其余同 [`TableQuery::update`]
500    pub async fn update_in_tx(
501        self,
502        tx: &mut yang_db::Transaction,
503        data: crate::table::Record,
504    ) -> Result<u64, BaseError> {
505        let data = self.prepare_update_data(data.into_columns())?;
506        let query = tx.table(&self.table_config.table_ref);
507        self.apply_write_plan(query)?
508            .update(&data)
509            .await
510            .map_err(BaseError::DatabaseExecuteFailed)
511    }
512
513    fn prepare_update_data(
514        &self,
515        data: std::collections::HashMap<String, Value>,
516    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
517        self.validate_update_data(&data)?;
518        self.with_updated_timestamp(data)
519    }
520
521    fn with_updated_timestamp(
522        &self,
523        mut data: std::collections::HashMap<String, Value>,
524    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
525        if data.is_empty() {
526            return Err(BaseError::ParamInvalid(
527                "data".to_string(),
528                "无可更新字段".to_string(),
529            ));
530        }
531        if let Some(updated_at) = self
532            .table_config
533            .timestamp_fields
534            .as_ref()
535            .and_then(|fields| fields.updated_at.as_ref())
536            .filter(|name| self.table_config.fields.contains_key(*name))
537        {
538            data.insert(
539                updated_at.clone(),
540                Value::Number(chrono::Utc::now().timestamp().into()),
541            );
542        }
543        Ok(data)
544    }
545
546    /// 验证更新数据
547    ///
548    /// 验证所有要更新的字段值的合法性和用户权限
549    ///
550    /// # 参数
551    ///
552    /// - `data`:要更新的数据
553    ///
554    /// # 返回值
555    ///
556    /// - `Ok(())`:验证通过
557    /// - `Err(BaseError)`:验证失败
558    ///
559    /// # 错误
560    ///
561    /// - `BaseError::FieldNotFound`:字段不存在
562    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
563    /// - `BaseError::ValidationFailed`:字段值验证失败
564    #[cfg(test)]
565    pub fn validate_update_data(
566        &self,
567        data: &std::collections::HashMap<String, Value>,
568    ) -> Result<(), BaseError> {
569        self.validate_update_data_impl(data)
570    }
571
572    /// 验证更新数据(内部实现)
573    #[cfg(not(test))]
574    fn validate_update_data(
575        &self,
576        data: &std::collections::HashMap<String, Value>,
577    ) -> Result<(), BaseError> {
578        self.validate_update_data_impl(data)
579    }
580
581    /// 验证更新数据的实际实现
582    fn validate_update_data_impl(
583        &self,
584        data: &std::collections::HashMap<String, Value>,
585    ) -> Result<(), BaseError> {
586        if data.is_empty() {
587            return Err(BaseError::ParamInvalid(
588                "data".to_string(),
589                "至少需要一个更新字段".to_string(),
590            ));
591        }
592        // 只验证提供的字段(与 INSERT 不同,UPDATE 不需要验证所有字段)
593        for (field_name, value) in data {
594            if self
595                .tenant_scope
596                .as_ref()
597                .is_some_and(|(tenant_field, _)| tenant_field == field_name)
598            {
599                return Err(BaseError::PermissionDenied(format!(
600                    "禁止修改租户字段: {field_name}"
601                )));
602            }
603            // 1. 检查字段是否存在于表配置中
604            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
605                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
606            })?;
607
608            // 2. 检查用户是否有写入权限
609            if !field_config.permissions.can_write(&self.user_roles_set) {
610                return Err(BaseError::FieldPermissionDenied(
611                    self.table_config.table_name.clone(),
612                    field_name.clone(),
613                    "用户无写入权限".to_string(),
614                ));
615            }
616
617            // 3. 验证显式提供的字段值。部分更新不要求提交其它必填字段,但若本字段
618            // 被显式设为 null,仍执行 required 约束。
619            field_config.validate(value, &self.regex_cache)?;
620        }
621
622        Ok(())
623    }
624
625    /// 批量 upsert 的**计划**(不连库、不执行)——测试专用。
626    ///
627    /// 只把 [`TableQuery::plan_upsert_batch`] 的产物摊平成 `(待写行集, 赋值列)`,让无库
628    /// 用例能断言「哪些列进了 INSERT、哪些列进了 ODKU 尾巴」;生产路径不经过这里。
629    // 摊平元组比再发明一个测试专用结构体更省;clippy 只嫌它长。
630    #[allow(clippy::type_complexity)]
631    #[cfg(test)]
632    pub fn upsert_batch_plan_for_test(
633        &self,
634        rows: Vec<crate::table::Record>,
635        update_columns: &[&str],
636    ) -> Result<Option<(Vec<std::collections::HashMap<String, Value>>, Vec<String>)>, BaseError>
637    {
638        Ok(self
639            .plan_upsert_batch(rows, update_columns)?
640            .map(|batch| (batch.rows, batch.tail)))
641    }
642
643    /// 执行 DELETE 操作
644    ///
645    /// 删除表中的数据,支持软删除和物理删除两种模式:
646    /// 1. 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
647    /// 2. 如果未配置软删除字段,执行物理删除
648    /// 3. 应用已配置的 WHERE 条件
649    /// 4. 返回影响行数
650    ///
651    /// # 返回值
652    ///
653    /// - `Ok(u64)`:删除成功,返回影响行数
654    /// - `Err(BaseError)`:删除失败,返回错误
655    ///
656    /// # 错误
657    ///
658    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
659    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
660    ///
661    /// # 示例
662    ///
663    /// ```rust,ignore
664    /// use serde_json::json;
665    /// use yang_base::table::{Field, Table};
666    ///
667    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
668    /// let users = Table::new("users")
669    ///     .fields(vec![
670    ///         Field::id("id"),
671    ///         Field::string("name", 50).required(),
672    ///         Field::soft_delete("deleted_at"),
673    ///     ])
674    ///     .build()?;
675    ///
676    /// // 执行软删除(实际上是 UPDATE deleted_at = <timestamp>)
677    /// let affected = users
678    ///     .bind(pool)
679    ///     .query(["admin"])
680    ///     .where_eq("id", json!(1))?
681    ///     .delete()
682    ///     .await?;
683    /// println!("删除成功,影响行数: {}", affected);
684    /// # Ok(())
685    /// # }
686    /// ```
687    pub async fn delete(self) -> Result<u64, BaseError> {
688        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
689            let data = self.with_updated_timestamp(std::collections::HashMap::from([(
690                soft_delete_field.clone(),
691                Value::Number(chrono::Utc::now().timestamp().into()),
692            )]))?;
693            return self
694                .compile_db_write_query()?
695                .update(&data)
696                .await
697                .map_err(BaseError::DatabaseExecuteFailed);
698        }
699        self.compile_db_write_query()?
700            .delete()
701            .await
702            .map_err(BaseError::DatabaseExecuteFailed)
703    }
704
705    /// 在事务中执行 DELETE 操作
706    ///
707    /// 与 [`TableQuery::delete`] 一致:配置了软删除字段时走 UPDATE 标记(同样在
708    /// 事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
709    ///
710    /// # 错误
711    ///
712    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
713    /// - 其余同 [`TableQuery::delete`]
714    pub async fn delete_in_tx(self, tx: &mut yang_db::Transaction) -> Result<u64, BaseError> {
715        let query = tx.table(&self.table_config.table_ref);
716        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
717            let data = self.with_updated_timestamp(std::collections::HashMap::from([(
718                soft_delete_field.clone(),
719                Value::Number(chrono::Utc::now().timestamp().into()),
720            )]))?;
721            return self
722                .apply_write_plan(query)?
723                .update(&data)
724                .await
725                .map_err(BaseError::DatabaseExecuteFailed);
726        }
727        self.apply_write_plan(query)?
728            .delete()
729            .await
730            .map_err(BaseError::DatabaseExecuteFailed)
731    }
732}