@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/src/commands/native/order/order/scan/command.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, withInputScope, constraints, modelAt } = require('../../../../../execution/error-details');
+const { parseIncludeModules } = require('../../../../../execution/command-io');
+const { readContext } = require('../../../../../identity/context');
+const { parseDateTime } = require('../../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../../execution/range');
+const { queryDefinition, validateCommandValue } = require('../../../../../execution/command-schema');
+const { bindingPath, targetScope, reject, serialize } = require('../../shared/query');
+const { listPath, toPreviewBody, filterOptions } = require('../../shared/search');
+const { scan, initialRanges, pageInput, addCalendarMonths } = require('./scan');
+const schema = require('./schema.json');
+
+const command = 'order.order.scan';
+const { includeModules } = queryDefinition(schema);
+const filterSchema = schema.input.properties.filters.properties;
+
+function buildInput(options, context) {
+  const scope = targetScope(options, context, command);
+  return withInputScope(scope, () => normalizedInput(options, scope));
+}
+
+function normalizedInput(options, scope) {
+  const fail = (path, reason, expected, relatedPaths) => {
+    throw inputIssue(path, reason, expected || constraints(modelAt(schema, 'input', path)), relatedPaths);
+  };
+  if ((options.createdAt !== undefined) === (options.paidAt !== undefined)) {
+    fail('/range', 'constraint', { format: '--created-at 与 --paid-at 必须二选一，提供完整 START..END' });
+  }
+  const timeField = options.paidAt !== undefined ? 'paidAt' : 'createdAt';
+  const now = Date.now();
+  let start;
+  let end;
+  let range;
+  try {
+    range = parseDateTimeRange(options[timeField], { precision: 'seconds', requireBoth: true, strictOrder: true });
+    start = parseDateTime(range.start);
+    end = parseDateTime(range.end);
+  } catch {
+    const error = inputIssue('/range', 'invalid_format', {
+      format: '北京时间 YYYY-MM-DD HH:mm:ss，START..END 必须两端，开始早于结束，非零毫秒不支持'
+    });
+    error.issues[0].option = timeField === 'paidAt' ? '--paid-at' : '--created-at';
+    throw error;
+  }
+  if (start % 1000 !== 0 || end % 1000 !== 0 || start < parseDateTime('2020-01-01 00:00:00') ||
+      end <= start || end > now || end > addCalendarMonths(start, 12)) {
+    const error = inputIssue('/range', 'out_of_range', {
+      format: '开始不早于2020年，结束晚于开始且不晚于当前时刻，跨度最多一日历年'
+    });
+    error.issues[0].option = timeField === 'paidAt' ? '--paid-at' : '--created-at';
+    throw error;
+  }
+  const filters = {};
+  for (const [name, optionName] of filterOptions) {
+    if (name === 'orderNo' || options[optionName] === undefined) continue;
+    const value = options[optionName];
+    if (typeof value !== 'string' || !value.trim()) fail(`/filters/${name}`, 'invalid_format');
+    if (name === 'item_id' && (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))) {
+      fail('/filters/item_id', 'invalid_format', { type: 'string', pattern: '^[1-9]\\d*$', maximum: Number.MAX_SAFE_INTEGER });
+    }
+    filters[name] = value;
+  }
+  const maxItems = options.maxItems === undefined ? 1000 : Number(options.maxItems);
+  const maxRequests = options.maxRequests === undefined ? 100 : Number(options.maxRequests);
+  const input = {
+    scope, filters, range, timeField,
+    limits: { maxItems, maxRequests }, include: [...parseIncludeModules(options.include, includeModules, '/include')],
+    format: options.format, dryRun: options.dryRun === true
+  };
+  validateCommandValue(schema, 'input', input);
+  return input;
+}
+
+function preview(input) {
+  const ranges = initialRanges(input.range);
+  const output = {
+    requests: [{ method: 'POST', path: bindingPath, body: {} }],
+    initialRanges: ranges.map(({ start, end }) => ({ start, end })),
+    requestTemplate: { method: 'POST', path: listPath, body: toPreviewBody(pageInput(input, ranges[0])) },
+    limits: { ...input.limits, pageSize: Math.min(100, input.limits.maxItems) }
+  };
+  validateCommandValue(schema, 'preview', output);
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  const instance = new DiagnosticCommand('scan', { path: command, schema, optionPaths: {
+    '/scope/kdtId': 'kdtId', '/range': 'createdAt', '/limits/maxItems': 'maxItems', '/limits/maxRequests': 'maxRequests',
+    ...Object.fromEntries(filterOptions.filter(([name]) => name !== 'orderNo').map(([name, option]) => [`/filters/${name}`, option]))
+  } })
+    .description('按显式时间范围和预算读取订单；可提前停止并报告已读结果和未完成范围')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略时使用当前上下文店铺')
+    .option('--created-at <range>', '创建时间 START..END，与 --paid-at 必须二选一，北京时间，秒精度，不早于2020年')
+    .option('--paid-at <range>', '支付时间 START..END，与 --created-at 必须二选一，北京时间，秒精度，不早于2020年')
+    .option('--yz-open-id <id>', '客户统一标识')
+    .addOption(new Option('--status <value>', '交易状态筛选').choices(filterSchema.status.enum))
+    .addOption(new Option('--type <value>', '订单类型筛选').choices(filterSchema.type.enum))
+    .option('--item-id <id>', '统一商品 ID')
+    .option('--item-title <text>', '商品名称模糊搜索')
+    .option('--receiver-phone <text>', '收货人电话')
+    .option('--receiver-name <text>', '收货人姓名')
+    .addOption(new Option('--delivery-type <value>', '配送类型筛选').choices(filterSchema.deliveryType.enum))
+    .option('--keyword <text>', '订单号、收货人手机或后四位搜索')
+    .option('--include <modules>', `追加模块：${includeModules.join(', ')}；仅投影，不增加请求`)
+    .option('--max-items <n>', '去重结果上限，1至10000，不裁切整页', '1000')
+    .option('--max-requests <n>', '总请求预算，2至500，含店铺核验、探测和翻页', '100')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地预览，收货电话、姓名及关键词全部遮盖为 ***；不读凭证、不联网')
+    .addHelpText('after', `
+商品行 item_id/sku_id 是OneID，channel_item_id/channel_sku_id 为历史渠道身份。
+--item-id沿用统一商品筛选，不把上游goods_id机械视为旧item_id，不增加渠道映射查询。
+示例：zan-saas order order scan --kdt-id 63077 --created-at "2026-10-01 00:00:00..2026-10-02 00:00:00" --max-requests 2 --dry-run
+创建时间或支付时间必须二选一，用 .. 分隔且包含两端，开始早于结束；结束不晚于当前时刻，跨度最多一日历年，非零毫秒拒绝。
+所有分片、二分、翻页和停止范围保持所选时间轴，支付轴不附加创建约束；固定并发1，每页 min(100,maxItems)，初始区间最多三个月，相邻区间共享端点。
+支付轴示例：zan-saas order order scan --kdt-id 63077 --paid-at "2026-10-01 00:00:00..2026-11-01 00:00:00" --max-requests 2 --dry-run
+默认订单可含 paidAt、isPaid；缺失表示未取得，不从状态、金额或请求窗口推算。订单级支付时间不是逐笔资金事件。
+--include payment 仍为列表金额，不含 realPayment，不逐单请求详情，不能据此求实付或净收入。
+返回订单号通常为 E/V/C 开头加 23 位数字，仅供核对，不按该格式拒绝响应；本命令不接收 --order-no。
+超过100页容量按整数秒二分；1秒区间仍过密时停止。不发送第101页，不重试、不轮询、不后台导出。
+按店铺和订单号去重，保留首次提交版本。剩余预算不足下一整页时停止，结果可能少于上限。
+pagination 返回停止原因；存在未完成范围时附带 pendingRanges，不提供恢复游标。
+预算不足可以成功返回已取得的完整页；须检查 stopReason 和 pendingRanges 判断是否读完。
+range_exhausted 只表示本次观测的范围走完，不保证端点开闭、稳定顺序、快照或无遗漏。
+本批默认 CNY，金额为两位小数字符串，不换汇、不新增币种字段；这是批次约定，不是官方币种保证。
+累计响应20MiB、最终UTF-8输出含换行10MiB，超限及任一请求/锚点/模型错误整体失败，不输出部分订单。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+`)
+    .action(async options => {
+      const state = readContext(context);
+      const input = buildInput(options, context);
+      const plan = preview(input);
+      const output = input.dryRun ? plan : await scan(input, state.context);
+      if (!input.dryRun) {
+        try { validateCommandValue(schema, 'output', output); }
+        catch { throw reject(command, 'protocol', 'output-model', input.scope, 'sent'); }
+      }
+      console.log(serialize(output, input.format, command, input.scope, 10 * 1024 * 1024));
+    });
+  return instance;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), buildInput, preview };

package/src/commands/native/order/order/scan/scan.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { formatDateTime, parseDateTime } = require('../../../../../execution/datetime');
+const { createOrderPageReader } = require('../../shared/search');
+
+function addCalendarMonths(milliseconds, months) {
+  const offset = 8 * 60 * 60 * 1000;
+  const date = new Date(milliseconds + offset);
+  const day = date.getUTCDate();
+  date.setUTCDate(1);
+  date.setUTCMonth(date.getUTCMonth() + months);
+  const lastDay = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0)).getUTCDate();
+  date.setUTCDate(Math.min(day, lastDay));
+  return date.getTime() - offset;
+}
+
+function initialRanges(range) {
+  const pending = [];
+  const end = parseDateTime(range.end);
+  let start = parseDateTime(range.start);
+  while (start < end) {
+    const next = Math.min(end, addCalendarMonths(start, 3));
+    pending.push({ start: formatDateTime(start), end: formatDateTime(next), pageNo: 1 });
+    start = next;
+  }
+  return pending;
+}
+
+function pageInput(input, range) {
+  return {
+    scope: input.scope, filters: input.filters,
+    range: { [input.timeField === 'paidAt' ? 'paid' : 'created']: { start: range.start, end: range.end } },
+    include: input.include, pagination: { pageNo: range.pageNo, pageSize: Math.min(100, input.limits.maxItems) }
+  };
+}
+
+async function scan(input, context, readerFactory = createOrderPageReader) {
+  const { maxItems, maxRequests } = input.limits;
+  const pageSize = Math.min(100, maxItems);
+  const pending = initialRanges(input.range);
+  const orders = [];
+  const seen = new Set();
+  let requests = 0;
+  let halt;
+  const read = await readerFactory(input.scope, context, 'order.order.scan', {
+    responseLimit: 20 * 1024 * 1024, bounded: true,
+    onRequest: () => { requests++; }
+  });
+  while (true) {
+    const stopReason = pending.length === 0 ? 'range_exhausted' :
+      maxItems - orders.length < pageSize ? 'max_items' :
+        requests >= maxRequests ? 'max_requests' : halt;
+    if (stopReason) {
+      const pagination = { stopReason };
+      if (pending.length > 0) pagination.pendingRanges = pending;
+      return { data: { orders, pagination } };
+    }
+    const current = pending[0];
+    const { output: result, total } = await read(pageInput(input, current));
+    const { hasMore } = result.data.pagination;
+    if (total > 100 * pageSize) {
+      if (current.pageNo > 1) {
+        current.pageNo = 1;
+        halt = 'page_window';
+      } else {
+        const start = parseDateTime(current.start);
+        const end = parseDateTime(current.end);
+        const midpoint = Math.floor((start / 1000 + end / 1000) / 2) * 1000;
+        if (midpoint <= start || midpoint >= end) halt = 'density_limit';
+        else {
+          const mid = formatDateTime(midpoint);
+          pending.splice(0, 1, { start: current.start, end: mid, pageNo: 1 },
+            { start: mid, end: current.end, pageNo: 1 });
+        }
+      }
+      continue;
+    }
+    for (const row of result.data.orders) {
+      const key = `${row.order.kdtId}:${row.order.orderNo}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      orders.push(row);
+    }
+    if (hasMore) current.pageNo++;
+    else pending.shift();
+  }
+}
+
+module.exports = { scan, initialRanges, pageInput, addCalendarMonths };