dsh-config-manager 0.1.71 → 0.1.73

package/src/client/sync/sync-api.test.ts

@@ -7,6 +7,7 @@ import assert from 'node:assert/strict';
 
 import { ConfigManagerApiError } from '../api.ts';
 import { SYNC_API, SYNC_WEBDAV_CREDENTIAL_REF, SyncApi } from './sync-api.ts';
+import { zhUiT } from '../../ui/i18n.ts';
 
 interface FetchCall {
   url: string;
@@ -57,7 +58,7 @@ test('S-01 api.status()：GET 到 /sync/status，解析配置/凭据/上次同
   // 经读取函数解除闭包赋值导致的 CFA 窄化（called 在回调内赋值，外部保持 null 窄化）
   const lastCall = (): FetchCall | null => called;
 
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.configured, true);
   assert.equal(result.repoUrl, 'https://github.com/u/r.git');
@@ -73,7 +74,7 @@ test('S-02 api.push()：POST /sync/push，请求体携带 repoUrl/token', async
     return jsonResponse(200, { ok: true, snapshotId: 'sync-1', sections: ['settings'], warnings: [] });
   });
 
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.push({ repoUrl: 'https://github.com/u/r.git', token: 'ghp_secret' });
   assert.equal(result.ok, true);
   assert.equal(result.snapshotId, 'sync-1');
@@ -97,7 +98,7 @@ test('S-03 api.pull()：POST /sync/pull，strategy 缺省透传 merge，响应
     });
   });
 
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.pull({ repoUrl: 'https://github.com/u/r.git', strategy: 'merge' });
   assert.equal(result.changes.length, 1);
   assert.equal(result.changes[0]?.kind, 'Conflict');
@@ -109,7 +110,7 @@ test('S-03 api.pull()：POST /sync/pull，strategy 缺省透传 merge，响应
 
 test('S-04 错误映射：4xx 携带 error → ConfigManagerApiError', async () => {
   installFetchMock(() => jsonResponse(400, { error: 'repoUrl is required' }));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await assert.rejects(api.push({ repoUrl: '' }), (err: unknown) => {
     assert.ok(err instanceof ConfigManagerApiError);
     assert.match(err.message, /repoUrl is required/);
@@ -120,7 +121,7 @@ test('S-04 错误映射：4xx 携带 error → ConfigManagerApiError', async ()
 test('S-05 服务未挂载：404（非 JSON 体）→ ConfigManagerApiError 提示插件未加载', async () => {
   // 路由不存在时宿主返回 404 但无 JSON error → readJson 兜底为「插件未挂载」提示
   installFetchMock(() => new Response('Not Found', { status: 404 }));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await assert.rejects(api.status(), (err: unknown) => {
     assert.ok(err instanceof ConfigManagerApiError);
     assert.match(err.message, /未挂载/);
@@ -141,7 +142,7 @@ test('S-06 api.githubStart()：POST /sync/github/start，解析 flowId/userCode/
     return jsonResponse(200, body);
   });
 
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.githubStart();
   assert.equal(result.flowId, 'flow-1');
   assert.equal(result.userCode, 'ABCD-EFGH');
@@ -157,7 +158,7 @@ test('S-07 api.githubPoll()：POST /sync/github/poll 携带 flowId；pending 透
     return jsonResponse(200, { status: 'pending', pollDelayMs: 5000 });
   });
 
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.githubPoll('flow-1');
   assert.equal(result.status, 'pending');
   assert.equal(result.pollDelayMs, 5000);
@@ -168,7 +169,7 @@ test('S-07 api.githubPoll()：POST /sync/github/poll 携带 flowId；pending 透
 
 test('S-08 api.githubPoll() 成功 → 响应只含状态，token 永不回传', async () => {
   installFetchMock(() => jsonResponse(200, { status: 'success', credentialConfigured: true }));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.githubPoll('flow-1');
   assert.equal(result.status, 'success');
   assert.equal(result.credentialConfigured, true);
@@ -182,7 +183,7 @@ test('S-09 api.githubCancel()：POST /sync/github/cancel 携带 flowId', async (
     calls.push(call);
     return jsonResponse(200, { ok: true });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.githubCancel('flow-1');
   assert.equal(result.ok, true);
   assert.equal(calls[0]?.url, SYNC_API.githubCancel);
@@ -206,7 +207,7 @@ test('S-10 api.snapshotsList()：POST /sync/snapshots-list，解析倒序快照
     calls.push(call);
     return jsonResponse(200, body);
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.snapshotsList({ repoUrl: 'https://github.com/u/r.git' });
   assert.equal(result.ok, true);
   assert.equal(result.snapshots.length, 2);
@@ -230,7 +231,7 @@ test('S-11 api.sync()：POST /sync/sync，请求体携带 snapshotId；响应含
     calls.push(call);
     return jsonResponse(200, body);
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.sync({ repoUrl: 'https://github.com/u/r.git', snapshotId: 'sync-3' });
   assert.equal(result.syncSessionId, 'sess-1');
   assert.equal(result.items.length, 1);
@@ -250,7 +251,7 @@ test('S-12 api.applyItems()：POST /sync/apply-items，携带 adoptions（含 Co
     calls.push(call);
     return jsonResponse(200, body);
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.applyItems({
     syncSessionId: 'sess-1',
     adoptions: [
@@ -273,7 +274,7 @@ test('S-13 api.cancel()：POST /sync/cancel 携带 syncSessionId', async () => {
     calls.push(call);
     return jsonResponse(200, { ok: true });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.cancel('sess-1');
   assert.equal(result.ok, true);
   assert.equal(calls[0]?.url, SYNC_API.cancel);
@@ -297,7 +298,7 @@ test('S-14 api.autosyncStatus()：GET /sync/autosync 返回 { git, webdav }，
     return jsonResponse(200, body);
   });
   const lastCall = (): FetchCall | null => called;
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.autosyncStatus('git');
   assert.equal(result.enabled, true);
   assert.equal(result.interval, '30m');
@@ -319,7 +320,7 @@ test('S-15 api.autosyncUpdate()：POST /sync/autosync，请求体携带 transpor
     calls.push(call);
     return jsonResponse(200, body);
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.autosyncUpdate({ transport: 'webdav', enabled: true, interval: '60m' });
   assert.equal(result.enabled, true);
   assert.equal(result.interval, '60m');
@@ -345,7 +346,7 @@ test('S-16 api.history()：GET /sync/history，解析 { entries }（含 autosync
     ],
   };
   installFetchMock(() => jsonResponse(200, body));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.history();
   assert.equal(result.entries.length, 2);
   assert.equal(result.entries[0]?.kind, 'apply');
@@ -374,7 +375,7 @@ test('S-18 api.status()：webdav 通道 → 解析 webdav 配置状态（url/use
     return jsonResponse(200, body);
   });
   const lastCall = (): FetchCall | null => called;
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.webdav?.url, 'https://dav.example.com/dav/config');
   assert.equal(result.webdav?.username, 'alice', 'status 可回传 username 值（非敏感，供表单回填）');
@@ -390,7 +391,7 @@ test('S-19 api.push()：transport=webdav → 请求体携带顶层扁平 url/use
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-w1', sections: [], warnings: [] });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.push({
     transport: 'webdav',
     url: 'https://dav.example.com/dav/config', username: 'alice', password: 'secret-pass',
@@ -413,7 +414,7 @@ test('S-20 api.pull()：transport=webdav 请求体透传扁平 webdav 配置', a
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-w1', changes: [], needsReview: false });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await api.pull({ transport: 'webdav', url: 'https://dav.example.com/dav/config', username: 'alice', password: 'secret-pass' });
   assert.equal(calls[0]?.url, SYNC_API.pull);
   const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
@@ -428,7 +429,7 @@ test('S-21 git 通道缺省：不带 transport → 请求体仍只含 git 字段
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-1', sections: [], warnings: [] });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await api.push({ repoUrl: 'https://github.com/u/r.git', token: 't' });
   const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
   assert.equal(sent['transport'], undefined, '缺省不声明 transport（Host 视为 git）');
@@ -442,7 +443,7 @@ test('S-22 api.push()：高级（自定义导出）模式 → 请求体携带 se
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-sel', sections: ['settings'], warnings: [] });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   // 高级模式：传勾选分区
   await api.push({ repoUrl: 'https://github.com/u/r.git', sections: ['settings', 'skills'] });
   assert.equal(calls.length, 1);
@@ -474,7 +475,7 @@ test('S-23 api.status()：解析 syncSections（可同步分区目录，无 secr
     return jsonResponse(200, body);
   });
   const lastCall = (): FetchCall | null => called;
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.syncSections?.length, 2);
   assert.equal(result.syncSections?.[0]?.id, 'settings');
@@ -493,7 +494,7 @@ test('S-24 api.status()：解析 syncSelection（持久化分区选择，UI 回
     return jsonResponse(200, body);
   });
   const lastCall = (): FetchCall | null => called;
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.syncSelection?.mode, 'advanced');
   assert.deepEqual(result.syncSelection?.sections, ['settings', 'skills']);
@@ -506,7 +507,7 @@ test('S-25 api.saveSelection()：POST /sync/selection 携带 transport + mode +
     calls.push(call);
     return jsonResponse(200, { ok: true, transport: 'webdav', mode: 'advanced', sections: ['settings', 'skills'] });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.saveSelection({ transport: 'webdav', mode: 'advanced', sections: ['settings', 'skills'] });
   assert.equal(result.mode, 'advanced');
   assert.equal(calls.length, 1);
@@ -524,7 +525,7 @@ test('S-26 api.push()：加密快照 → 请求体携带 encrypt/encryptPassword
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-enc', sections: ['settings'], warnings: [] });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await api.push({
     repoUrl: 'https://github.com/u/r.git',
     encrypt: true,
@@ -544,7 +545,7 @@ test('S-27 api.pull()：拉取加密快照 → 请求体携带 decryptPassword
     calls.push(call);
     return jsonResponse(200, { ok: true, snapshotId: 'sync-enc', changes: [], needsReview: false });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   await api.pull({ repoUrl: 'https://github.com/u/r.git', decryptPassword: 'pw-12345678' });
   assert.equal(calls[0]?.url, SYNC_API.pull);
   const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>;
@@ -557,7 +558,7 @@ test('S-28 api.status()：syncSelection 含 encrypt/includeSecrets 开关（UI
     syncSelection: { mode: 'advanced', sections: ['settings'], encrypt: true, includeSecrets: true },
   };
   installFetchMock(() => jsonResponse(200, body));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.syncSelection?.encrypt, true);
   assert.equal(result.syncSelection?.includeSecrets, true);
@@ -576,7 +577,7 @@ test('S-28b api.status()：syncSelectionByChannel / autosyncByChannel 按通道
     },
   };
   installFetchMock(() => jsonResponse(200, body));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.syncSelectionByChannel?.git.mode, 'default', 'git 通道选择独立');
   assert.equal(result.syncSelectionByChannel?.webdav.mode, 'advanced');
@@ -592,7 +593,7 @@ test('S-29 api.saveUiPrefs()：POST /sync/ui-prefs 携带 lastSyncChannel（磁
     calls.push(call);
     return jsonResponse(200, { ok: true, lastSyncChannel: 'webdav' });
   });
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.saveUiPrefs({ lastSyncChannel: 'webdav' });
   assert.equal(result.lastSyncChannel, 'webdav');
   assert.equal(calls.length, 1);
@@ -608,7 +609,7 @@ test('S-30 api.status()：lastSyncChannel 回填（磁盘 ui-prefs；UI 通道
     lastSyncChannel: 'webdav',
   };
   installFetchMock(() => jsonResponse(200, body));
-  const api = new SyncApi();
+  const api = new SyncApi(zhUiT);
   const result = await api.status();
   assert.equal(result.lastSyncChannel, 'webdav');
 });
@@ -619,7 +620,7 @@ test('S-31 api.githubListRepositories()：GET 列举仓库（不设 method，只
     calls.push(call)
     return jsonResponse(200, { ok: true, repos: [REPO_SUMMARY] })
   })
-  const api = new SyncApi()
+  const api = new SyncApi(zhUiT)
   const result = await api.githubListRepositories()
   assert.equal(calls.length, 1)
   assert.equal(calls[0]?.url, SYNC_API.githubRepositories)
@@ -634,7 +635,7 @@ test('S-32 api.githubCreateRepository()：POST 新建仓库，请求体不含 pr
     calls.push(call)
     return jsonResponse(200, { ok: true, repo: REPO_SUMMARY })
   })
-  const api = new SyncApi()
+  const api = new SyncApi(zhUiT)
   const result = await api.githubCreateRepository('  dsh-configs  ', ' 我的配置 ')
   assert.equal(calls[0]?.url, SYNC_API.githubRepositories)
   assert.equal(calls[0]?.init?.method, 'POST')
@@ -651,8 +652,31 @@ test('S-33 api.githubCreateRepository()：描述为空时不发送 description
     calls.push(call)
     return jsonResponse(200, { ok: true, repo: REPO_SUMMARY })
   })
-  const api = new SyncApi()
+  const api = new SyncApi(zhUiT)
   await api.githubCreateRepository('dsh-configs', '   ')
   const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>
   assert.ok(!('description' in sent), '空描述不占字段（与 GitHub 默认描述口径一致）')
 });
+
+test('S-34 api.rollback()：POST /sync/rollback 透传 full=false 与 failed（未回滚项 + 人工提示）', async () => {
+  const body = {
+    ok: true,
+    full: false,
+    failed: [{ item: 'credentialsStatus:DEEPSEEK_API_KEY', reason: 'DSH 不回读凭据值，无法自动恢复', manualHint: '请重新补录该凭据' }],
+  }
+  const calls: FetchCall[] = []
+  installFetchMock((call) => {
+    calls.push(call)
+    return jsonResponse(200, body)
+  })
+  const api = new SyncApi(zhUiT)
+  const result = await api.rollback({ restoreId: 'rest-9' })
+  assert.equal(result.full, false)
+  assert.equal(result.failed?.length, 1, '未回滚项必须透传（旧实现只回 ok/full，界面据此误报「已回滚」）')
+  assert.equal(result.failed?.[0]?.item, 'credentialsStatus:DEEPSEEK_API_KEY')
+  assert.equal(result.failed?.[0]?.manualHint, '请重新补录该凭据')
+  assert.equal(calls[0]?.url, SYNC_API.rollback)
+  assert.equal(calls[0]?.init?.method, 'POST')
+  const sent = JSON.parse(String(calls[0]?.init?.body ?? '{}')) as Record<string, unknown>
+  assert.equal(sent['restoreId'], 'rest-9')
+});

package/src/client/sync/sync-api.ts

@@ -37,7 +37,7 @@ import type { ConsultReport } from '../../core/migration-consult.ts';
 import { getJson, LONG_REQUEST_TIMEOUT_MS, postJson, type RequestOptions } from '../common/http.ts';
 import { CONFIG_MANAGER_API, SYNC_API } from '../common/routes.ts';
 import type { ExportPreviewResponse } from '../api.ts';
-import { zhUiT, type UiT } from '../../ui/i18n.ts';
+import type { UiT } from '../../ui/i18n.ts';
 import { repoCreateBody } from '../../ui/sync-repository-picker.ts';
 
 /** 同步端点常量：**唯一来源** = `common/routes.ts`（W4 单点化），此处重导出保持既有导入面。 */
@@ -97,6 +97,30 @@ export interface SyncStatusResponse {
   autosync?: AutosyncStatusResponse;
   /** 全部通道的自动同步状态（git/webdav 各自独立；UI 按当前 tab 取对应通道） */
   autosyncByChannel?: Record<SyncTransportType, AutosyncStatusResponse>;
+  /**
+   * issue #79：git 工作副本与配置地址的关系（host 只读自检）。
+   *  - `{ facts }` = 自检成功（origin 是否已跟随 repoUrl）
+   *  - `{ error }` = 自检读不出来（git 不可用 / 工作副本异常）——**如实回传**，不伪装成「不存在」
+   */
+  workDir?: { facts: SyncWorkDirFacts } | { error: string };
+}
+
+/** git 工作副本自检事实（与宿主 GitWorkDirFacts 同形；无任何敏感值）。 */
+export interface SyncWorkDirFacts {
+  /** 工作副本路径 */
+  path: string;
+  /** `.git` 是否存在 */
+  exists: boolean;
+  /** 当前 origin（读不出 → null） */
+  origin: string | null;
+  /** 单独配置的 push URL（未单独配置 → null） */
+  pushUrl: string | null;
+  /** fetch / push 地址是否都已跟随 repoUrl */
+  match: boolean;
+  /** 未上行的本地提交数（仅 detail 自检时给出，否则 null） */
+  ahead: number | null;
+  /** 工作树是否有未提交改动（仅 detail 自检时给出，否则 null） */
+  dirty: boolean | null;
 }
 
 /** 同步密码的保存状态（只回布尔；密码值永不回传浏览器）。 */
@@ -384,9 +408,39 @@ export interface ApplyItemsResponse {
    * 旧宿主不返回 → undefined（按「无未生效项」处理，不误报）。
    */
   ineffective?: { itemId: string; adapter: string; message?: string }[];
+  /**
+   * 「整体回滚是否完整」（诚实性，2026-10）。`rolledBack=true` 只说「触发了整体回滚」，
+   * 不代表每一项都补偿成功（典型：原本已存在的凭据值 DSH 不可回读 → 无法自动恢复）。
+   * 此时引擎把失败项并入 `warnings`，并置 `rollbackFull=false`；界面据此**不得**
+   * 显示成「已整体回滚」，必须列出未恢复项。
+   * 旧宿主不返回 → undefined（按旧的「已整体回滚」文案处理，不误报）。
+   */
+  rollbackFull?: boolean;
   result: unknown;
 }
 
+/** POST /sync/rollback 响应：一键回滚的诚实结果（full=false 时 failed 列出未回滚项）。 */
+export interface SyncRollbackResponse {
+  ok: boolean;
+  /** 是否**每一项**都补偿成功（false = 部分回滚，配置可能停留在中间状态） */
+  full: boolean;
+  /**
+   * 未回滚项（full=false 时非空）。`reason` = 为什么没能恢复；`manualHint` = 人工怎么补
+   * （如「请重新补录该凭据」）。旧宿主不返回 → undefined（按「无未回滚项」处理）。
+   */
+  failed?: SyncRollbackFailedItem[];
+  /** 同步历史写入失败（回滚本身已完成；仅提示） */
+  historyWriteError?: string;
+}
+
+/** 单条未回滚项。 */
+export interface SyncRollbackFailedItem {
+  /** 形如 `<adapter>:<ref>` */
+  item: string;
+  reason: string;
+  manualHint?: string;
+}
+
 /* ---------------------------------------------------------------- 自动同步 */
 
 /** 统一间隔类型。 */
@@ -402,6 +456,14 @@ export interface AutosyncStatusResponse {
   lastRunAt?: string;
   lastRunStatus?: AutosyncRunStatus;
   lastRunMessage?: string;
+  /**
+   * issue #79：本轮跳过的**结构化原因码**（界面按码取字典，绝不渲染裸枚举）。
+   * 取值与同步历史的 skipReason 同一套：conflict / mutation-locked / encrypted /
+   * unconfigured / upToDate / unchanged。
+   */
+  lastRunSkipReason?: string;
+  /** 跳过涉及的分区数（当前仅 conflict：远端另有 N 个分区待确认） */
+  lastRunSkipCount?: number;
   consecutiveFailures: number;
   /** 距上次自动同步已过 ms（host 计算，供 UI 倒计时/立即触发判断） */
   elapsedMs: number;
@@ -539,15 +601,27 @@ const SYNC_OPTS: RequestOptions = { timeoutMs: LONG_REQUEST_TIMEOUT_MS, timeoutK
 /** 远程同步浏览器半数据入口（备份与迁移页第 4 个 tab 的注入业务面） */
 export class SyncApi {
   readonly t: UiT
-  constructor(t: UiT = zhUiT) {
+  constructor(t: UiT) {
     this.t = t
   }
 
-  /** 读取同步状态（配置 / 凭据 / 上次同步时间 / 分区数） */
+  /** 读取同步状态（配置 / 凭据 / 上次同步时间 / 分区数 / 工作副本自检） */
   async status(): Promise<SyncStatusResponse> {
     return getJson<SyncStatusResponse>(SYNC_API.status, this.t, SYNC_OPTS);
   }
 
+  /**
+   * 重建 git 工作副本（issue #79 的自救入口）。
+   *
+   * - `relink`：只把 origin / push URL 重指向当前配置地址（非破坏性，不碰工作树与本地提交）；
+   * - `reclone`：删除工作副本后重新 clone（**丢弃未上行的本地提交**）→ 必须带 `confirm: true`。
+   *
+   * 写动作：host 侧过 mutation gate（SAFE MODE / 环境锁）。
+   */
+  async workdirReset(payload: { mode: 'relink' | 'reclone'; confirm?: boolean }): Promise<{ ok: boolean; mode: string; workDir: { facts: SyncWorkDirFacts } }> {
+    return postJson<{ ok: boolean; mode: string; workDir: { facts: SyncWorkDirFacts } }>(SYNC_API.workdirReset, payload, this.t, SYNC_OPTS);
+  }
+
   /**
    * 分区条目清单（复用 /export-preview；**只读**，不写任何内容）。
    *
@@ -698,9 +772,9 @@ export class SyncApi {
     return postJson<{ ok: boolean; lastSyncChannel?: SyncTransportType }>(SYNC_API.uiPrefs, payload, this.t, SYNC_OPTS);
   }
 
-  /** 一键回滚：按 restoreId 调用 backup→rollback */
-  async rollback(payload: { restoreId: string }): Promise<{ ok: boolean; full: boolean }> {
-    return postJson<{ ok: boolean; full: boolean }>(SYNC_API.rollback, payload, this.t, SYNC_OPTS);
+  /** 一键回滚：按 restoreId 调用 backup→rollback（full=false 时 failed 列出未回滚项与人工提示） */
+  async rollback(payload: { restoreId: string }): Promise<SyncRollbackResponse> {
+    return postJson<SyncRollbackResponse>(SYNC_API.rollback, payload, this.t, SYNC_OPTS);
   }
 
   /** Phase 7 迁移前咨询（只读健康评分 + 建议）：对远端快照生成咨询报告。 */