fix(sync): resolve low-risk logic issues SYNC2-L1~L5

- SYNC2-L1: oplog pull cursor advances only to last successfully applied
  version, preventing permanent skip of failed operations
- SYNC2-L2: autoSync no longer counts lock/offline states as failures,
  avoiding spurious exponential backoff after network recovery
- SYNC2-L3: getPendingCRDTChanges supports per-table filtering, fixing
  push starvation when multiple tables have pending changes
- SYNC2-L4: offline queue max version read by version instead of
  createdAt to avoid duplicate versions within the same millisecond
- SYNC2-L5: reset per-table CRDT in-memory doc on persistence failure,
  preventing baseline drift and MissingDependencyError

Author: Aparencia

client/src/lib/storage/writeWithLog.ts

@@ -169,8 +169,12 @@ async function applyCRDTChange(
     await enqueueCRDTChange(changeset);
     await crdtEngine.persistDoc(tableName);
   } catch (err) {
-    // CRDT 路径失败不应阻塞主写入流程，仅记录警告
-    console.warn('[writeWithLog] CRDT change failed (non-blocking):', err);
+    // SYNC2-L5: CRDT 路径失败不阻塞主写入，但必须重置该表内存文档——
+    // applyLocalChange 已前滚内存 doc，若 enqueue/persistDoc 失败，
+    // 内存与队列/快照基线漂移，下次变更会生成非法 changeset
+    //（MissingDependencyError），该表 CRDT 路径从此永久失效
+    await crdtEngine.resetTable(tableName);
+    console.warn('[writeWithLog] CRDT change failed, table reset (non-blocking):', err);
   }
 }
 

client/src/lib/sync/OfflineQueue.ts

@@ -42,8 +42,10 @@ export class OfflineQueue {
     const deviceId = getDeviceId();
 
     // 在 Dexie 事务内完成"读 max version + 1 + 写入"，避免版本号竞态
+    // SYNC2-L4: 取最大值必须按 version（单调自增主键）而非 createdAt——
+    // Date 毫秒精度下同一毫秒的并发写入会取到错误基线，产生重复版本号
     await db.transaction('rw', db.offlineQueue, async () => {
-      const items = await db.offlineQueue.orderBy('createdAt').reverse().limit(1).toArray();
+      const items = await db.offlineQueue.orderBy('version').reverse().limit(1).toArray();
       const version = items.length > 0 ? (items[0].version || 0) + 1 : 1;
 
       await db.offlineQueue.add({

client/src/lib/sync/SyncEngine.ts

@@ -70,7 +70,13 @@ export class SyncEngine {
     if (now - this.lastAutoSyncAt < gapMs) return;
     this.lastAutoSyncAt = now;
     const result = await this.sync();
-    if (result.errors.length > 0) {
+    // SYNC2-L2: 并发锁/离线是正常状态而非故障——原实现把这两个错误计入
+    // autoSyncFailures，网络恢复瞬间的并发 sync 会误触发指数退避，
+    // 导致自动同步长时间被抑制
+    const actionableErrors = result.errors.filter(
+      (e) => e !== 'Sync already in progress' && e !== 'Device is offline',
+    );
+    if (actionableErrors.length > 0) {
       this.autoSyncFailures += 1;
     } else {
       this.autoSyncFailures = 0;

client/src/lib/sync/crdtEngine.ts

@@ -285,6 +285,18 @@ export class CRDTEngine {
     this.docs.clear();
     this.initialized = false;
   }
+
+  /**
+   * 重置单表 CRDT 文档（SYNC2-L5: 本地变更持久化失败后调用）
+   * 从 crdt_docs 最新快照重建该表内存状态，丢弃本次未落盘的变更——
+   * 避免内存 doc 前滚而队列/快照未跟上导致的基线漂移
+   *（下次 applyLocalChange 基于漂移基线生成非法 changeset）。
+   * 该变更最终仍会随下次业务写入重新生成，数据不丢。
+   */
+  async resetTable(tableName: string): Promise<void> {
+    this.docs.delete(tableName);
+    await this.initDoc(tableName);
+  }
 }
 
 // ─── 单例 ────────────────────────────────────────────────────────────────────

client/src/lib/sync/crdtPersistence.ts

@@ -23,9 +23,22 @@ export async function enqueueCRDTChange(changeset: CRDTChangeset): Promise<void>
 
 /**
  * 获取待上传的 changesets（按 seq 排序）
+ * SYNC2-L3: 支持按表过滤——原实现仅支持全局 limit，多表启用 CRDT 时
+ * crdtSyncChannel 每表取前 50 条再 filter，靠后表（数据量大）的变更
+ * 可能被全局前 50 条挤掉，形成推送饥饿。
  */
-export async function getPendingCRDTChanges(limit: number = 50): Promise<CRDTChangeRecord[]> {
+export async function getPendingCRDTChanges(
+  limit: number = 50,
+  tableName?: string,
+): Promise<CRDTChangeRecord[]> {
   const { db } = await import('@/lib/storage/database');
+  if (tableName) {
+    return db.crdtChanges
+      .orderBy('seq')
+      .filter(c => c.tableName === tableName)
+      .limit(limit)
+      .toArray();
+  }
   return db.crdtChanges
     .orderBy('seq')
     .limit(limit)

client/src/lib/sync/crdtSyncChannel.ts

@@ -25,10 +25,12 @@ export async function crdtPush(
 
   try {
     // 收集所有启用 CRDT 的表的待上传变更
+    // SYNC2-L3: 按表分别取（每表各自 limit 50）——原实现每表取全局前 50
+    // 条再 filter，靠后表的高 seq 变更会被靠前表挤掉，形成推送饥饿
     const allPending: CRDTChangeRecord[] = [];
     for (const tableName of CRDT_ENABLED_TABLES) {
-      const pending = await getPendingCRDTChanges(50);
-      allPending.push(...pending.filter(p => p.tableName === tableName));
+      const pending = await getPendingCRDTChanges(50, tableName);
+      allPending.push(...pending);
     }
 
     if (allPending.length === 0) return { pushed: 0, errors };

client/src/lib/sync/oplogSyncChannel.ts

@@ -122,39 +122,69 @@ export async function oplogPull(
     }>(`${basePath}/pull?deviceId=${encodeURIComponent(deviceId)}&sinceVersion=${lastVersion}`);
 
     if (response.operations.length > 0) {
-      await applyRemoteOperations(response.operations);
-      setLastSyncVersion(response.latestVersion);
+      // SYNC2-L1: 游标只推进到最后成功应用的版本——原实现直接用
+      // response.latestVersion 一次性跳过全部，若中间某条 apply 失败
+      //（表缺失/数据异常），该操作被永久跳过（sinceVersion 已越过它）
+      const { applied, lastVersion: appliedVersion } = await applyRemoteOperations(response.operations);
+      if (appliedVersion > lastVersion) {
+        setLastSyncVersion(appliedVersion);
+      }
+      return { pulled: applied, errors };
     }
 
-    return { pulled: response.operations.length, errors };
+    return { pulled: 0, errors };
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     errors.push(`Pull failed: ${message}`);
     return { pulled: 0, errors };
   }
 }
 
-/** 将远端操作应用到本地 Dexie（create/update 用 put 幂等覆盖） */
+/**
+ * 将远端操作应用到本地 Dexie（create/update 用 put 幂等覆盖）
+ * 逐条 try/catch：单条失败即停止，返回已成功应用的计数与最后成功版本。
+ * 未知 entityType 的操作跳过但不阻断游标推进（与应用成功等价，
+ * 否则 sinceVersion 不推进会反复拉取同一批数据）。
+ */
 async function applyRemoteOperations(
-  operations: Array<{ entityType: string; entityId: string; operation: string; data: unknown }>,
-): Promise<void> {
+  operations: Array<{ entityType: string; entityId: string; operation: string; data: unknown; version: number }>,
+): Promise<{ applied: number; lastVersion: number }> {
   const { db } = await import('../storage/database');
+  let applied = 0;
+  let lastVersion = -1;
 
   for (const op of operations) {
     const tableName = getEntityTableName(op.entityType);
-    if (!tableName) continue;
-
-    const table = db.table(tableName);
-    switch (op.operation) {
-      case 'create':
-      case 'update':
-        await table.put(op.data);
-        break;
-      case 'delete':
-        await table.delete(op.entityId);
-        break;
+    if (!tableName) {
+      // 未知类型：跳过但继续推进游标，避免永久重复拉取
+      lastVersion = Math.max(lastVersion, op.version);
+      continue;
+    }
+
+    try {
+      const table = db.table(tableName);
+      switch (op.operation) {
+        case 'create':
+        case 'update':
+          await table.put(op.data);
+          break;
+        case 'delete':
+          await table.delete(op.entityId);
+          break;
+      }
+      applied += 1;
+      lastVersion = Math.max(lastVersion, op.version);
+    } catch (err) {
+      // 单条失败：停止应用，游标停在失败前的最后成功版本，
+      // 下轮拉取重试该操作（避免数据永久丢失）
+      const message = err instanceof Error ? err.message : String(err);
+      // eslint-disable-next-line no-console -- 远端操作应用失败需记录以便排查
+      console.warn(`[oplogSyncChannel] 远端操作应用失败 [${op.entityType}:${op.entityId}] v${op.version}: ${message}`);
+      break;
     }
   }
+
+  return { applied, lastVersion };
 }
 
 /** entityType（服务端操作记录中的键）→ Dexie 表名映射 */