云盘客户端同步（三）：冲突检测与服务端优先的用户处理

function checkOperation(entry, operation) {
  if (operation.type === "create") {
    // 重复提交在进入本函数之前已按 operationId 返回首次结果。
    var sameName = findChildByName(operation.parentId, operation.name);
    if (!sameName) return accept(operation);
    return rejectConflict(operation, "name", sameName, {
      identical: sameName.entryType === operation.entryType &&
        sameName.contentHash === operation.contentHash
    });
  }

  if (!entry) return reject(operation, "not_found");
  if (operation.baseVersion >= entry.version) return accept(operation);

  if (operation.type === "update" &&
      operation.contentHash === entry.contentHash) {
    return acceptAsDuplicate(operation, entry.version);
  }
  if (operation.type === "rename" && operation.name === entry.name) {
    return acceptAsDuplicate(operation, entry.version);
  }
  if (operation.type === "move" && operation.parentId === entry.parentId) {
    return acceptAsDuplicate(operation, entry.version);
  }

  return rejectConflict(operation, conflictTypeOf(entry, operation), entry);
}

// 在第一篇 syncOnce 的 rejected 分支基础上展开：delete 的 not_found
// 按幂等确认，identical 同名 create 自动关闭，version_conflict
// 在同一事务内完成冻结与登记。
result.rejected.forEach(function (item) {
  var operation = tx.readOperation(item.operationId);

  // delete 收到 not_found：服务端对象已不存在，删除意图已达成，按幂等结果确认。
  if (operation.type === "delete" && item.reason === "not_found") {
    // not_found 响应不携带 currentVersion，markOperation 第三参按约定传 null。
    tx.markOperation(item.operationId, "confirmed", null);
    // 服务端不会为这个 operationId 生成日志，按本次响应的游标直接记为已消费。
    tx.markOperationLogConsumed(item.operationId, result.nextCursor);
    tx.clearDeleteTombstone(operation.fileId);
    return;
  }

  if (item.reason !== "version_conflict") {
    var operationState = item.retryable ? "pending" : "failed";
    tx.markOperation(item.operationId, operationState, item.currentVersion);
    tx.saveOperationError(item.operationId, item.reason, item.retryable, {
      currentEntry: item.currentEntry || null,
      conflict: item.conflict || null
    });
    return;
  }

  // identical 同名 create 的自动关闭：服务端同名对象的类型和内容摘要与
  // 本地新建对象一致，删除本地对象不丢内容，不创建副本、不登记下载任务。
  // 前提是本地没有其他引用该 fileId 的未提交操作（例如先建目录再建子项），
  // 存在依赖操作时不自动关闭，落入下方用户冲突流程，由用户决定。
  if (operation.type === "create" && item.conflict.identical &&
      !tx.hasUncommittedOperationFor(operation.fileId)) {
    var localEntry = tx.readEntry(operation.fileId);
    // 删除本地对象会引发事件回流：登记一次性预期 delete 事件，携带
    // 路径与客户端生成的 fileId，事件到达后由监听器核验消费，登记
    // 方式与副本清理一致；实际删除在事务提交后执行。
    tx.expectFsEvent({
      type: "delete",
      path: localEntry.path,
      fileId: operation.fileId,
      conflictId: "conflict-" + item.operationId
    });
    // 冲突记录直接以 keep_server 关闭，不进入待用户处理的 pending 状态。
    tx.createConflictRecord({
      conflictId: "conflict-" + item.operationId,
      fileId: item.currentEntry.fileId,
      baseVersion: operation.baseVersion,
      serverVersion: item.currentVersion,
      localOperationId: item.operationId,
      conflictType: item.conflict.type,
      localCopyPath: null,
      landingState: "applied",
      state: "resolved",
      userAction: "keep_server",
      occurredAt: Date.now()
    });
    // 这条 create 从未被服务端接受，服务端不会为它生成日志；创建意图
    // 已由服务端同名对象达成，按幂等结果确认，并直接写入已消费记录。
    tx.markOperation(item.operationId, "confirmed", item.currentVersion);
    tx.markOperationLogConsumed(item.operationId, result.nextCursor);
    // 移除本地索引条目，服务端对象随后经正常日志拉取落地。
    tx.removeEntry(operation.fileId);
    return;
  }

  // rename/move 前置拦截：服务端没有改动名称和父目录时，落后的只是内容版本，
  // 用 currentVersion 更新 baseVersion 后重新排队，不创建冲突记录。
  if ((operation.type === "rename" || operation.type === "move") &&
      item.currentEntry.name === operation.originalName &&
      item.currentEntry.parentId === operation.originalParentId) {
    tx.markOperation(item.operationId, "pending", item.currentVersion);
    tx.updateOperationBaseVersion(item.operationId, item.currentVersion);
    return;
  }

  var conflictId = "conflict-" + item.operationId;

  tx.markOperation(item.operationId, "conflict", item.currentVersion);
  tx.saveOperationError(item.operationId, item.reason, false, {
    currentEntry: item.currentEntry,
    conflict: item.conflict
  });
  tx.createConflictRecord({
    conflictId: conflictId,
    fileId: item.currentEntry.fileId,
    baseVersion: operation.baseVersion,
    serverVersion: item.currentVersion,
    localOperationId: item.operationId,
    conflictType: item.conflict.type,
    localCopyPath: null,
    landingState: "pending_download",
    state: "landing",
    occurredAt: Date.now()
  });
  // 目录没有内容字节，currentEntry.contentHash 为 null 时不登记下载任务；
  // 对应目录变体的落地流程跳过下载与核验，见下文 landConflict 的说明。
  if (item.currentEntry.contentHash) {
    tx.createDownloadTask({
      fileId: item.currentEntry.fileId,
      version: item.currentVersion,
      contentHash: item.currentEntry.contentHash,
      targetPath: downloadTargetOf(item.currentEntry),
      conflictId: conflictId,
      state: "pending"
    });
  }
});
// 事务其余部分不变，最后统一 tx.saveRemoteCursor(result.nextCursor)。

// 对应 update/rename/move 冲突路径：服务端已存在同 fileId 的条目，
// 本地路径直接按 conflict.fileId 查索引。create 冲突的落地变体见下文。
function landConflict(store, fs, conflictId, callback) {
  var prepared = store.transaction(function (tx) {
    var conflict = tx.readConflict(conflictId);
    var entry = tx.readEntry(conflict.fileId);
    // 门禁按对象类型分支：目录没有内容字节，冲突登记时不创建下载
    // 任务，folder 只核对 landingState；文件还要求下载任务核验完成。
    if (conflict.landingState !== "pending_download") {
      return null;
    }
    var task = null;
    if (entry.entryType !== "folder") {
      task = tx.readDownloadTask(conflictId);
      if (task.state !== "verified") {
        return null;
      }
    }

    var operation = tx.readOperation(conflict.localOperationId);
    var copyPath = tx.allocateConflictCopyPath(entry.path,
      tx.deviceName(), conflict.occurredAt);

    // copyContentHash 是本地内容的摘要，登记副本时使用：update 冲突取被拒绝
    // 操作的 contentHash，rename/move 不改动内容，取本地索引条目的摘要。
    // 下方的 task.contentHash 是服务端版本的摘要，只用于核验写回原路径的
    // 预期 create 事件。两者来源不同，不能混用。
    var copyContentHash = operation.type === "update"
      ? operation.contentHash
      : entry.contentHash;

    tx.expectFsEvent({
      type: "rename",
      from: entry.path,
      to: copyPath,
      fileId: conflict.fileId,
      conflictId: conflictId
    });
    tx.expectFsEvent({
      type: "create",
      path: entry.path,
      fileId: conflict.fileId,
      version: conflict.serverVersion,
      // 目录变体的 task 为 null，这条事件不带 contentHash。
      contentHash: task && task.contentHash,
      conflictId: conflictId
    });
    tx.updateConflictLanding(conflictId, "renaming", {
      localCopyPath: copyPath
    });

    return {
      fileId: conflict.fileId,
      originalPath: entry.path,
      copyPath: copyPath,
      copyContentHash: copyContentHash,
      // 副本登记需要对象类型，keepLocalVersion 按 copy.entryType
      // 拦截目录副本。主流程取自本地索引条目；create 目录变体取自
      // 被移除条目的 entryType。
      entryType: entry.entryType,
      // 文件冲突的 task 已通过门禁；目录变体没有 task，这两个字段
      // 为 null，目录落地在下方执行段的 entryType 分流中不读取它们。
      tempPath: task && task.tempPath,
      version: conflict.serverVersion,
      contentHash: task && task.contentHash
    };
  });

  if (!prepared) return callback(null, false);

  fs.rename(prepared.originalPath, prepared.copyPath, function (renameErr) {
    if (renameErr) {
      return store.failConflictLanding(conflictId, renameErr, callback);
    }
    store.markConflictLanding(conflictId, "renamed", function (markErr) {
      if (markErr) return callback(markErr);
      // 执行段按对象类型分流：文件把下载核验过的临时文件原子替换到
      // 原路径；目录没有临时文件，直接在原路径创建目录。
      if (prepared.entryType === "folder") {
        fs.mkdir(prepared.originalPath, function (mkdirErr) {
          if (mkdirErr) {
            return store.failConflictLanding(conflictId, mkdirErr, callback);
          }
          finishConflictLanding(store, prepared, conflictId, callback);
        });
        return;
      }
      atomicReplace(prepared.tempPath, prepared.originalPath,
        function (replaceErr) {
          if (replaceErr) {
            return store.failConflictLanding(conflictId, replaceErr, callback);
          }
          finishConflictLanding(store, prepared, conflictId, callback);
        });
    });
  });
}

// 文件原子替换与目录创建之后汇合的最终事务。
function finishConflictLanding(store, prepared, conflictId, callback) {
  store.transaction(function (tx) {
    tx.updateConflictLanding(conflictId, "applied", null);
    tx.updateConflictState(conflictId, "pending");
    tx.updateEntryVersion(prepared.fileId, prepared.version);
    // 副本登记为不参与同步的索引对象，摘要取本地内容的
    // copyContentHash，后续事件归并入冲突记录。entryType 随
    // 副本一并登记，作为 copy.entryType 的写入来源。
    tx.addConflictCopy(conflictId, prepared.copyPath,
      prepared.copyContentHash, prepared.entryType);
  }, callback);
}

// create 冲突落地变体相对 landConflict 的关键差异：
var operation = tx.readOperation(conflict.localOperationId);
var clientFileId = operation.fileId; // 客户端生成、服务端从未接受
var localEntry = tx.readEntry(clientFileId);
// 重命名的 from 取 localEntry.path，预期 rename 事件登记 clientFileId。
// 最终事务在 updateConflictLanding 等步骤之外补一条：
tx.removeEntry(clientFileId);

function keepLocalVersion(store, conflictId, callback) {
  store.transaction(function (tx) {
    var state = tx.readSyncState();
    var conflict = tx.readConflict(conflictId);
    var entry = tx.readEntry(conflict.fileId);
    var copy = tx.readConflictCopy(conflictId);

    // 只有落地完成、等待用户处理的冲突才能执行这个动作。
    // 第三项是防御判断：索引版本落后于冲突记录的服务端版本说明落地未完成。
    // create 冲突的服务端条目要等后续日志拉取落地，落地前 entry 为空，
    // 空值与版本落后一样按未就绪返回，风格与 task && task.contentHash 一致。
    // 连续冲突时索引版本可能已被常规日志拉取推进，属于正常情况，
    // appendOperation 会以它为新的 baseVersion。
    if (conflict.state !== "pending" ||
        conflict.landingState !== "applied" ||
        !entry || entry.version < conflict.serverVersion) {
      return { error: "conflict_not_ready" };
    }
    // delete 冲突没有本地内容需要保护，不登记副本，落地后直接标记
    // resolved，正常流程到不了这里。这里防御副本记录为空的情况：
    // 没有副本就没有可上传的内容，动作不适用。该判断必须放在下方
    // copy.entryType 读取之前。
    if (!copy) {
      tx.saveConflictLastError(conflictId, "action_not_applicable");
      return { error: "action_not_applicable" };
    }
    // 本动作只适用于有内容的文件冲突。目录副本没有内容字节，
    // contentHash 为空属于正常情况，必须先按对象类型拦截，
    // 否则下方的副本缺失判断会把目录副本误判为缺失。
    if (copy.entryType === "folder") {
      tx.saveConflictLastError(conflictId, "action_not_applicable");
      return { error: "action_not_applicable" };
    }
    // 新操作以副本路径为上传来源，副本在确认前不可删除。
    if (!copy.exists || !copy.contentHash) {
      // 错误写入冲突记录的 lastError，不覆盖旧操作的 version_conflict 记录。
      tx.saveConflictLastError(conflictId, "conflict_copy_missing");
      return { error: "conflict_copy_missing" };
    }

    var sequence = tx.nextSequence();
    tx.appendOperation({
      operationId: state.deviceId + ":" + sequence,
      deviceId: state.deviceId,
      sequence: sequence,
      type: "update",
      fileId: conflict.fileId,
      baseVersion: entry.version,
      contentHash: copy.contentHash,
      sourcePath: copy.path,
      state: "pending",
      resolvesConflictId: conflictId
    });
    tx.resolveConflict(conflictId, "keep_local",
      state.deviceId + ":" + sequence);
    return { error: null };
  }, callback);
}

// 新操作确认且对应服务端日志已消费后，才能清理副本。
function cleanupConflictCopy(store, fs, conflictId, callback) {
  var prepared = store.transaction(function (tx) {
    var conflict = tx.readConflict(conflictId);
    if (conflict.userAction !== "keep_local" ||
        !conflict.resolveOperationId) {
      return null;
    }
    var operation = tx.readOperation(conflict.resolveOperationId);
    if (!operation || operation.state !== "confirmed" ||
        !tx.isOperationLogConsumed(operation.operationId)) {
      return null;
    }

    var copy = tx.readConflictCopy(conflictId);
    tx.expectFsEvent({
      type: "delete",
      path: copy.path,
      conflictId: conflictId
    });
    // 先持久化 deleting 中间状态，删除成功后才标记 deleted。
    tx.markConflictCopyDeleting(conflictId);
    return { path: copy.path };
  });

  if (!prepared) return callback(null, false);
  fs.unlink(prepared.path, function (unlinkErr) {
    if (unlinkErr) {
      return store.failConflictCopyDelete(conflictId, unlinkErr, callback);
    }
    store.markConflictCopyDeleted(conflictId, callback);
  });
}