@lark-apaas/miaoda-cli 0.1.2-alpha.8bc93eb → 0.1.2-alpha.8f744c0

package/dist/api/db/api.js

@@ -7,6 +7,7 @@ exports.exportData = exportData;
 exports.listDDLChangelog = listDDLChangelog;
 exports.getAuditStatus = getAuditStatus;
 exports.setAuditConfig = setAuditConfig;
+exports.listAuditLog = listAuditLog;
 exports.migrationInit = migrationInit;
 exports.migrate = migrate;
 exports.recover = recover;
@@ -32,6 +33,22 @@ async function mapDbHttpError(err, url, ctx,
 onErrorBody) {
     if (err instanceof error_1.AppError)
         throw err;
+    // 客户端超时 / abort：SdkHttpError 时 response 通常缺失（status=0），落到 throw 时
+    // message 形如 'Failed to recover: 0' 让用户看不懂。识别 abort / timeout 关键字
+    // 转成专用错误码 + 友好 hint。
+    if (err instanceof Error) {
+        const msg = err.message.toLowerCase();
+        if (msg.includes("aborted") ||
+            msg.includes("timeout") ||
+            err.name === "AbortError" ||
+            err.name === "TimeoutError") {
+            throw new error_1.AppError("REQUEST_TIMEOUT", `${ctx}: request timed out`, {
+                next_actions: [
+                    "Server-side async tasks may take up to 60s. Retry the command if the underlying task likely succeeded.",
+                ],
+            });
+        }
+    }
     if (err instanceof http_client_1.HttpError) {
         const status = err.response?.status ?? 0;
         const statusText = err.response?.statusText ?? "";
@@ -392,6 +409,51 @@ async function setAuditConfig(opts) {
     }
     return data.status;
 }
+// ── db audit log → InnerAdminListAuditLog ──
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/audit/log?tables=&since=&until=&limit=&cursor=&dbBranch=
+ *
+ * 走 admin-inner 接口而不是 InnerAdminExecuteSQL 直接 SELECT pg_audit：
+ *   - operator 在 details JSONB 内是 user_id，服务端解析成 username
+ *   - summary 后端按 type + before/after diff 合成（pg_audit 表无此列）
+ *   - before/after JSONB 后端 JSON.stringify 后透传字符串，CLI 按需 parse
+ *
+ * 多表用逗号拼接走 query；后端按 target_table IN (...) 一次查。skipped 字段返
+ * 多表中无记录的表名，便于 CLI 展示 hint。
+ */
+async function listAuditLog(opts) {
+    if (opts.tables.length === 0) {
+        throw new error_1.AppError("ARGS_INVALID", "at least one table is required");
+    }
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/audit/log", {
+        tables: opts.tables.join(","),
+        since: opts.since,
+        until: opts.until,
+        limit: opts.limit !== undefined ? String(opts.limit) : undefined,
+        cursor: opts.cursor,
+        dbBranch: opts.dbBranch,
+    });
+    const start = Date.now();
+    let response;
+    try {
+        response = await client.get(url);
+        (0, client_1.traceHttp)("GET", url, start, response);
+    }
+    catch (err) {
+        (0, client_1.traceHttp)("GET", url, start, err instanceof http_client_1.HttpError ? err.response : undefined, err);
+        await mapDbHttpError(err, url, "Failed to list audit log");
+        throw err; // 不可达
+    }
+    const body = (await response.json());
+    const data = (0, client_1.extractData)(body);
+    return {
+        items: data.items ?? [],
+        nextCursor: data.nextCursor && data.nextCursor !== "" ? data.nextCursor : null,
+        hasMore: Boolean(data.hasMore),
+        skipped: data.skipped ?? [],
+    };
+}
 // ── db migration → InnerAdminMigrationInit / InnerAdminMigrate ──
 /**
  * 后端：POST /v1/dataloom/app/{appId}/db/enableMultiEnv

package/dist/api/db/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.getDbQuota = exports.recover = exports.migrate = exports.migrationInit = exports.setAuditConfig = exports.getAuditStatus = exports.listDDLChangelog = exports.exportData = exports.importData = exports.getSchema = exports.execSql = void 0;
+exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.getDbQuota = exports.recover = exports.migrate = exports.migrationInit = exports.listAuditLog = exports.setAuditConfig = exports.getAuditStatus = exports.listDDLChangelog = exports.exportData = exports.importData = exports.getSchema = exports.execSql = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "execSql", { enumerable: true, get: function () { return api_1.execSql; } });
 Object.defineProperty(exports, "getSchema", { enumerable: true, get: function () { return api_1.getSchema; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "exportData", { enumerable: true, get: function (
 Object.defineProperty(exports, "listDDLChangelog", { enumerable: true, get: function () { return api_1.listDDLChangelog; } });
 Object.defineProperty(exports, "getAuditStatus", { enumerable: true, get: function () { return api_1.getAuditStatus; } });
 Object.defineProperty(exports, "setAuditConfig", { enumerable: true, get: function () { return api_1.setAuditConfig; } });
+Object.defineProperty(exports, "listAuditLog", { enumerable: true, get: function () { return api_1.listAuditLog; } });
 Object.defineProperty(exports, "migrationInit", { enumerable: true, get: function () { return api_1.migrationInit; } });
 Object.defineProperty(exports, "migrate", { enumerable: true, get: function () { return api_1.migrate; } });
 Object.defineProperty(exports, "recover", { enumerable: true, get: function () { return api_1.recover; } });

package/dist/cli/handlers/db/audit.js

@@ -44,7 +44,6 @@ const colors_1 = require("../../../utils/colors");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
-const index_2 = require("../../../api/db/index");
 const VALID_RETENTION = new Set(["7d", "30d", "180d", "360d", "forever"]);
 async function handleDbAuditStatus(table, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -113,13 +112,27 @@ async function handleDbAuditEnable(table, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: true,
-        retention,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: true,
+            retention,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 enable 报错时附带 hint，引导用户去 status 看 retention 或换值更新
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300030") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    `Use \`miaoda db audit status ${table}\` to check current retention, or run this command with a different --retention to update.`,
+                ],
+            });
+        }
+        throw err;
+    }
     // PRD JSON：{"data": {"table": "...", "enabled": true, "retention": "..."}}
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -142,12 +155,24 @@ async function handleDbAuditDisable(table, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: false,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: false,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 disable / 未启用就 disable 报错时附带 hint，引导用户去看哪些表已开启
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300031") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: ["Use `miaoda db audit status` to see which tables have audit enabled."],
+            });
+        }
+        throw err;
+    }
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
             table: status.table,
@@ -169,40 +194,35 @@ async function handleDbAuditList(tables, opts) {
     }
     const appId = (0, shared_1.resolveAppId)(opts);
     const limit = opts.limit ?? 20;
-    // since 优先级：opts.cursor（前一页末条 event_time）> opts.since
-    const sinceRaw = opts.cursor ?? opts.since;
-    const since = normalizeTime(sinceRaw, "--since/--cursor");
+    // 时间字段归一化为 ISO 8601 UTC（服务端按 event_time 字段比较）。cursor 由
+    // 后端管理（本质也是 ISO 时间），CLI 不再混用 cursor/since。
+    const since = normalizeTime(opts.since, "--since");
     const until = normalizeTime(opts.until, "--until");
-    const inList = tables.map((t) => `'${escapeSqlLiteral(t)}'`).join(",");
-    const whereParts = [`target_table IN (${inList})`];
-    if (since !== undefined)
-        whereParts.push(`event_time >= '${since}'`);
-    if (until !== undefined)
-        whereParts.push(`event_time <= '${until}'`);
-    const sql = `SELECT event_id, event_time, target_table, type, operator, summary, details ` +
-        `FROM _dl_audit_log WHERE ${whereParts.join(" AND ")} ORDER BY event_time DESC LIMIT ${String(limit + 1)}`;
-    const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
-    const allRows = collectSelectRows(results);
-    const hasMore = allRows.length > limit;
-    const visible = hasMore ? allRows.slice(0, limit) : allRows;
-    const nextCursor = hasMore && visible.length > 0 ? asString(visible[visible.length - 1].event_time) : null;
-    // 多表混合时统计哪些表无记录
-    const seen = new Set();
-    for (const r of visible)
-        seen.add(asString(r.target_table));
-    const skipped = tables.filter((t) => !seen.has(t));
+    const result = await api.db.listAuditLog({
+        appId,
+        tables,
+        since,
+        until,
+        limit,
+        cursor: opts.cursor,
+        dbBranch: opts.env,
+    });
+    const visible = result.items;
+    const skipped = result.skipped;
     // PRD JSON：data 是数组，元素是事件对象（snake_case），分页信封 next_cursor / has_more
     if ((0, output_1.isJsonMode)()) {
-        const items = visible.map((r) => ({
-            event_id: asString(r.event_id),
-            event_time: asString(r.event_time),
-            target_table: asString(r.target_table),
-            type: asString(r.type),
-            operator: asString(r.operator),
-            summary: asString(r.summary),
-            details: r.details, // 已经是结构化 JSON，透传
+        const items = visible.map((it) => ({
+            event_id: it.eventId,
+            event_time: it.eventTime,
+            target_table: it.targetTable,
+            type: it.type,
+            operator: it.operator,
+            summary: it.summary,
+            // before/after 服务端是 JSON 字符串，反序列化回结构化对象供下游消费
+            ...(it.before !== undefined ? { before: safeParseJson(it.before) } : {}),
+            ...(it.after !== undefined ? { after: safeParseJson(it.after) } : {}),
         }));
-        (0, output_1.emitPaged)(items, nextCursor, hasMore);
+        (0, output_1.emitPaged)(items, result.nextCursor, result.hasMore);
         if (skipped.length > 0) {
             process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
         }
@@ -225,23 +245,17 @@ async function handleDbAuditList(tables, opts) {
         ? ["target_table", "event_time", "type", "event_id", "operator", "summary"]
         : ["event_time", "type", "event_id", "operator", "summary"];
     const rows = visible.map((it) => {
-        const eventTime = (0, render_1.formatTime)(asString(it.event_time), tty);
-        const eventId = truncateId(asString(it.event_id));
-        const cells = [
-            eventTime,
-            asString(it.type),
-            eventId,
-            asString(it.operator, "—"),
-            asString(it.summary),
-        ];
-        return isMultiTable ? [asString(it.target_table), ...cells] : cells;
+        const eventTime = (0, render_1.formatTime)(it.eventTime, tty);
+        // event_id 完整透传——PRD 截图里的 "..." 只是文档省略写法，不是 CLI 行为
+        const cells = [eventTime, it.type, it.eventId, it.operator || "—", it.summary];
+        return isMultiTable ? [it.targetTable, ...cells] : cells;
     });
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
     if (skipped.length > 0) {
         process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
     }
-    if (hasMore && nextCursor) {
-        process.stderr.write(`(more results; use --cursor '${nextCursor}')\n`);
+    if (result.hasMore && result.nextCursor) {
+        process.stderr.write(`(more results; use --cursor '${result.nextCursor}')\n`);
     }
 }
 // ── helpers ──
@@ -255,35 +269,17 @@ function normalizeTime(input, flagName) {
     const ms = (0, index_1.parseTimeFilterMs)(input, flagName);
     return new Date(ms).toISOString();
 }
-function collectSelectRows(results) {
-    const out = [];
-    for (const r of results) {
-        const parsed = (0, index_2.parseSqlResult)(r);
-        if (parsed.kind === "select")
-            out.push(...parsed.rows);
+// 服务端 before/after 是 JSON 字符串透传，CLI JSON 输出再反序列化回对象，
+// 给下游 jq 等工具消费。失败时透传原始字符串避免数据丢失。
+function safeParseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
     }
-    return out;
-}
-// SQL 字面量转义。表名 / 时间戳由调用方控制范围（白名单或严格 ISO 8601 正则）。
-function escapeSqlLiteral(s) {
-    return s.replace(/'/g, "''");
 }
 // PRD 输出 enabled 列用 yes/no 而非 true/false
 function boolToYesNo(b) {
     return b ? "yes" : "no";
 }
-function asString(v, fallback = "") {
-    if (v == null)
-        return fallback;
-    if (typeof v === "string")
-        return v;
-    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
-        return String(v);
-    return JSON.stringify(v);
-}
-// audit list 的 event_id 在 TTY 视图里截断展示（PRD 示例 "01525416B44F..."）
-function truncateId(id) {
-    if (id.length <= 12)
-        return id;
-    return id.slice(0, 12) + "...";
-}

package/dist/cli/handlers/db/migration.js

@@ -42,45 +42,85 @@ exports.handleDbMigrationApply = handleDbMigrationApply;
 const node_readline_1 = __importDefault(require("node:readline"));
 const api = __importStar(require("../../../api/index"));
 const shared_1 = require("../../../cli/commands/shared");
+const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        const ok = await confirm(`? Initialize multi-env (single → dev/online), this is IRREVERSIBLE${opts.syncData ? " and will copy existing data to dev" : ""}? (y/N) `);
+        // 文案对齐 PRD：先讲不可逆，再问是否初始化；syncData 时追加一句而不是塞进同一句话
+        const suffix = opts.syncData ? " (existing data will be copied to dev)" : "";
+        const ok = await confirm(`? This action is irreversible. Initialize multi-env (dev / online)${suffix}? (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             return;
         }
     }
-    const result = await api.db.migrationInit({ appId, syncData: opts.syncData });
+    let result;
+    try {
+        result = await api.db.migrationInit({ appId, syncData: opts.syncData });
+    }
+    catch (err) {
+        // PRD: 重复 init 报错带 hint，引导用户去 diff 看待发布变更
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300034") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: ["Run `miaoda db migration diff` to view pending changes."],
+            });
+        }
+        throw err;
+    }
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(result));
         return;
     }
+    // PRD 单行格式（不用 key:value 表格）：
+    //   默认 ✓ / OK：     "Multi-env initialized (dev / online)"
+    //   --sync-data：      "Multi-env initialized, data synced to dev"
     const tty = (0, render_1.isStdoutTty)();
-    (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["Status", result.status],
-        ["Environments", result.environments.join(", ")],
-        ["Data synced", String(result.dataSynced)],
-    ], tty));
+    const prefix = tty ? "✓" : "OK";
+    const body = result.dataSynced
+        ? "Multi-env initialized, data synced to dev"
+        : `Multi-env initialized (${result.environments.join(" / ")})`;
+    (0, output_1.emit)(`${prefix} ${body}`);
 }
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const result = await api.db.migrate({ appId, dryRun: true });
+    let result;
+    try {
+        result = await api.db.migrate({ appId, dryRun: true });
+    }
+    catch (err) {
+        throw decorateMigrationError(err);
+    }
+    // PRD: diff 在无待发布变更时报错带 hint，而不是渲染空列表
+    if (result.changes.length === 0) {
+        throw new error_1.AppError("DB_API_k_dl_1300035", `No pending changes between ${result.from} and ${result.to}`, {
+            next_actions: [
+                'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+            ],
+        });
+    }
     renderDiff(result);
 }
 async function handleDbMigrationApply(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     // TTY 下先 diff 给用户审；--yes 直接打到 online
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        const preview = await api.db.migrate({ appId, dryRun: true });
+        let preview;
+        try {
+            preview = await api.db.migrate({ appId, dryRun: true });
+        }
+        catch (err) {
+            throw decorateMigrationError(err);
+        }
         if (preview.changes.length === 0) {
-            (0, output_1.emit)(`Error: No pending changes between ${preview.from} and ${preview.to}`);
-            (0, output_1.emit)(`  hint: Make schema changes in dev first.`);
-            process.exitCode = 1;
-            return;
+            // PRD 文案 + hint
+            throw new error_1.AppError("DB_API_k_dl_1300035", `No pending changes between ${preview.from} and ${preview.to}`, {
+                next_actions: [
+                    'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+                ],
+            });
         }
         renderDiff(preview);
         const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) to ${preview.to}? (y/N) `);
@@ -89,7 +129,13 @@ async function handleDbMigrationApply(opts) {
             return;
         }
     }
-    const result = await api.db.migrate({ appId, dryRun: false });
+    let result;
+    try {
+        result = await api.db.migrate({ appId, dryRun: false });
+    }
+    catch (err) {
+        throw decorateMigrationError(err);
+    }
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -134,6 +180,28 @@ function renderDiff(result) {
     (0, output_1.emit)(`${result.from} ${arrow} ${result.to} (${String(result.changes.length)} changes):\n\n` +
         result.changes.map((c) => `  ${c.statement}`).join("\n"));
 }
+// decorateMigrationError 给 migration / recovery 路径上的几个错误码补 PRD 规定的 hint。
+// dataloom 后端只返 message + code，hint 由 CLI 端按错误码映射；其它错误码原样透传。
+function decorateMigrationError(err) {
+    if (!(err instanceof error_1.AppError))
+        return err;
+    switch (err.code) {
+        case "DB_API_k_dl_1300039":
+            // 多环境未初始化：引导先 init
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: ["Run `miaoda db migration init` to set up multi-env first."],
+            });
+        case "DB_API_k_dl_1300035":
+            // 无待发布变更：引导先在 dev 改 schema
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+                ],
+            });
+        default:
+            return err;
+    }
+}
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
     return new Promise((resolve) => {

package/dist/cli/handlers/db/recovery.js

@@ -48,7 +48,13 @@ const render_1 = require("../../../utils/render");
 async function handleDbRecoveryDiff(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
-    const result = await api.db.recover({ appId, target: ts, dryRun: true });
+    let result;
+    try {
+        result = await api.db.recover({ appId, target: ts, dryRun: true });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
     renderDiff(result);
 }
 async function handleDbRecoveryApply(target, opts) {
@@ -56,7 +62,13 @@ async function handleDbRecoveryApply(target, opts) {
     const ts = normalizeTimestamp(target);
     // PITR 高危：TTY 下先 diff 给用户审；--yes 直接执行
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        let preview;
+        try {
+            preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        }
+        catch (err) {
+            throw decorateRecoveryError(err);
+        }
         renderDiff(preview);
         const ok = await confirm(`? Restore database to ${preview.target}? This will overwrite current data. (y/N) `);
         if (!ok) {
@@ -64,7 +76,13 @@ async function handleDbRecoveryApply(target, opts) {
             return;
         }
     }
-    const result = await api.db.recover({ appId, target: ts, dryRun: false });
+    let result;
+    try {
+        result = await api.db.recover({ appId, target: ts, dryRun: false });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "restored", "target": "...", "tables_affected": 2, "elapsed_seconds": 30}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -82,21 +100,25 @@ async function handleDbRecoveryApply(target, opts) {
 }
 // ── helpers ──
 /**
- * 把用户传入的时间统一成 ISO 8601 UTC。
- * 接受：`YYYY-MM-DD` / `YYYY-MM-DD HH:MM:SS` / 完整 ISO 8601。
+ * 把用户传入的时间统一成 ISO 8601 UTC。PRD 只接受两种格式：
+ *   - `YYYY-MM-DD`（按 UTC 0 点解释）
+ *   - 完整 ISO 8601 `YYYY-MM-DDTHH:MM:SS[Z|±HH:MM]`
+ *
+ * 严格 regex 匹配 + 不用 new Date(input) 兜底——Node Date 解析 `2026/04/15` 这种
+ * 非 ISO 字符串居然成功（落到本地时区），绕过格式校验把脏值送到后端，导致用户拿到
+ * 「窗口超限」错误而不是「格式错误」。PRD 明确这两种格式以外的都应该报 INVALID_TIMESTAMP。
  */
 function normalizeTimestamp(input) {
-    const FORMAT_HINT = "Use ISO 8601 / yyyy-mm-dd / yyyy-mm-dd HH:MM:SS.";
+    // PRD hint 文案对齐 PRD 截图（同时是 dataloom 端 ErrInvalidTimestamp 的 hint）
+    const FORMAT_HINT = "Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z";
     if (input === "") {
         throw new error_1.AppError("ARGS_INVALID", "target timestamp is required", {
             next_actions: ["Usage: miaoda db recovery diff|apply <timestamp>"],
         });
     }
+    // 仅日期：YYYY-MM-DD → 按 UTC 0 点
     if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
-        return new Date(`${input}T00:00:00Z`).toISOString();
-    }
-    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(:\d{2})?$/.test(input)) {
-        const d = new Date(input.replace(" ", "T"));
+        const d = new Date(`${input}T00:00:00Z`);
         if (Number.isNaN(d.getTime())) {
             throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
                 next_actions: [FORMAT_HINT],
@@ -104,13 +126,20 @@ function normalizeTimestamp(input) {
         }
         return d.toISOString();
     }
-    const d = new Date(input);
-    if (Number.isNaN(d.getTime())) {
-        throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
-            next_actions: [FORMAT_HINT],
-        });
+    // 完整 ISO 8601 datetime：T 分隔，秒可选 ms，Z 或 ±HH:MM 时区
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/.test(input)) {
+        const d = new Date(input);
+        if (Number.isNaN(d.getTime())) {
+            throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
+                next_actions: [FORMAT_HINT],
+            });
+        }
+        return d.toISOString();
     }
-    return d.toISOString();
+    // 其它一律按格式错误拒绝（`2026/04/15` / `2026.04.15` / `2026年4月15日` 等都走这里）
+    throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
+        next_actions: [FORMAT_HINT],
+    });
 }
 // PRD diff 输出（结构化 prose）：
 //   Recovery preview (→ 2026-04-15T10:00:00Z):
@@ -177,6 +206,28 @@ function describeChange(c) {
         parts.push(`~${String(c.modified)} rows modified`);
     return parts.length === 0 ? "no changes" : parts.join(", ");
 }
+// decorateRecoveryError 给 recovery 路径上的几个错误码补 PRD 规定的 hint。
+// dataloom 后端只返 message + code，hint 由 CLI 端按错误码映射；其它错误码原样透传。
+function decorateRecoveryError(err) {
+    if (!(err instanceof error_1.AppError))
+        return err;
+    switch (err.code) {
+        case "DB_API_k_dl_1300036":
+            // 窗口超限：引导用户检查 last migration apply 时间
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    "PITR window is up to 7 days back, limited by your last `db migration apply` time.",
+                ],
+            });
+        case "DB_API_k_dl_1300038":
+            // 时间格式错误：引导 ISO 8601
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: ["Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z"],
+            });
+        default:
+            return err;
+    }
+}
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
     return new Promise((resolve) => {

package/dist/utils/http.js

@@ -42,7 +42,11 @@ function setRuntimeHttpClient(custom) {
 }
 function createClient(opts) {
     const config = {
-        timeout: 30_000,
+        // 90s = dataloom admin-inner 异步轮询 asyncPollTimeout(60s) + 网络/解析 buffer(30s)。
+        // migration apply / recovery diff 等长轮询命令的服务端最长等 60s，CLI 超时短于
+        // 服务端会让请求被客户端 abort（'Failed to recover: 0' / 'Request aborted'），
+        // 用户拿不到真实结果。普通命令 1-2s 就返，30→90s 全局上限对短查询无可感知影响。
+        timeout: 90_000,
         platform: {
             enabled: true,
             adminInnerApi: opts.adminInnerApi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.2-alpha.8bc93eb",
+  "version": "0.1.2-alpha.8f744c0",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {