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

package/src/commands/native/valuecard/card/list/command.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, parseIntegerOption, withInputScope, constraints, modelAt } = require('../../../../../execution/error-details');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+const { object } = require('../../../../../execution/query-api');
+const { parseInclude, projectCardType, projectBalance, projectTemplate } = require('../../shared/projection');
+const { projectPagination } = require('./pagination');
+const schema = require('./schema.json');
+
+const command = 'valuecard.card.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  try {
+    if (!object(data)) throw new TypeError('Invalid card list');
+    const pagination = projectPagination(data.paginator, data.items, input);
+    const cardNumbers = new Set();
+    const cards = data.items.map(item => {
+      if (!object(item) || typeof item.card_no !== 'string' || !item.card_no.trim()
+        || cardNumbers.has(item.card_no) || typeof item.card_status !== 'string' || !item.card_status.trim()) {
+        throw new TypeError('Invalid card identity');
+      }
+      cardNumbers.add(item.card_no);
+      const card = {
+        cardNo: item.card_no,
+        cardType: projectCardType(item.card_sub_type, 'card_sub_type'),
+        cardStatus: item.card_status,
+        balance: projectBalance(item)
+      };
+      if (!input.statuses.includes(card.cardStatus)) throw new RangeError('Card status outside requested scope');
+      if (Object.hasOwn(item, 'biz_card_status')) card.bizCardStatus = item.biz_card_status;
+      if (input.include.includes('template')) card.template = projectTemplate(item);
+      return card;
+    });
+    const output = { data: { cards, pagination } };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch (error) {
+    throw reject(error instanceof RangeError ? 'scope_unresolved' : 'protocol',
+      'cards-model', scope, 'sent', facts);
+  }
+}
+
+function body(input) {
+  return { yz_open_id: input.yzOpenId, card_status_list: input.statuses, page: input.pageNo, page_size: input.pageSize };
+}
+
+async function execute(input) {
+  const scope = { kdtId: input.kdtId };
+  const read = await createShopQuery(scope, command);
+  let response;
+  try {
+    response = await read(schema.api.path, body(input), 'cards');
+  } catch (error) {
+    const details = error.cliDetails;
+    if (details?.category === 'business_rejected' && details.stage === 'cards'
+      && details.api === schema.api.path && !Object.hasOwn(details, 'gatewayCode')
+      && [118703002, '118703002'].includes(details.businessCode)) {
+      throw reject('not_found', 'cards', scope, 'sent', {
+        api: details.api, httpStatus: details.httpStatus, businessCode: details.businessCode,
+        ...(details.trace_id && { trace_id: details.trace_id }),
+        ...(details.request_id && { request_id: details.request_id })
+      });
+    }
+    throw error;
+  }
+  return project(response.data, input, response.facts);
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter', optionPaths: { '/statuses': 'status' } })
+    .description('分页查询指定客户持有的储值卡及每张卡的状态和余额')
+    .allowExcessArguments(false)
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId；不是手机号、员工 ID 或微信 openId')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId，非总部不可跨店')
+    .option('--status <statuses>', '状态 CSV：normal正常、init未激活、freeze冻结、close注销、receding退卡中、receded已退卡', 'normal')
+    .option('--page-no <n>', '页码 1..200；每次只读一页', '1')
+    .option('--page-size <n>', '每页容量 1..50，默认 20', '20')
+    .option('--include <modules>', '仅支持 template；本地追加模板关联，不新增请求')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地脱敏预览；不读凭证、不联网、不回显客户 ID')
+    .addHelpText('after', `
+total 只描述本次筛选的接口总数，不保证跨页快照；按 nextPageNo 继续并保留店铺、筛选和容量。
+nextPageNo=null 不能单独解释为结束；windowLimitReached=true 表示达到页码上限，仍有后续。
+输出固定为 data.cards 和 data.pagination；同模板多张卡仍逐张返回。
+默认仅查询 normal，其他状态显式 CSV；不接受 all、cmpfrz 或卡种筛选。
+cardType 为 balance 或 gift；cardStatus 与可选 bizCardStatus 分别保留，不推算支付资格。
+balance 含 totalBalance、principalBalance、bonusBalance，为元两位字符串，不表示客户总额。
+--include template 仅本地投影 templateNo 与可选 templateName，不表示完整模板详情。
+分页保留实际容量，hasMore 由 pageNo * pageSize < total 计算；空页或短页不代表取完。
+第 200 页仍可能 hasMore=true，本入口不可访问第 201 页；不自动翻页、过滤或逐卡补查。
+先以同凭证核验店铺 sid，再查一页；最多两次只读请求，不重试、切店或换身份。
+真实调用需有效四字段上下文及同店凭证；at: all 不证明员工 OAuth 或跨机构权限。
+接口支持微商城单店、零售单店、连锁 D 总部及连锁 L 总部高级版，不承诺分店或合伙人直接调用。
+不返回手机号、持有人、创建时间或有效期；无卡不代表客户不存在，不汇总客户资产。
+缺少上下文仅显式合法目标可 dry-run；失败 stdout 为空，stderr 为脱敏错误 JSON。
+契约：zan-saas schema valuecard.card.list
+示例：zan-saas valuecard card list --yz-open-id customer-1 --status normal,freeze --include template --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      const input = withInputScope(scope, () => {
+        if (/[\u0000-\u001f\u007f-\u009f]/u.test(options.yzOpenId)) throw inputIssue('/yzOpenId', 'invalid_format', constraints(modelAt(schema, 'input', '/yzOpenId')));
+        let include;
+        try { include = parseInclude(options.include); }
+        catch { throw inputIssue('/include', 'invalid_choice', { items: { enum: ['template'] }, maxItems: 1 }); }
+        const input = {
+          ...scope, yzOpenId: options.yzOpenId.trim(), statuses: options.status.split(',').map(status => status.trim()),
+          pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo'),
+          pageSize: parseIntegerOption(options.pageSize, schema, '/pageSize'), include
+        };
+        validateCommandValue(schema, 'input', input);
+        return input;
+      });
+      const preview = {
+        scope,
+        prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [{ method: 'POST', path: schema.api.path, body: { ...body(input), yz_open_id: '<redacted>' } }],
+        selection: input.include
+      };
+      validateCommandValue(schema, 'preview', preview);
+      const output = options.dryRun ? preview : await execute(input);
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/valuecard/card/list/pagination.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+function projectPagination(paginator, items, { pageNo, pageSize }) {
+  const invalid = () => new TypeError('Invalid valuecard card list pagination');
+  if (!Number.isSafeInteger(pageNo) || pageNo < 1 || pageNo > 200
+    || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 50
+    || paginator === null || typeof paginator !== 'object' || Array.isArray(paginator)
+    || !Array.isArray(items)) throw invalid();
+
+  const { page, page_size: actualPageSize } = paginator;
+  const total = readTotal(paginator, 'total_count', invalid);
+  if (!Number.isSafeInteger(page) || page !== pageNo
+    || !Number.isSafeInteger(actualPageSize) || actualPageSize < 1 || actualPageSize > pageSize
+    || items.length > actualPageSize || (total !== null && items.length > total)) throw invalid();
+
+  const hasMore = total === null ? null : page * actualPageSize < total;
+  return { pageNo: page, pageSize: actualPageSize, ...(total === null ? {} : { total }), hasMore,
+    nextPageNo: hasMore === true && page < 200 ? page + 1 : null, windowLimitReached: hasMore !== false && page === 200 };
+}
+
+module.exports = { projectPagination };