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

package/src/commands/native/coupon/activity/list/command.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+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 { createShopQuery, failure, bindingPath } = require('../../shared/query');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { object } = require('../../../../../execution/query-api');
+const { parseDateTime } = require('../../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../../execution/range');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const schema = require('./schema.json');
+
+const command = 'coupon.activity.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function buildInput(options, scope) {
+  const input = { ...scope, form: options.form };
+  for (const field of ['stage', 'pageNo', 'pageSize', 'displayType']) {
+    if (options[field] === undefined) continue;
+    input[field] = parseIntegerOption(options[field], schema, `/${field}`);
+  }
+  if (options.keyword !== undefined) {
+    if (/[\u0000-\u001f\u007f-\u009f]/u.test(options.keyword)) throw inputIssue('/keyword', 'invalid_format', constraints(modelAt(schema, 'input', '/keyword')));
+    input.keyword = options.keyword.trim();
+  }
+  if (options.createdAt !== undefined) {
+    try {
+      input.createdAt = parseDateTimeRange(options.createdAt, { precision: 'milliseconds', strictOrder: true });
+    } catch {
+      throw inputIssue('/createdAt', 'invalid_format', {
+        format: '北京时间 YYYY-MM-DD HH:mm:ss[.SSS]..YYYY-MM-DD HH:mm:ss[.SSS]，可省略一端；开始须早于结束'
+      });
+    }
+  }
+  validateCommandValue(schema, 'input', input);
+  return input;
+}
+
+function requestBody(input) {
+  const body = { activity_type_group: input.form === 'card' ? 1 : 2,
+    time_line_status: input.stage, page_no: input.pageNo, page_size: input.pageSize };
+  for (const [field, upstream] of [['keyword', 'title_keyword'], ['displayType', 'activity_display_type']]) {
+    if (Object.hasOwn(input, field)) body[upstream] = input[field];
+  }
+  for (const [field, upstream] of [['start', 'create_begin_time'], ['end', 'create_end_time']]) {
+    if (input.createdAt?.[field] !== undefined) body[upstream] = parseDateTime(input.createdAt[field]);
+  }
+  return body;
+}
+
+function project(envelope, input, scope, facts) {
+  if (!Array.isArray(envelope.data)) throw new Error('Invalid activities');
+  const activities = envelope.data.map(row => {
+    if (!object(row) || !object(row.activity)) throw new Error('Invalid activity');
+    const activity = row.activity;
+    if (Number.isSafeInteger(activity.kdt_id) && activity.kdt_id > 0 && activity.kdt_id !== scope.kdtId) {
+      throw reject('scope_unresolved', 'response', scope, 'sent', facts);
+    }
+    const result = { activityId: activity.activity_id, ownerKdtId: activity.kdt_id,
+      title: activity.title, activityType: activity.activity_type, status: activity.status };
+    for (const [field, upstream] of [['alias', 'alias'], ['isDeleted', 'is_deleted']]) {
+      if (Object.hasOwn(activity, upstream)) result[field] = activity[upstream];
+    }
+    if (Object.hasOwn(row, 'preferential_copywriting')) result.offerText = row.preferential_copywriting;
+    if (Object.hasOwn(row, 'activity_budget')) {
+      if (!object(row.activity_budget)) throw new Error('Invalid budget');
+      result.budget = {};
+      for (const [field, upstream] of [
+        ['takenQty', 'taken_qty'], ['usedQty', 'used_qty'],
+        ['sendTotalQty', 'budget_send_total_qty'], ['useTotalQty', 'budget_use_total_qty'],
+        ['sendStockQty', 'send_stock_qty'], ['useStockQty', 'use_stock_qty']
+      ]) {
+        if (Object.hasOwn(row.activity_budget, upstream)) result.budget[field] = row.activity_budget[upstream];
+      }
+    }
+    return result;
+  });
+  const reportedPage = Object.hasOwn(envelope, 'page_no') ? envelope.page_no : envelope.page_num;
+  if (Object.hasOwn(envelope, 'page_num') && envelope.page_num !== reportedPage) {
+    throw new Error('Conflicting page numbers');
+  }
+  const emptySentinel = activities.length === 0 && envelope.total === 0 &&
+    reportedPage === 0 && envelope.page_size === 0;
+  const pageNo = emptySentinel ? input.pageNo : reportedPage;
+  const total = readTotal(envelope, 'total');
+  const pagination = { pageNo, pageSize: emptySentinel ? input.pageSize : envelope.page_size,
+    ...(total === null ? {} : { total }), returnedCount: activities.length, hasMore: null, nextPageNo: null };
+  const output = { data: { activities, pagination } };
+  validateCommandValue(schema, 'output', output);
+  const offset = (input.pageNo - 1) * input.pageSize;
+  if (pageNo !== input.pageNo || pagination.pageSize !== input.pageSize ||
+      activities.length > input.pageSize ||
+      (total !== null && ((activities.length > 0 && offset + activities.length > total) ||
+      (activities.length === 0 && offset < total)))) throw new Error('Invalid pagination');
+  pagination.hasMore = total === null ? null : input.pageNo * input.pageSize < total;
+  pagination.nextPageNo = pagination.hasMore === true && input.pageNo < 500 ? input.pageNo + 1 : null;
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('查询同店一页券发行活动摘要及已返回的预算计数')
+    .allowExcessArguments(false)
+    .addOption(new Option('--form <form>', '必填：card 优惠卡券；code 优惠码，分别分页')
+      .choices(['card', 'code']).makeOptionMandatory())
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId')
+    .option('--keyword <text>', '活动名称关键词，去除首尾空白后非空且无控制字符')
+    .option('--stage <n>', '0 全部；1 未开始；2 进行中；3 已结束；4 未结束', '0')
+    .option('--display-type <n>', '1 满减；2 折扣；3 随机金额；4 兑换；5 社区团购；6 通用码；7 一卡一码')
+    .option('--created-at <range>', '创建时间 START..END，可省略一端；北京时间 YYYY-MM-DD HH:mm:ss[.SSS]，两端齐备时开始早于结束')
+    .option('--page-no <n>', '页码，十进制整数 1..500；只读取指定单页', '1')
+    .option('--page-size <n>', '单页容量，十进制整数 1..20', '10')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览两个请求，不读取凭证、不联网')
+    .addHelpText('after', `
+返回 data.activities 和 data.pagination；预算是固定摘要，可选源字段缺失保持省略。
+创建区间必须包含 ..，省略边界不补值，不承诺端点包含性。
+活动不是客户实际持有的券；活动 ID 不等于持券 ID，状态不证明领取资格或订单可用。
+status：0 有效；1 已失效或审核失败，无法区分原因；2 审核中。未知整数保留，不当正常。
+hasMore 只按 total 判断；第500页仍有后续时为 true，但 nextPageNo=null，不能请求501页。
+保留店铺、分组和筛选继续下一页；收窄条件是新查询，不承诺无重无漏或跨页快照。
+真实执行需有效四字段上下文与同店凭证，先核验凭证店铺，再查询同归属店铺活动。
+每次最多2个请求，无自动重试、重定向、切店、翻页或详情补查；核验不证明员工 OAuth。
+不提供 --include、--timeout、--retry 或旧 flag 别名。缺少上下文仅可显式店铺本地预览。
+契约：zan-saas schema coupon.activity.list
+示例：zan-saas coupon activity list --form card
+示例：zan-saas coupon activity list --form code --kdt-id 63077 --page-no 2 --dry-run
+`)
+    .action(async options => {
+      let scope;
+      try { scope = resolveTargetShop(options, context, command); }
+      catch (error) {
+        if (error.cliDetails) error.cliDetails.stage = error.cliDetails.category === 'configuration' ? 'configuration' : 'input';
+        throw error;
+      }
+      let input;
+      try { input = withInputScope(scope, () => buildInput(options, scope)); }
+      catch (error) {
+        error.cliDetails = reject('validation', 'input', scope).cliDetails;
+        throw error;
+      }
+      const body = requestBody(input);
+      const preview = { scope, prerequisites: ['context', 'token-shop-binding'], requests: [
+        { method: 'POST', api: bindingPath, body: {} },
+        { method: 'POST', api: schema.api.path, body }
+      ] };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const { envelope, facts } = await read(schema.api.path, body, 'query');
+        try { output = project(envelope, input, scope, facts); }
+        catch (error) {
+          if (error.cliDetails) throw error;
+          throw reject('protocol', 'response', scope, 'sent', facts);
+        }
+      }
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };