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

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

@@ -0,0 +1,230 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, withInputScope, constraints, modelAt, parseIntegerOption } = 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 { toRequestBody, toPreviewBody, adaptPage: adapt, createOrderPageReader } = require('../../shared/search');
+const schema = require('./schema.json');
+
+const command = 'order.order.list';
+const listPath = schema.api.path;
+const { includeModules } = queryDefinition(schema);
+const lifecyclePairs = Object.freeze([
+  ['created', 'createdAt'],
+  ['updated', 'updatedAt'],
+  ['paid', 'paidAt'],
+  ['succeeded', 'succeededAt']
+]);
+const filterOptions = Object.freeze([
+  ['orderNo', 'orderNo', 'tid'], ['yzOpenId', 'yzOpenId', 'yz_open_id'],
+  ['status', 'status', 'status'], ['type', 'type', 'type'],
+  ['item_id', 'itemId', 'goods_id'], ['itemTitle', 'itemTitle', 'goods_title'],
+  ['receiverPhone', 'receiverPhone', 'receiver_phone'],
+  ['receiverName', 'receiverName', 'receiver_name'],
+  ['deliveryType', 'deliveryType', 'express_type'], ['keyword', 'keyword', 'keywords']
+]);
+const statusValues = Object.freeze([
+  'WAIT_BUYER_PAY', 'WAIT_SELLER_SEND_GOODS', 'WAIT_BUYER_CONFIRM_GOODS',
+  'TRADE_SUCCESS', 'TRADE_CLOSED', 'TRADE_REFUND'
+]);
+const typeValues = Object.freeze([
+  'NORMAL', 'PEERPAY', 'GIFT', 'FX_CAIGOUDAN', 'PRESENT', 'WISH', 'QRCODE',
+  'QRCODE_3RD', 'FX_MERGED', 'VERIFIED', 'PINJIAN', 'REBATE', 'FX_QUANYUANDIAN',
+  'FX_DEPOSIT', 'PF', 'GROUP', 'HOTEL', 'TAKE_AWAY', 'CATERING_OFFLINE',
+  'CATERING_QRCODE', 'BEAUTY_APPOINTMENT', 'BEAUTY_SERVICE', 'KNOWLEDGE_PAY',
+  'GIFT_CARD'
+]);
+const deliveryValues = Object.freeze(['EXPRESS', 'SELF_FETCH', 'LOCAL_DELIVERY']);
+
+function failInput(path, reason = 'constraint', expected, relatedPaths) {
+  throw inputIssue(path, reason, expected || constraints(modelAt(schema, 'input', path)), relatedPaths);
+}
+
+function requiredText(value, path, maxLength) {
+  if (typeof value !== 'string') failInput(path, 'invalid_type');
+  if (!value.trim() || value.length > maxLength) failInput(path, 'out_of_range', {
+    type: 'string', minLength: 1, maxLength
+  });
+  return value;
+}
+
+function addCalendarMonths(milliseconds, months) {
+  const beijingOffset = 8 * 60 * 60 * 1000;
+  const date = new Date(milliseconds + beijingOffset);
+  const targetMonth = date.getUTCMonth() + months;
+  const day = date.getUTCDate();
+  date.setUTCDate(1);
+  date.setUTCMonth(targetMonth);
+  const lastDay = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0)).getUTCDate();
+  date.setUTCDate(Math.min(day, lastDay));
+  return date.getTime() - beijingOffset;
+}
+
+function validatePair(raw, path, now) {
+  if (raw === undefined) return undefined;
+  let range;
+  try { range = parseDateTimeRange(raw, { precision: 'seconds', requireBoth: true, strictOrder: true }); }
+  catch { failInput(path, 'invalid_format', { format: '北京时间 YYYY-MM-DD HH:mm:ss，START..END 必须两端，开始早于结束，非零毫秒不支持' }); }
+  const startMs = parseDateTime(range.start);
+  const endMs = parseDateTime(range.end);
+  if (endMs <= startMs || endMs > now + 7 * 24 * 60 * 60 * 1000 ||
+      endMs > addCalendarMonths(startMs, 3)) failInput(path, 'out_of_range', {
+        format: '开始早于结束，跨度不超过三个月，结束不晚于当前时刻加7天'
+      });
+  return range;
+}
+
+function buildInput(options, context) {
+  const target = targetScope(options, context, command);
+  return withInputScope(target, () => normalizedInput(options, target));
+}
+
+function normalizedInput(options, target) {
+  const now = Date.now();
+  const filters = {};
+  let conditionCount = 0;
+  for (const [name, optionName] of filterOptions) {
+    const value = options[optionName];
+    if (value === undefined) continue;
+    if (name === 'item_id') {
+      if (!/^[1-9]\d*$/.test(value)) failInput('/filters/item_id', 'invalid_format');
+      if (!Number.isSafeInteger(Number(value))) failInput('/filters/item_id', 'out_of_range', {
+        type: 'string', pattern: '^[1-9]\\d*$', maximum: Number.MAX_SAFE_INTEGER
+      });
+      filters[name] = String(value);
+      conditionCount++;
+      continue;
+    } else if (name === 'status') {
+      if (!statusValues.includes(value)) failInput('/filters/status', 'invalid_choice');
+    } else if (name === 'type') {
+      if (!typeValues.includes(value)) failInput('/filters/type', 'invalid_choice');
+    } else if (name === 'deliveryType') {
+      if (!deliveryValues.includes(value)) failInput('/filters/deliveryType', 'invalid_choice');
+    } else if (name !== 'orderNo') {
+      requiredText(value, `/filters/${name}`, name === 'receiverPhone' ? 20 : name === 'receiverName' ? 50 : 200);
+    }
+    filters[name] = value;
+    conditionCount++;
+  }
+  const range = {};
+  let lifecycleCount = 0;
+  for (const [name, option] of lifecyclePairs) {
+    const pair = validatePair(options[option], `/range/${name}`, now);
+    if (pair) {
+      if (name === 'created' && parseDateTime(pair.start) < parseDateTime('2020-01-01 00:00:00.000')) {
+        failInput('/range/created', 'out_of_range', { format: '创建时间不早于2020-01-01 00:00:00' });
+      }
+      range[name] = pair;
+      lifecycleCount++;
+      conditionCount++;
+    }
+  }
+  const delivery = validatePair(options.deliveryAt, '/range/delivery', now);
+  if (delivery) {
+    range.delivery = delivery;
+    conditionCount++;
+    if (filters.deliveryType !== 'LOCAL_DELIVERY') failInput('/filters/deliveryType',
+      'conditional_required', { enum: ['LOCAL_DELIVERY'] }, ['/range/delivery']);
+  }
+  if (lifecycleCount > 1) {
+    const paths = lifecyclePairs.filter(([name]) => range[name]).map(([name]) => `/range/${name}`);
+    failInput(paths[0], 'constraint', { format: '创建、更新、支付、交易完成时间区间最多提供一组' }, paths.slice(1));
+  }
+  if (conditionCount === 0) {
+    failInput('/filters', 'conditional_required', { format: '请提供至少一个筛选条件，例如 --order-no、--status 或 --created-at' }, ['/range']);
+  }
+  const pageNo = parseIntegerOption(String(options.pageNo ?? '1'), schema, '/pagination/pageNo');
+  const pageSize = parseIntegerOption(String(options.pageSize ?? '20'), schema, '/pagination/pageSize');
+  const input = {
+    scope: target,
+    filters,
+    range,
+    pagination: { pageNo, pageSize },
+    include: [...parseIncludeModules(options.include, includeModules, '/include')],
+    format: options.format,
+    dryRun: options.dryRun === true
+  };
+  validateCommandValue(schema, 'input', input);
+  return input;
+}
+
+function preview(input) {
+  const result = { requests: [
+    { method: 'POST', path: bindingPath, body: {} },
+    { method: 'POST', path: listPath, body: toPreviewBody(input) }
+  ] };
+  validateCommandValue(schema, 'preview', result);
+  return result;
+}
+
+function createCommand({ context } = {}) {
+  const commandInstance = new DiagnosticCommand('list', { path: command, schema, optionPaths: {
+    '/scope/kdtId': 'kdtId',
+    ...Object.fromEntries(filterOptions.map(([name, option]) => [`/filters/${name}`, option])),
+    ...Object.fromEntries(lifecyclePairs.map(([name, option]) => [`/range/${name}`, option])),
+    '/range/delivery': 'deliveryAt', '/pagination/pageNo': 'pageNo', '/pagination/pageSize': 'pageSize'
+  } })
+    .description('按明确筛选读取一页交易订单')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略时使用当前上下文店铺')
+    .option('--order-no <no>', '原始订单号筛选，最多 128 字符；不限定前缀或位数')
+    .option('--yz-open-id <id>', '客户统一标识')
+    .addOption(new Option('--status <value>', '订单状态筛选').choices(statusValues))
+    .addOption(new Option('--type <value>', '订单类型筛选').choices(typeValues))
+    .option('--item-id <id>', '统一商品 ID')
+    .option('--item-title <text>', '商品名称模糊搜索')
+    .option('--receiver-phone <text>', '收货人电话')
+    .option('--receiver-name <text>', '收货人姓名')
+    .addOption(new Option('--delivery-type <value>', '配送类型筛选').choices(deliveryValues))
+    .option('--keyword <text>', '订单号、收货人手机或后四位搜索')
+    .option('--created-at <range>', '创建时间 START..END，必须两端，北京时间，秒精度')
+    .option('--updated-at <range>', '更新时间 START..END，必须两端，北京时间，秒精度')
+    .option('--paid-at <range>', '支付完成时间 START..END，必须两端，北京时间，秒精度')
+    .option('--succeeded-at <range>', '交易完成时间 START..END，必须两端，北京时间，秒精度')
+    .option('--delivery-at <range>', '同城送预计送达时间 START..END，必须两端，北京时间，秒精度')
+    .option('--include <modules>', `追加模块：${includeModules.join(', ')}；仅投影，不增加请求`)
+    .option('--page-no <n>', '页码，1 至 100', '1')
+    .option('--page-size <n>', '每页条数，1 至 100', '20')
+    .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，不增加渠道映射查询。
+店铺省略 --kdt-id 时使用当前上下文店铺；显式传入时必须与当前店铺范围一致。至少提供一个明确筛选条件；一次只读取一页，最多一次列表请求，默认第1页20条，页码和每页条数上限100。
+订单号通常为 E/V/C 开头加 23 位数字，仅供核对；不按该格式拒绝筛选值或返回订单，不改写订单号。
+基础每行固定返回 order，include 可追加 items、payment、buyer、address、remark、source、aftersale、fulfillment。
+order 默认含可取得的 paidAt/isPaid，不需 include payment；缺失不表示未支付，不从状态或金额推算。
+生命周期时间区间必须用 .. 分隔且显式提供两端，开始早于结束；最多一组且跨度不超过三个月，结束不晚于当前时刻加7天。
+创建时间不早于2020年；非零毫秒拒绝，不承诺端点包含性。配送时间必须同时筛选 LOCAL_DELIVERY，沿用相同窗口限制。
+不提供全渠道、分片、详情补齐、自动重试、旧参数别名或无限翻页。第100页仍有后页时停止；total 为本次服务端匹配数，不是快照。nextPageNo 仅给出窗口内可请求页码，windowLimitReached=true 时缩小原范围，不越界。预算内跨页读取使用 order order scan，需显式创建时间范围。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+本批默认 CNY 计价，金额为两位小数字符串，不新增币种字段或换汇；列表 payment 是最终支付价格，不是详情实付，不提供或推算 realPayment。
+这是用户确认的批次约定，不是上游官方币种保证。字段、枚举及边界见 zan-saas schema order.order.list。
+示例：zan-saas order order list --kdt-id 63077 --status WAIT_SELLER_SEND_GOODS --dry-run
+`)
+    .action(async options => {
+      const state = readContext(context);
+      const input = buildInput(options, context);
+      const plan = preview(input);
+      let output = plan;
+      if (!input.dryRun) {
+        const readPage = await createOrderPageReader(input.scope, state.context, command);
+        ({ output } = await readPage(input));
+        try { validateCommandValue(schema, 'output', output); }
+        catch { throw reject(command, 'protocol', 'output-model', input.scope, 'sent'); }
+      }
+      console.log(serialize(output, input.format, command, input.scope));
+    });
+  return commandInstance;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), toRequestBody, buildInput, adapt };