@lark-apaas/miaoda-cli 0.1.2-alpha.4e370b6 → 0.1.2-alpha.51197c2

package/dist/api/db/api.js

@@ -10,7 +10,9 @@ exports.setAuditConfig = setAuditConfig;
 exports.listAuditLog = listAuditLog;
 exports.migrationInit = migrationInit;
 exports.migrate = migrate;
+exports.getMigrationStatus = getMigrationStatus;
 exports.recover = recover;
+exports.getRecoveryPreview = getRecoveryPreview;
 exports.getDbQuota = getDbQuota;
 const http_1 = require("../../utils/http");
 const error_1 = require("../../utils/error");
@@ -33,6 +35,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 ?? "";
@@ -484,6 +502,31 @@ async function migrate(opts) {
     const respBody = (await response.json());
     return (0, client_1.extractData)(respBody);
 }
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/migration/status?taskId=...
+ * CLI 拿到 migration apply 的 taskId 后定时调本接口，直到 status=success/failed。
+ * 网络层超时仍走 mapDbHttpError → 单次 30s；轮询节奏由 CLI handler 自行控制。
+ */
+async function getMigrationStatus(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/migration/status", {
+        taskId: opts.taskId,
+        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 get migration status");
+        throw err; // 不可达
+    }
+    const body = (await response.json());
+    return (0, client_1.extractData)(body);
+}
 // ── db recovery → InnerAdminRecover ──
 /**
  * 后端：POST /v1/dataloom/app/{appId}/db/recovery
@@ -509,6 +552,30 @@ async function recover(opts) {
     const respBody = (await response.json());
     return (0, client_1.extractData)(respBody);
 }
+/**
+ * 后端：GET /v1/dataloom/app/{appId}/db/recovery/preview?previewRequestId=...
+ * CLI 拿到 recovery diff 的 previewRequestId 后定时调本接口直到 previewStatus=success/failed。
+ */
+async function getRecoveryPreview(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/recovery/preview", {
+        previewRequestId: opts.previewRequestId,
+        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 get recovery preview");
+        throw err; // 不可达
+    }
+    const body = (await response.json());
+    return (0, client_1.extractData)(body);
+}
 // ── db quota → InnerAdminGetDbQuota ──
 /**
  * 后端：GET /v1/dataloom/app/{appId}/db/quota?dbBranch=

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.listAuditLog = 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.getRecoveryPreview = exports.recover = exports.getMigrationStatus = 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; } });
@@ -12,7 +12,9 @@ Object.defineProperty(exports, "setAuditConfig", { enumerable: true, get: functi
 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, "getMigrationStatus", { enumerable: true, get: function () { return api_1.getMigrationStatus; } });
 Object.defineProperty(exports, "recover", { enumerable: true, get: function () { return api_1.recover; } });
+Object.defineProperty(exports, "getRecoveryPreview", { enumerable: true, get: function () { return api_1.getRecoveryPreview; } });
 Object.defineProperty(exports, "getDbQuota", { enumerable: true, get: function () { return api_1.getDbQuota; } });
 var client_1 = require("./client");
 Object.defineProperty(exports, "buildInnerUrl", { enumerable: true, get: function () { return client_1.buildInnerUrl; } });

package/dist/cli/commands/db/index.js

@@ -218,17 +218,49 @@ Examples:
     dbCmd
         .command("changelog")
         .summary("查看 DDL 变更历史")
-        .description("列出 DDL 变更（CREATE / ALTER / DROP），支持按表、时间窗筛选与游标分页。")
+        .description("查看 DDL 变更记录（建表、改表、删表等）。默认按时间倒序显示，可按表名或时间范围过滤。")
         .usage("[flags]")
-        .option("--table <name>", "只看某张表的 DDL 变更")
-        .option("--since <time>", "起始时间（含），相对 1h/2d / 日期 YYYY-MM-DD / ISO 8601")
-        .option("--until <time>", "结束时间（含），同 --since 格式")
-        .option("--limit <n>", "单次返回上限（默认 20）", parsePositiveInt, 20)
-        .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
-        .option("--all", "自动翻页直到取完所有记录")
+        .option("--table <name>", "按表名过滤")
+        .option("--since <time>", "起始时间，支持 YYYY-MM-DD（按当日 00:00:00 UTC）/ ISO 8601（如 2026-04-01T10:00:00Z）/ 相对时间（1h、2d、1w）")
+        .option("--until <time>", "截止时间，格式同 --since")
+        .option("--limit <n>", "返回条数上限（默认 20）", parsePositiveInt, 20)
+        .option("--cursor <token>", "从上一页返回的游标位置继续获取")
+        .option("--all", "获取全部结果，自动翻页")
         .action(async function () {
         await (0, index_1.handleDbChangelog)(this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - DDL 变更由系统自动记录，不可关闭，无需单独开启。
+  - 默认输出展示摘要（summary），完整 SQL 原文（statement）通过 --json 获取。
+
+Examples:
+  # 列出近期变更（statement 截断展示，完整 SQL 用 --json 获取）
+  $ miaoda db changelog
+  change_id          changed_at             operator   target_table   change_type             summary
+  1862462453263587   2026-04-16 13:24:59    zqy        users          ALTER_AUDIT_RETENTION   修改记录日志周期
+  1861814222210116   2026-04-08 20:12:37    zqy        users          CREATE_TABLE            创建并修改数据表
+
+  # 按条件过滤
+  $ miaoda db changelog --table users --since 2026-04-01
+  $ miaoda db changelog --limit 5
+
+  # JSON 输出包含完整 statement
+  $ miaoda db changelog --limit 1 --json
+  {
+    "data": [{
+      "change_id": "1861814222210116",
+      "changed_at": "2026-04-08T20:12:37Z",
+      "operator": "zqy",
+      "target_table": "users",
+      "change_type": "CREATE_TABLE",
+      "summary": "创建并修改数据表",
+      "statement": "CREATE TABLE ... ;"
+    }],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
     // ── audit ──
     const auditCmd = dbCmd
         .command("audit")
@@ -240,42 +272,136 @@ Examples:
     });
     auditCmd
         .command("status")
-        .summary("查看审计开关状态（不传 table 返列表）")
+        .summary("查看审计开关状态")
+        .description("查看表的审计开关状态。不指定表则显示全部。")
         .usage("[table] [flags]")
         .argument("[table]", "表名；省略时返所有已配置审计的表")
         .action(async function (table) {
         await (0, index_1.handleDbAuditStatus)(table, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  # 全部表
+  $ miaoda db audit status
+  table     enabled   enabled_at            retention
+  users     yes       2026-04-01 08:00:00   30d
+  orders    no        —                     —
+  products  yes       2026-03-15 10:30:00   forever
+
+  # 单表
+  $ miaoda db audit status users
+       Table:  users
+     Enabled:  yes
+  Enabled at:  2026-04-01 08:00:00
+   Retention:  30d
+
+  # JSON
+  $ miaoda db audit status --json
+  $ miaoda db audit status users --json
+`);
     auditCmd
         .command("enable")
         .summary("启用表审计")
+        .description("开启指定表的审计，记录每次 INSERT / UPDATE / DELETE 操作。")
         .usage("<table> [flags]")
         .argument("<table>", "目标表名")
-        .option("--retention <ttl>", "保留时长 7d / 30d / 180d / 360d / forever", "7d")
+        .option("--retention <period>", "审计日志保留时长，可选 7d / 30d / 180d / 360d / forever", "7d")
         .action(async function (table) {
         await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 开启审计会占用额外存储空间，计入应用的存储配额。
+  - 用 \`miaoda db quota\` 查看用量；用 \`miaoda db audit disable\` 或调整 --retention 控制开销。
+
+Examples:
+  # 默认保留 7 天
+  $ miaoda db audit enable orders
+  ✓ Audit enabled for table 'orders' (retention: 7d)
+
+  # 指定保留时长 / 永久保留
+  $ miaoda db audit enable orders --retention 180d
+  $ miaoda db audit enable orders --retention forever
+
+  # JSON
+  $ miaoda db audit enable orders --retention 180d --json
+
+  # 报错：已经开启
+  $ miaoda db audit enable orders
+  Error: Audit is already enabled for table 'orders'
+    hint: Use \`miaoda db audit status orders\` to check current retention,
+          or run this command with a different --retention to update.
+
+  # 报错：retention 值非法
+  $ miaoda db audit enable orders --retention 60d
+  Error: Invalid retention '60d'
+    hint: Allowed values: 7d, 30d, 180d, 360d, forever.
+`);
     auditCmd
         .command("disable")
         .summary("关闭表审计")
+        .description("关闭指定表的审计。")
         .usage("<table> [flags]")
         .argument("<table>", "目标表名")
         .action(async function (table) {
         await (0, index_1.handleDbAuditDisable)(table, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db audit disable orders
+  ✓ Audit disabled for table 'orders'
+
+  # JSON
+  $ miaoda db audit disable orders --json
+
+  # 报错：未开启
+  $ miaoda db audit disable orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Use \`miaoda db audit status\` to see which tables have audit enabled.
+`);
     auditCmd
         .command("list")
         .summary("查询审计日志")
-        .description("按表 + 时间窗查询审计日志（INSERT / UPDATE / DELETE）。")
+        .description("查询一个或多个表的审计日志记录。多表查询时输出会带 target_table 列标识每条记录所属的表。")
         .usage("<table...> [flags]")
-        .argument("<tables...>", "一个或多个表名（多表时空表会汇总到 stderr）")
-        .option("--since <time>", "起始时间")
-        .option("--until <time>", "结束时间")
-        .option("--limit <n>", "单次返回上限（默认 50）", parsePositiveInt, 50)
-        .option("--cursor <ts>", "分页游标，传上一页末条 event_time")
+        .argument("<tables...>", "一个或多个表名")
+        .option("--since <time>", "起始时间，支持 YYYY-MM-DD / ISO 8601 / 相对时间（同 changelog --since）")
+        .option("--until <time>", "截止时间，格式同 --since")
+        .option("--limit <n>", "返回条数上限（默认 20）", parsePositiveInt, 20)
+        .option("--cursor <token>", "从上一页返回的游标位置继续获取")
+        .option("--all", "获取全部结果，自动翻页")
         .action(async function (tables) {
         await (0, index_1.handleDbAuditList)(tables, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 默认输出展示变更摘要（summary），完整变更快照（details 含 before / after）通过 --json 获取。
+  - 多表查询时不可用的表（未开启审计或不存在）会被跳过而非整体失败，全部不可用才返回错误。
+  - 退出码：只要有任何一张表有结果即为 0（跳过不算失败）；全部不可用才为 1。
+
+Examples:
+  # 单表
+  $ miaoda db audit list users --limit 5
+
+  # 多表（输出带 target_table 列区分来源）
+  $ miaoda db audit list users orders --limit 5
+
+  # 按时间范围
+  $ miaoda db audit list users --since 2026-04-14 --limit 10
+
+  # JSON（含完整 details / before / after）
+  $ miaoda db audit list users --limit 1 --json
+
+  # 报错：单表未开启
+  $ miaoda db audit list orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Run \`miaoda db audit enable orders\` to start recording changes.
+
+  # 多表全部不可用才整体报错
+  $ miaoda db audit list orders invoices
+  Error: No audit data available for any of the specified tables
+    hint: Check audit status with \`miaoda db audit status\`.
+`);
     // ── migration ──
     const migrationCmd = dbCmd
         .command("migration")
@@ -287,28 +413,106 @@ Examples:
     });
     migrationCmd
         .command("init")
-        .summary("初始化多环境（不可逆）")
+        .summary("初始化多环境模式（dev / online）")
+        .description("初始化多环境模式（dev / online）。初始化后，dev 环境的数据库结构变更需要经 `migration apply` " +
+        "应用到 online；online 将无法直接更改数据库结构（仍可进行数据 DML 操作）。")
         .usage("[flags]")
-        .option("--sync-data", "同时把现有数据复制到 dev")
-        .option("--yes", "跳过 TTY 确认")
+        .option("--sync-data", "启用时将现有数据同步一份到 dev 环境")
+        .option("-y, --yes", "跳过确认提示直接执行")
         .action(async function () {
         await (0, index_1.handleDbMigrationInit)(this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 多环境模式一旦启用无法恢复为单库模式，请确认后再启用。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration init
+  ? This action is irreversible. Initialize multi-env (dev / online)? (y/N) y
+  ✓ Multi-env initialized (dev / online)
+
+  # --yes 跳过确认（Agent / CI 场景）
+  $ miaoda db migration init --sync-data --yes
+  ✓ Multi-env initialized, data synced to dev
+
+  # JSON
+  $ miaoda db migration init --yes --json
+  {"data": {"status": "initialized", "environments": ["dev", "online"], "data_synced": false}}
+
+  # 报错：已经初始化过
+  $ miaoda db migration init
+  Error: Multi-env is already initialized
+    hint: Run \`miaoda db migration diff\` to view pending changes.
+`);
     migrationCmd
         .command("diff")
         .summary("预览 dev → online 待发布变更")
+        .description("预览 dev → online 的待发布变更。只读预览，不会实际发布。")
         .usage("[flags]")
         .action(async function () {
         await (0, index_1.handleDbMigrationDiff)(this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db migration diff
+  dev → online (2 changes):
+
+    ALTER TABLE users ADD COLUMN avatar_url text;
+    CREATE INDEX idx_users_avatar ON users(avatar_url);
+
+  # JSON
+  $ miaoda db migration diff --json
+
+  # 报错：无待发布变更
+  $ miaoda db migration diff
+  Error: No pending changes between dev and online
+    hint: Make schema changes in dev first (e.g. \`miaoda db sql "ALTER TABLE ..." --env dev\`).
+
+  # 报错：多环境未初始化
+  $ miaoda db migration diff
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
     migrationCmd
         .command("apply")
-        .summary("应用 dev 变更到 online（多 DDL 单事务原子）")
+        .summary("将 dev 的变更发布到 online（单事务原子）")
+        .description("将 dev 的变更发布到 online。")
         .usage("[flags]")
-        .option("--yes", "跳过 TTY 二次确认")
+        .option("-y, --yes", "跳过确认提示直接执行")
         .action(async function () {
         await (0, index_1.handleDbMigrationApply)(this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 该操作会直接改动线上数据库，建议先用 \`migration diff\` 确认变更。
+  - 变更以单事务执行：多条 DDL 任何一条失败整批回滚，online 保持原状态。
+  - 退出码：0 表示全部成功；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration apply
+  ? Apply 2 changes to online? (y/N) y
+  ✓ Applied dev → online (2 changes)
+
+  # --yes 跳过确认
+  $ miaoda db migration apply --yes
+  ✓ Applied dev → online (2 changes)
+
+  # JSON
+  $ miaoda db migration apply --yes --json
+  {"data": {"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}}
+
+  # 报错：无待发布变更
+  $ miaoda db migration apply
+  Error: No pending changes to apply
+    hint: Make schema changes in dev first, then run \`miaoda db migration diff\` to preview.
+
+  # 报错：多环境未启用
+  $ miaoda db migration apply
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
     // ── recovery（PITR）──
     const recoveryCmd = dbCmd
         .command("recovery")
@@ -321,26 +525,119 @@ Examples:
     recoveryCmd
         .command("diff")
         .summary("预览恢复到指定时间点的影响范围")
+        .description("预览恢复到指定时间点的影响范围（受影响的表、数据变更量、预计耗时）。只读预览，不改动数据。")
         .usage("<timestamp> [flags]")
-        .argument("<timestamp>", "目标时间，YYYY-MM-DD / YYYY-MM-DD HH:MM[:SS] / ISO 8601")
+        .argument("<timestamp>", "目标时间，YYYY-MM-DD 或 ISO 8601（如 2026-04-15T10:00:00Z）")
         .action(async function (target) {
         await (0, index_1.handleDbRecoveryDiff)(target, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 超出可恢复窗口的时间点会报错，错误信息中会标注当前可恢复窗口。
+
+Examples:
+  # TTY pretty
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z
+  Recovery preview (→ 2026-04-15T10:00:00Z):
+
+    tables affected: 2
+    users:   +3 rows, -1 row, ~5 rows modified
+    orders:  table will be restored (was dropped at 10:25:00)
+
+    estimated time: ~30s
+
+  # non-TTY（管道，TAB 分列）
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z | cat
+  Recovery preview (-> 2026-04-15T10:00:00Z):
+  tables_affected	2
+  users	+3 rows, -1 row, ~5 rows modified
+  orders	table will be restored (was dropped at 10:25:00)
+  estimated_time	30
+
+  # JSON
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z --json
+
+  # 无变更（目标时间点与当前状态一致）
+  $ miaoda db recovery diff 2026-04-15T14:00:00Z
+  Recovery preview (→ 2026-04-15T14:00:00Z):
+
+    No changes — database is already at this state.
+
+  # 超出可恢复窗口
+  $ miaoda db recovery diff 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+
+  # 时间格式错误
+  $ miaoda db recovery diff 2026/04/15
+  Error: Invalid timestamp format '2026/04/15'
+    hint: Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z
+`);
     recoveryCmd
         .command("apply")
-        .summary("触发恢复到指定时间点（不可逆覆盖）")
+        .summary("将数据库恢复到指定时间点的状态")
+        .description("将数据库恢复到指定时间点的状态。")
         .usage("<timestamp> [flags]")
-        .argument("<timestamp>", "目标时间，YYYY-MM-DD / YYYY-MM-DD HH:MM[:SS] / ISO 8601")
-        .option("--yes", "跳过 TTY 二次确认")
+        .argument("<timestamp>", "目标时间，YYYY-MM-DD 或 ISO 8601（如 2026-04-15T10:00:00Z）")
+        .option("-y, --yes", "跳过确认提示直接执行")
         .action(async function (target) {
         await (0, index_1.handleDbRecoveryApply)(target, this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Notes:
+  - 该操作会覆盖当前数据且不可撤销，建议先用 \`recovery diff\` 预览影响。
+  - 恢复过程是原子的：中途失败时数据库回到操作前的状态，不会出现部分恢复。
+  - 退出码：0 表示完成；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  ? Restore database to 2026-04-15T10:00:00Z? This will overwrite current data. (y/N) y
+  ✓ Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
+
+  # --yes 跳过确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes
+
+  # JSON
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes --json
+
+  # 超出可恢复窗口
+  $ miaoda db recovery apply 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+          Run \`miaoda db recovery diff <ts>\` within this window to preview impact.
+
+  # 并发冲突（已有恢复任务在执行）
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  Error: Another recovery is already in progress
+    hint: Wait for the current recovery to finish.
+`);
     // ── quota ──
     dbCmd
         .command("quota")
-        .summary("查看数据库用量与限额")
+        .summary("查看数据库的存储用量与限额")
+        .description("查看数据库的存储用量、配额和表数量。")
         .usage("[flags]")
         .action(async function () {
         await (0, index_1.handleDbQuota)(this.optsWithGlobals());
-    });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db quota
+      Storage:  14.9 MB / 1 GB (1.5%)
+       Tables:  3
+        Views:  10
+
+  # JSON
+  $ miaoda db quota --json
+  {
+    "data": {
+      "storage_used_bytes": 15623782,
+      "storage_quota_bytes": 1073741824,
+      "usage_percent": 1.5,
+      "tables": 3,
+      "views": 10
+    }
+  }
+`);
 }

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

@@ -44,6 +44,7 @@ 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 poll_1 = require("../../../utils/poll");
 const render_1 = require("../../../utils/render");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -136,21 +137,42 @@ async function handleDbMigrationApply(opts) {
     catch (err) {
         throw decorateMigrationError(err);
     }
+    // dataloom 立即返 taskId（apply 实际是异步流水线）。CLI 自己 poll 直到 success/failed，
+    // 避免单次 HTTP 长连接 30s+ 被网关 / SDK 中断。
+    if (result.taskId === undefined || result.taskId === "") {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "migration apply did not return taskId");
+    }
+    const taskId = result.taskId;
+    const final = await (0, poll_1.pollUntilDone)({
+        label: "migration apply",
+        intervalMs: 1000,
+        fetch: () => api.db.getMigrationStatus({ appId, taskId }),
+        isDone: (cur) => {
+            // 同 recovery preview，dataloom 上下游枚举大小写不完全统一，客户端归一兜底。
+            const status = cur.status.toLowerCase();
+            if (status === "success")
+                return { done: true, value: cur };
+            if (status === "failed") {
+                throw new error_1.AppError("DB_API_k_dl_1300030", cur.errorMessage ?? `migration apply failed (taskId=${taskId})`);
+            }
+            return { done: false };
+        },
+    });
+    const appliedCount = final.changesApplied ?? result.changes.length;
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
-            status: result.status ?? "applied",
+            status: "applied",
             from: result.from,
             to: result.to,
-            changesApplied: result.changesApplied ?? result.changes.length,
+            changesApplied: appliedCount,
         }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
     const prefix = tty ? "✓" : "OK";
     const arrow = tty ? "→" : "->";
-    const applied = result.changesApplied ?? result.changes.length;
-    (0, output_1.emit)(`${prefix} Applied ${result.from} ${arrow} ${result.to} (${String(applied)} changes)`);
+    (0, output_1.emit)(`${prefix} Applied ${result.from} ${arrow} ${result.to} (${String(appliedCount)} changes)`);
 }
 // ── helpers ──
 // PRD diff 输出：

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

@@ -43,60 +43,121 @@ 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 poll_1 = require("../../../utils/poll");
 const render_1 = require("../../../utils/render");
 // ── recovery diff ──
+//
+// PITR preview 是异步任务：dataloom 立即返 previewRequestId，CLI 自己 poll 直到 success/failed。
+// 失败时 dataloom 已用 translateRestoreErr 把中文窗口错误翻成 PRD 英文 + k_dl_1300036 code，
+// CLI 走 decorateRecoveryError 补 hint。
 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 });
-    renderDiff(result);
+    const preview = await runRecoveryPreview(appId, ts);
+    renderDiff(ts, preview);
 }
 async function handleDbRecoveryApply(target, opts) {
     const appId = (0, shared_1.resolveAppId)(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 });
-        renderDiff(preview);
-        const ok = await confirm(`? Restore database to ${preview.target}? This will overwrite current data. (y/N) `);
+        const preview = await runRecoveryPreview(appId, ts);
+        renderDiff(ts, preview);
+        const ok = await confirm(`? Restore database to ${ts}? This will overwrite current data. (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             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}
+        // PRD：{"status": "restored", "target": "...", "elapsed_seconds": 30}
+        // tables_affected 来源于 preview，apply 路径不再回带，由 CLI 不强求字段。
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
             status: result.status ?? "restored",
             target: result.target,
-            tablesAffected: result.tablesAffected,
             elapsedSeconds: result.elapsedSeconds ?? 0,
         }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
     const prefix = tty ? "✓" : "OK";
-    (0, output_1.emit)(`${prefix} Database restored to ${result.target} ` +
-        `(${String(result.tablesAffected)} tables affected, ${String(result.elapsedSeconds ?? 0)}s elapsed)`);
+    (0, output_1.emit)(`${prefix} Database restore triggered for ${result.target} ` +
+        `(${String(result.elapsedSeconds ?? 0)}s elapsed)`);
+}
+/**
+ * 触发 PITR 预览任务并轮询到终态：
+ *   1. POST /db/recovery dryRun=true → previewRequestId
+ *   2. GET /db/recovery/preview?previewRequestId 直到 previewStatus=success/failed
+ *
+ * 错误透传：业务错误（窗口超限 / 格式错）由 dataloom 直接 throw，CLI 在 catch 里
+ * 补 hint。failed 状态下 dataloom 已把 errorMessage 翻好，CLI 包成 k_dl_1300036
+ * 让 decorateRecoveryError 命中窗口超限 hint。
+ */
+async function runRecoveryPreview(appId, ts) {
+    let triggered;
+    try {
+        triggered = await api.db.recover({ appId, target: ts, dryRun: true });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
+    if (triggered.previewRequestId === undefined || triggered.previewRequestId === "") {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "recovery diff did not return previewRequestId");
+    }
+    const previewRequestId = triggered.previewRequestId;
+    try {
+        return await (0, poll_1.pollUntilDone)({
+            label: "recovery preview",
+            intervalMs: 1000,
+            fetch: () => api.db.getRecoveryPreview({ appId, previewRequestId }),
+            isDone: (cur) => {
+                // dataloom 内部 pgsvc 返回首字母大写枚举（Pending/Running/Success/Failed），
+                // 但 admin-inner thrift 契约里写的是小写。客户端做大小写归一兜底，避免依赖
+                // 上游 case 一致性导致死循环。
+                const status = cur.previewStatus.toLowerCase();
+                if (status === "success")
+                    return { done: true, value: cur };
+                if (status === "failed") {
+                    // 复用 k_dl_1300036（窗口超限 / 预览失败的统一对外码），让 decorateRecoveryError
+                    // 命中后给 PITR 7 天窗口的 hint。errorMessage 优先用 dataloom 翻好的 PRD 文案。
+                    throw new error_1.AppError("DB_API_k_dl_1300036", cur.errorMessage ?? "recovery preview failed");
+                }
+                return { done: false };
+            },
+        });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
 }
 // ── 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,15 +165,24 @@ 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）：
+// PRD diff 输出，三套：
+//
+// TTY pretty（缩进 prose、带 Unicode 箭头 / 波浪号、表名按列对齐）：
 //   Recovery preview (→ 2026-04-15T10:00:00Z):
 //
 //     tables affected: 2
@@ -120,12 +190,24 @@ function normalizeTimestamp(input) {
 //     orders:  table will be restored (was dropped at 10:25:00)
 //
 //     estimated time: ~30s
-function renderDiff(result) {
+//
+// non-TTY pretty（管道友好，扁平 TSV、ASCII 箭头、snake_case key、estimated_time 不带 ~/s）：
+//   Recovery preview (-> 2026-04-15T10:00:00Z):
+//   tables_affected\t2
+//   users\t+3 rows, -1 row, ~5 rows modified
+//   orders\ttable will be restored (was dropped at 10:25:00)
+//   estimated_time\t30
+//
+// --json：标准 envelope，字段名固定 snake_case。
+function renderDiff(target, preview) {
+    const changes = preview.changes ?? [];
+    const tablesAffected = preview.tablesAffected ?? changes.length;
+    const estimated = preview.estimatedSeconds;
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
-            target: result.target,
-            tablesAffected: result.tablesAffected,
-            changes: result.changes.map((c) => ({
+            target,
+            tablesAffected,
+            changes: changes.map((c) => ({
                 table: c.table,
                 inserted: c.inserted,
                 deleted: c.deleted,
@@ -133,40 +215,77 @@ function renderDiff(result) {
                 action: c.action,
                 droppedAt: c.droppedAt,
             })),
-            estimatedSeconds: result.estimatedSeconds ?? 0,
+            estimatedSeconds: estimated ?? 0,
         }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const arrow = tty ? "→" : "->";
-    if (result.changes.length === 0) {
-        (0, output_1.emit)(`Recovery preview (${arrow} ${result.target}):\n\n` +
-            `  No changes — database is already at this state.`);
+    if (tty) {
+        (0, output_1.emit)(renderDiffTty(target, changes, tablesAffected, estimated));
         return;
     }
-    const lines = [
-        `Recovery preview (${arrow} ${result.target}):`,
-        "",
-        `  tables affected: ${String(result.tablesAffected)}`,
-    ];
-    for (const c of result.changes) {
-        lines.push(`  ${c.table}:  ${describeChange(c)}`);
+    (0, output_1.emit)(renderDiffPipe(target, changes, tablesAffected, estimated));
+}
+function renderDiffTty(target, changes, tablesAffected, estimated) {
+    const header = `Recovery preview (→ ${target}):`;
+    if (changes.length === 0) {
+        return `${header}\n\n  No changes — database is already at this state.`;
+    }
+    // 对齐：所有表名右侧补到 max(len) + 1 个 ":" + 1 个空格再起描述。PRD 用例里
+    // "users:   " / "orders:  " 三/二空格其实就是按 6 个 char 列宽对齐出来的。
+    const maxName = Math.max(...changes.map((c) => c.table.length));
+    const lines = [header, "", `  tables affected: ${String(tablesAffected)}`];
+    for (const c of changes) {
+        const pad = " ".repeat(Math.max(1, maxName - c.table.length + 2));
+        lines.push(`  ${c.table}:${pad}${describeChange(c)}`);
     }
-    if (result.estimatedSeconds !== undefined) {
+    if (estimated !== undefined) {
         lines.push("");
-        lines.push(`  estimated time: ~${String(result.estimatedSeconds)}s`);
+        lines.push(`  estimated time: ~${String(estimated)}s`);
+    }
+    return lines.join("\n");
+}
+function renderDiffPipe(target, changes, tablesAffected, estimated) {
+    // 管道场景：去掉缩进，TAB 分列，箭头降级为 ->，key 用 snake_case，
+    // estimated_time 只输出秒数（不带 ~/s），方便 awk/grep。
+    const header = `Recovery preview (-> ${target}):`;
+    if (changes.length === 0) {
+        return `${header}\nNo changes — database is already at this state.`;
+    }
+    const lines = [header, `tables_affected\t${String(tablesAffected)}`];
+    for (const c of changes) {
+        lines.push(`${c.table}\t${describeChange(c)}`);
+    }
+    if (estimated !== undefined) {
+        lines.push(`estimated_time\t${String(estimated)}`);
     }
-    (0, output_1.emit)(lines.join("\n"));
+    return lines.join("\n");
 }
 function describeChange(c) {
-    if (c.action === "restore_table" || c.action === "drop" || c.action === "create") {
+    // 表级操作：dataloom 现在把 schema diff 透出为 action="schema_<diffType>"，
+    // 老协议的 restore_table / drop / create 一并保留兼容。
+    if (c.action === "restore_table") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        return `table will be restored${ts}`;
+    }
+    if (c.action === "drop") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        return `table will be dropped${ts}`;
+    }
+    if (c.action === "create") {
         const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
-        if (c.action === "restore_table")
-            return `table will be restored${ts}`;
-        if (c.action === "drop")
-            return `table will be dropped${ts}`;
         return `table will be created${ts}`;
     }
+    if (c.action?.startsWith("schema_") === true) {
+        // schema diff 子类不细化，统一显示 "schema changed (<diffType>)"
+        const diffType = c.action.slice("schema_".length);
+        return `schema changed${diffType !== "" ? ` (${diffType})` : ""}`;
+    }
+    if (c.action === "unavailable") {
+        // dataloom 端 count 失败的表，复用 droppedAt 透传 message
+        return `diff unavailable${c.droppedAt !== undefined && c.droppedAt !== "" ? `: ${c.droppedAt}` : ""}`;
+    }
+    // 数据变更：+N rows / -N rows / ~N rows modified
     const parts = [];
     if (c.inserted !== undefined && c.inserted !== 0)
         parts.push(`+${String(c.inserted)} rows`);
@@ -177,6 +296,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/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.isJsonMode = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+exports.pollUntilDone = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.isJsonMode = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
 var error_1 = require("./error");
 Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
 Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
@@ -25,3 +25,5 @@ Object.defineProperty(exports, "getRuntimeHttpClient", { enumerable: true, get:
 Object.defineProperty(exports, "resetHttpClient", { enumerable: true, get: function () { return http_1.resetHttpClient; } });
 Object.defineProperty(exports, "setHttpClient", { enumerable: true, get: function () { return http_1.setHttpClient; } });
 Object.defineProperty(exports, "setRuntimeHttpClient", { enumerable: true, get: function () { return http_1.setRuntimeHttpClient; } });
+var poll_1 = require("./poll");
+Object.defineProperty(exports, "pollUntilDone", { enumerable: true, get: function () { return poll_1.pollUntilDone; } });

package/dist/utils/poll.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollUntilDone = pollUntilDone;
+const error_1 = require("../utils/error");
+async function pollUntilDone(opts) {
+    const interval = opts.intervalMs ?? 1000;
+    const timeout = opts.timeoutMs ?? 300_000;
+    const deadline = Date.now() + timeout;
+    // 立即拉一次（绝大多数轻量任务在 dataloom 端已是同步语义，第一次 fetch 就能拿到 success）
+    for (;;) {
+        const cur = await opts.fetch();
+        const verdict = opts.isDone(cur);
+        if (verdict.done)
+            return verdict.value;
+        if (Date.now() + interval > deadline) {
+            throw new error_1.AppError("TASK_TIMEOUT", `${opts.label} did not complete within ${String(Math.round(timeout / 1000))}s`, {
+                next_actions: [
+                    "The task may still be running server-side. Retry the command, or check `miaoda db migration diff` to verify final state.",
+                ],
+            });
+        }
+        await sleep(interval);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

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