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

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

@@ -0,0 +1,78 @@
+'use strict';
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { buildInput, requestBody } = require('./input');
+const { reject, createQuery, adapt, serialize, bindingPath } = require('./query');
+const schema = require('./schema.json');
+
+function preview(input) {
+  const body = requestBody(input);
+  for (const name of ['keyword', 'mobile']) if (Object.hasOwn(body, name)) body[name] = '***';
+  const plan = { requests: [{ method: 'POST', path: bindingPath, body: {} },
+    { method: 'POST', path: schema.api.path, body }] };
+  validateCommandValue(schema, 'preview', plan);
+  return plan;
+}
+
+function createCommand({ context } = {}) {
+  const seen = new Set();
+  const optionPaths = Object.fromEntries(Object.keys(schema.input.properties.filters.properties)
+    .map(name => [`/filters/${name}`, name]));
+  const command = new DiagnosticCommand('list', { path: 'customer.customer.list', schema, optionPaths })
+    .description('按条件查询一页客户摘要，恢复等级与持卡筛选，不返回全店全集')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正安全整数 ID；省略时使用当前上下文店铺')
+    .option('--keyword <text>', '模糊搜索姓名、手机号、昵称，1..200 字符，与 mobile 互斥')
+    .option('--mobile <number>', '精确单手机号，可选加号及 5..20 位数字，保留前导零')
+    .option('--is-member <boolean>', 'true 会员，false 非会员，省略不筛选')
+    .option('--tag-ids <ids>', '必须全部满足的标签 ID，CSV 或 JSON 字符串数组，1..50 项')
+    .option('--created <range>', '成为客户时间，北京时间起点..终点，可单边，必须含 ..')
+    .option('--member-created <range>', '成为会员时间，起点..终点，可单边，不推断当前会员身份')
+    .option('--last-trade <range>', '最后购买时间，起点..终点，可单边，不表示窗口内任意购买')
+    .option('--trade-count <range>', '历史购次 LOW..HIGH，可单边或裸值，非负 32 位整数')
+    .option('--trade-amount <range>', '历史消费金额，元文本 LOW..HIGH，可单边或裸值，最多两位小数')
+    .option('--points <range>', '积分 LOW..HIGH，可单边或裸值，非负安全整数')
+    .option('--stored-balance <range>', '储值余额，元文本 LOW..HIGH，可单边或裸值，不代表逐卡可支付余额')
+    .option('--level-ids <ids>', '等级定义数值 ID，CSV 或 JSON 字符串数组，非 alias 或等级值')
+    .option('--has-level <boolean>', 'true 有等级，false 无等级；false 与 level-ids 冲突')
+    .option('--benefit-card-ids <ids>', '权益卡定义数值 ID，CSV 或 JSON 字符串数组，非 cardAlias 或 cardNo')
+    .option('--has-benefit-card <boolean>', 'true 有卡，false 无卡；false 与 benefit-card-ids 冲突，不证明卡有效')
+    .option('--page-no <number>', '页码 1..500，页码乘页容量不得超过 10000', '1')
+    .option('--page-size <number>', '本页容量 1..50，不表示总量', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地脱敏预览，零认证和业务请求')
+    .addHelpText('after', `
+固定按服务端创建时间降序，不开放排序、来源渠道、批量手机号或任意过滤 JSON。
+时间格式 YYYY-MM-DD HH:mm:ss[.SSS]，固定 UTC+08:00，只允许零毫秒。
+数值裸值传相同双边；省略边界不补零或当前时间，范围上下限不可倒置。
+等级和卡使用定义 ID，集合关系沿用服务端语义，不自动补 has=true。
+执行需要四字段上下文，同店核验后仅查询一页，最多两次请求，不重试、切店或换身份。
+只输出有限客户摘要和四字段分页；未取得总数时省略 total，hasMore 为 null，短页或空页不证明取完。
+响应累计上限 10MiB，输出含换行上限 5MiB；失败 stdout 为空，stderr 为脱敏错误。
+手机号和姓名不能代替 yzOpenId；本地预览和店铺绑定不证明员工权限。
+契约：zan-saas schema customer.customer.list
+示例：zan-saas customer customer list --kdt-id 63077 --points '100..500' --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      if (options.dryRun) {
+        console.log(JSON.stringify(preview(input), null, options.format === 'pretty' ? 2 : 0));
+        return;
+      }
+      const read = await createQuery(input);
+      const { data, facts } = await read(requestBody(input));
+      console.log(serialize(adapt(data, input, facts), options.format, { kdtId: input.kdtId }));
+    });
+  for (const option of command.options) {
+    command.on(`option:${option.name()}`, () => {
+      if (seen.has(option.name())) throw command.issue('constraint', option);
+      seen.add(option.name());
+    });
+  }
+  return command;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), preview, buildInput };

package/src/commands/native/customer/customer/list/input.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { apiSeconds } = require('../../../../../execution/datetime');
+const { parseIntegerRange, parseMoneyRange, parseDateTimeRange } = require('../../../../../execution/range');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { inputIssue, constraints, modelAt, withInputScope } = require('../../../../../execution/error-details');
+const { reject } = require('./query');
+const schema = require('./schema.json');
+
+const rangeFields = {
+  created: ['created_at', 'time'],
+  memberCreated: ['created_member_at', 'time'],
+  lastTrade: ['last_trade_time', 'time'],
+  tradeCount: ['total_trade_count', 'count'],
+  tradeAmount: ['total_trade_amount', 'money'],
+  points: ['points', 'points'],
+  storedBalance: ['stored_balance', 'money']
+};
+
+function integer(value, maximum = Number.MAX_SAFE_INTEGER) {
+  if (typeof value !== 'string' || !/^(0|[1-9]\d*)$/.test(value) ||
+      !Number.isSafeInteger(Number(value)) || Number(value) > maximum) throw new Error('integer');
+  return Number(value);
+}
+
+function cents(value) {
+  if (typeof value !== 'string' || !/^(0|[1-9]\d*)(\.\d{1,2})?$/.test(value)) throw new Error('money');
+  const [whole, fraction = ''] = value.split('.');
+  const amount = BigInt(whole) * 100n + BigInt(fraction.padEnd(2, '0'));
+  if (amount > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error('money');
+  return Number(amount);
+}
+
+function boundary(value, type) {
+  if (type === 'time') {
+    if (value !== value.trim()) throw new Error('time whitespace');
+    const seconds = apiSeconds(value);
+    if (seconds < 0 || seconds > 4102444800) throw new Error('time bounds');
+    return;
+  }
+  if (type === 'money') {
+    cents(value);
+    return;
+  }
+  integer(value, type === 'count' ? 2147483647 : Number.MAX_SAFE_INTEGER);
+}
+
+function range(value, type) {
+  if (typeof value !== 'string') throw new Error('range');
+  for (const part of value.split('..')) if (part !== '') boundary(part, type);
+  if (type === 'time') return parseDateTimeRange(value, { precision: 'seconds' });
+  if (type === 'money') return parseMoneyRange(value, { maximum: '90071992547409.91' });
+  return parseIntegerRange(value, { maximum: type === 'count' ? 2147483647 : Number.MAX_SAFE_INTEGER });
+}
+
+function idList(value) {
+  if (typeof value !== 'string' || value !== value.trim()) throw new Error('ids');
+  const entries = value.startsWith('[') ? JSON.parse(value) : value.split(',');
+  if (!Array.isArray(entries) || entries.length < 1 || entries.length > 50) throw new Error('ids');
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || integer(entry) < 1) throw new Error('id');
+  }
+  return [...new Set(entries)];
+}
+
+function buildInput(options, context) {
+  let kdtId;
+  try {
+    if (typeof options.kdtId !== 'string' || integer(options.kdtId) < 1) throw new Error('shop');
+    kdtId = options.kdtId;
+  } catch { throw inputIssue('/kdtId', 'invalid_format', constraints(modelAt(schema, 'input', '/kdtId'))); }
+  const scope = { kdtId };
+  try { resolveTargetShop(options, context, 'customer.customer.list'); }
+  catch (error) {
+    const details = error.cliDetails;
+    throw reject(details?.category || 'configuration', details?.stage === 'context' ? 'context' : 'input', scope);
+  }
+  return withInputScope(scope, () => {
+    function field(name, parse, path = `/filters/${name}`) {
+      try { return parse(); }
+      catch {
+        const expected = constraints(modelAt(schema, 'input', path));
+        if (rangeFields[name]?.[1] === 'time') {
+          expected.format = '北京时间 YYYY-MM-DD HH:mm:ss，区间必须包含 ..，不接受时间戳';
+        }
+        throw inputIssue(path, expected.type === 'integer' ? 'out_of_range' : 'invalid_format', expected);
+      }
+    }
+    const filters = {};
+    for (const name of ['keyword', 'mobile']) {
+      if (options[name] !== undefined) filters[name] = options[name];
+    }
+    for (const name of ['isMember', 'hasLevel', 'hasBenefitCard']) {
+      if (options[name] === undefined) continue;
+      if (!['true', 'false'].includes(options[name])) {
+        throw inputIssue(`/filters/${name}`, 'invalid_choice', { type: 'boolean', enum: [true, false] });
+      }
+      filters[name] = options[name] === 'true';
+    }
+    for (const name of ['tagIds', 'levelIds', 'benefitCardIds']) {
+      if (options[name] !== undefined) filters[name] = field(name, () => idList(options[name]));
+    }
+    for (const [name, [, type]] of Object.entries(rangeFields)) {
+      if (options[name] !== undefined) filters[name] = field(name, () => range(options[name], type));
+    }
+    const input = { kdtId, filters,
+      pageNo: field('pageNo', () => integer(options.pageNo, 500), '/pageNo'),
+      pageSize: field('pageSize', () => integer(options.pageSize, 50), '/pageSize') };
+    validateCommandValue(schema, 'input', input);
+    for (const [left, right] of [['keyword', 'mobile'], ['hasLevel', 'levelIds'], ['hasBenefitCard', 'benefitCardIds']]) {
+      if (filters[right] !== undefined && (left === 'keyword' ? filters[left] !== undefined : filters[left] === false)) {
+        throw inputIssue(`/filters/${right}`, 'constraint', undefined, [`/filters/${left}`]);
+      }
+    }
+    if (input.pageNo * input.pageSize > 10000) {
+      throw inputIssue('/pageNo', 'constraint', { maximum: Math.floor(10000 / input.pageSize) }, ['/pageSize']);
+    }
+    return input;
+  });
+}
+
+function requestBody(input) {
+  const body = { page_no: input.pageNo, page_size: input.pageSize };
+  const { filters } = input;
+  for (const name of ['keyword', 'mobile']) {
+    if (filters[name] !== undefined) body[name] = filters[name];
+  }
+  if (filters.isMember !== undefined) body.is_member = filters.isMember ? 1 : 0;
+  for (const [name, field] of Object.entries({ tagIds: 'all_match_tag_ids', levelIds: 'level_ids', benefitCardIds: 'card_ids' })) {
+    if (filters[name]) body[field] = filters[name].map(Number);
+  }
+  for (const [name, field] of Object.entries({ hasLevel: 'has_level', hasBenefitCard: 'has_card' })) {
+    if (filters[name] !== undefined) body[field] = filters[name];
+  }
+  for (const [name, [field, type]] of Object.entries(rangeFields)) {
+    if (!filters[name]) continue;
+    for (const [bound, value] of Object.entries(filters[name])) {
+      body[`${field}_${bound}`] = type === 'time' ? apiSeconds(value) : type === 'money' ? cents(value) : value;
+    }
+  }
+  return body;
+}
+
+module.exports = { buildInput, requestBody, range, cents };

package/src/commands/native/customer/customer/list/query.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+const { createBoundShopQuery, bindingPath } = require('../../../../../execution/shop-query');
+const { QueryError, object } = require('../../../../../execution/query-api');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { formatDateTime } = require('../../../../../execution/datetime');
+const schema = require('./schema.json');
+
+const command = 'customer.customer.list';
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+
+function reject(category, stage, scope = {}, state = 'not_sent', facts = {}) {
+  return new QueryError(category, stage, scope, facts, state, command,
+    '核对原店铺、筛选范围、字段来源和服务端授权；失败不返回部分客户，不自动换店、换身份或重放请求。');
+}
+
+async function createQuery(input, responseLimit = RESPONSE_LIMIT) {
+  const scope = { kdtId: input.kdtId };
+  let responseBytes = 0;
+  try {
+    const query = await createBoundShopQuery({ kdtId: Number(input.kdtId) }, command, 'shop-binding', {
+      onResponse: response => { responseBytes += response.responseBytes; },
+      transportOptions: { maxResponseBytes: () => responseLimit - responseBytes, shopApp: false }
+    });
+    return async body => {
+      try { return await query.read(schema.api.path, body, 'search'); }
+      catch (error) { throw adaptError(error, scope); }
+    };
+  } catch (error) { throw adaptError(error, scope); }
+}
+
+function adaptError(error, scope) {
+  if (!error.cliDetails) return reject('configuration', 'configuration', scope);
+  const { category, stage, requestState, ...details } = error.cliDetails;
+  const facts = {};
+  for (const name of ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']) {
+    if (details[name] !== undefined) facts[name] = details[name];
+  }
+  return reject(category, stage, scope, requestState, facts);
+}
+
+function customer(source) {
+  if (!object(source)) throw new Error('customer');
+  const result = {};
+  for (const [name, field] of Object.entries({ yzOpenId: 'yz_open_id', name: 'name', showName: 'show_name',
+    mobile: 'mobile', gender: 'gender', tradeCount: 'trade_count', points: 'points', isMobileAuthorized: 'is_mobile_auth' })) {
+    if (Object.hasOwn(source, field)) result[name] = source[field];
+  }
+  if (Object.hasOwn(source, 'is_member')) {
+    if (![0, 1].includes(source.is_member)) throw new Error('member');
+    result.isMember = source.is_member === 1;
+  }
+  for (const [name, field] of Object.entries({ createdAt: 'created_at', memberCreatedAt: 'created_member_at' })) {
+    if (!Object.hasOwn(source, field)) continue;
+    const seconds = source[field];
+    if (field === 'created_member_at' && seconds === 0) result[name] = 0;
+    else {
+      if (!Number.isSafeInteger(seconds) || seconds <= 0) throw new Error('timestamp');
+      result[name] = formatDateTime(seconds * 1000);
+    }
+  }
+  return result;
+}
+
+function adapt(data, input, facts = {}) {
+  try {
+    if (!object(data) || !Array.isArray(data.record_list) || data.record_list.length > input.pageSize) throw new Error('page');
+    for (const [name, value] of Object.entries({ page_no: input.pageNo, page_size: input.pageSize })) {
+      if (Object.hasOwn(data, name) && data[name] !== value) throw new Error('page mismatch');
+    }
+    const total = readTotal(data, 'total');
+    const count = data.record_list.length;
+    const position = (input.pageNo - 1) * input.pageSize + count;
+    if (total !== null && (count > 0 && total < position || count < input.pageSize && total > position)) {
+      throw new Error('total position');
+    }
+    const customers = data.record_list.map(customer);
+    const boundary = input.pageNo * input.pageSize;
+    const canContinue = input.pageNo < 500 && boundary + input.pageSize <= 10000;
+    const hasMore = total === null ? null : total <= boundary ? false : canContinue ? true : null;
+    const output = { data: { customers, pagination: { pageNo: input.pageNo, pageSize: input.pageSize,
+      ...(total === null ? {} : { total }), hasMore } } };
+    validateCommandValue(schema, 'output', output);
+    const seen = new Set();
+    output.data.customers = customers.filter(row => {
+      if (seen.has(row.yzOpenId)) return false;
+      seen.add(row.yzOpenId);
+      return true;
+    });
+    return output;
+  } catch { throw reject('protocol', 'output', { kdtId: input.kdtId }, 'sent', facts); }
+}
+
+function serialize(output, format, scope, limit = OUTPUT_LIMIT) {
+  const text = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${text}\n`, 'utf8') > limit) throw reject('limit', 'output', scope, 'sent');
+  return text;
+}
+
+module.exports = { reject, createQuery, adapt, serialize, bindingPath, RESPONSE_LIMIT, OUTPUT_LIMIT };