dsh-api-runner 0.1.0 → 0.2.1

package/src/restart.js

@@ -437,14 +437,8 @@ export function spawnService({ javaExe, argv, cwd, logPath }) {
     } catch {
         out = 'ignore';
     }
-    try {
-        const child = spawn(exe, argv, {
-            cwd: cwd || undefined,
-            detached: true,
-            stdio: ['ignore', out, out],
-            windowsHide: true,
-        });
-        child.unref();
+
+    const closeOut = () => {
         if (typeof out === 'number') {
             try {
                 fs.closeSync(out);
@@ -452,10 +446,47 @@ export function spawnService({ javaExe, argv, cwd, logPath }) {
                 /* 已交给子进程 */
             }
         }
-        return { ok: true, pid: child.pid, logPath: logPath || '' };
-    } catch (error) {
-        return { ok: false, message: `拉起进程失败：${error?.message || error}`, logPath: logPath || '' };
-    }
+    };
+
+    /**
+     * 返回 Promise：等到 'spawn' 或 'error' 再决定成败。
+     *
+     * 为什么不能直接返回 `{ok:true}`：可执行文件不存在时 spawn **不抛异常**，
+     * 而是异步发 'error'；没有监听器时 Node 把它当未捕获异常，会把 DSH 整个进程崩掉。
+     * 一键启动要连续拉起多个服务，其中一个 javaExe 配错（换机器、JDK 路径变了）
+     * 就足以让宿主挂掉，所以这里必须挂监听器，并且如实报告失败原因。
+     */
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(exe, argv, {
+                cwd: cwd || undefined,
+                detached: true,
+                stdio: ['ignore', out, out],
+                windowsHide: true,
+            });
+        } catch (error) {
+            closeOut();
+            resolve({ ok: false, message: `拉起进程失败：${error?.message || error}`, logPath: logPath || '' });
+            return;
+        }
+
+        let settled = false;
+        const settle = (value) => {
+            if (settled) return;
+            settled = true;
+            closeOut();
+            resolve(value);
+        };
+
+        child.once('error', (error) => {
+            settle({ ok: false, message: `拉起进程失败：${error?.message || error}`, logPath: logPath || '' });
+        });
+        child.once('spawn', () => {
+            child.unref();
+            settle({ ok: true, pid: child.pid, logPath: logPath || '' });
+        });
+    });
 }
 
 /** 等端口开始 LISTENING（用 TCP 连接探测，不依赖 netstat） */

package/test/client.mjs

@@ -1,109 +1,162 @@
-/**
- * client/client.js 的形态测试。
- *
- * 客户端 bundle 是「经典脚本」：加载时立刻调用 window.__ModuleLoader__.load(...)，
- * 由 DSH 前端注入的 loader 提供 require。这里用最小桩模拟这套环境，
- * 校验：① 注册的 id 与包名一致；② 导出 inject/apply；③ apply 会注册一个侧边栏 tab；
- * ④ 面板组件能在没有 scope 的情况下渲染不崩。
- */
-import assert from 'node:assert';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const source = fs.readFileSync(path.join(root, 'client', 'client.js'), 'utf8');
-
-let recorded;
-/** 极简 React 桩：只够执行 createElement 与 hooks */
-const React = {
-    createElement: (type, props, ...children) => ({ type, props: { ...(props || {}), children: children.length > 1 ? children : children[0] } }),
-    Fragment: 'Fragment',
-    useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
-    useEffect: () => {},
-    useMemo: (factory) => factory(),
-    useCallback: (fn) => fn,
-    useRef: (initial) => ({ current: initial }),
-};
-const requireStub = (name) => {
-    if (name === 'react') return React;
-    throw new Error(`客户端 bundle 请求了未桩的模块：${name}`);
-};
-
-const windowStub = {
-    __ModuleLoader__: {
-        load: (entry) => {
-            recorded = entry;
-            recorded.exports = entry.factory(requireStub);
-        },
-    },
-    confirm: () => true,
-    document: {
-        getElementById: () => null,
-        createElement: () => ({ set textContent(v) {}, id: '' }),
-        head: { appendChild: () => {} },
-    },
-};
-// bundle 里会读 document / window，通过函数参数作用域注入
-const run = new Function('window', 'document', 'setInterval', 'clearInterval', 'fetch', source);
-run(windowStub, windowStub.document, () => 0, () => {}, () => { throw new Error('测试里不应真的发请求'); });
-
-assert.ok(recorded, '应当调用 window.__ModuleLoader__.load');
-assert.equal(recorded.id, 'dsh-api-runner', 'bundle id 必须与包名一致');
-assert.deepEqual(recorded.exports.inject, ['betterSidebar']);
-assert.equal(typeof recorded.exports.apply, 'function');
-
-// apply：用一个只提供 betterSidebar 的 ctx，断言注册了一个 tab
-const tabs = [];
-const effects = [];
-const ctx = {
-    betterSidebar: {
-        registerTab: (descriptor) => {
-            tabs.push(descriptor);
-            return () => {};
-        },
-    },
-    // 没有 slots 时也要能正常注册 tab（设置页是可选的）
-    get: () => undefined,
-    effect: (callback, label) => {
-        effects.push(label);
-        return callback();
-    },
-};
-recorded.exports.apply(ctx);
-assert.equal(tabs.length, 1, 'apply 应注册一个侧边栏 tab');
-assert.equal(tabs[0].id, 'dsh-api-runner');
-assert.equal(tabs[0].single, true);
-assert.equal(typeof tabs[0].title, 'function');
-assert.equal(tabs[0].title(), '接口调试');
-
-// 有 slots 时，还要在设置里挂一个插件主页（settings.section）
-const sections = [];
-const injectedSlots = [];
-const ctxWithSlots = {
-    betterSidebar: { registerTab: () => () => {} },
-    get: (name) => (name === 'slots' ? {
-        inject: (slot, callback) => { injectedSlots.push(slot); callback(); return () => {}; },
-        register: (descriptor, render) => { sections.push({ descriptor, render }); return () => {}; },
-    } : undefined),
-    effect: (callback) => callback(),
-};
-recorded.exports.apply(ctxWithSlots);
-assert.deepEqual(injectedSlots, ['settings.section'], '设置页应通过 slots.inject 等待 slot 就绪');
-assert.equal(sections.length, 1, '应注册一个设置页');
-assert.equal(sections[0].descriptor.name, 'settings.section');
-assert.equal(sections[0].descriptor.id, 'dsh-api-runner');
-assert.equal(sections[0].descriptor.label(), '接口调试');
-const page = sections[0].render();
-assert.ok(page, '设置页应返回元素');
-assert.equal(typeof page.type, 'function');
-
-// 面板组件：没有 scope 也不能崩
-const panel = tabs[0].component({ visible: false, scope: {} });
-assert.ok(panel, '面板组件应返回元素');
-assert.equal(typeof panel.type, 'function');
-
-// 没有 betterSidebar 时 apply 要安全退出，不能抛
-recorded.exports.apply({ effect: () => {} });
-
-console.log('PASSED: client bundle shape');
+/**
+ * client/client.js 的形态测试。
+ *
+ * 客户端 bundle 是「经典脚本」：加载时立刻调用 window.__ModuleLoader__.load(...)，
+ * 由 DSH 前端注入的 loader 提供 require。这里用最小桩模拟这套环境，校验：
+ *   ① 注册的 id 与包名一致；
+ *   ② 导出 inject/apply，且 inject 里**没有**第三方侧边栏（本插件是独立的）；
+ *   ③ apply 只往宿主自带的 slot 席位注册（panellist / main / 右栏页签 / 设置页）；
+ *   ④ 面板组件在缺少 scope 时也能渲染不崩；
+ *   ⑤ 宿主没提供 slots 时安静退出，不抛异常。
+ */
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const source = fs.readFileSync(path.join(root, 'client', 'client.js'), 'utf8');
+
+let recorded;
+/** 极简 React 桩：只够执行 createElement 与 hooks */
+const React = {
+    createElement: (type, props, ...children) => ({ type, props: { ...(props || {}), children: children.length > 1 ? children : children[0] } }),
+    Fragment: 'Fragment',
+    useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
+    useEffect: () => {},
+    useMemo: (factory) => factory(),
+    useCallback: (fn) => fn,
+    useRef: (initial) => ({ current: initial }),
+};
+const requireStub = (name) => {
+    if (name === 'react') return React;
+    throw new Error(`客户端 bundle 请求了未桩的模块：${name}`);
+};
+
+const windowStub = {
+    __ModuleLoader__: {
+        load: (entry) => {
+            recorded = entry;
+            recorded.exports = entry.factory(requireStub);
+        },
+    },
+    confirm: () => true,
+    document: {
+        getElementById: () => null,
+        createElement: () => ({ set textContent(v) {}, id: '' }),
+        head: { appendChild: () => {} },
+    },
+};
+// bundle 里会读 document / window，通过函数参数作用域注入
+const run = new Function('window', 'document', 'setInterval', 'clearInterval', 'fetch', source);
+run(windowStub, windowStub.document, () => 0, () => {}, () => { throw new Error('测试里不应真的发请求'); });
+
+assert.ok(recorded, '应当调用 window.__ModuleLoader__.load');
+assert.equal(recorded.id, 'dsh-api-runner', 'bundle id 必须与包名一致');
+assert.deepEqual(recorded.exports.inject, ['slots'], 'client half 只硬依赖 slots，不依赖任何第三方侧边栏');
+assert.equal(typeof recorded.exports.apply, 'function');
+
+/**
+ * 造一个记录注册的 slots 服务桩。
+ * @param {{withInject?: boolean}} options - 是否提供 inject（宿主一定有，缺省时走直注册分支）
+ */
+function makeSlots(options = {}) {
+    const registrations = [];
+    const injected = [];
+    const slots = {
+        register: (descriptor, render) => {
+            registrations.push({ descriptor, render });
+            return () => {};
+        },
+    };
+    if (options.withInject !== false) {
+        slots.inject = (slot, callback) => {
+            injected.push(slot);
+            callback();
+            return () => {};
+        };
+    }
+    return { slots, registrations, injected };
+}
+
+// apply：只提供 slots 的 ctx，断言注册落在宿主自带的席位上
+const first = makeSlots();
+const tabTypes = [];
+const effects = [];
+const ctx = {
+    get: (name) => {
+        if (name === 'slots') return first.slots;
+        if (name === 'sidebarRightTabs') {
+            return {
+                register: (definition) => {
+                    tabTypes.push(definition);
+                    return () => {};
+                },
+            };
+        }
+        return undefined;
+    },
+    effect: (callback, label) => {
+        effects.push(label);
+        return callback();
+    },
+};
+recorded.exports.apply(ctx);
+
+assert.deepEqual(
+    first.injected,
+    ['sidebar.panellist', 'main', 'sidebar.right.pane.tab', 'sidebar.right.pane.tab.title', 'settings.section'],
+    '每个席位都要通过 slots.inject 等待声明就绪',
+);
+
+const byName = (name) => first.registrations.filter((item) => item.descriptor.name === name);
+const panellist = byName('sidebar.panellist');
+assert.equal(panellist.length, 1, '应注册一个左栏图标');
+assert.equal(panellist[0].descriptor.id, 'dsh-api-runner');
+assert.equal(panellist[0].descriptor.label(), '接口调试');
+
+const main = byName('main');
+assert.equal(main.length, 1, '应注册一个中栏整页');
+assert.equal(main[0].descriptor.key, 'dsh-api-runner', 'main 的 key 必须与 panellist 的 id 一致，点图标才切得过去');
+
+assert.equal(byName('sidebar.right.pane.tab').length, 1, '应注册一个右侧栏页签正文');
+assert.equal(byName('sidebar.right.pane.tab')[0].descriptor.key, 'dsh-api-runner');
+assert.equal(byName('sidebar.right.pane.tab.title').length, 1, '应注册一个右侧栏页签标题');
+
+const sections = byName('settings.section');
+assert.equal(sections.length, 1, '应注册一个设置页');
+assert.equal(sections[0].descriptor.id, 'dsh-api-runner');
+assert.equal(sections[0].descriptor.label(), '接口调试');
+
+assert.equal(tabTypes.length, 1, '应向 sidebarRightTabs 注册一个页签类型');
+assert.equal(tabTypes[0].id, 'dsh-api-runner');
+assert.equal(tabTypes[0].kind, 'dsh-api-runner');
+assert.equal(tabTypes[0].title(), '接口调试');
+
+// 设置页能渲染
+const page = sections[0].render();
+assert.ok(page, '设置页应返回元素');
+assert.equal(typeof page.type, 'function');
+
+// 面板组件：没有 scope 也不能崩（全局页没有会话时就是这条路径）
+const panel = main[0].render({});
+assert.ok(panel, '面板组件应返回元素');
+assert.equal(typeof panel.type, 'function');
+
+// 右侧栏页签：没有 useTabInfo 时按可见渲染，也不崩
+const rightPanel = byName('sidebar.right.pane.tab')[0].render({ sessionId: 'session-1' });
+assert.ok(rightPanel, '右侧栏页签正文应返回元素');
+assert.equal(typeof rightPanel.type, 'function');
+
+// 宿主没提供 slots 时 apply 要安全退出，不能抛
+recorded.exports.apply({ effect: () => {} });
+
+// slots 没有 inject 时退回直接注册（旧版宿主）
+const second = makeSlots({ withInject: false });
+recorded.exports.apply({
+    get: (name) => (name === 'slots' ? second.slots : undefined),
+    effect: (callback) => callback(),
+});
+assert.equal(second.registrations.length, 5, '没有 inject 时也要把五个席位都注册上');
+
+console.log('PASSED: client bundle shape');

package/test/plugin.mjs

@@ -396,12 +396,46 @@ await ok('java/save、java/unsave、java/start-saved 都能给出可读结果',
     assert.equal(unsavePayload.ok, true, unsave.body);
     assert.ok(Array.isArray(unsavePayload.saved));
 });
+await ok('java/start-all 与状态轮询路由都已挂载', async () => {
+    const route = registered.routes[0];
+    const post = (path, payload) => ({
+        url: `${path}?cwd=${encodeURIComponent(projectDir)}`,
+        method: 'POST',
+        headers: {},
+        async *[Symbol.asyncIterator]() {
+            yield Buffer.from(JSON.stringify(payload), 'utf8');
+        },
+    });
+    const get = (path) => ({
+        url: `${path}?cwd=${encodeURIComponent(projectDir)}`,
+        method: 'GET',
+        headers: {},
+        async *[Symbol.asyncIterator]() {},
+    });
+
+    // 一个配方都没保存：一键启动要说清楚，不能 404 也不能抛
+    const empty = createMockResponse();
+    await route.handler(post('/dsh-api-runner/api/java/start-all', {}), empty);
+    const emptyPayload = JSON.parse(empty.body);
+    assert.equal(emptyPayload.ok, false, empty.body);
+    assert.equal(emptyPayload.code, 'NOTHING_SAVED');
+
+    // 状态路由：查不存在的批次给 NO_BATCH（证明路由存在且不崩）
+    const status = createMockResponse();
+    await route.handler(get('/dsh-api-runner/api/java/start-all/status?batch=nope'), status);
+    const statusPayload = JSON.parse(status.body);
+    assert.equal(statusPayload.ok, false, status.body);
+    assert.equal(statusPayload.code, 'NO_BATCH');
+});
+
 await ok('工具 action 里有 login 与 java', () => {
     const tool = registered.tools[0];
     const actions = tool.parameters.properties.action.enum;
     assert.ok(actions.includes('login'));
     assert.ok(actions.includes('java'));
     assert.ok(tool.parameters.properties.token_from, '应有 token_from 参数');
+    assert.ok(tool.parameters.properties.java_action.enum.includes('start_all'), 'java_action 应有 start_all');
+    assert.ok(tool.parameters.properties.java_ids, '应有 java_ids 参数');
 });
 
 // ---- 清理 ----

package/test/smoke.mjs

@@ -289,6 +289,120 @@ await ok('面板接口的 tokenPath 会自动写回配置，第二次登录不
     service.deleteApiUi(projectDir, 'ui-login');
 });
 
+console.log('面板回显与数据保留:');
+await ok('示例参数保存后能回显（不再永远空）', async () => {
+    service.saveApiUi(projectDir, {
+        id: 'ui-sample',
+        name: '回显示例参数',
+        method: 'GET',
+        url: `${base}/echo`,
+        sampleParams: { matterCd: 'SX-202609-0012', page: 1 },
+    });
+    const state = await service.uiState(projectDir);
+    const api = state.apis.find((item) => item.id === 'ui-sample');
+    assert.ok(api, '接口应出现在 uiState 里');
+    assert.notEqual(api.sampleText, '', 'sampleText 不能为空，否则编辑框回显不出来');
+    const parsed = JSON.parse(api.sampleText);
+    assert.equal(parsed.matterCd, 'SX-202609-0012');
+    assert.equal(parsed.page, 1);
+    service.deleteApiUi(projectDir, 'ui-sample');
+});
+
+await ok('YAML 里的 query 不会被面板保存抹掉', async () => {
+    // 先写进面板（模拟 YAML 已有该接口），再在面板里只改说明后保存
+    service.saveApiUi(projectDir, {
+        id: 'ui-query',
+        name: '带 query 的接口',
+        method: 'GET',
+        url: `${base}/system/library/matter/billList`,
+        query: { matterCd: '{matterCd}' },
+    });
+    const before = await service.uiState(projectDir);
+    const b = before.apis.find((item) => item.id === 'ui-query');
+    assert.ok(b.queryText && b.queryText.includes('matterCd'), 'uiState 应返回 queryText 供面板回显');
+
+    // 面板只改说明，不带 query 字段（真实表单就是这样提交的）
+    service.saveApiUi(projectDir, {
+        id: 'ui-query',
+        name: '带 query 的接口',
+        method: 'GET',
+        url: `${base}/system/library/matter/billList`,
+        description: '只改了说明',
+    });
+    const stored = service.projectStore.project(projectDir).apis.find((item) => item.id === 'ui-query');
+    assert.ok(stored.query && stored.query.matterCd === '{matterCd}', 'query 必须被保留，不能被整体覆盖丢掉');
+    assert.equal(stored.description, '只改了说明');
+
+    // 运行期确实用上了 query
+    const config = service.config(projectDir);
+    const runtime = config.config.apis.find((item) => item.id === 'ui-query');
+    assert.equal(runtime.query.matterCd, '{matterCd}');
+    service.deleteApiUi(projectDir, 'ui-query');
+});
+
+await ok('显式传 query 时以新值为准（不是只增不减）', async () => {
+    service.saveApiUi(projectDir, {
+        id: 'ui-query2',
+        name: 'q2',
+        method: 'GET',
+        url: `${base}/echo`,
+        query: { a: '1', b: '2' },
+    });
+    service.saveApiUi(projectDir, {
+        id: 'ui-query2',
+        name: 'q2',
+        method: 'GET',
+        url: `${base}/echo`,
+        query: { a: '9' },
+    });
+    const stored = service.projectStore.project(projectDir).apis.find((item) => item.id === 'ui-query2');
+    assert.deepEqual(stored.query, { a: '9' }, '显式提交的 query 应整体替换，不被旧值污染');
+    service.deleteApiUi(projectDir, 'ui-query2');
+});
+
+await ok('面板传空 query 能真正清空（不被旧值粘回来）', async () => {
+    service.saveApiUi(projectDir, {
+        id: 'ui-query3',
+        name: 'q3',
+        method: 'GET',
+        url: `${base}/echo`,
+        query: { a: '1' },
+    });
+    // 面板把输入框清空后提交的是 {}，必须覆盖成空
+    service.saveApiUi(projectDir, {
+        id: 'ui-query3',
+        name: 'q3',
+        method: 'GET',
+        url: `${base}/echo`,
+        query: {},
+    });
+    const stored = service.projectStore.project(projectDir).apis.find((item) => item.id === 'ui-query3');
+    assert.deepEqual(stored.query, {}, '清空 query 必须生效，否则用户没法去掉参数');
+    service.deleteApiUi(projectDir, 'ui-query3');
+});
+
+await ok('只改说明时示例参数也要保留（不能变成空）', async () => {
+    service.saveApiUi(projectDir, {
+        id: 'ui-sample2',
+        name: 's2',
+        method: 'GET',
+        url: `${base}/echo`,
+        sampleParams: { matterCd: 'SX-1' },
+    });
+    service.saveApiUi(projectDir, {
+        id: 'ui-sample2',
+        name: 's2',
+        method: 'GET',
+        url: `${base}/echo`,
+        description: '只改说明',
+    });
+    const state = await service.uiState(projectDir);
+    const api = state.apis.find((item) => item.id === 'ui-sample2');
+    assert.notEqual(api.sampleText, '', '只改说明不应把示例参数弄丢');
+    assert.equal(JSON.parse(api.sampleText).matterCd, 'SX-1');
+    service.deleteApiUi(projectDir, 'ui-sample2');
+});
+
 console.log('面板按项目分类:');
 const otherProjectDir = path.join(tmp, 'another-project');
 fs.mkdirSync(otherProjectDir, { recursive: true });
@@ -436,6 +550,91 @@ await ok('describe 展示完整地址（含路径）并列出占位符', () => {
     assert.deepEqual(echo.params.sort(), ['fixed', 'id']);
 });
 
+console.log('java 一键启动:');
+await ok('没有保存的服务时给出明确提示', async () => {
+    const result = await service.startAllSavedJava(projectDir, []);
+    assert.equal(result.ok, false);
+    assert.equal(result.code, 'NOTHING_SAVED');
+});
+
+await ok('一键启动逐个记账：成功/跳过/失败都进 items，不中断', async () => {
+    // 造两个配方：一个能起来（假的 java 命令必然失败），一个 id 不存在。
+    // 这里不真的拉 Java 进程，只验证编排逻辑：失败被记进 items，循环继续。
+    const store = service.projectStore;
+    store.saveJava(projectDir, {
+        id: 'demo-a',
+        name: 'demo-a',
+        mainClass: 'com.example.DemoAApplication',
+        classPath: '/tmp/none/target/classes',
+        javaExe: 'definitely-not-a-real-java-binary',
+        cwd: projectDir,
+    });
+    store.saveJava(projectDir, {
+        id: 'demo-b',
+        name: 'demo-b',
+        mainClass: 'com.example.DemoBApplication',
+        classPath: '/tmp/none/target/classes',
+        javaExe: 'definitely-not-a-real-java-binary',
+        cwd: projectDir,
+    });
+
+    const result = await service.startAllSavedJava(projectDir, ['demo-a', 'ghost']);
+    assert.equal(result.ok, false, '有失败项时整体 ok 为 false');
+    assert.equal(result.code, 'PARTIAL');
+    assert.equal(result.total, 2);
+    // ghost 不存在 → NOT_SAVED；demo-a 拉不起来 → 各自有失败原因
+    const ghost = result.items.find((item) => item.id === 'ghost');
+    assert.equal(ghost.code, 'NOT_SAVED');
+    const a = result.items.find((item) => item.id === 'demo-a');
+    assert.equal(a.ok, false, '假 java 路径不可能启动成功');
+    assert.ok(a.code || a.message, '失败项必须带原因');
+    // 关键：第一个失败没有阻止第二个被处理
+    assert.equal(result.items.length, 2, '失败不应中断整批');
+    assert.match(result.message, /成功 \d+ 个，跳过 \d+ 个，失败 \d+ 个/);
+});
+
+await ok('一键启动跳过已在运行的服务', async () => {
+    // 直接往托管记录里塞一条 alive 的假记录（用当前进程的 pid，保证 isAlive 为 true）
+    service.javaRunner._put(projectDir, {
+        id: 'demo-b',
+        pid: process.pid,
+        mainClass: 'com.example.DemoBApplication',
+        logPath: path.join(homeDir, 'java-logs', 'demo-b.log'),
+        startedAt: new Date().toISOString(),
+    });
+    const result = await service.startAllSavedJava(projectDir, ['demo-b']);
+    const b = result.items.find((item) => item.id === 'demo-b');
+    assert.equal(b.skipped, true, JSON.stringify(b));
+    assert.equal(result.skipped, 1);
+    assert.equal(result.failed, 0);
+});
+
+await ok('后台批次立刻返回 id，轮询能看到进度与结束状态', async () => {
+    const started = service.startSavedJavaBatch(projectDir, ['ghost']);
+    assert.equal(started.ok, true);
+    assert.ok(started.batchId, '必须立刻返回批次 id');
+    assert.equal(started.total, 1);
+
+    // 轮询到结束（失败也算结束）
+    let status;
+    for (let i = 0; i < 50; i += 1) {
+        status = service.startBatchStatus(started.batchId);
+        if (status.finished) break;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+    assert.equal(status.ok, true);
+    assert.equal(status.finished, true, JSON.stringify(status));
+    assert.equal(status.total, 1);
+    assert.ok(status.result, '结束后必须带上 result');
+    assert.equal(status.items.length, 1, '每个服务都要有一条进度记录');
+});
+
+await ok('查不存在的批次给出 NO_BATCH', () => {
+    const status = service.startBatchStatus('batch-does-not-exist');
+    assert.equal(status.ok, false);
+    assert.equal(status.code, 'NO_BATCH');
+});
+
 service.dispose();
 server.close();
 fs.rmSync(tmp, { recursive: true, force: true });