fix(client): 同步引擎高危修复——resume死锁/冲突循环/localData空对象/synced类型不一致

- SYNC2-H3: pause() 不再置 syncInProgress（该锁由 sync finally 释放），resume 等待加 15s 超时兜底——存储路径切换等流程不再永久挂起
- SYNC2-H1: resolve 成功后 markEntityLogsSynced 清理该实体全部未同步日志——配合服务端版本语义收紧（<=冲突），消除 resolve 后旧日志永久循环冲突
- SYNC2-H2: 冲突对象 localData 携带真实本地数据（最后一条 payload 日志，纯 delete 回退读业务表），localVersion 取最后一条日志版本——修复保留本地提交空对象清空实体数据
- SYNC2-H4: operationLog.synced 写入数值 0/1 与查询 equals(0/1) 类型一致，修复 oplog push 链路静默失效与模式切换丢数据；类型同步改为 0|1

验证: lint 0 errors + 875 tests passed

Author: Aparencia

client/src/lib/storage/operationLog.ts

@@ -60,7 +60,10 @@ export async function logOperation<T extends Record<string, unknown>>(
       payload: serializedPayload,
       patch,
       createdAt: new Date(),
-      synced: false,
+      // SYNC2-H4: 写入数值 0/1（与查询 equals(0)/equals(1) 保持一致）——
+      // IndexedDB 键相等判定要求同类型，boolean 与 number 不相等会
+      // 导致 getUnsyncedLogs 永远返回空、oplog push 静默失效
+      synced: 0,
       version,
       deviceId,
     });
@@ -81,11 +84,29 @@ export async function getUnsyncedLogsBatch(batchSize: number = 50): Promise<Oper
   return logs.slice(0, batchSize);
 }
 
-// 标记日志为已同步
+// 标记日志为已同步（SYNC2-H4: 写入数值 1 与查询一致）
 export async function markLogsSynced(ids: string[]): Promise<void> {
   await db.operationLog.bulkUpdate(ids.map(id => ({
     key: id,
-    changes: { synced: true }
+    changes: { synced: 1 }
+  })));
+}
+
+/**
+ * SYNC2-H1: 将指定实体的全部未同步日志标记为已同步。
+ * 冲突 resolve 成功后调用——resolve 已代表该实体最终状态，
+ * 若不清除本地日志，下次 push 时旧版本日志仍会冲突（服务端
+ * 版本已推进），形成永久循环冲突。
+ */
+export async function markEntityLogsSynced(entityType: string, entityId: string): Promise<void> {
+  const logs = await db.operationLog
+    .where('entityType').equals(entityType)
+    .filter(l => l.entityId === entityId && l.synced === 0)
+    .toArray();
+  if (logs.length === 0) return;
+  await db.operationLog.bulkUpdate(logs.map(l => ({
+    key: l.id,
+    changes: { synced: 1 },
   })));
 }
 

client/src/lib/sync/SyncEngine.ts

@@ -1,5 +1,5 @@
 import { apiClient } from '@/lib/http/apiClient';
-import { getDeviceId } from '../storage/operationLog';
+import { getDeviceId, markEntityLogsSynced } from '../storage/operationLog';
 import { offlineQueue } from './OfflineQueue';
 import { networkManager, type NetworkStatus } from './NetworkManager';
 import type { SyncConflict } from '@/types/models';
@@ -90,10 +90,13 @@ export class SyncEngine {
   /**
    * 暂停同步引擎
    * 阻止新的同步请求（用于路径切换等关键操作前）
+   * SYNC2-H3: 不再置 syncInProgress=true——该标志是"sync 执行中"的锁，
+   * 由 sync() 的 finally 负责释放；pause 直接置位会导致无 sync 运行时
+   * 锁永不清除，resume() 轮询等待永久挂起（同步引擎瘫痪）。
+   * paused 标志本身已足以阻止新 sync 启动。
    */
   pause(): void {
     this.paused = true;
-    this.syncInProgress = true;
   }
 
   /**
@@ -102,12 +105,19 @@ export class SyncEngine {
    */
   async resume(): Promise<void> {
     this.paused = false;
-    // 如有进行中的 sync，等待其完成
+    // 如有进行中的 sync，等待其完成（SYNC2-H3: 15s 超时保护，
+    // 防止 sync 异常挂起导致 resume 永久等待）
     if (this.syncInProgress) {
       await new Promise<void>((resolve) => {
+        const startedAt = Date.now();
         const check = () => {
           if (!this.syncInProgress) {
             resolve();
+          } else if (Date.now() - startedAt > 15000) {
+            // 超时兜底：强制清锁继续（sync 的 finally 可能因异常路径未执行）
+            logger.warn('[SyncEngine] resume: waiting for in-flight sync timed out, forcing unlock');
+            this.syncInProgress = false;
+            resolve();
           } else {
             setTimeout(check, 50);
           }
@@ -290,6 +300,13 @@ export class SyncEngine {
         version: strategy === 'remote' ? conflict.remoteVersion : Math.max(conflict.localVersion, conflict.remoteVersion) + 1,
       });
 
+      if (response.resolved) {
+        // SYNC2-H1: resolve 成功后该实体的本地日志全部标记已同步——
+        // resolve 已代表该实体最终状态；若不清理，旧版本日志下次 push
+        // 仍会冲突（服务端版本已推进），形成永久循环冲突
+        await markEntityLogsSynced(conflict.entityType, conflict.entityId);
+      }
+
       return { resolved: response.resolved, errors };
     } catch (error: unknown) {
       const message = error instanceof Error ? error.message : String(error);

client/src/lib/sync/oplogSyncChannel.ts

@@ -2,6 +2,7 @@ import { apiClient } from '@/lib/http/apiClient';
 import { getDeviceId, getUnsyncedLogsBatch, markLogsSynced } from '../storage/operationLog';
 import type { SyncConflict } from '@/types/models';
 import { getLastSyncVersion, setLastSyncVersion } from './syncCursors';
+import type { OperationLog } from '@/types/sync';
 
 /**
  * oplog 同步通道（传统 operationLog 推拉路径）
@@ -71,13 +72,16 @@ export async function oplogPush(
     // Handle conflicts
     if (response.conflicts.length > 0) {
       for (const conflict of response.conflicts) {
+        // SYNC2-H2: 冲突对象必须携带真实本地数据——原实现 localData 硬编码 '{}'
+        // 导致用户选择"保留本地"时提交空对象覆盖服务端实体（数据清空）
+        const { localDataStr, localVersion } = await resolveLocalConflictData(logs, conflict.entityType, conflict.entityId);
         conflicts.push({
           id: crypto.randomUUID(),
           entityType: conflict.entityType,
           entityId: conflict.entityId,
-          localData: '{}',
+          localData: localDataStr,
           remoteData: JSON.stringify(conflict.serverData),
-          localVersion: logs.find(l => l.entityId === conflict.entityId)?.version || 0,
+          localVersion,
           remoteVersion: conflict.serverVersion,
           status: 'pending',
           createdAt: new Date(),
@@ -171,3 +175,43 @@ function getEntityTableName(entityType: string): string | null {
   };
   return typeMap[entityType] || null;
 }
+
+/**
+ * SYNC2-H2: 解析冲突实体的本地数据与版本。
+ * 优先取该实体最后一条携带 payload 的日志（本地最终写入状态）；
+ * 无 payload（纯 delete 日志）时回退读取业务表当前数据。
+ * localVersion 取该实体最后一条日志的版本（原实现取第一条=最小版本）。
+ */
+async function resolveLocalConflictData(
+  logs: OperationLog[],
+  entityType: string,
+  entityId: string,
+): Promise<{ localDataStr: string; localVersion: number }> {
+  const entityLogs = logs.filter(l => l.entityId === entityId && l.entityType === entityType);
+  const lastLog = entityLogs[entityLogs.length - 1];
+  const lastPayloadLog = [...entityLogs].reverse().find(l => l.payload);
+
+  if (lastPayloadLog?.payload) {
+    return {
+      localDataStr: lastPayloadLog.payload,
+      localVersion: lastLog?.version ?? lastPayloadLog.version,
+    };
+  }
+
+  // 纯 delete 或 payload 缺失：尝试从业务表读取当前数据
+  if (lastLog) {
+    const { db } = await import('../storage/database');
+    const tableName = getEntityTableName(entityType);
+    if (tableName) {
+      try {
+        const row = await db.table(tableName).get(entityId);
+        if (row) {
+          return { localDataStr: JSON.stringify(row), localVersion: lastLog.version };
+        }
+      } catch {
+        // 表不存在/读取失败时回退空对象（保持原有行为）
+      }
+    }
+  }
+  return { localDataStr: '{}', localVersion: lastLog?.version ?? 0 };
+}

client/src/types/sync.ts

@@ -18,7 +18,8 @@ export interface OperationLog {
   operation: 'create' | 'update' | 'delete';
   payload?: string;              // JSON 格式的变更数据
   createdAt: Date;
-  synced: boolean;               // 是否已同步到云端
+  /** 是否已同步到云端（SYNC2-H4: 存储为数值 0/1——IndexedDB 键相等判定要求同类型，boolean 与 number 0/1 不相等会导致查询失效） */
+  synced: 0 | 1;
   // MVP-2 新增同步字段
   version: number;
   deviceId: string;