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}