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

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

@@ -0,0 +1,80 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { buildInput, reject } = require('../../shared/search-input');
+const { preview, scan, serialize } = require('./scan');
+const schema = require('./schema.json');
+
+function createCommand({ context } = {}) {
+  const instance = new Command('scan')
+    .description('在显式成为客户时间及数量、请求预算内串行跨页观察客户')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('validation', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数ID文本；省略时使用当前上下文店铺')
+    .requiredOption('--created <start..end>', '必填：成为客户的北京时间完整范围，严格开始早于结束，最多366天')
+    .option('--keyword <text>', '姓名、手机号或昵称模糊搜索，非空且最多200字符，与mobile互斥')
+    .option('--mobile <text>', '单个精确手机号，可选+及5至20位数字，保留前导零；不接受CSV')
+    .option('--is-member <boolean>', 'true=会员，false=非会员；省略不筛选')
+    .option('--tag-ids <ids>', '1至50项标签定义ID，CSV或JSON字符串数组，固定全部满足')
+    .option('--member-created <start..end>', '成为会员的北京时间范围，可单边，不证明当前仍是会员')
+    .option('--last-trade <start..end>', '最后购买的北京时间范围，可单边，不是任意窗口购买或未下单')
+    .option('--trade-count <range>', '历史购次非负32位整数范围，不保证全渠道口径')
+    .option('--trade-amount <range>', '历史累计消费人民币元文本范围，最多两位小数，精确转分，不是净收入')
+    .option('--points <range>', '搜索积分非负安全整数范围，不读取流水')
+    .option('--stored-balance <range>', '搜索储值余额人民币元范围，不等于逐卡可支付余额或全部资产')
+    .option('--level-ids <ids>', '会员等级定义level_id，1至50项，不能用alias或等级值，不推定多值AND/OR')
+    .option('--has-level <boolean>', 'true=有等级，false=无等级；false与level-ids冲突')
+    .option('--benefit-card-ids <ids>', '权益卡定义cardId，1至50项，不能用cardAlias或cardNo，不推定多值AND/OR')
+    .option('--has-benefit-card <boolean>', 'true=有本搜索API会员卡，false=无卡；false与卡ID冲突，不证明卡有效')
+    .option('--max-items <n>', '去重客户预算1至2000，默认200，可裁切末页', '200')
+    .option('--max-requests <n>', '业务请求预算2至200，默认20，含绑定、窗口观察和翻页', '20')
+    .addOption(new Option('--format <format>', 'json或pretty，只改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '零认证零请求本地预览，mobile与keyword遮盖为***')
+    .addHelpText('after', `
+范围语法 LOW..HIGH、LOW..、..HIGH；数值裸值传相同双边，时间必须含..。
+时间输入北京时间 YYYY-MM-DD HH:mm:ss[.SSS]，输出固定三位毫秒；秒接口只接受零毫秒。
+时间限Unix秒0至4102444800。范围不补当前时间或0，空范围、空白、负数、指数均拒绝。
+金额元文本精确转分，分值及积分上限9007199254740991。ID均为正安全整数文本。
+所有标量选项不得重复。标签固定AND；has=false加相应定义ID零请求拒绝，不自动补true。
+固定服务端创建时间降序、每页50、并发1，不承诺跨窗口全局排序。
+按yzOpenId保留首次记录，不按手机号合并；缺失明细省略，null或错型整体失败。
+摘要包括身份、展示名、手机、性别、会员标记、购次、积分及创建时间，不读取详情代验筛选。
+createdAt源0无效；memberCreatedAt允许数字0，不能据此推断会员身份。
+pagination包含traversalCompleted、stopReason、requestCount、duplicatesRemoved。
+pages_exhausted仅表示本轮叶窗遍历结束，不是快照、无遗漏或全店完整历史导出证明。
+其它停止原因max_items、max_requests、window_limit、total_unknown、inconsistent_page均不完整。
+父窗越10000时严格缩小重叠1秒子窗，新窗先读；预算包含父窗观察，绝不发超窗口页。
+每请求10秒，累计业务响应10MiB，最终含换行输出5MiB；任何后页失败整体失败，不输出前批。
+无恢复游标、后台导出、来源渠道、phones/lookup、include或sort，不自动重试、初始化应用或换身份。
+真实调用需有效四字段上下文与公共认证；非总部显式目标须等于shopId，总部仍须同店绑定及服务端授权。
+缺上下文仅可显式目标本地预览，预览不证明授权。应用测试身份不证明店铺员工权限隔离。
+完整闭合输入、摘要及错误模型见 zan-saas schema customer.customer.scan。
+
+示例：
+  zan-saas customer customer scan --kdt-id 63077 --created "2026-10-01 00:00:00..2026-10-02 00:00:00" --points "100..500" --max-requests 2 --dry-run
+  zan-saas customer customer scan --kdt-id 63077 --created "2026-10-01 00:00:00..2026-10-02 00:00:00" --mobile +8613800000000 --has-level false
+`);
+  const supplied = new Set();
+  for (const option of instance.options) {
+    instance.on(`option:${option.name()}`, () => {
+      if (supplied.has(option.name())) throw reject('validation', 'input');
+      supplied.add(option.name());
+    });
+  }
+  return instance.action(async options => {
+    const input = buildInput(options, context);
+    validateCommandValue(schema, 'input', input);
+    const result = options.dryRun ? preview(input) : await scan(input);
+    try { validateCommandValue(schema, options.dryRun ? 'preview' : 'output', result); }
+    catch { throw reject('protocol', 'output', { kdtId: input.kdtId }, options.dryRun ? 'not_sent' : 'sent'); }
+    process.stdout.write(serialize(result, options.format === 'pretty', { kdtId: input.kdtId }, options.dryRun ? 'not_sent' : 'sent'));
+  });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/customer/customer/scan/scan.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const { createBoundShopQuery, bindingPath } = require('../../../../../execution/shop-query');
+const { parseDateTime } = require('../../../../../execution/datetime');
+const { bodyFor, reject, adaptError, searchPath, command } = require('../../shared/search-input');
+const { projectPage } = require('../../shared/search-page');
+
+const responseLimit = 10 * 1024 * 1024;
+const outputLimit = 5 * 1024 * 1024;
+
+function preview(input) {
+  const body = bodyFor(input.filters);
+  for (const key of ['mobile', 'keyword']) if (Object.hasOwn(body, key)) body[key] = '***';
+  return {
+    requests: [{ method: 'POST', path: bindingPath, body: {} }, { method: 'POST', path: searchPath, body }],
+    strategy: { kind: 'bounded-created-time-scan', ...input.limits,
+      pageSize: 50, concurrency: 1, dynamicRequests: true }
+  };
+}
+
+async function scan(input) {
+  const scope = { kdtId: input.kdtId };
+  let requestCount = 0, responseBytes = 0, duplicatesRemoved = 0;
+  const customers = [], seenIds = new Set();
+  const originalWindow = { start: parseDateTime(input.filters.created.start) / 1000,
+    end: parseDateTime(input.filters.created.end) / 1000 };
+  const pendingWindows = [{ ...originalWindow }];
+  const finish = stopReason => ({ data: { customers, pagination: {
+    traversalCompleted: stopReason === 'pages_exhausted', stopReason, requestCount, duplicatesRemoved
+  } } });
+  let read;
+  try {
+    ({ read } = await createBoundShopQuery({ kdtId: Number(input.kdtId) }, command, 'shop-binding', {
+      onResponse(response) { responseBytes += response.responseBytes; },
+      transportOptions: { shopApp: false, timeoutMs: 10000,
+        maxResponseBytes: () => responseLimit - responseBytes,
+        onRequest() {
+          if (requestCount >= input.limits.maxRequests) throw reject('limit', 'scan', scope);
+          requestCount += 1;
+        }
+      }
+    }));
+  } catch (error) { throw adaptError(error, scope); }
+  while (pendingWindows.length) {
+    const window = pendingWindows.pop();
+    let pageNo = 1, previousIds;
+    while (true) {
+      if (requestCount >= input.limits.maxRequests) return finish('max_requests');
+      let response;
+      try { response = await read(searchPath, bodyFor(input.filters, window, pageNo), 'search'); }
+      catch (error) { throw adaptError(error, scope); }
+      const page = projectPage(response.data, pageNo, originalWindow, scope, response.facts);
+      let undelivered = false;
+      for (const customer of page.customers) {
+        if (seenIds.has(customer.yzOpenId)) duplicatesRemoved += 1;
+        else if (customers.length === input.limits.maxItems) undelivered = true;
+        else { seenIds.add(customer.yzOpenId); customers.push(customer); }
+      }
+      const ids = page.customers.map(customer => customer.yzOpenId);
+      const exceedsWindow = page.total > 10000;
+      const leafDone = page.total !== undefined && !exceedsWindow && pageNo * 50 >= page.total;
+      const shortPage = page.customers.length < 50;
+      if (!exceedsWindow && page.total !== undefined && shortPage &&
+          (pageNo - 1) * 50 + page.customers.length < page.total) return finish('inconsistent_page');
+      if (!exceedsWindow && !leafDone && previousIds && JSON.stringify(ids) === JSON.stringify(previousIds)) {
+        return finish('inconsistent_page');
+      }
+      if (page.total === undefined && shortPage) return finish('total_unknown');
+      if (undelivered) return finish('max_items');
+      if (leafDone && pendingWindows.length === 0) return finish('pages_exhausted');
+      if (customers.length === input.limits.maxItems) return finish('max_items');
+      if (leafDone) break;
+      if (exceedsWindow || (pageNo + 1) * 50 > 10000) {
+        if (window.end - window.start < 3) return finish('window_limit');
+        const middle = Math.floor((window.start + window.end) / 2);
+        pendingWindows.push({ start: window.start, end: middle + 1 }, { start: middle, end: window.end });
+        break;
+      }
+      previousIds = ids;
+      pageNo += 1;
+    }
+  }
+  return finish('pages_exhausted');
+}
+
+function serialize(output, pretty, scope, state = 'sent') {
+  const json = JSON.stringify(output, null, pretty ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`) > outputLimit) throw reject('limit', 'output', scope, state);
+  return `${json}\n`;
+}
+
+module.exports = { preview, scan, serialize };

package/src/commands/native/customer/customer/scan/schema.json

@@ -0,0 +1,211 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object", "additionalProperties": false, "required": ["kdtId", "filters", "limits"],
+    "description": "规范化业务输入，不是argv；范围表达式在CLI层解析，不把表达式原文传给接口。",
+    "properties": {
+      "kdtId": { "$ref": "#/definitions/id", "description": "目标查询店铺；省略 --kdt-id 时取当前上下文 shopId，显式非法值不回退；非总部须等于上下文 shopId，总部不自动遍历分店。" },
+      "filters": {
+        "type": "object", "additionalProperties": false, "required": ["created"],
+        "properties": {
+          "keyword": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(?:[\\s\\S]*\\S)?$", "description": "姓名、手机号或昵称模糊搜索，与mobile互斥。" },
+          "mobile": { "type": "string", "pattern": "^\\+?\\d{5,20}$", "description": "单值精确手机号文本，保留前导零和加号，不支持CSV或数组。" },
+          "isMember": { "type": "boolean", "description": "true=会员，false=非会员；省略不筛选，不从卡或等级推算。" },
+          "tagIds": { "$ref": "#/definitions/ids", "description": "标签定义ID，固定全部满足AND，首现去重。" },
+          "created": { "$ref": "#/definitions/createdRange" },
+          "memberCreated": { "$ref": "#/definitions/timeRange", "description": "成为会员时间范围，不证明当前仍是会员。" },
+          "lastTrade": { "$ref": "#/definitions/timeRange", "description": "最后购买时间，不是任意窗口内购买或未下单。" },
+          "tradeCount": { "$ref": "#/definitions/countRange", "description": "搜索服务历史购次，不保证全渠道口径。" },
+          "tradeAmount": { "$ref": "#/definitions/moneyRange", "description": "历史累计消费人民币元文本，不是净收入。" },
+          "points": { "$ref": "#/definitions/integerRange", "description": "搜索积分非负范围，不读取流水。" },
+          "storedBalance": { "$ref": "#/definitions/moneyRange", "description": "搜索储值余额人民币元文本，不等于逐卡可支付余额或全部资产。" },
+          "levelIds": { "$ref": "#/definitions/ids", "description": "会员等级定义level_id，不接受alias、等级值或客户ID；不推定多值AND/OR。" },
+          "hasLevel": { "type": "boolean", "description": "true=有等级，false=无等级；false与非空levelIds冲突，不自动补true。" },
+          "benefitCardIds": { "$ref": "#/definitions/ids", "description": "权益卡定义cardId，可由benefit card-definition list取得，不接受cardAlias、cardNo或储值卡号；不推定多值AND/OR。" },
+          "hasBenefitCard": { "type": "boolean", "description": "true=有搜索API会员卡，false=无卡；false与卡定义ID冲突，不证明卡当前有效。" }
+        },
+        "allOf": [
+          { "not": { "properties": { "keyword": { "type": "string" }, "mobile": { "type": "string" } }, "required": ["keyword", "mobile"] } },
+          { "not": { "required": ["hasLevel", "levelIds"], "properties": { "hasLevel": { "const": false }, "levelIds": { "$ref": "#/definitions/ids" } } } },
+          { "not": { "required": ["hasBenefitCard", "benefitCardIds"], "properties": { "hasBenefitCard": { "const": false }, "benefitCardIds": { "$ref": "#/definitions/ids" } } } }
+        ]
+      },
+      "limits": {
+        "type": "object", "additionalProperties": false, "required": ["maxItems", "maxRequests"],
+        "properties": {
+          "maxItems": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 200, "description": "去重客户预算，可截取已完整校验的末页；未交付新客户必须标记max_items。" },
+          "maxRequests": { "type": "integer", "minimum": 2, "maximum": 200, "default": 20, "description": "总业务请求预算，含绑定、窗口观察及翻页，不含公共认证。" }
+        }
+      }
+    }
+  },
+  "output": {
+    "type": "object", "additionalProperties": false, "required": ["data"],
+    "properties": {
+      "data": {
+        "type": "object", "additionalProperties": false, "required": ["customers", "pagination"],
+        "properties": {
+          "customers": { "type": "array", "maxItems": 2000, "items": { "$ref": "#/definitions/customer" }, "description": "按实际请求观察顺序保留首次yzOpenId，不按手机号合并，不承诺跨窗口全局排序。" },
+          "pagination": {
+            "type": "object", "additionalProperties": false,
+            "required": ["traversalCompleted", "stopReason", "requestCount", "duplicatesRemoved"],
+            "properties": {
+              "traversalCompleted": { "type": "boolean", "description": "仅pages_exhausted为true，只表示本轮计划叶窗遍历结束，不证明快照、无遗漏或完整历史导出。" },
+              "stopReason": {
+                "type": "string", "enum": ["pages_exhausted", "max_items", "max_requests", "window_limit", "total_unknown", "inconsistent_page"],
+                "description": "pages_exhausted=当次有效总数下所有叶窗读完；max_items=仍有工作或本页未交付新客户而达到数量预算；max_requests=下一业务请求超过预算；window_limit=最小时间桶仍需拆窗但无法严格缩小；total_unknown=未知总数的短页或空页；inconsistent_page=非越窗页的已知总数前提前短页，或同叶连续页主键序列相同且仍有工作。非越窗页指total已知且total<=10000；越窗页指total>10000。越窗观察页即使短页也不因此判为inconsistent_page，保留合法客户，预算允许且时间桶可严格缩小时继续拆窗。协议失败优先且整体失败；非越窗提前短页、同叶停滞及未知总数短页优先于预算。越窗观察后的优先级为max_items、window_limit、max_requests，分别对应数量预算已满或本页仍有未交付新客户、无法严格缩小的必要拆窗、下一业务请求超预算。仅所有叶窗完成且没有未交付新客户时，pages_exhausted优先于恰好耗尽的预算。"
+              },
+              "requestCount": { "type": "integer", "minimum": 2, "maximum": 200, "description": "实际已发送业务API请求数，含绑定与父窗观察。" },
+              "duplicatesRemoved": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "已交付yzOpenId后续重复记录数，不覆盖首条或暗示内容相同。" }
+            },
+            "allOf": [{ "if": { "properties": { "stopReason": { "const": "pages_exhausted" } } }, "then": { "properties": { "traversalCompleted": { "const": true } } }, "else": { "properties": { "traversalCompleted": { "const": false } } } }]
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "additionalProperties": false, "required": ["requests", "strategy"],
+    "properties": {
+      "requests": {
+        "type": "array", "minItems": 2, "maxItems": 2,
+        "items": { "oneOf": [{ "$ref": "#/definitions/bindingRequest" }, { "$ref": "#/definitions/searchRequest" }] },
+        "description": "依次为同店绑定和原始创建窗口第一页；后续窗口由真实响应决定，不探测总数。"
+      },
+      "strategy": {
+        "type": "object", "additionalProperties": false,
+        "required": ["kind", "maxItems", "maxRequests", "pageSize", "concurrency", "dynamicRequests"],
+        "properties": {
+          "kind": { "type": "string", "const": "bounded-created-time-scan", "description": "创建时间有界扫描。" },
+          "maxItems": { "type": "integer", "minimum": 1, "maximum": 2000, "description": "本次用户结果预算。" },
+          "maxRequests": { "type": "integer", "minimum": 2, "maximum": 200, "description": "本次用户业务请求预算。" },
+          "pageSize": { "type": "integer", "const": 50, "description": "固定页容量。" },
+          "concurrency": { "type": "integer", "const": 1, "description": "固定串行读取。" },
+          "dynamicRequests": { "type": "boolean", "const": true, "description": "后续请求需看真实响应。" }
+        }
+      }
+    }
+  },
+  "error": {
+    "type": "object", "additionalProperties": false, "required": ["success", "code", "message", "details"],
+    "properties": {
+      "success": { "type": "boolean", "const": false },
+      "code": { "type": "integer", "const": -10001 },
+      "message": { "type": "string", "minLength": 1, "description": "受控说明，不回显客户条件、token或上游自由消息。" },
+      "details": {
+        "type": "object", "additionalProperties": false,
+        "required": ["category", "stage", "command", "targetScope", "requestState", "nextStep"],
+        "properties": {
+          "category": { "type": "string", "enum": ["validation", "configuration", "authentication", "permission", "scope_unresolved", "http", "business_rejected", "transport", "protocol", "limit"], "description": "validation=本地输入非法；configuration=公共配置不可用；authentication=认证失败；permission=明确权限拒绝；scope_unresolved=范围未确认；http=HTTP拒绝；business_rejected=业务拒绝；transport=传输失败；protocol=模型不符；limit=字节或固定资源超限。" },
+          "stage": { "type": "string", "enum": ["input", "context", "configuration", "shop-binding", "search", "scan", "output"], "description": "input=输入；context=上下文；configuration=公共环境；shop-binding=店铺绑定；search=搜索；scan=遍历；output=输出组装。" },
+          "command": { "type": "string", "const": "customer.customer.scan" },
+          "targetScope": { "type": "object", "additionalProperties": false, "properties": { "kdtId": { "$ref": "#/definitions/id" } }, "description": "仅保留已本地校验的目标店铺，否则空对象；不回显客户条件。" },
+          "requestState": { "type": "string", "enum": ["not_sent", "sent", "unknown"], "description": "not_sent=相关请求未发送；sent=收到响应但不代表业务成功；unknown=已发送但结果不明。" },
+          "nextStep": { "type": "string", "minLength": 1, "description": "核对原目标、输入及授权，不自动重试或变更查询模式，前批结果不构成成功。" },
+          "api": { "type": "string", "enum": ["youzan.shop.basic.get/3.0.0", "youzan.scrm.customer.list/1.0.0"], "description": "实际失败API。" },
+          "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 },
+          "businessCode": { "$ref": "#/definitions/diagnosticCode" },
+          "gatewayCode": { "$ref": "#/definitions/diagnosticCode" },
+          "trace_id": { "$ref": "#/definitions/trace" },
+          "request_id": { "$ref": "#/definitions/trace" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "id": { "type": "string", "pattern": "^[1-9]\\d*$", "maxLength": 16, "description": "正十进制安全整数ID文本，最大9007199254740991，不接受首尾空白或别名。" },
+    "ids": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "$ref": "#/definitions/id" }, "description": "原始CSV或JSON字符串数组1至50项，逐项验证后首现去重。" },
+    "safeNonnegative": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "safeInteger": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+    "count": { "type": "integer", "minimum": 0, "maximum": 2147483647 },
+    "money": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.\\d{2}$", "description": "人民币元固定两位文本，精确分值不超过9007199254740991。" },
+    "time": { "type": "string", "format": "beijing-date-time-ms", "pattern": "\\.000$", "description": "北京时间YYYY-MM-DD HH:mm:ss.SSS，零毫秒，输入Unix秒0至4102444800。" },
+    "outputTime": { "type": "string", "format": "beijing-date-time-ms", "description": "按源Unix秒转换的北京时间YYYY-MM-DD HH:mm:ss.SSS，正安全整数源时间且在0001至9999年内。" },
+    "createdRange": {
+      "type": "object", "additionalProperties": false, "required": ["start", "end"],
+      "properties": { "start": { "$ref": "#/definitions/time" }, "end": { "$ref": "#/definitions/time" } },
+      "description": "成为客户时间，argv必须start..end，严格start<end且跨度至多366天，规范化原范围不被拆窗改写。"
+    },
+    "timeRange": {
+      "type": "object", "additionalProperties": false, "minProperties": 1,
+      "properties": { "start": { "$ref": "#/definitions/time" }, "end": { "$ref": "#/definitions/time" } },
+      "description": "时间必须含..，允许单边，不补缺省，双边start≤end，拒绝非零毫秒、非法日历、Unix数字、T分隔或时区后缀。"
+    },
+    "integerRange": {
+      "type": "object", "additionalProperties": false, "minProperties": 1,
+      "properties": { "min": { "$ref": "#/definitions/safeNonnegative" }, "max": { "$ref": "#/definitions/safeNonnegative" } },
+      "description": "LOW..HIGH、LOW..、..HIGH；裸值传相同双边，不补0或缺省上限，双边min≤max，拒绝空白、负数及指数。"
+    },
+    "countRange": {
+      "type": "object", "additionalProperties": false, "minProperties": 1,
+      "properties": { "min": { "$ref": "#/definitions/count" }, "max": { "$ref": "#/definitions/count" } },
+      "description": "购次整数范围，语法同数值范围，双边min≤max。"
+    },
+    "moneyRange": {
+      "type": "object", "additionalProperties": false, "minProperties": 1,
+      "properties": { "min": { "$ref": "#/definitions/money" }, "max": { "$ref": "#/definitions/money" } },
+      "description": "金额数值范围，输入最多两位小数，规范化固定两位，按精确分值比较min≤max，拒绝负数和指数。"
+    },
+    "customer": {
+      "type": "object", "additionalProperties": false, "required": ["yzOpenId"],
+      "properties": {
+        "yzOpenId": { "type": "string", "minLength": 1, "pattern": "^\\S(?:[\\s\\S]*\\S)?$", "description": "稳定开放客户标识，不裁空白、不数值化，不是手机号或内部Long用户ID。" },
+        "name": { "type": "string", "description": "客户姓名，合法空串保留。" },
+        "showName": { "type": "string", "description": "服务端推荐展示名，不重新排优先级。" },
+        "mobile": { "type": "string", "description": "手机号，允许空串，缺失不推断无手机号，不代替稳定标识。" },
+        "gender": { "$ref": "#/definitions/safeInteger", "description": "0=其他、1=男、2=女；未来安全整数原值保留，不贴新标签。" },
+        "isMember": { "type": "boolean", "description": "源整数0=非会员、1=会员；其它编码失败，不由等级、卡或时间推算。" },
+        "tradeCount": { "$ref": "#/definitions/count", "description": "搜索服务购次，不保证全渠道口径。" },
+        "points": { "$ref": "#/definitions/safeInteger", "description": "搜索积分，允许负安全整数原值，不由筛选补值。" },
+        "createdAt": { "$ref": "#/definitions/outputTime", "description": "成为客户时间，源正Unix秒，0或null失败；若返回须处于原始查询总窗口。" },
+        "memberCreatedAt": { "anyOf": [{ "$ref": "#/definitions/outputTime" }, { "type": "integer", "const": 0 }], "description": "成为会员时间，源正Unix秒转换；数字0原样保留，不独立表示非会员。" },
+        "isMobileAuthorized": { "type": "boolean", "description": "是否授权手机号，不称为已验证。" }
+      },
+      "description": "有限摘要，所选可选明细缺失省略，null或错型失败；未知源扩展忽略。"
+    },
+    "diagnosticCode": { "anyOf": [{ "$ref": "#/definitions/safeInteger" }, { "type": "string", "pattern": "^-?\\d{1,12}$" }], "description": "白名单诊断码，不含任意自由消息。" },
+    "trace": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$", "description": "安全追踪号，不拼入自由文本。" },
+    "bindingRequest": {
+      "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+      "properties": { "method": { "type": "string", "const": "POST" }, "path": { "type": "string", "const": "youzan.shop.basic.get/3.0.0" }, "body": { "type": "object", "additionalProperties": false, "maxProperties": 0 } }
+    },
+    "searchRequest": {
+      "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+      "properties": {
+        "method": { "type": "string", "const": "POST" }, "path": { "type": "string", "const": "youzan.scrm.customer.list/1.0.0" },
+        "body": {
+          "type": "object", "additionalProperties": false, "required": ["page_no", "page_size", "created_at_start", "created_at_end"],
+          "properties": {
+            "page_no": { "type": "integer", "const": 1 }, "page_size": { "type": "integer", "const": 50 },
+            "keyword": { "type": "string", "const": "***" }, "mobile": { "type": "string", "const": "***" },
+            "is_member": { "type": "integer", "enum": [0, 1], "description": "0=非会员，1=会员。" },
+            "has_level": { "type": "boolean", "description": "true=有等级，false=无等级。" }, "has_card": { "type": "boolean", "description": "true=有卡，false=无卡。" },
+            "all_match_tag_ids": { "$ref": "#/definitions/requestIds", "description": "标签定义安全整数JSON数组，全部满足。" },
+            "level_ids": { "$ref": "#/definitions/requestIds", "description": "等级定义安全整数JSON数组。" }, "card_ids": { "$ref": "#/definitions/requestIds", "description": "卡定义安全整数JSON数组。" },
+            "created_at_start": { "$ref": "#/definitions/seconds" }, "created_at_end": { "$ref": "#/definitions/seconds" },
+            "created_member_at_start": { "$ref": "#/definitions/seconds" }, "created_member_at_end": { "$ref": "#/definitions/seconds" },
+            "last_trade_time_start": { "$ref": "#/definitions/seconds" }, "last_trade_time_end": { "$ref": "#/definitions/seconds" },
+            "total_trade_count_min": { "$ref": "#/definitions/count" }, "total_trade_count_max": { "$ref": "#/definitions/count" },
+            "points_min": { "$ref": "#/definitions/safeNonnegative" }, "points_max": { "$ref": "#/definitions/safeNonnegative" },
+            "total_trade_amount_min": { "$ref": "#/definitions/safeNonnegative" }, "total_trade_amount_max": { "$ref": "#/definitions/safeNonnegative" },
+            "stored_balance_min": { "$ref": "#/definitions/safeNonnegative" }, "stored_balance_max": { "$ref": "#/definitions/safeNonnegative" }
+          }
+        }
+      }
+    },
+    "seconds": { "type": "integer", "minimum": 0, "maximum": 4102444800, "description": "北京时间适配后的Unix秒整数。" },
+    "requestIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "description": "HTTP JSON body原生安全整数数组，不是JSON数组文本。" }
+  },
+  "api": { "method": "POST", "path": "youzan.scrm.customer.list/1.0.0" },
+  "success": { "description": "同店绑定与全部实际请求成功且视图满足模型后输出；有界预算停止可返回有限结果，其余失败无部分成功。" },
+  "errors": { "description": "失败stdout为空，stderr一份脱敏错误JSON，退出码非零；不自动重试、初始化应用、换身份或切店。" },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "公开选项为15项业务筛选和5项控制；format与dryRun不进入规范化业务input。",
+    "固定每页50、并发1、服务端创建时间降序；越10000窗口时按秒严格缩小并重叠1秒，先遍历较新窗口。重叠不是无遗漏证明。",
+    "每页重新使用当次total，不冻结首次总数；未知总数短页与同叶停滞不会报告完整；父子重叠不触发同叶停滞。",
+    "每请求10秒、累计流式业务响应10MiB、最终含换行UTF-8输出5MiB，任一后页失败整体失败。",
+    "无恢复游标，重复执行是新观察；不提供phones/lookup、来源渠道、sort、任意字段、后台导出或逐客户详情校验。",
+    "真实执行需有效四字段上下文及公共认证，同店绑定sid须等于显式目标；at=all或预览成功不证明授权，应用身份不证明员工权限隔离。"
+  ]
+}

package/src/commands/native/customer/customer-tag/get/command.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command } = require('commander');
+const { requestApi, snapshotApiEnvironment, ApiConfigurationError } = require('../../../../../transport/api');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const schema = require('./schema.json');
+
+const commandPath = 'customer.customer-tag.get';
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const safeCode = value => Number.isSafeInteger(value) ||
+  (typeof value === 'string' && /^-?\d{1,12}$/.test(value));
+
+function failure(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = new Error(`客户标签关系查询失败：${category}（${stage}）`);
+  error.cliDetails = {
+    category, stage, command: commandPath, targetScope: scope, requestState,
+    nextStep: '核对本命令 help/schema、目标店铺和客户标识；服务端拒绝时停止核对授权，不自动重试、切换编码、身份、店铺或接口。',
+    ...facts
+  };
+  return error;
+}
+
+function buildRequest(options, context) {
+  let input;
+  try {
+    const target = Object.hasOwn(options, 'kdtId') ? options.kdtId : context?.shopId;
+    if (typeof target !== 'string' || !/^[1-9]\d*$/.test(target) || !['json', 'pretty'].includes(options.format)) {
+      throw new Error('invalid input');
+    }
+    input = { kdtId: Number(target), yzOpenId: options.yzOpenId.trim() };
+    validateCommandValue(schema, 'input', input);
+  } catch {
+    throw failure('parameter', 'input');
+  }
+  const scope = { kdtId: input.kdtId };
+  if (context && context.orgType !== 'hq' && String(input.kdtId) !== context.shopId) {
+    throw failure('permission', 'scope', scope);
+  }
+  const preview = {
+    targetScope: scope,
+    request: {
+      method: schema.api.method,
+      path: schema.api.path,
+      body: {
+        account: { account_type: 5, account_id: input.yzOpenId },
+        filter_invalid_tag: false,
+        filter_category_tag: false,
+        display_type: 2
+      }
+    }
+  };
+  validateCommandValue(schema, 'preview', preview);
+  return { input, preview };
+}
+
+function diagnostics(result, httpStatus) {
+  const facts = { api: schema.api.path, httpStatus };
+  if (safeCode(result?.code)) facts.businessCode = result.code;
+  if (object(result?.gw_err_resp) && safeCode(result.gw_err_resp.err_code)) {
+    facts.gatewayCode = result.gw_err_resp.err_code;
+  }
+  for (const field of ['trace_id', 'request_id']) {
+    const value = result?.[field] ?? result?.gw_err_resp?.[field];
+    if (typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value)) {
+      facts[field] = value;
+    }
+  }
+  return facts;
+}
+
+async function execute({ input, preview }) {
+  const scope = preview.targetScope;
+  let response;
+  try {
+    const env = await snapshotApiEnvironment(undefined, input.kdtId);
+    response = await requestApi(preview.request, env);
+  } catch (error) {
+    if (error instanceof ApiConfigurationError) throw failure('configuration', 'configuration', scope);
+    throw failure('transport', 'request', scope, 'unknown');
+  }
+  const fail = (category, stage, facts) => failure(category, stage, scope, 'sent', facts);
+  if (Buffer.byteLength(response.body) > MAX_RESPONSE_BYTES) {
+    throw fail('protocol', 'response-budget', { api: schema.api.path, httpStatus: response.httpStatus });
+  }
+  let result;
+  try { result = JSON.parse(response.body); }
+  catch { result = null; }
+  const facts = diagnostics(result, response.httpStatus);
+  if (!response.ok) {
+    const category = response.httpStatus === 401 ? 'authentication' :
+      response.httpStatus === 403 ? 'permission' : 'http';
+    throw fail(category, 'response', facts);
+  }
+  if (!object(result)) throw fail('protocol', 'response', facts);
+  if (object(result.gw_err_resp) && safeCode(result.gw_err_resp.err_code)) {
+    throw fail(result.success === true || result.code === 200 ? 'protocol' : 'business_rejected', 'response', facts);
+  }
+  if (result.success === false && safeCode(result.code) && Number(result.code) !== 200) {
+    throw fail('business_rejected', 'response', facts);
+  }
+  if (result.success !== true || result.code !== 200) throw fail('protocol', 'success', facts);
+  const data = result.data;
+  if (!object(data) || data.yz_open_id !== input.yzOpenId || !Array.isArray(data.tags)) {
+    throw fail('protocol', 'customer-tag-model', facts);
+  }
+  const tags = data.tags.map(tag => {
+    if (!object(tag)) throw fail('protocol', 'customer-tag-model', facts);
+    const mapped = { tag_id: tag.tag_id, tag_name: tag.name };
+    if (Object.hasOwn(tag, 'category_id')) mapped.tag_category_id = tag.category_id;
+    if (Object.hasOwn(tag, 'category_name')) mapped.tag_category_name = tag.category_name;
+    return mapped;
+  });
+  const output = { data: { customer_tag: { yz_open_id: data.yz_open_id, tags } } };
+  try { validateCommandValue(schema, 'output', output); }
+  catch { throw fail('protocol', 'customer-tag-model', facts); }
+  return { output, facts };
+}
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('获取单个客户本次返回的完整标签集合及已取得的分组信息')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw failure('parameter', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺 ID，省略时使用当前选中店铺')
+    .requiredOption('--yz-open-id <id>', '必填：目标客户 yzOpenId，不接受手机号替代')
+    .option('--format <format>', 'json 或 pretty（仅改变缩进）', 'json')
+    .option('--dry-run', '仅本地预览，不读凭证、不联网')
+    .addHelpText('after', `
+返回 data.customer_tag；tags 完整保留本次响应中的该客户标签集合；受授权可见范围限制，不承诺历史全集或跨时点快照。
+请求隐藏和展示标签，不主动排除禁用或组内标签；仍受服务端授权和可见范围限制。
+空 tags 数组可以成功；缺失数组、客户不匹配、非安全整数或成功信号冲突整体失败。
+保留接口顺序、重复项和分类 ID 0；缺少分类名称时省略，不补 null。
+不提供 --tag-id、分页、--include 或客户详情降级；现行客户详情 --include tags 不变。
+获取单个客户标签集合推荐使用本命令；已有 customer-tag list 保留原契约供现有调用方使用。
+list 的 data.yzOpenId/data.tags 与本命令结构不同，不互作别名或失败降级，不据此区分时效或历史范围。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+店铺上下文中目标必须等于 shopId；at: all 不是任意跨店授权。
+接口不含店铺字段，目标店铺由网关上下文传递；省略 --kdt-id 时使用当前选中店铺。
+一次最多一个请求；响应读取后检查10MiB、最终stdout检查5MiB，超额整体失败，不截断。
+失败 stdout 为空、stderr 为错误 JSON；不自动重试、切编码、换身份、店铺或接口。
+
+示例：
+  zan-saas customer customer-tag get --yz-open-id customer-1
+  zan-saas customer customer-tag get --kdt-id 63077 --yz-open-id customer-1 --format pretty
+  zan-saas customer customer-tag get --kdt-id 63077 --yz-open-id customer-1 --dry-run
+`)
+    .action(async options => {
+      const request = buildRequest(options, context);
+      const { output, facts } = options.dryRun ? { output: request.preview } : await execute(request);
+      const text = `${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`;
+      if (Buffer.byteLength(text) > MAX_OUTPUT_BYTES) {
+        throw failure('protocol', 'output-budget', request.preview.targetScope,
+          options.dryRun ? 'not_sent' : 'sent', facts);
+      }
+      process.stdout.write(text);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };