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

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

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 3,
+  "domain": "benefit",
+  "businessCommands": [
+    {
+      "path": "benefit.card-definition.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "benefit/card-definition/get/command.js",
+      "fingerprint": "2f2d6c59004d152c5630abc5c4dc12f250b654db2d1435bfdfbfe69461d71e1e"
+    },
+    {
+      "path": "benefit.card-definition.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "benefit/card-definition/list/command.js",
+      "fingerprint": "7ae054562f154e27f37ac58a06c547cde7ee3457c7382a1d3086d93e7976f4cd"
+    },
+    {
+      "path": "benefit.card-grant.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "benefit/card-grant/list/command.js",
+      "fingerprint": "fcdc6d6a0415449fc65bff2dd942e5332b87f3b87fac3372953c4ca4a421b1af"
+    },
+    {
+      "path": "benefit.customer-card.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "benefit/customer-card/get/command.js",
+      "fingerprint": "c13c8d29bea7cd4de36916cacb7d61ac7112f005e88189137d48e7f7332e5551"
+    },
+    {
+      "path": "benefit.customer-card.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "benefit/customer-card/list/command.js",
+      "fingerprint": "a2db429e8c0c2d46e8f74db4d1a8a6e862670cb5340038ac8946769d26c12b1e"
+    }
+  ]
+}

package/src/commands/native/benefit/customer-card/get/command.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const schema = require('./schema.json');
+const { normalizeTimes } = require('../../../../../execution/datetime');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { object } = require('../../../../../execution/query-api');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+
+const command = 'benefit.customer-card.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+const fields = {
+  card_alias: 'cardAlias', yz_open_id: 'yzOpenId', card_start_time: 'cardStartTime',
+  card_end_time: 'cardEndTime', card_name: 'cardName', take_card_time: 'takeCardTime',
+  activated_time: 'activatedTime', is_experience_card: 'isExperienceCard'
+};
+
+function buildInput(options, context) {
+  const scope = resolveTargetShop(options, context, command);
+  try {
+    const input = { ...scope, cardNo: options.cardNo.trim() };
+    validateCommandValue(schema, 'input', input);
+    return Object.freeze(input);
+  } catch { throw reject('parameter', 'input', scope); }
+}
+
+function project(envelope, input, facts) {
+  const invalid = () => reject('protocol', 'customer-card-get-model',
+    { kdtId: input.kdtId }, 'sent', facts);
+  const wrapped = Object.hasOwn(envelope, 'data');
+  if (wrapped && (!object(envelope.data) ||
+      Object.keys(fields).some(field => Object.hasOwn(envelope, field)))) throw invalid();
+  const payload = wrapped ? envelope.data : envelope;
+  const customerCard = { cardNo: input.cardNo };
+  for (const [source, target] of Object.entries(fields)) {
+    if (Object.hasOwn(payload, source)) customerCard[target] = payload[source];
+  }
+  const output = { data: { customerCard } };
+  try {
+    output.data.customerCard = normalizeTimes(customerCard,
+      schema.output.properties.data.properties.customerCard, schema.definitions);
+    validateCommandValue(schema, 'output', output);
+  }
+  catch { throw invalid(); }
+  return output;
+}
+
+async function execute(input, preview) {
+  const scope = { kdtId: input.kdtId };
+  const read = await createShopQuery(scope, command);
+  let response;
+  try {
+    response = await read(preview.path, preview.body, 'customer-card-get');
+  } catch (error) {
+    const details = error.cliDetails;
+    if (details?.category === 'business_rejected' && details.stage === 'customer-card-get' &&
+        details.api === schema.api.path &&
+        !Object.hasOwn(details, 'gatewayCode') &&
+        [141502105, 141502107, '141502105', '141502107'].includes(details.businessCode)) {
+      details.category = 'not_found';
+      error.message = '查询失败：not_found（customer-card-get）';
+    }
+    throw error;
+  }
+  return project(response.envelope, input, response.facts);
+}
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('根据卡号查询一张客户权益卡的关联信息和有效期')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .requiredOption('--card-no <no>', '必填：完整卡号字符串，保留前导零和长数字，不是卡定义 alias')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览主请求与店铺核验；不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.customerCard：cardNo、cardAlias、yzOpenId、cardStartTime、cardEndTime 为必需字段。
+cardName、takeCardTime、activatedTime、isExperienceCard 仅取得时返回；false 原样保留。
+时间点统一为北京时间 YYYY-MM-DD HH:mm:ss.SSS；空文本哨兵保留，不由时间合成 cardState。
+先核验凭证店铺 sid，再按卡号查询一次；最多两次请求，不重试、切店、换身份或遍历列表。
+只接受完整单层载荷；缺核心字段、错型或双层混合均整体失败，不输出部分结果。
+支持微商城单店、零售单店、连锁 D 总部/网店/合伙人；不承诺教育多校区总部。
+执行需有效四字段上下文及同店铺授权凭证；店铺核验不证明员工 OAuth 或跨店共享。
+没有上下文时，仅显式合法店铺配合 --dry-run 可预览；失败 stdout 为空，stderr 为安全错误 JSON。
+契约：zan-saas schema benefit.customer-card.get --format json
+示例：zan-saas benefit customer-card get --card-no 000337092113264760725
+预览：zan-saas benefit customer-card get --kdt-id 63077 --card-no 000337092113264760725 --dry-run`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const preview = {
+        method: 'POST', path: schema.api.path, body: { card_no: input.cardNo },
+        scope: { kdtId: input.kdtId },
+        prerequisites: [{ method: 'POST', path: bindingPath, body: {} }]
+      };
+      validateCommandValue(schema, 'preview', preview);
+      const result = options.dryRun ? preview : await execute(input, preview);
+      console.log(JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/benefit/customer-card/get/schema.json

@@ -0,0 +1,340 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "cardNo"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "cardNo": {
+        "$ref": "#/definitions/cardNo"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "customerCard"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "customerCard": {
+            "type": "object",
+            "required": [
+              "cardNo",
+              "cardAlias",
+              "yzOpenId",
+              "cardStartTime",
+              "cardEndTime"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "cardNo": {
+                "$ref": "#/definitions/cardNo",
+                "description": "成功查询的规范化输入卡号；不是响应回显的独立核验证据。"
+              },
+              "cardAlias": {
+                "type": "string",
+                "minLength": 1,
+                "description": "关联卡定义的别名。"
+              },
+              "yzOpenId": {
+                "type": "string",
+                "minLength": 1,
+                "description": "持卡客户的有赞用户标识，不是操作员工 ID。"
+              },
+              "cardStartTime": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "beijing-date-time-ms"
+                  },
+                  {
+                    "const": ""
+                  }
+                ],
+                "$comment": "upstream-time:text:empty",
+                "description": "实例有效期开始的源时间文本；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+              },
+              "cardEndTime": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "beijing-date-time-ms"
+                  },
+                  {
+                    "const": ""
+                  }
+                ],
+                "$comment": "upstream-time:text:empty",
+                "description": "实例有效期结束的源时间文本；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+              },
+              "cardName": {
+                "type": "string"
+              },
+              "takeCardTime": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "beijing-date-time-ms"
+                  },
+                  {
+                    "const": ""
+                  }
+                ],
+                "$comment": "upstream-time:text:empty",
+                "description": "领取时间；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+              },
+              "activatedTime": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "format": "beijing-date-time-ms"
+                  },
+                  {
+                    "const": ""
+                  }
+                ],
+                "$comment": "upstream-time:text:empty",
+                "description": "激活时间；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+              },
+              "isExperienceCard": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body",
+      "scope",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.customer.info.get/3.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "card_no"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "card_no": {
+            "$ref": "#/definitions/cardNo"
+          }
+        }
+      },
+      "scope": {
+        "type": "object",
+        "required": [
+          "kdtId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": {
+            "$ref": "#/definitions/shopId"
+          }
+        }
+      },
+      "prerequisites": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1,
+        "items": {
+          "type": "object",
+          "required": [
+            "method",
+            "path",
+            "body"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "const": "POST"
+            },
+            "path": {
+              "const": "youzan.shop.basic.get/3.0.0"
+            },
+            "body": {
+              "type": "object",
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "required": [
+      "success",
+      "code",
+      "message",
+      "details"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "success": {
+        "const": false
+      },
+      "code": {
+        "const": -10001
+      },
+      "message": {
+        "type": "string",
+        "minLength": 1
+      },
+      "details": {
+        "type": "object",
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "enum": [
+              "validation",
+              "configuration",
+              "parameter",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "not_found"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "validation",
+              "context",
+              "scope",
+              "input",
+              "configuration",
+              "shop-binding",
+              "customer-card-get",
+              "customer-card-get-model"
+            ]
+          },
+          "command": {
+            "const": "benefit.customer-card.get"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/shopId"
+              }
+            }
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string"
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "businessCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string"
+          },
+          "request_id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "cardNo": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![\\s\\S]*[\\u0000-\\u001f\\u007f-\\u009f])\\S(?:[\\s\\S]*\\S)?$",
+      "description": "去除首尾空白的完整卡号字符串，无控制字符；长数字和前导零无损，不转 number。"
+    }
+  },
+  "success": {
+    "description": "目标持卡实例及所有必需内容满足模型后成功；不接受空或混合层级载荷。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。 明确业务拒绝 141502105 或 141502107 为 not_found；矛盾信号、空或错型载荷为 protocol。"
+  },
+  "notes": [
+    "按完整卡号查询单张客户持卡实例，卡号按文本无损保留；不补查客户、权益卡定义或列表。",
+    "可选字段缺失保持省略，null 或错型失败；false 和字段显式允许的空文本保留。",
+    "不返回姓名、手机号、粉丝资料或 cardState；不按日期自行推算持卡状态。",
+    "支持微商城单店、零售单店、连锁 D 总部、网店及合伙人；不承诺教育多校区总部。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ],
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.customer.info.get/3.0.0"
+  }
+}

package/src/commands/native/benefit/customer-card/list/command.js

@@ -0,0 +1,102 @@
+'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 { parseIntegerOption, withInputScope } = 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 schema = require('./schema.json');
+const { normalizeTimes } = require('../../../../../execution/datetime');
+
+const command = 'benefit.customer-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 };
+  const invalid = () => reject('protocol', 'customer-card-list-model', scope, 'sent', facts);
+  if (!object(data) || !Array.isArray(data.items) || data.page !== input.pageNo ||
+      !Number.isSafeInteger(data.page_size) || data.page_size < 1 ||
+      !Number.isSafeInteger(data.page * data.page_size) ||
+      data.items.length > data.page_size) {
+    throw invalid();
+  }
+  try { readTotal(data, 'total'); } catch { throw invalid(); }
+  const seen = new Set();
+  const customerCards = data.items.map(row => {
+    if (!object(row) || seen.has(row.card_no)) throw invalid();
+    seen.add(row.card_no);
+    return {
+      cardNo: row.card_no, cardAlias: row.card_alias, cardState: row.card_state,
+      cardStartTime: row.card_start_time, cardEndTime: row.card_end_time
+    };
+  });
+  const output = { data: {
+    customerCards,
+    pagination: { pageNo: data.page, pageSize: data.page_size, returned: customerCards.length,
+      hasMore: null, nextPageNo: null, windowLimitReached: input.pageNo === Number.MAX_SAFE_INTEGER }
+  } };
+  try {
+    output.data.customerCards = normalizeTimes(customerCards,
+      { type: 'array', items: { $ref: '#/definitions/customerCard' } }, schema.definitions);
+    validateCommandValue(schema, 'output', output);
+  }
+  catch { throw invalid(); }
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('分页查询指定客户持有的权益卡、状态和有效期')
+    .allowExcessArguments(false)
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId；不是手机号或微信 openId')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--status <status>', 'available 查询可用范围；all 请求全部状态范围')
+      .choices(['available', 'all']).default('available'))
+    .option('--page-no <n>', '页码正安全整数，从 1 开始；容量以实际响应为准', '1')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验和持卡请求，不读凭证、不联网')
+    .addHelpText('after', `
+当前接口未提供可靠的匹配总数，因此省略 total，hasMore 为 null、nextPageNo 为 null，不自动续页。
+返回 data.customerCards 和 data.pagination；returned 为本次客户持卡条数。
+cardNo 是完整字符串实例号；cardAlias 仅关联定义，不按定义合并持卡。
+保留源 cardState；时间点统一为北京时间 YYYY-MM-DD HH:mm:ss.SSS，包括 9999 年永久哨兵。
+空页不证明耗尽；all 不保证删除历史完整或跨页快照。
+先核验凭证店铺，再查询一页持卡；最多两次请求，不重试或切换身份、店铺。
+支持微商城单店、零售单店、连锁 D 总部/网店/合伙人，不承诺教育多校区总部。
+真实执行需有效四字段上下文和同店授权凭证；店铺核验不证明员工 OAuth。
+契约：zan-saas schema benefit.customer-card.list
+示例：zan-saas benefit customer-card list --yz-open-id customer-a --status all --page-no 2
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      const input = withInputScope(scope, () => {
+        const value = { ...scope, yzOpenId: options.yzOpenId.trim(), status: options.status,
+          pageNo: parseIntegerOption(options.pageNo, schema, '/pageNo') };
+        validateCommandValue(schema, 'input', value);
+        return value;
+      });
+      const request = { method: 'POST', path: schema.api.path,
+        body: { params: { user: { account_id: input.yzOpenId, account_type: 5 },
+          page_no: input.pageNo, state: input.status === 'all' } } };
+      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, { transportOptions: { shopApp: false } });
+        const { data, facts } = await read(request.path, request.body, 'customer-card-list');
+        output = project(data, input, 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) };