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

package/src/commands/native/coupon/commands.index.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 3,
+  "domain": "coupon",
+  "businessCommands": [
+    {
+      "path": "coupon.activity.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "coupon/activity/get/command.js",
+      "fingerprint": "8eb9727bc232a48fe2b59ddffb8dd905e55504bba87887a5a73fdd8ebf7a064e"
+    },
+    {
+      "path": "coupon.activity.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "coupon/activity/list/command.js",
+      "fingerprint": "fb6320dced053084ee34b8b4952af462882334463cab76e038dd7b2cb7f7b24b"
+    },
+    {
+      "path": "coupon.voucher.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "coupon/voucher/get/command.js",
+      "fingerprint": "b4838c07ac5042f9a807954f2afc484ba1602b62141905446eef659b85bf08eb"
+    },
+    {
+      "path": "coupon.voucher.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "coupon/voucher/list/command.js",
+      "fingerprint": "d0a09a0443614d23ef3f2d52579e6430af86017d2dd5996428a8829895870c6d"
+    }
+  ]
+}

package/src/commands/native/coupon/domain.json

@@ -0,0 +1,3 @@
+{
+  "description": "优惠券：券发行活动与客户持券"
+}

package/src/commands/native/coupon/shared/query.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../execution/target-shop');
+const { createShopQuery, failure, bindingPath } = require('../../../../execution/shop-query');
+
+function resolveScope(options, context, command) {
+  try { return resolveTargetShop(options, context, command); }
+  catch (error) {
+    if (!error.cliDetails) throw error;
+    const { category, targetScope } = error.cliDetails;
+    throw failure(command, category, category === 'configuration' ? 'configuration' : 'input', targetScope);
+  }
+}
+
+module.exports = { resolveScope, createShopQuery, failure, bindingPath };

package/src/commands/native/coupon/voucher/get/command.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { resolveScope, createShopQuery, failure, bindingPath } = require('../../shared/query');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { object } = require('../../../../../execution/query-api');
+const { formatDateTime } = require('../../../../../execution/datetime');
+const schema = require('./schema.json');
+
+const command = 'coupon.voucher.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function timestamp(value) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error('Invalid milliseconds');
+  return formatDateTime(value);
+}
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = () => reject('protocol', 'response', scope, 'sent', facts);
+  if (!object(data) || !object(data.voucher_identity)) throw invalid();
+  const identity = data.voucher_identity;
+  if (identity.coupon_id !== input.voucherId ||
+      identity.coupon_type !== (input.form === 'card' ? 0 : 1)) throw invalid();
+  if (!Number.isSafeInteger(data.kdt_id) || data.kdt_id < 1) throw invalid();
+  if (data.kdt_id !== input.kdtId) {
+    throw reject('scope_unresolved', 'response', scope, 'sent', facts);
+  }
+  try {
+    if (data.valid_start_time > data.valid_end_time) throw invalid();
+    const voucher = {
+      voucherId: identity.coupon_id, form: input.form, ownerKdtId: data.kdt_id,
+      activityId: data.activity_id, status: data.status,
+      validity: { startAt: timestamp(data.valid_start_time), endAt: timestamp(data.valid_end_time) }
+    };
+    if (Object.hasOwn(data, 'send_at')) voucher.sentAt = timestamp(data.send_at);
+    if (Object.hasOwn(data, 'user_identity')) {
+      if (!object(data.user_identity)) throw invalid();
+      if (Object.hasOwn(data.user_identity, 'yz_open_id')) {
+        voucher.holder = { yzOpenId: data.user_identity.yz_open_id };
+      }
+    }
+    if (Object.hasOwn(data, 'used_order_no')) voucher.usage = { orderNo: data.used_order_no };
+    const output = { data: { voucher } };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch { throw invalid(); }
+}
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('根据持券 ID 和券形态查询一张客户持有的券')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .addOption(new Option('--form <form>', '必填：card 优惠卡券，code 优惠码；不猜测持券类型')
+      .choices(['card', 'code']).makeOptionMandatory())
+    .requiredOption('--voucher-id <id>', '必填：持券 ID，十进制正安全整数；不是活动 ID 或核销码')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId，非总部不可跨店')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验和主请求，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.voucher，身份由 form 与 voucherId 共同确定。状态 2 为已冻结；未来整数原样保留。
+默认返回已有 holder 开放 ID、usage 订单引用；源缺失时省略，状态 2/3 不强制补订单。
+有效期与发放时间为北京时间 YYYY-MM-DD HH:mm:ss.SSS，固定毫秒，不猜永久有效。
+不提供 --include，不输出手机号、核销码、面额或活动规则；订单引用不证明支付或交易完成。
+真实执行固定同店凭证，先核验店铺再查详情，最多两次请求；不重试、不切店、不补查。
+支持微商城单店、连锁 D 总部/网店/合伙人；零售单店不在本详情正式支持范围。
+同店核验不证明店铺员工 OAuth 或跨店授权，券状态不证明可用于某笔订单。
+指引：zan-saas skills read zan-saas-coupon references/voucher-get.md
+契约：zan-saas schema coupon.voucher.get
+示例：zan-saas coupon voucher get --form card --voucher-id 2001 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveScope(options, context, command);
+      let input;
+      try {
+        if (!/^[1-9]\d*$/.test(options.voucherId)) throw new Error('Invalid ID');
+        input = { ...scope, form: options.form, voucherId: Number(options.voucherId) };
+        validateCommandValue(schema, 'input', input);
+      } catch { throw reject('validation', 'input', scope); }
+      const body = { coupon_id: input.voucherId, coupon_type: input.form === 'card' ? 0 : 1 };
+      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);
+        let result;
+        try { result = await read(schema.api.path, body, 'query'); }
+        catch (error) {
+          const details = error.cliDetails;
+          if (details?.category === 'business_rejected' && details.gatewayCode === undefined &&
+              String(details.businessCode) === '161201044') details.category = 'not_found';
+          throw error;
+        }
+        output = project(result.data, input, result.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) };

package/src/commands/native/coupon/voucher/get/schema.json

@@ -0,0 +1,147 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "description": "argv 解析并从有效上下文补全后的业务输入，不是 CLI JSON 或上游请求体。",
+    "required": ["form", "voucherId", "kdtId"],
+    "additionalProperties": false,
+    "properties": {
+      "form": { "$ref": "#/definitions/form" },
+      "voucherId": { "$ref": "#/definitions/id", "description": "完整持券 ID，与 form 组成身份；不能用活动 ID、码号或核销码替代。" },
+      "kdtId": { "$ref": "#/definitions/id", "description": "目标店铺，省略选项时取有效 context.shopId；不表示已经获准访问。" }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": ["data"],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": ["voucher"],
+        "additionalProperties": false,
+        "properties": {
+          "voucher": {
+            "type": "object",
+            "required": ["voucherId", "form", "ownerKdtId", "activityId", "status", "validity"],
+            "additionalProperties": false,
+            "properties": {
+              "voucherId": { "$ref": "#/definitions/id", "description": "持券 ID，必须与输入一致。" },
+              "form": { "$ref": "#/definitions/form", "description": "持券形态，必须与输入一致。" },
+              "ownerKdtId": { "$ref": "#/definitions/id", "description": "持券归属店铺，必须等于目标店铺；不是发放店铺。" },
+              "activityId": { "$ref": "#/definitions/id", "description": "发行来源活动 ID；不是持券 ID，不补查当前活动规则。" },
+              "status": {
+                "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991,
+                "description": "1 正常，2 已冻结，3 已核销，4 不可用，5 已删除；未来安全整数原样保留，不当正常，也不证明订单可用。"
+              },
+              "validity": {
+                "type": "object", "required": ["startAt", "endAt"], "additionalProperties": false,
+                "description": "必需有效期，开始不晚于结束；未知、0 或 null 不能推导永久有效。",
+                "properties": {
+                  "startAt": { "$ref": "#/definitions/time", "description": "有效期开始，源为正安全整数毫秒。" },
+                  "endAt": { "$ref": "#/definitions/time", "description": "有效期结束，源为正安全整数毫秒。" }
+                }
+              },
+              "sentAt": { "$ref": "#/definitions/time", "description": "发放时间，源为正安全整数毫秒；源省略时省略，null 或错型失败。" },
+              "holder": {
+                "type": "object", "required": ["yzOpenId"], "additionalProperties": false,
+                "description": "同次响应已有的持有人开放 ID，源省略时整组省略，不说明没有持有人。",
+                "properties": {
+                  "yzOpenId": { "type": "string", "pattern": "\\S", "description": "客户开放 ID，非空文本；不是手机号、微信 openId 或操作员工 ID。" }
+                }
+              },
+              "usage": {
+                "type": "object", "required": ["orderNo"], "additionalProperties": false,
+                "description": "同次响应已有的订单关联；源省略时整组省略，即使状态为 2/3 也不补造，不说明从未使用。",
+                "properties": {
+                  "orderNo": { "type": "string", "pattern": "\\S", "description": "非空订单引用，不证明支付、交易完成或最终核销，不提供订单详情。" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "required": ["scope", "prerequisites", "requests"], "additionalProperties": false,
+    "properties": {
+      "scope": { "$ref": "#/definitions/scope" },
+      "prerequisites": { "type": "array", "items": { "type": "string" }, "const": ["context", "token-shop-binding"] },
+      "requests": {
+        "type": "array", "minItems": 2, "maxItems": 2,
+        "items": [
+          {
+            "type": "object", "required": ["method", "api", "body"], "additionalProperties": false,
+            "properties": {
+              "method": { "const": "POST" }, "api": { "const": "youzan.shop.basic.get/3.0.0" },
+              "body": { "type": "object", "additionalProperties": false, "maxProperties": 0 }
+            }
+          },
+          {
+            "type": "object", "required": ["method", "api", "body"], "additionalProperties": false,
+            "properties": {
+              "method": { "const": "POST" }, "api": { "const": "youzan.ump.voucher.query.detail/1.0.1" },
+              "body": {
+                "type": "object", "required": ["coupon_id", "coupon_type"], "additionalProperties": false,
+                "properties": {
+                  "coupon_id": { "$ref": "#/definitions/id" },
+                  "coupon_type": { "type": "integer", "enum": [0, 1], "description": "0 优惠卡券，1 优惠码；不是列表分组的 1/2。" }
+                }
+              }
+            }
+          }
+        ],
+        "additionalItems": false
+      }
+    }
+  },
+  "error": {
+    "type": "object", "required": ["success", "code", "message", "details"], "additionalProperties": false,
+    "properties": {
+      "success": { "const": false }, "code": { "const": -10001 },
+      "message": { "type": "string", "minLength": 1, "description": "本地安全错误，不回显上游自由文本。" },
+      "details": {
+        "type": "object",
+        "required": ["command", "category", "stage", "targetScope", "requestState", "nextStep"],
+        "additionalProperties": false,
+        "properties": {
+          "command": { "const": "coupon.voucher.get" },
+          "category": { "type": "string", "enum": ["parameter", "validation", "configuration", "authentication", "permission", "scope_unresolved", "transport", "http", "protocol", "business_rejected", "not_found"] },
+          "stage": { "type": "string", "enum": ["input", "configuration", "shop-binding", "query", "response"] },
+          "targetScope": { "type": "object", "additionalProperties": false, "properties": { "kdtId": { "$ref": "#/definitions/id" } } },
+          "requestState": { "type": "string", "enum": ["not_sent", "sent", "unknown"], "description": "当前失败阶段的请求事实，不等于整次调用次数。" },
+          "nextStep": { "type": "string", "minLength": 1 },
+          "api": { "type": "string", "minLength": 1 },
+          "httpStatus": { "type": "integer" },
+          "businessCode": { "$ref": "#/definitions/diagnosticCode" },
+          "gatewayCode": { "$ref": "#/definitions/diagnosticCode" },
+          "trace_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" },
+          "request_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "form": { "type": "string", "enum": ["card", "code"], "description": "card 优惠卡券，code 优惠码；不按数字外观猜测类型。" },
+    "time": { "type": "string", "format": "beijing-date-time-ms", "description": "北京时间 Asia/Shanghai，YYYY-MM-DD HH:mm:ss.SSS，固定三位毫秒。" },
+    "scope": { "type": "object", "required": ["kdtId"], "additionalProperties": false, "properties": { "kdtId": { "$ref": "#/definitions/id" } } },
+    "diagnosticCode": { "anyOf": [
+      { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+      { "type": "string", "pattern": "^-?\\d{1,12}$" }
+    ] }
+  },
+  "api": { "method": "POST", "path": "youzan.ump.voucher.query.detail/1.0.1" },
+  "success": { "description": "服务端确认成功，复合身份、归属店铺及整个固定投影均通过才输出一次 data；stderr 为空，退出 0。" },
+  "errors": { "description": "失败 stdout 为空，stderr 一份安全 JSON，退出 1。主查询明确凭证不存在时为 not_found，不扫描列表、不补查活动；其他业务码不按消息猜语义。" },
+  "notes": [
+    "无 include 或 selection。holder/usage 默认投影，源省略则省略，显式 null、空白文本或错型失败；不回显手机号、核销码和原始扩展。",
+    "本地预览零请求、不读 token；缺上下文仅可带显式合法 --kdt-id 预览，无效或冲突上下文仍拒绝。",
+    "真实调用最多同店凭证核验一次和主请求一次，两次使用固定基址与 token 快照；无自动重试、重定向、切店或补查。",
+    "真实执行需要 userId/hq/shopId/orgType 有效四字段上下文；非总部目标必须等于 shopId，总部不自动取得跨店访问权。",
+    "仅承诺凭证店铺与对象归属店铺一致；不以 send_kdt_id 代替 ownerKdtId，不承诺总部代查和连锁共享券。",
+    "主接口正式范围为微商城单店、有赞连锁 D 总部/网店/合伙人；零售单店未在详情正式支持范围列出，不继承列表范围。",
+    "应用凭证加本地 fixture 上下文不证明店铺员工身份授权与权限隔离；不提供订单可用性判断或任何业务写入。"
+  ]
+}

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

@@ -0,0 +1,155 @@
+'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, 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 { formatDateTime } = require('../../../../../execution/datetime');
+const schema = require('./schema.json');
+
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+
+const command = 'coupon.voucher.list';
+const maxPage = 2147483647;
+const positiveId = value => Number.isSafeInteger(value) && value > 0;
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function project(envelope, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = () => reject('protocol', 'voucher-list-model', scope, 'sent', facts);
+  const unresolved = () => reject('scope_unresolved', 'voucher-list-model', scope, 'sent', facts);
+  const { page_num: pageNo, page_size: pageSize, data } = envelope;
+  const total = readTotal(envelope, 'total', invalid);
+  if (pageNo !== input.pageNo ||
+      pageSize !== input.pageSize || !Array.isArray(data) || data.length > pageSize ||
+      (total !== null && ((data.length > 0 && (pageNo - 1) * pageSize + data.length > total) ||
+      (data.length === 0 && (pageNo - 1) * pageSize < total)))) {
+    throw invalid();
+  }
+  const vouchers = data.map(row => {
+    if (!object(row) || !object(row.voucher_identity) || !object(row.user_identity) ||
+        !positiveId(row.voucher_identity.coupon_id) || !positiveId(row.kdt_id) ||
+        !positiveId(row.activity_id) || typeof row.user_identity.yz_open_id !== 'string' ||
+        !row.user_identity.yz_open_id.trim() || !Number.isSafeInteger(row.status)) {
+      throw invalid();
+    }
+    const form = row.voucher_identity.coupon_type === 0 ? 'card' :
+      row.voucher_identity.coupon_type === 1 ? 'code' : null;
+    if (form === null || form !== input.form || row.kdt_id !== input.kdtId ||
+        row.user_identity.yz_open_id !== input.yzOpenId) throw unresolved();
+    if (!positiveId(row.valid_start_time) || !positiveId(row.valid_end_time) ||
+        row.valid_start_time > row.valid_end_time) throw invalid();
+    const voucher = {
+      voucherId: row.voucher_identity.coupon_id, form, ownerKdtId: row.kdt_id,
+      activityId: row.activity_id, yzOpenId: row.user_identity.yz_open_id, status: row.status
+    };
+    try {
+      voucher.validity = { startAt: formatDateTime(row.valid_start_time),
+        endAt: formatDateTime(row.valid_end_time) };
+      for (const field of ['title', 'description']) {
+        if (Object.hasOwn(row, field)) {
+          if (typeof row[field] !== 'string') throw invalid();
+          voucher[field] = row[field];
+        }
+      }
+      if (Object.hasOwn(row, 'send_at')) {
+        if (!positiveId(row.send_at)) throw invalid();
+        voucher.sentAt = formatDateTime(row.send_at);
+      }
+    } catch { throw invalid(); }
+    return voucher;
+  });
+  const hasMore = total === null ? null : pageNo * pageSize < total;
+  const output = { data: { vouchers, pagination: {
+    pageNo, pageSize, ...(total === null ? {} : { total }), returnedCount: data.length, hasMore,
+    nextPageNo: hasMore === true && pageNo < maxPage ? pageNo + 1 : null
+  } } };
+  try { validateCommandValue(schema, 'output', output); }
+  catch { throw invalid(); }
+  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())
+    .requiredOption('--yz-open-id <id>', '必填：客户有赞开放标识；不是手机号、微信 openId 或员工 ID')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId')
+    .option('--status <n>', '默认类别内筛选：0全部状态、1生效未使用且未过期、2已使用、3未使用已过期、4已使用或已过期', '0')
+    .option('--page-no <n>', '固定单页，完整十进制 1..2147483647', '1')
+    .option('--page-size <n>', '单页容量 1..200，默认 20', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验与单页请求，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.vouchers 和 data.pagination，页码、容量及 total 取精确根响应。
+筛选 status 0..4 不等于单券状态：1正常、2冻结、3已核销、4不可用、5已删除；未来整数保留。
+validity 和 sentAt 按上游毫秒转北京时间 YYYY-MM-DD HH:mm:ss.SSS，不按时间推算状态。
+hasMore 按 pageNo * pageSize < total；nextPageNo 在页码上限可能为 null，不保证跨页快照。
+无 include、活动筛选、自动翻页或详情补查；不返回面额、折扣、核销码、手机号及未知扩展。
+card 默认普通优惠券类别；不承诺完整覆盖三方券、兑换券、买赠券及运费抵扣券。
+code 仅为优惠码分组默认返回范围，不承诺所有码活动；status=0 只表示上述范围内全部使用状态。
+total 与空页仅描述该范围和筛选，不代表全部券资产，不证明从未领券、客户资格或订单可用性。
+固定同店凭证核验加一次主请求，最多两次应用请求，不重试、不切店或切换身份。
+需有效 userId/hq/shopId/orgType 上下文；店铺核验不证明员工 OAuth 授权。
+支持微商城单店、零售单店、连锁 D 总部/网店/合伙人，仅查凭证所属店铺。
+契约：zan-saas schema coupon.voucher.list
+指引：zan-saas skills read zan-saas-coupon references/voucher-list.md
+示例：zan-saas coupon voucher list --form card --yz-open-id customer-a --page-no 1
+`)
+    .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 {
+        if (/[\u0000-\u001f\u007f-\u009f]/.test(options.yzOpenId)) {
+          throw inputIssue('/yzOpenId', 'invalid_format', constraints(modelAt(schema, 'input', '/yzOpenId')));
+        }
+        input = { ...scope, form: options.form, yzOpenId: options.yzOpenId.trim(),
+          status: parseIntegerOption(options.status, schema, '/status'),
+          pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo'),
+          pageSize: parseIntegerOption(options.pageSize, schema, '/pageSize') };
+        validateCommandValue(schema, 'input', input);
+      } catch (error) { error.inputScope = scope; throw error; }
+      const request = { method: 'POST', path: schema.api.path, body: {
+        activity_type_group: input.form === 'card' ? 1 : 2, yz_open_id: input.yzOpenId,
+        status: input.status, page_num: input.pageNo, page_size: input.pageSize
+      } };
+      const preview = { scope, prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [request] };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        let result;
+        try { result = await read(request.path, request.body, 'voucher-list'); }
+        catch (error) {
+          if (error.cliDetails?.category === 'business_rejected' &&
+              String(error.cliDetails.businessCode ?? error.cliDetails.gatewayCode) === '161201523') {
+            const facts = Object.fromEntries(['api', 'httpStatus', 'businessCode', 'gatewayCode',
+              'trace_id', 'request_id'].filter(key => Object.hasOwn(error.cliDetails, key))
+              .map(key => [key, error.cliDetails[key]]));
+            throw reject('not_found', 'voucher-list', scope, 'sent', facts);
+          }
+          throw error;
+        }
+        output = project(result.envelope, input, result.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), project };