@youzan-cloud/zan-saas-cli 0.1.0-beta.7 → 0.1.0-beta.8

package/src/commands/native/valuecard/transaction/scan/command.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { withInputScope, inputIssue, parseIntegerOption } = require('../../../../../execution/error-details');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { parseDateTime, formatDateTime, apiDateTime } = require('../../../../../execution/datetime');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+const { scan, projectPage, maxItems, maxRequests } = require('./scan');
+const schema = require('./schema.json');
+
+const command = 'valuecard.transaction.scan';
+const filterFields = ['mobile', 'billCardNo', 'transactionNo', 'tradeNo'];
+const reject = (category, stage, scope, state, facts) => failure(command, category, stage, scope, state, facts);
+
+function body(input, pageNo) {
+  return { biz_type: input.bizType.toUpperCase(), begin_time: apiDateTime(input.occurredAt.start),
+    end_time: apiDateTime(input.occurredAt.end), page: pageNo, page_size: input.pageSize };
+}
+
+function normalize(options, scope) {
+  const parts = options.occurredAt.split('..');
+  let occurredAt;
+  try {
+    if (parts.length !== 2) throw new TypeError();
+    const [start, end] = parts.map(value => {
+      apiDateTime(value);
+      return formatDateTime(parseDateTime(value));
+    });
+    if (start >= end) throw new TypeError();
+    occurredAt = { start, end };
+  } catch {
+    throw inputIssue('/occurredAt', 'invalid_format', { format: 'beijing-date-time' });
+  }
+  const input = {
+    ...scope, bizType: options.bizType, occurredAt,
+    filters: Object.fromEntries(filterFields.filter(field => options[field] !== undefined).map(field => [field, options[field]])),
+    pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo'),
+    pageSize: parseIntegerOption(options.pageSize, schema, '/pageSize'),
+    format: options.format, dryRun: Boolean(options.dryRun)
+  };
+  validateCommandValue(schema, 'input', input);
+  if (input.pageNo * input.pageSize > 5000) {
+    throw inputIssue('/pageNo', 'constraint', { maximum: Math.floor(5000 / input.pageSize) }, ['/pageSize']);
+  }
+  return input;
+}
+
+async function execute(input) {
+  const scope = { kdtId: input.kdtId };
+  let responseBytes = 0;
+  const read = await createShopQuery(scope, command, {
+    transportOptions: { maxResponseBytes: () => Math.min(10 * 1024 * 1024, 20 * 1024 * 1024 - responseBytes),
+      limitStage: 'response', shopApp: false },
+    onResponse: response => { responseBytes += response.responseBytes; }
+  });
+  const output = await scan(input, async pageNo => {
+    const response = await read(schema.api.path, body(input, pageNo), 'transactions');
+    try { return projectPage(response.data, input, pageNo); }
+    catch { throw reject('protocol', 'transactions-model', scope, 'sent', response.facts); }
+  });
+  validateCommandValue(schema, 'output', output);
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  const leaf = new DiagnosticCommand('scan', { path: command, schema, parameterCategory: 'parameter',
+    optionPaths: Object.fromEntries(filterFields.map(field => [`/filters/${field}`, field])) })
+    .description('按业务类型和时间逐页读取储值流水，按原始标识本地精确查找')
+    .allowExcessArguments(false)
+    .requiredOption('--biz-type <type>', '必填：单一业务类型，支持值见 help/schema，不接受 all 或 CSV')
+    .requiredOption('--occurred-at <START..END>', '必填：北京时间 YYYY-MM-DD HH:mm:ss..YYYY-MM-DD HH:mm:ss，开始早于结束')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId，非总部不可跨店')
+    .option('--mobile <text>', '本地精确匹配流水手机号，可选 + 及 5..20 位数字，保留前导零')
+    .option('--bill-card-no <text>', '本地精确匹配流水卡号；不等于系统资产卡号，不改写原值')
+    .option('--transaction-no <text>', '本地精确匹配储值流水号；不承诺全局唯一')
+    .option('--trade-no <text>', '本地精确匹配有赞交易单号；不是外部支付请求号')
+    .option('--page-no <n>', '起始页，默认 1；页码乘容量不超过 5000，不证明前页已核实', '1')
+    .option('--page-size <n>', '固定每页容量 1..50，默认 20', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '零认证零请求预览，所有筛选值遮盖')
+    .addHelpText('after', `
+四个精确匹配条件至少一个，多条件为 AND；筛选仅在本地执行，不发送给服务端。
+固定最多 200 条匹配记录、21 次业务请求，包含一次同凭证店铺绑定；串行，不重试或自动切店。
+为完整页预留容量，可能少于 200 条；末页耗尽优先于预算停止。移除的预算选项不接受。
+单响应 10 MiB、累计响应 20 MiB、最终输出含换行 5 MiB；超限整体失败，不返回部分页。
+transactions 保留无效记录、重复项及原始未知字典值，金额为 CNY 元两位字符串，时间为北京时间毫秒文本。
+reportedBalance 时点未明确，amount 不代表统一增减方向，不推算余额变动或自动对账。
+pagination 不提供匹配 total；原始页非空但匹配为空不等于无历史。traversalCompleted 只指本次起始页之后。
+stopReason: pages_exhausted 已核实耗尽；max_items/max_requests 预算停止；window_limit 窗口停止；
+total_unknown 总数未知；inconsistent_page 总数漂移，未接纳该页。后三者也不代表无历史。
+未完成且 nextPageNo 非空时，保持同店、类型、时间、筛选和 pageSize，用 --page-no 继续。
+nextPageNo=null 不单独证明结束；窗口满时缩小时间范围，漂移时建议缩小范围从第一页重查。
+不承诺稳定排序、快照、全历史或稳定客户身份；手机号不是 yzOpenId，流水卡号不是 card.cardNo。
+biz-type: ${schema.definitions.bizType.enum.join(', ')}
+真实调用需有效四字段上下文及同店凭证，at: all 不扩大产品、员工 OAuth 或跨店授权。
+新储值商家可查全部卡交易，老储值商家仅支持礼品卡流水；不把查询结果扩大为所有储值资产历史。
+后页失败整体失败，stdout 为空；先核查原范围，不自动重试、二分、换身份或重放。
+契约：zan-saas schema valuecard.transaction.scan
+示例：zan-saas valuecard transaction scan --biz-type pay --occurred-at "2026-11-01 00:00:00..2026-11-11 12:00:00" --bill-card-no bill-card-demo --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      const input = withInputScope(scope, () => normalize(options, scope));
+      const preview = { command, kind: 'atomic', risk: 'read', target: scope,
+        requests: [{ method: 'POST', path: bindingPath, body: {} },
+          { method: 'POST', path: schema.api.path, body: body(input, input.pageNo) }],
+        localFilters: Object.fromEntries(Object.keys(input.filters).map(field => [field, '***'])),
+        limits: { maxItems, maxRequests, pageSize: input.pageSize } };
+      validateCommandValue(schema, 'preview', preview);
+      const output = input.dryRun ? preview : await execute(input);
+      const text = `${JSON.stringify(output, null, input.format === 'pretty' ? 2 : 0)}\n`;
+      if (Buffer.byteLength(text, 'utf8') > 5 * 1024 * 1024) {
+        throw reject('limit', 'output', scope, input.dryRun ? 'not_sent' : 'sent');
+      }
+      process.stdout.write(text);
+    });
+  const supplied = new Set();
+  for (const option of leaf.options) {
+    leaf.on(`option:${option.name()}`, () => {
+      if (supplied.has(option.name())) throw leaf.issue('constraint', option);
+      supplied.add(option.name());
+    });
+  }
+  return leaf;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/valuecard/transaction/scan/projection.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { object } = require('../../../../../execution/query-api');
+const { normalizeMoney } = require('../../../../../execution/money');
+const { fromBeijingSeconds } = require('../../../../../execution/beijing-date-time');
+
+const requiredFields = {
+  transactionNo: 'consumption_no', billCardNo: 'group_no', bizType: 'biz_type', validity: 'valid'
+};
+const optionalFields = {
+  mobile: 'mobile', tradeNo: 'trade_no', externalRequestNo: 'out_request_no', remark: 'remark',
+  externalRemark: 'out_remark', nickname: 'nick_name', acceptShopName: 'accept_shop_name'
+};
+const control = /[\u0000-\u001f\u007f-\u009f]/u;
+
+function requiredText(value) {
+  if (typeof value !== 'string' || !value.trim() || control.test(value)) {
+    throw new TypeError('Invalid transaction text');
+  }
+  return value;
+}
+
+function money(value) {
+  if (!Number.isSafeInteger(value)) throw new TypeError('Invalid transaction amount');
+  return normalizeMoney(value, { $comment: 'upstream-money:fen' });
+}
+
+function projectTransaction(item, filters) {
+  if (!object(item)) throw new TypeError('Invalid transaction');
+  const transaction = {};
+  for (const [field, source] of Object.entries(requiredFields)) transaction[field] = requiredText(item[source]);
+  transaction.occurredAt = fromBeijingSeconds(item.consumption_time);
+  transaction.amount = {
+    totalAmount: money(item.consumption_amount), principalAmount: money(item.principal_consumption_amount),
+    bonusAmount: money(item.bonus_consumption_amount)
+  };
+  const balances = [item.sum_dnom, item.principal_dnom, item.bonus_dnom];
+  if (!balances.every(Number.isSafeInteger) || BigInt(balances[0]) !== BigInt(balances[1]) + BigInt(balances[2])) {
+    throw new TypeError('Invalid reported balance');
+  }
+  transaction.reportedBalance = {
+    totalBalance: money(balances[0]), principalBalance: money(balances[1]), bonusBalance: money(balances[2])
+  };
+  for (const [field, source] of Object.entries(optionalFields)) {
+    if (Object.hasOwn(item, source)) {
+      if (typeof item[source] !== 'string') throw new TypeError('Invalid optional transaction text');
+      transaction[field] = item[source];
+    }
+  }
+  if (Object.hasOwn(item, 'kdt_id')) {
+    if (!Number.isSafeInteger(item.kdt_id) || item.kdt_id < 1) throw new TypeError('Invalid transaction shop');
+    transaction.kdtId = String(item.kdt_id);
+  }
+  for (const field of Object.keys(filters)) requiredText(transaction[field]);
+  return transaction;
+}
+
+module.exports = { projectTransaction };

package/src/commands/native/valuecard/transaction/scan/scan.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const { object } = require('../../../../../execution/query-api');
+const { readTotal } = require('../../../../../execution/list-total');
+const { projectTransaction } = require('./projection');
+
+const maxItems = 200;
+const maxRequests = 21;
+
+function projectPage(data, input, pageNo) {
+  const invalid = () => new TypeError('Invalid transaction page');
+  if (!object(data) || !object(data.paginator) || !Array.isArray(data.items)) throw invalid();
+  const paginator = data.paginator;
+  const total = readTotal(paginator, 'total_count', invalid);
+  if (paginator.page !== pageNo || paginator.page_size !== input.pageSize || data.items.length > input.pageSize
+    || (total !== null && data.items.length > Math.max(0, total - (pageNo - 1) * input.pageSize))) throw invalid();
+  const transactions = data.items.map(item => projectTransaction(item, input.filters));
+  return { total, transactions };
+}
+
+async function scan(input, readPage) {
+  const transactions = [];
+  const pagination = {
+    startPageNo: input.pageNo, pageSize: input.pageSize, scannedPages: 0, scannedRecords: 0,
+    returned: 0, requestCount: 1, hasMore: null, nextPageNo: null, traversalCompleted: false, stopReason: 'total_unknown'
+  };
+  let previousTotal;
+  let pageNo = input.pageNo;
+  while (true) {
+    const page = await readPage(pageNo);
+    pagination.requestCount += 1;
+    if (previousTotal !== undefined && page.total !== null && page.total !== previousTotal) {
+      pagination.hasMore = null;
+      pagination.nextPageNo = pageNo;
+      pagination.stopReason = 'inconsistent_page';
+      break;
+    }
+    pagination.scannedPages += 1;
+    pagination.scannedRecords += page.transactions.length;
+    transactions.push(...page.transactions.filter(transaction =>
+      Object.entries(input.filters).every(([field, value]) => transaction[field] === value)));
+    pagination.returned = transactions.length;
+    pagination.hasMore = page.total === null ? null : pageNo * input.pageSize < page.total;
+    if (pagination.hasMore === false) {
+      pagination.stopReason = 'pages_exhausted';
+      pagination.traversalCompleted = true;
+      break;
+    }
+    if (page.total === null) break;
+    if ((pageNo + 1) * input.pageSize > 5000) {
+      pagination.stopReason = 'window_limit';
+      break;
+    }
+    pagination.nextPageNo = pageNo + 1;
+    if (maxItems - transactions.length < input.pageSize) {
+      pagination.stopReason = 'max_items';
+      break;
+    }
+    if (pagination.requestCount >= maxRequests) {
+      pagination.stopReason = 'max_requests';
+      break;
+    }
+    previousTotal = page.total;
+    pageNo += 1;
+    pagination.nextPageNo = null;
+  }
+  return { data: { transactions, pagination } };
+}
+
+module.exports = { scan, projectPage, maxItems, maxRequests };