dsh-todo-time-log 0.6.0 → 0.6.2

package/lib/index.js

@@ -25,12 +25,14 @@ import {
   TYPES,
   MAX_FILES,
   MAX_PROJECT_LENGTH,
+  IMPORT_MODES,
   normalizeFilePath,
   normalizeProjectName,
 } from './store.js';
 import { formatLocalDateTime, TIME_FORMAT, EMPTY_TIME } from './time.js';
 import { parseQuickAdd, parseQuickAddLine, hasQuickAddMarkers } from './parse.js';
 import { createFileIndex } from './files.js';
+import { EXPORT_FORMATS, exportTodoData, parseImportText } from './transfer.js';
 
 /**
  * A todo record exactly as `store.js` persists it (see the data-model comment
@@ -283,6 +285,8 @@ export const DEFAULT_CONFIG = Object.freeze({
 });
 
 const MAX_BODY_BYTES = 1024 * 1024;
+/** Import payloads carry a whole backup (5000 records can exceed 1 MiB). */
+const MAX_IMPORT_BODY_BYTES = 8 * 1024 * 1024;
 
 /** Tool/HTTP-facing priority enum: '' = 未设置 (default). */
 export const PRIORITY_VALUES = Object.freeze(['', ...PRIORITIES]);
@@ -1026,7 +1030,14 @@ function httpStatusForCode(code) {
     case 'TYPE_INVALID':
     case 'FILES_INVALID':
     case 'TOO_MANY_FILES':
+    case 'IMPORT_EMPTY':
+    case 'IMPORT_INVALID':
+    case 'IMPORT_FORMAT_UNSUPPORTED':
+    case 'IMPORT_VERSION_UNSUPPORTED':
+    case 'BACKUP_INVALID':
       return 400;
+    case 'PAYLOAD_TOO_LARGE':
+      return 413;
     case 'NOT_FOUND':
       return 404;
     case 'ALREADY_COMPLETED':
@@ -1034,6 +1045,8 @@ function httpStatusForCode(code) {
     case 'TOO_MANY_TODOS':
       return 409;
     case 'PERSIST_FAILED':
+    case 'IMPORT_FAILED':
+    case 'BACKUP_FAILED':
       return 500;
     default:
       return 500;
@@ -1060,22 +1073,30 @@ function sendJson(res, status, payload) {
  * Read and parse a JSON request body (an empty body means `{}`).
  *
  * @param {import('node:http').IncomingMessage} req
+ * @param {number} [limit]  maximum accepted byte size (import allows more)
  * @returns {Promise<Record<string, any>>}
  */
-function readJsonBody(req) {
+function readJsonBody(req, limit = MAX_BODY_BYTES) {
   return new Promise((resolve, reject) => {
     const chunks = [];
     let size = 0;
+    let failed = false;
     req.on('data', (chunk) => {
+      if (failed) return;
       size += chunk.length;
-      if (size > MAX_BODY_BYTES) {
-        reject(Object.assign(new Error('请求体过大'), { code: 'BAD_REQUEST' }));
-        req.destroy();
+      if (size > limit) {
+        if (!failed) {
+          failed = true;
+          reject(Object.assign(new Error('请求体过大'), { code: 'PAYLOAD_TOO_LARGE' }));
+        }
+        // Keep draining (and discarding) the rest of the upload so the client
+        // can read the 413 instead of seeing a connection reset.
         return;
       }
       chunks.push(chunk);
     });
     req.on('end', () => {
+      if (failed) return;
       if (chunks.length === 0) {
         resolve({});
         return;
@@ -1211,19 +1232,31 @@ export function createHttpHandler(store, options = {}) {
         });
         return;
       }
-      const EXTRA_PATHS = ['quick-add', 'quick_add', 'files', 'workspaces', 'projects'];
+      const EXTRA_PATHS = [
+        'quick-add',
+        'quick_add',
+        'files',
+        'workspaces',
+        'projects',
+        'export',
+        'import',
+        'restore',
+      ];
       if (!CRUD_ACTIONS.includes(action) && !EXTRA_PATHS.includes(action)) {
         sendJson(res, 404, {
           ok: false,
           error: {
             code: 'NOT_FOUND',
-            message: `未知接口：${action}；可用接口：${[...CRUD_ACTIONS, 'quick-add', 'files'].join(', ')}`,
+            message: `未知接口：${action}；可用接口：${[...CRUD_ACTIONS, ...EXTRA_PATHS].join(', ')}`,
           },
         });
         return;
       }
 
-      const body = await readJsonBody(req);
+      const body = await readJsonBody(
+        req,
+        action === 'import' ? MAX_IMPORT_BODY_BYTES : MAX_BODY_BYTES,
+      );
 
       if (action === 'workspaces') {
         const candidates = listWorkspaces();
@@ -1326,6 +1359,95 @@ export function createHttpHandler(store, options = {}) {
         sendJson(res, 200, { ok: true, value: listing });
         return;
       }
+      if (action === 'export') {
+        const requested = body.format === undefined || body.format === null || body.format === ''
+          ? 'json'
+          : String(body.format).trim().toLowerCase();
+        if (!EXPORT_FORMATS.includes(requested)) {
+          sendJson(res, 400, {
+            ok: false,
+            error: { code: 'EXPORT_FORMAT_UNSUPPORTED', message: '只支持导出 JSON 或 CSV' },
+          });
+          return;
+        }
+        // Merge what other instances wrote before serializing: a download must
+        // never be a stale snapshot. A failure here still exports what we have.
+        await store.refresh();
+        const listed = await store.list({ filter: 'all' });
+        const exported = exportTodoData(listed.todos ?? [], { format: requested });
+        sendJson(res, 200, { ok: true, value: exported });
+        return;
+      }
+
+      if (action === 'import') {
+        const content = typeof body.content === 'string'
+          ? body.content
+          : (typeof body.text === 'string' ? body.text : '');
+        if (content.trim() === '') {
+          sendJson(res, 400, {
+            ok: false,
+            error: { code: 'IMPORT_EMPTY', message: '导入内容为空' },
+          });
+          return;
+        }
+        const parsed = parseImportText(content, { format: body.format });
+        if (parsed.ok !== true) {
+          sendJson(res, httpStatusForCode(parsed.code), {
+            ok: false,
+            error: { code: parsed.code, message: parsed.message },
+          });
+          return;
+        }
+        const mode = IMPORT_MODES.includes(body.mode) ? body.mode : 'merge';
+        const dryRun = body.dryRun === true;
+        const result = await store.importTodos(parsed.records, { mode, dryRun });
+        if (result.ok !== true) {
+          sendJson(res, httpStatusForCode(result.code), {
+            ok: false,
+            error: { code: result.code, message: result.message },
+          });
+          return;
+        }
+        sendJson(res, 200, {
+          ok: true,
+          value: {
+            format: parsed.format,
+            mode,
+            dryRun,
+            rowCount: parsed.rowCount,
+            summary: result.summary,
+            invalid: parsed.invalid,
+            invalidCount: parsed.invalidCount,
+            notices: [...(parsed.notices ?? []), ...(result.notices ?? [])],
+            backup: result.backup ?? null,
+            persisted: result.persisted !== false,
+          },
+        });
+        return;
+      }
+
+      if (action === 'restore') {
+        const result = await store.restoreBackup(body.file);
+        if (result.ok !== true) {
+          sendJson(res, httpStatusForCode(result.code), {
+            ok: false,
+            error: { code: result.code, message: result.message },
+          });
+          return;
+        }
+        sendJson(res, 200, {
+          ok: true,
+          value: {
+            restored: result.restored,
+            dropped: result.dropped,
+            backup: result.backup ?? null,
+            notices: result.notices ?? [],
+            persisted: result.persisted !== false,
+          },
+        });
+        return;
+      }
+
       const result = await executeTodoAction(store, action, body);
       if (result.ok === false) {
         sendJson(res, httpStatusForCode(result.code), {
@@ -1337,9 +1459,11 @@ export function createHttpHandler(store, options = {}) {
       const { ok: _ok, ...value } = result;
       sendJson(res, 200, { ok: true, value });
     } catch (error) {
-      const code = error?.code === 'BAD_REQUEST' ? 'BAD_REQUEST' : 'INTERNAL';
+      const code = error?.code === 'BAD_REQUEST'
+        ? 'BAD_REQUEST'
+        : error?.code === 'PAYLOAD_TOO_LARGE' ? 'PAYLOAD_TOO_LARGE' : 'INTERNAL';
       const message = error?.message ?? String(error);
-      sendJson(res, code === 'BAD_REQUEST' ? 400 : 500, { ok: false, error: { code, message } });
+      sendJson(res, httpStatusForCode(code), { ok: false, error: { code, message } });
     }
   };
 }

package/lib/store.js

@@ -70,6 +70,37 @@ export const MAX_FILE_PATH_LENGTH = 300;
 export const UNCATEGORIZED_PROJECT = '';
 export const MAX_TODOS = 5000;
 
+/**
+ * Extract the todo rows from an already-parsed store document. Accepts the
+ * persisted envelope (`{ version, todos }`) and a bare `Todo[]`, and rejects a
+ * version this build does not understand instead of guessing at it.
+ *
+ * Shared by backup restore and import so both read exactly the same shapes the
+ * store itself writes.
+ *
+ * @param {any} parsed
+ * @returns {{ ok: true, rows: any[], version: number | null } | { ok: false, code: string, message: string, version?: number }}
+ */
+export function extractStoreRows(parsed) {
+  if (Array.isArray(parsed)) return { ok: true, rows: parsed, version: null };
+  if (parsed === null || typeof parsed !== 'object') {
+    return { ok: false, code: 'SHAPE_INVALID', message: '不是待办数据' };
+  }
+  const version = parsed.version;
+  if (typeof version === 'number' && !SUPPORTED_STORE_VERSIONS.includes(version)) {
+    return {
+      ok: false,
+      code: 'VERSION_UNSUPPORTED',
+      version,
+      message: `数据版本 ${version} 不受支持（支持 1-${STORE_VERSION}）`,
+    };
+  }
+  if (!Array.isArray(parsed.todos)) {
+    return { ok: false, code: 'SHAPE_INVALID', message: '缺少 todos 数组' };
+  }
+  return { ok: true, rows: parsed.todos, version: typeof version === 'number' ? version : null };
+}
+
 export const ERROR_CODES = Object.freeze({
   TITLE_REQUIRED: 'TITLE_REQUIRED',
   TITLE_TOO_LONG: 'TITLE_TOO_LONG',
@@ -84,9 +115,18 @@ export const ERROR_CODES = Object.freeze({
   ALREADY_PENDING: 'ALREADY_PENDING',
   TOO_MANY_TODOS: 'TOO_MANY_TODOS',
   PERSIST_FAILED: 'PERSIST_FAILED',
+  IMPORT_EMPTY: 'IMPORT_EMPTY',
+  IMPORT_INVALID: 'IMPORT_INVALID',
+  IMPORT_FAILED: 'IMPORT_FAILED',
+  BACKUP_INVALID: 'BACKUP_INVALID',
+  BACKUP_FAILED: 'BACKUP_FAILED',
   BAD_REQUEST: 'BAD_REQUEST',
 });
 
+/** Conflict strategies accepted by `TodoStore.importTodos()`. */
+export const IMPORT_MODES = Object.freeze(['merge', 'add', 'replace']);
+export const DEFAULT_IMPORT_MODE = 'merge';
+
 function failure(code, message) {
   return { ok: false, code, message };
 }
@@ -498,6 +538,33 @@ async function writeFileAtomic(file, text) {
   }
 }
 
+/** An Error carrying the same `code` vocabulary as the result envelopes. */
+function codedError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+/** Local-time stamp used in backup file names: `20261106-085732-123`. */
+function backupStamp(date) {
+  const pad = (value, width = 2) => String(value).padStart(width, '0');
+  return (
+    `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-`
+    + `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}-`
+    + pad(date.getMilliseconds(), 3)
+  );
+}
+
+/** Human-readable one-line summary of an import plan. */
+function importSummary(stats) {
+  const parts = [];
+  if (stats.added > 0) parts.push(`新增 ${stats.added} 条`);
+  if (stats.updated > 0) parts.push(`更新 ${stats.updated} 条`);
+  if (stats.skipped > 0) parts.push(`跳过 ${stats.skipped} 条`);
+  if (stats.removed > 0) parts.push(`移除 ${stats.removed} 条`);
+  if (parts.length === 0) return '没有需要变更的待办';
+  const prefix = stats.mode === 'replace' ? '已覆盖全部数据：' : '导入完成：';
+  return `${prefix}${parts.join('，')}（当前共 ${stats.total} 条）`;
+}
+
 /**
  * The single owner of todo state for one data file.
  *
@@ -900,6 +967,386 @@ export class TodoStore {
     );
   }
 
+  /**
+   * Merge what other processes wrote since our last known state without writing
+   * anything. Used before an export so a download is never a stale snapshot, and
+   * by the import preview so its counts match the current disk state.
+   *
+   * @returns {Promise<{ ok: true, count: number }>}
+   */
+  async refresh() {
+    await this.#ensureLoaded();
+    try {
+      await this.#persistChain;
+    } catch {
+      /* the failed write was already reported to its own caller */
+    }
+    await this.#mergeIfDiskChanged();
+    return { ok: true, count: this.#todos.size };
+  }
+
+  /**
+   * Import already-normalized records in one write.
+   *
+   * Modes:
+   *   merge   - same id: the record with the newer `updatedAt` wins; unknown ids
+   *             are added (the default).
+   *   add     - same id: the existing record wins (skip); unknown ids are added.
+   *   replace - the imported records replace the whole list; the current file is
+   *             backed up first.
+   *
+   * `dryRun: true` computes the same plan against the refreshed state without
+   * writing anything or touching the in-memory list.
+   *
+   * @param {object[]} records
+   * @param {{ mode?: string, dryRun?: boolean }} [options]
+   * @returns {Promise<object>}
+   */
+  async importTodos(records, options = {}) {
+    await this.#ensureLoaded();
+    const mode = IMPORT_MODES.includes(options.mode) ? options.mode : DEFAULT_IMPORT_MODE;
+    const dryRun = options.dryRun === true;
+    if (!Array.isArray(records) || records.length === 0) {
+      return failure(ERROR_CODES.IMPORT_EMPTY, '没有可导入的待办');
+    }
+    if (records.length > MAX_TODOS) {
+      return failure(ERROR_CODES.TOO_MANY_TODOS, `单次导入不能超过 ${MAX_TODOS} 条待办`);
+    }
+    // Re-run the same repair/validation every other write path uses, so a
+    // direct caller cannot smuggle an invalid record into the store.
+    const normalized = [];
+    for (const record of records) {
+      const repaired = normalizeTodo(record, { now: this.now() });
+      if (repaired.todo !== null) normalized.push(repaired.todo);
+    }
+    if (normalized.length === 0) {
+      return failure(ERROR_CODES.IMPORT_INVALID, '没有可导入的有效待办');
+    }
+    if (dryRun) {
+      await this.refresh();
+      const plan = this.#planImport(normalized, mode);
+      if (plan.stats.total > MAX_TODOS) {
+        return failure(
+          ERROR_CODES.TOO_MANY_TODOS,
+          `导入后共 ${plan.stats.total} 条待办，超过上限 ${MAX_TODOS} 条`,
+        );
+      }
+      return { ok: true, dryRun: true, summary: plan.stats, notices: [] };
+    }
+
+    let applied;
+    try {
+      applied = await this.#persistImport(normalized, mode);
+    } catch (error) {
+      if (error?.code === ERROR_CODES.TOO_MANY_TODOS || error?.code === ERROR_CODES.BACKUP_FAILED) {
+        return failure(error.code, error.message);
+      }
+      return failure(ERROR_CODES.IMPORT_FAILED, `导入失败：${error?.message ?? String(error)}`);
+    }
+    if (applied.persisted === false) {
+      return {
+        ok: true,
+        dryRun: false,
+        summary: applied.stats,
+        backup: applied.backupFile,
+        notices: [`导入已生效，但写入磁盘失败，将在下次写入时重试：${applied.error}`],
+        persisted: false,
+      };
+    }
+    return {
+      ok: true,
+      dryRun: false,
+      summary: applied.stats,
+      backup: applied.backupFile,
+      notices: [importSummary(applied.stats)],
+      persisted: true,
+    };
+  }
+
+  /**
+   * Restore the whole list from a backup produced by this store
+   * (`<dataFile>.bak-<stamp>`). The current state is backed up first, so an
+   * undesired restore can itself be undone by restoring that safety copy.
+   *
+   * @param {string} file  backup file name (basename only)
+   * @returns {Promise<object>}
+   */
+  async restoreBackup(file) {
+    await this.#ensureLoaded();
+    const resolved = this.#resolveBackupFile(file);
+    if (resolved.ok !== true) return resolved;
+    let text;
+    try {
+      text = await fsp.readFile(resolved.path, 'utf8');
+    } catch {
+      return failure(ERROR_CODES.BACKUP_INVALID, `无法读取备份文件：${String(file)}`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return failure(ERROR_CODES.BACKUP_INVALID, '备份文件不是合法 JSON，无法恢复');
+    }
+    const extracted = extractStoreRows(parsed);
+    if (extracted.ok !== true) {
+      return failure(ERROR_CODES.BACKUP_INVALID, `备份文件结构异常：${extracted.message}`);
+    }
+    const next = new Map();
+    const notices = [];
+    let dropped = 0;
+    for (const row of extracted.rows) {
+      const { todo, notices: rowNotices } = normalizeTodo(row, { now: this.now() });
+      if (todo === null) {
+        dropped += 1;
+        continue;
+      }
+      let record = todo;
+      if (next.has(record.id)) {
+        record = { ...record, id: makeTodoId(this.now()) };
+        const note = '备份中存在重复 id 的记录，已为后者重新生成 id';
+        if (!notices.includes(note)) notices.push(note);
+      }
+      next.set(record.id, record);
+      for (const notice of rowNotices) {
+        if (!notices.includes(notice)) notices.push(notice);
+      }
+    }
+    if (next.size === 0) {
+      return failure(ERROR_CODES.BACKUP_INVALID, '备份文件里没有可恢复的待办');
+    }
+    let outcome;
+    try {
+      outcome = await this.#replaceAll(next);
+    } catch (error) {
+      if (error?.code === ERROR_CODES.BACKUP_FAILED) {
+        return failure(error.code, error.message);
+      }
+      return failure(ERROR_CODES.PERSIST_FAILED, `恢复失败：${error?.message ?? String(error)}`);
+    }
+    notices.unshift(`已从备份恢复 ${next.size} 条待办`);
+    if (dropped > 0) notices.push(`已丢弃 ${dropped} 条非法待办记录`);
+    if (outcome.persisted === false) {
+      notices.push(`恢复已生效，但写入磁盘失败，将在下次写入时重试：${outcome.error}`);
+    }
+    return {
+      ok: true,
+      restored: next.size,
+      dropped,
+      backup: outcome.backupFile,
+      notices,
+      persisted: outcome.persisted !== false,
+    };
+  }
+
+  /**
+   * Compute the list import would produce, without mutating anything.
+   * Runs while holding the write lock in `#persistImport`, so the plan is
+   * computed against the merged on-disk state.
+   */
+  #planImport(records, mode) {
+    const before = this.#todos;
+    const next = mode === 'replace' ? new Map() : new Map(before);
+    const stats = {
+      mode,
+      added: 0,
+      updated: 0,
+      skipped: 0,
+      removed: 0,
+      total: 0,
+      changed: false,
+    };
+    const imported = new Set();
+    for (const record of records) {
+      if (imported.has(record.id)) {
+        stats.skipped += 1;
+        continue;
+      }
+      imported.add(record.id);
+      const existing = next.get(record.id);
+      const existedBefore = before.has(record.id);
+      if (existing === undefined) {
+        next.set(record.id, record);
+        if (existedBefore) stats.updated += 1;
+        else stats.added += 1;
+        continue;
+      }
+      if (mode === 'replace' || mode === 'add') {
+        stats.skipped += 1;
+        continue;
+      }
+      const existingMs = parseTimestamp(existing.updatedAt);
+      const incomingMs = parseTimestamp(record.updatedAt);
+      if (incomingMs !== null && (existingMs === null || incomingMs > existingMs)) {
+        next.set(record.id, record);
+        stats.updated += 1;
+      } else {
+        stats.skipped += 1;
+      }
+    }
+    if (mode === 'replace') {
+      for (const id of before.keys()) {
+        if (!next.has(id)) stats.removed += 1;
+      }
+    }
+    stats.total = next.size;
+    stats.changed = stats.added > 0 || stats.updated > 0 || stats.removed > 0;
+    return { next, stats };
+  }
+
+  /** Apply an import plan under the write lock, backing up the current file first. */
+  async #persistImport(records, mode) {
+    let outcome;
+    const write = async () => {
+      let applied = false;
+      let plan = null;
+      let backupFile = null;
+      await this.#acquireLock();
+      try {
+        await this.#mergeIfDiskChanged();
+        plan = this.#planImport(records, mode);
+        if (plan.stats.total > MAX_TODOS) {
+          throw codedError(
+            ERROR_CODES.TOO_MANY_TODOS,
+            `导入后共 ${plan.stats.total} 条待办，超过上限 ${MAX_TODOS} 条`,
+          );
+        }
+        if (!plan.stats.changed) {
+          outcome = { stats: plan.stats, backupFile: null, persisted: true };
+          return outcome;
+        }
+        backupFile = await this.#createBackup();
+        this.#todos = plan.next;
+        for (const record of records) {
+          // Only drop the tombstone for records this import actually applied;
+          // a skipped older copy must not resurrect a locally deleted todo.
+          if (plan.next.get(record.id) === record) this.#tombstones.delete(record.id);
+        }
+        applied = true;
+        const text = this.serialize();
+        await writeFileAtomic(this.dataFile, text);
+        let stat = null;
+        try {
+          stat = await fsp.stat(this.dataFile);
+        } catch {
+          /* unknown mtime: the next write re-reads and the hash skips the merge */
+        }
+        this.#adoptDiskState(stat, text);
+        this.#lastPersistError = null;
+        outcome = { stats: plan.stats, backupFile, persisted: true };
+        return outcome;
+      } catch (error) {
+        // A write failure after the in-memory list changed keeps the import in
+        // memory (the next write retries), matching create/remove semantics.
+        if (!applied || plan === null) throw error;
+        this.#lastPersistError = error?.message ?? String(error);
+        this.#warn(`todo-time-log: import persist failed: ${this.#lastPersistError}`);
+        outcome = {
+          stats: plan.stats,
+          backupFile,
+          persisted: false,
+          error: this.#lastPersistError,
+        };
+        return outcome;
+      } finally {
+        await this.#releaseLock();
+      }
+    };
+    const chained = this.#persistChain.then(write, write);
+    this.#persistChain = chained.then(() => undefined, () => undefined);
+    return chained;
+  }
+
+  /** Replace the whole list under the write lock (backup restore). */
+  async #replaceAll(nextMap) {
+    let outcome;
+    const write = async () => {
+      let applied = false;
+      let backupFile = null;
+      await this.#acquireLock();
+      try {
+        backupFile = await this.#createBackup();
+        this.#todos = nextMap;
+        this.#tombstones.clear();
+        applied = true;
+        const text = this.serialize();
+        await writeFileAtomic(this.dataFile, text);
+        let stat = null;
+        try {
+          stat = await fsp.stat(this.dataFile);
+        } catch {
+          /* unknown mtime */
+        }
+        this.#adoptDiskState(stat, text);
+        this.#lastPersistError = null;
+        outcome = { backupFile, persisted: true };
+        return outcome;
+      } catch (error) {
+        if (!applied) throw error;
+        this.#lastPersistError = error?.message ?? String(error);
+        this.#warn(`todo-time-log: restore persist failed: ${this.#lastPersistError}`);
+        outcome = { backupFile, persisted: false, error: this.#lastPersistError };
+        return outcome;
+      } finally {
+        await this.#releaseLock();
+      }
+    };
+    const chained = this.#persistChain.then(write, write);
+    this.#persistChain = chained.then(() => undefined, () => undefined);
+    return chained;
+  }
+
+  /**
+   * Copy the current data file next to itself as `<dataFile>.bak-<stamp>`.
+   * Called while the write lock is held. Returns the basename (safe to hand to
+   * a client and post back to `restoreBackup`) or null when no file exists yet.
+   */
+  async #createBackup() {
+    let stat;
+    try {
+      stat = await fsp.stat(this.dataFile);
+    } catch {
+      return null;
+    }
+    if (!stat.isFile()) return null;
+    const base = `${this.dataFile}.bak-${backupStamp(new Date(this.now()))}`;
+    // Two operations in the same millisecond (or a fixed test clock) must not
+    // overwrite an earlier safety copy.
+    let backupFile = base;
+    let suffix = 0;
+    for (;;) {
+      try {
+        await fsp.access(backupFile);
+      } catch {
+        break;
+      }
+      suffix += 1;
+      backupFile = `${base}-${suffix}`;
+    }
+    try {
+      await fsp.copyFile(this.dataFile, backupFile);
+    } catch (error) {
+      throw codedError(
+        ERROR_CODES.BACKUP_FAILED,
+        `导入前备份失败，已取消导入：${error?.message ?? String(error)}`,
+      );
+    }
+    return path.basename(backupFile);
+  }
+
+  /** Validate that `file` is a `.bak-*` sibling of the data file. */
+  #resolveBackupFile(file) {
+    const name = typeof file === 'string' ? file.trim() : '';
+    if (name === '') return failure(ERROR_CODES.BACKUP_INVALID, '备份文件名不能为空');
+    if (name !== path.basename(name) || name.includes('/') || name.includes('\\')) {
+      return failure(ERROR_CODES.BACKUP_INVALID, '备份文件名不合法');
+    }
+    const base = path.basename(this.dataFile);
+    if (!name.startsWith(`${base}.bak-`)) {
+      return failure(ERROR_CODES.BACKUP_INVALID, '只允许恢复本插件生成的待办备份（.bak-*）');
+    }
+    return { ok: true, path: path.join(path.dirname(this.dataFile), name) };
+  }
+
   #persist() {
     const write = async () => {
       await this.#acquireLock();