更新upsert

packages/storage_sdk/lib/src/presentation/facade/storage_sdk_api.dart

@@ -79,7 +79,10 @@ abstract class StorageSdkApi {
 
   // ── 插入 ─────────────────────────────────────────────────────────────────
 
-  /// 插入或替换（主键冲突时覆盖）。
+  /// 插入或替换（主键冲突时删除原行再插入）。
+  ///
+  /// 注意：底层是 DELETE + INSERT，会导致 rowid 变更，并触发 DELETE 级联。
+  /// 如需原地更新，请使用 [insertOnConflictUpdate]。
   ///
   /// 示例：
   /// ```dart
@@ -92,9 +95,26 @@ abstract class StorageSdkApi {
   /// 插入或忽略（主键冲突时跳过）。
   Future<void> insert<D>(Insertable<D> companion);
 
-  /// 批量插入或替换。
+  /// 批量插入或替换（主键冲突时删除原行再插入）。
+  ///
+  /// 注意：底层是 DELETE + INSERT，rowid 变更，触发 DELETE 级联。
+  /// 如需原地更新，请使用 [batchInsertOnConflictUpdate]。
   Future<void> batchInsertOrReplace<D>(List<Insertable<D>> companions);
 
+  /// 插入，主键冲突时原地更新全部字段（INSERT ... ON CONFLICT DO UPDATE SET）。
+  ///
+  /// 与 [insertOrReplace] 的区别：
+  /// - [insertOrReplace]        → DELETE + INSERT，rowid 变更，触发 DELETE 级联
+  /// - [insertOnConflictUpdate] → 原地 UPDATE，rowid 不变，不触发 DELETE 级联
+  ///
+  /// 适用场景：upsert 语义，且不希望影响依赖 rowid 的其他逻辑。
+  Future<void> insertOnConflictUpdate<D>(Insertable<D> companion);
+
+  /// 批量插入，主键冲突时原地更新全部字段。
+  ///
+  /// 与 [batchInsertOrReplace] 的区别同 [insertOnConflictUpdate]。
+  Future<void> batchInsertOnConflictUpdate<D>(List<Insertable<D>> companions);
+
   // ── 更新 ─────────────────────────────────────────────────────────────────
 
   /// 按条件更新。

packages/storage_sdk/lib/src/presentation/wiring/storage_sdk_api_impl.dart

@@ -67,6 +67,14 @@ class StorageSdkApiImpl implements StorageSdkApi, StorageSdkLifecycle {
   Future<void> batchInsertOrReplace<D>(List<Insertable<D>> companions) =>
       _core.repo.batchInsertOrReplace(_tableFor<Table, D>(), companions);
 
+  @override
+  Future<void> insertOnConflictUpdate<D>(Insertable<D> companion) =>
+      _core.repo.insertOnConflictUpdate(_tableFor<Table, D>(), companion);
+
+  @override
+  Future<void> batchInsertOnConflictUpdate<D>(List<Insertable<D>> companions) =>
+      _core.repo.batchInsertOnConflictUpdate(_tableFor<Table, D>(), companions);
+
   // ── 更新 ─────────────────────────────────────────────────────────────────
 
   @override