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

package/src/commands/native/customer/segment-customer/list/command.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { createBoundShopQuery, bindingPath } = require('../../../../../execution/shop-query');
+const { QueryError, object } = require('../../../../../execution/query-api');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { normalizeMoney } = require('../../../../../execution/money');
+const { normalizeTimes } = require('../../../../../execution/datetime');
+const schema = require('./schema.json');
+
+const command = 'customer.segment-customer.list';
+const nextStep = '核对原店铺、分群 ID、页码和服务端授权；需要时稍后主动重查，不自动切换身份、店铺或重放。';
+const responseLimit = 2 * 1024 * 1024;
+const outputLimit = 5 * 1024 * 1024;
+const fields = {
+  yzOpenId: 'yz_open_id', mobileCountryCode: 'mobile_country_code', mobile: 'mobile',
+  nickName: 'nick_name', gender: 'gender', freeLevelName: 'free_level_name',
+  payLevelName: 'pay_level_name', cardNames: 'card_names', points: 'points',
+  storedBalance: 'stored_balance', allChannelTotalTradeCount: 'all_channel_total_trade_count',
+  allChannelTotalTradeAmount: 'all_channel_total_trade_amount',
+  allChannelLastTradeAt: 'all_channel_last_trade_time'
+};
+
+function failure(category, stage, scope = {}, state = 'not_sent', facts = {}) {
+  const safeFacts = {};
+  for (const name of ['api', 'httpStatus', 'businessCode', 'trace_id', 'request_id']) {
+    if (Object.hasOwn(facts, name)) safeFacts[name] = facts[name];
+  }
+  return new QueryError(category, stage, scope, safeFacts, state, command, nextStep);
+}
+
+function integer(text) {
+  if (typeof text !== 'string' || !/^[1-9]\d*$/.test(text) ||
+      !Number.isSafeInteger(Number(text))) throw new Error('invalid integer');
+  return Number(text);
+}
+
+function buildInput(options, context) {
+  let scope;
+  try { scope = resolveTargetShop(options, context, command); }
+  catch (error) {
+    const details = error.cliDetails;
+    throw failure(details.category, details.stage === 'validation' ? 'input' : details.stage,
+      details.targetScope);
+  }
+  try {
+    if (typeof options.segmentId !== 'string' || !/^[1-9]\d{0,18}$/.test(options.segmentId) ||
+        BigInt(options.segmentId) > 9223372036854775807n) throw new Error('invalid segment');
+    if (!['json', 'pretty'].includes(options.format)) throw new Error('invalid format');
+    const input = { ...scope, segmentId: options.segmentId,
+      pageNo: integer(options.pageNo), pageSize: integer(options.pageSize) };
+    validateCommandValue(schema, 'input', input);
+    return input;
+  } catch { throw failure('validation', 'input', scope); }
+}
+
+function project(data, input, facts) {
+  const scope = { kdtId: input.kdtId };
+  const invalid = () => failure('protocol', 'segment-customers', scope, 'sent', facts);
+  try {
+    if (!object(data) || !Array.isArray(data.crowd_customer_info_list) ||
+        data.page_no !== input.pageNo || data.page_size !== input.pageSize) throw invalid();
+    const rows = data.crowd_customer_info_list;
+    if (rows.length > input.pageSize) throw invalid();
+    const total = readTotal(data, 'total_count');
+    let hasMore = null;
+    if (total !== null) {
+      const offset = BigInt(input.pageNo - 1) * BigInt(input.pageSize);
+      const end = offset + BigInt(rows.length);
+      const count = BigInt(total);
+      if ((rows.length > 0 && end > count) || (rows.length === 0 && offset < count) ||
+          (rows.length > 0 && rows.length < input.pageSize && end !== count)) throw invalid();
+      hasMore = BigInt(input.pageNo) * BigInt(input.pageSize) < count
+        ? (input.pageNo < 10000 ? true : null) : false;
+    }
+    const seen = new Set();
+    const customerModel = schema.definitions.customer;
+    const customers = rows.map(row => {
+      if (!object(row) || typeof row.yz_open_id !== 'string' || !row.yz_open_id ||
+          row.yz_open_id.trim() !== row.yz_open_id || seen.has(row.yz_open_id)) throw invalid();
+      seen.add(row.yz_open_id);
+      const selected = {};
+      for (const [name, source] of Object.entries(fields)) {
+        if (Object.hasOwn(row, source)) selected[name] = row[source];
+      }
+      return normalizeTimes(normalizeMoney(selected, customerModel), customerModel);
+    });
+    const output = { data: { customers,
+      pagination: { pageNo: data.page_no, pageSize: data.page_size,
+        ...(total === null ? {} : { total }), hasMore } } };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch { throw invalid(); }
+}
+
+function serialize(output, format, scope) {
+  const text = `${JSON.stringify(output, null, format === 'pretty' ? 2 : 0)}\n`;
+  if (Buffer.byteLength(text) > outputLimit) {
+    throw failure('limit', 'output', scope, 'sent');
+  }
+  return text;
+}
+
+function createCommand({ context } = {}) {
+  const leaf = new Command('list')
+    .description('查询已知自定义分群内一页客户摘要，不扫描、不导出')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw failure('validation', 'input');
+    })
+    .requiredOption('--segment-id <id>', '分群 ID，规范正十进制文本，最大 9223372036854775807')
+    .option('--kdt-id <id>', '目标店铺正安全整数；默认当前有效上下文店铺')
+    .option('--page-no <n>', '页码 1..10000，不自动翻页', '1')
+    .option('--page-size <n>', '每页 1、2、4、5、8、10、20、25、40、50、100 条', '20')
+    .addOption(new Option('--format <format>', 'json=单行 JSON，pretty=缩进 JSON')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地校验并预览两步逻辑请求，不读取凭证、不联网')
+    .addHelpText('after', `
+返回 data.customers 和 pagination.pageNo/pageSize/total/hasMore，只观察当前页，不是历史快照。
+使用店铺与分群 ID 定位；客户以同店 yzOpenId 引用。等级、卡名不证明会员身份或卡当前有效。
+未取得总数时省略 total，hasMore 为 null；仍有下一页但超页码预算时 hasMore 为 null。
+hasMore=true 时保留店铺、分群和 pageSize，将 pageNo 加 1 手动继续。短页与人数冲突整体失败。
+金额为人民币元字符串，固定两位；时间为北京时间 YYYY-MM-DD HH:mm:ss.SSS。
+先核验同店，再取一页；1106 公共应用准备可能增加 HTTP 请求。普通失败不自动重放。
+每次业务响应最多 2 MiB，最终输出含换行最多 5 MiB，超限整体失败。
+支持官方列明的微商城/零售单店、连锁 D/L 总部，不承诺连锁分店或系统推荐分群。
+不支持分群目录、规则、筛选、排序、include 或触达；缺少分群 ID 时不自动选群。
+示例：zan-saas customer segment-customer list --segment-id 4938280 --kdt-id 63077 --dry-run
+契约：zan-saas schema customer.segment-customer.list`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const scope = { kdtId: input.kdtId };
+      const body = { request: `{"crowd_id":${input.segmentId},"page_no":${input.pageNo},"page_size":${input.pageSize}}` };
+      const preview = { scope, requests: [
+        { method: 'POST', path: bindingPath, body: {} },
+        { method: 'POST', path: schema.api.path, body }
+      ] };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        try {
+          const { read } = await createBoundShopQuery(scope, command, 'shop-binding', {
+            transportOptions: { maxResponseBytes: () => responseLimit, shopApp: { notify: () => {} } }
+          });
+          const { data, facts } = await read(schema.api.path, body, 'segment-customers');
+          output = project(data, input, facts);
+        } catch (error) {
+          const details = error.cliDetails;
+          if (!details) throw failure('protocol', 'segment-customers', scope, 'unknown');
+          throw failure(details.category, details.stage, scope, details.requestState, details);
+        }
+      }
+      process.stdout.write(serialize(output, options.format, scope));
+    });
+  const seen = new Set();
+  for (const option of leaf.options) {
+    leaf.on(`option:${option.name()}`, () => {
+      if (seen.has(option.name())) throw failure('validation', 'input');
+      seen.add(option.name());
+    });
+  }
+  return leaf;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), project, serialize };

package/src/commands/native/customer/segment-customer/list/schema.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "api": { "method": "POST", "path": "youzan.crm.crowd.query/1.0.0" },
+  "input": {
+    "type": "object", "additionalProperties": false,
+    "required": ["kdtId", "segmentId", "pageNo", "pageSize"],
+    "properties": {
+      "kdtId": { "$ref": "#/definitions/kdtId" },
+      "segmentId": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "目标店铺内的分群 ID，范围 1..9223372036854775807，保留完整十进制文本，不接受符号、空白、前导零或指数" },
+      "pageNo": { "$ref": "#/definitions/pageNo" },
+      "pageSize": { "$ref": "#/definitions/pageSize" }
+    }
+  },
+  "output": {
+    "type": "object", "additionalProperties": false, "required": ["data"],
+    "properties": {
+      "data": {
+        "type": "object", "additionalProperties": false, "required": ["customers", "pagination"],
+        "properties": {
+          "customers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/customer" }, "description": "当前页客户摘要，保留返回顺序；实际成功空页为 []，不保证跨页无重复或遗漏" },
+          "pagination": {
+            "type": "object", "additionalProperties": false, "required": ["pageNo", "pageSize", "hasMore"],
+            "properties": {
+              "pageNo": { "$ref": "#/definitions/pageNo" },
+              "pageSize": { "$ref": "#/definitions/pageSize" },
+              "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。" },
+              "hasMore": { "type": ["boolean", "null"], "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "additionalProperties": false, "required": ["scope", "requests"],
+    "properties": {
+      "scope": { "$ref": "#/definitions/scope" },
+      "requests": {
+        "type": "array", "minItems": 2, "maxItems": 2, "additionalItems": false,
+        "description": "两步逻辑计划；不展开公共认证或条件性的应用准备，不证明真实授权",
+        "items": [
+          {
+            "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+            "properties": {
+              "method": { "const": "POST" }, "path": { "const": "youzan.shop.basic.get/3.0.0" },
+              "body": { "type": "object", "additionalProperties": false, "properties": {} }
+            }
+          },
+          {
+            "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+            "properties": {
+              "method": { "const": "POST" }, "path": { "const": "youzan.crm.crowd.query/1.0.0" },
+              "body": {
+                "type": "object", "additionalProperties": false, "required": ["request"],
+                "properties": { "request": { "type": "string", "description": "JSON 对象文本，仅 crowd_id、page_no、page_size；crowd_id 是完整分群 ID 的无损数字 token，另两项为实际页码和条数" } }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "error": {
+    "type": "object", "additionalProperties": false, "required": ["success", "code", "message", "details"],
+    "properties": {
+      "success": { "const": false }, "code": { "const": -10001 }, "message": { "type": "string" },
+      "details": {
+        "type": "object", "additionalProperties": false,
+        "required": ["command", "category", "stage", "targetScope", "requestState", "nextStep"],
+        "properties": {
+          "command": { "const": "customer.segment-customer.list" },
+          "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", "scope", "configuration", "shop-binding", "segment-customers", "output"], "description": "input=选项校验，context=上下文，scope=目标解析，configuration=环境准备，shop-binding=同店核验，segment-customers=客户页查询及适配，output=序列化和输出预算" },
+          "targetScope": { "type": "object", "additionalProperties": false, "properties": { "kdtId": { "$ref": "#/definitions/kdtId" } }, "description": "目标已确定时只有 kdtId，否则为空对象" },
+          "requestState": { "type": "string", "enum": ["not_sent", "sent", "unknown"], "description": "针对失败阶段，not_sent=对应业务请求未发，sent=已取得响应，unknown=发送或结果无法确认；不否认先前绑定及公共准备" },
+          "nextStep": { "type": "string" },
+          "api": { "type": "string", "enum": ["youzan.shop.basic.get/3.0.0", "youzan.crm.crowd.query/1.0.0"], "description": "失败接口，分别为店铺核验、分群客户页查询" },
+          "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 },
+          "businessCode": { "anyOf": [{ "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "pattern": "^-?[0-9]{1,12}$" }], "description": "安全诊断码，不包含上游自由文本" },
+          "trace_id": { "$ref": "#/definitions/trace" }, "request_id": { "$ref": "#/definitions/trace" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "kdtId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "目标店铺 ID，默认当前有效上下文店铺；shop 位置须同店，不代表服务端授权" },
+    "scope": { "type": "object", "additionalProperties": false, "required": ["kdtId"], "properties": { "kdtId": { "$ref": "#/definitions/kdtId" } } },
+    "pageNo": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "实际页码，从 1 开始，最多 10000，不自动翻页" },
+    "pageSize": { "type": "integer", "enum": [1, 2, 4, 5, 8, 10, 20, 25, 40, 50, 100], "description": "每页条数，只支持 1、2、4、5、8、10、20、25、40、50、100；不表示总读取量" },
+    "trace": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "安全追踪值" },
+    "customer": {
+      "type": "object", "additionalProperties": false, "required": ["yzOpenId"],
+      "description": "分群内客户摘要，不代表会员身份或完整档案；可选字段缺失省略，返回 null 或错型整体失败；保留合法空串、零和空数组",
+      "properties": {
+        "yzOpenId": { "type": "string", "minLength": 1, "pattern": "^\\S(?:[\\s\\S]*\\S)?$", "description": "同店客户稳定标识，不接受首尾空白且同页不能重复，不以手机号或昵称合并" },
+        "mobileCountryCode": { "type": "string", "description": "手机号国家或地区区号，原样保留 86 或 +86 等文本，不自动改写" },
+        "mobile": { "type": "string", "description": "本次返回的手机号，保留空串或掩码，不补全，也不证明可触达" },
+        "nickName": { "type": "string", "description": "微信昵称，可为空，不作为姓名或稳定标识" },
+        "gender": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "description": "整数 0=未知，1=男，2=女；未来 Java Integer 范围整数码原样保留，不猜含义，不接受字符串或 null" },
+        "freeLevelName": { "type": "string", "description": "免费等级名称摘要，可为空，不据此推算会员身份或完整等级关系" },
+        "payLevelName": { "type": "string", "description": "付费等级名称摘要，可为空，不证明付费资格当前有效" },
+        "cardNames": { "type": "array", "items": { "type": "string" }, "description": "权益卡名称摘要，保留空数组、空名称和重复名称，不推断持卡号、卡数量或当前有效性" },
+        "points": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "本次积分摘要，保留零和负值，不代表累计积分" },
+        "storedBalance": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)\\.[0-9]{2}$", "$comment": "upstream-money:fen", "description": "储值余额摘要，人民币 CNY 元，固定两位，范围 -90071992547409.91..90071992547409.91；不是逐卡可支付余额或客户全部资产" },
+        "allChannelTotalTradeCount": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "全渠道累计有效消费次数，不是任意时间窗口的订单笔数" },
+        "allChannelTotalTradeAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)\\.[0-9]{2}$", "$comment": "upstream-money:fen", "description": "全渠道累计有效消费金额，人民币 CNY 元，固定两位，范围 -90071992547409.91..90071992547409.91；不是净收入或近 90 天金额" },
+        "allChannelLastTradeAt": { "type": "string", "format": "beijing-date-time-ms", "$comment": "upstream-time:milliseconds", "description": "全渠道上次消费时间，北京时间 YYYY-MM-DD HH:mm:ss.SSS；纪元零值为 1970-01-01 08:00:00.000，不解释为从未消费" }
+      }
+    }
+  },
+  "success": { "description": "同店核验后取得一页，客户标识、摘要、分页和字节预算全部通过才一次性输出 data；无部分成功" },
+  "errors": { "description": "stdout 为空，stderr 一份脱敏 JSON，退出 1。绑定不一致、人数冲突、所选字段 null 或错型不降级为空页；普通失败、超时和断连不自动重放" },
+  "notes": [
+    "仅查询已知自定义分群的一页客户。支持官方列明的微商城单店、零售单店及连锁 D/L 总部；不承诺连锁分店或系统推荐分群。",
+    "执行需要有效四字段上下文；省略店铺用当前店铺。无上下文时仅可显式指定合法店铺本地预览；无效上下文不能绕过。",
+    "结果是动态观察，不是历史快照。跨页可能新增、删除、重复或遗漏，空页不能证明分群不存在。",
+    "hasMore=true 时保留店铺、分群 ID 和 pageSize，将 pageNo 加 1；达到 10000 页不改变条数冒充无缝恢复。未知总数时不能从短页证明读完。",
+    "非空短页必须恰好到报告尾部；人数冲突整体失败。超过尾页的成功空页 hasMore=false，不表示分群不存在。",
+    "正常两个逻辑业务查询；公共 1106 应用准备可能增加 HTTP 请求，最多 22 次业务发送及 22 次账号准备调用。普通失败不重试。",
+    "每次业务响应最多 2 MiB，最终序列化输出含换行最多 5 MiB；超限整体失败，不截断客户或卡名。",
+    "不读取目录或规则、不遍历、不导出、不触达、不逐客户补档案。等级、卡名和手机号均不能代替同店 yzOpenId。"
+  ]
+}

package/src/commands/native/customer/shared/search-input.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const { parseDateTime, formatDateTime } = require('../../../../execution/datetime');
+const { resolveTargetShop } = require('../../../../execution/target-shop');
+const { failure } = require('../../../../execution/shop-query');
+
+const command = 'customer.customer.scan';
+const searchPath = 'youzan.scrm.customer.list/1.0.0';
+const maxSafe = Number.MAX_SAFE_INTEGER;
+
+function reject(category, stage, scope = {}, state = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, state, facts);
+  error.cliDetails.nextStep = '核对原店铺、参数、字段来源和服务端授权；前批结果不构成成功，不自动重试、切店、换身份或改变查询模式。';
+  return error;
+}
+
+function adaptError(error, scope) {
+  const details = error.cliDetails;
+  if (!details) return reject('protocol', 'output', scope, 'sent');
+  const stage = ['input', 'context', 'configuration', 'shop-binding', 'search', 'scan', 'output']
+    .includes(details.stage) ? details.stage : 'input';
+  const adapted = reject(details.category, stage, scope, details.requestState);
+  for (const key of ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']) {
+    if (Object.hasOwn(details, key)) adapted.cliDetails[key] = details[key];
+  }
+  return adapted;
+}
+
+function integer(value, maximum = maxSafe, minimum = 0) {
+  if (typeof value !== 'string' || !/^(0|[1-9]\d*)$/.test(value) ||
+      !Number.isSafeInteger(Number(value)) || Number(value) < minimum || Number(value) > maximum) {
+    throw new Error('invalid integer');
+  }
+  return Number(value);
+}
+
+function id(value) {
+  integer(value, maxSafe, 1);
+  return value;
+}
+
+function ids(value) {
+  if (typeof value !== 'string') throw new Error('invalid IDs');
+  const values = value.startsWith('[') ? JSON.parse(value) : value.split(',');
+  if (!Array.isArray(values) || values.length < 1 || values.length > 50) throw new Error('invalid IDs');
+  return [...new Set(values.map(id))];
+}
+
+function boolean(value) {
+  if (!['true', 'false'].includes(value)) throw new Error('invalid boolean');
+  return value === 'true';
+}
+
+function cents(value) {
+  if (typeof value !== 'string' || !/^(0|[1-9]\d*)(?:\.\d{1,2})?$/.test(value)) {
+    throw new Error('invalid money');
+  }
+  const [whole, fraction = ''] = value.split('.');
+  const amount = BigInt(whole) * 100n + BigInt(fraction.padEnd(2, '0'));
+  if (amount > BigInt(maxSafe)) throw new Error('unsafe money');
+  return amount;
+}
+
+function money(value) {
+  const amount = cents(value);
+  return `${amount / 100n}.${String(amount % 100n).padStart(2, '0')}`;
+}
+
+function time(value) {
+  if (typeof value !== 'string' || value.trim() !== value) throw new Error('invalid time');
+  const milliseconds = parseDateTime(value);
+  if (milliseconds % 1000 !== 0 || milliseconds < 0 || milliseconds > 4102444800000) {
+    throw new Error('invalid seconds');
+  }
+  return formatDateTime(milliseconds);
+}
+
+function range(value, parse, temporal = false) {
+  if (typeof value !== 'string') throw new Error('invalid range');
+  const parts = value.split('..');
+  if (parts.length > 2 || temporal && parts.length !== 2 || parts.every(part => part === '')) {
+    throw new Error('invalid range');
+  }
+  if (parts.length === 1) parts.push(parts[0]);
+  const [lower, upper] = temporal ? ['start', 'end'] : ['min', 'max'];
+  const result = {};
+  if (parts[0] !== '') result[lower] = parse(parts[0]);
+  if (parts[1] !== '') result[upper] = parse(parts[1]);
+  const compare = parse === money ? cents : value => value;
+  if (result[lower] !== undefined && result[upper] !== undefined &&
+      compare(result[lower]) > compare(result[upper])) throw new Error('reversed range');
+  return result;
+}
+
+function buildInput(options, context) {
+  let scope = {};
+  try {
+    scope = { kdtId: id(options.kdtId) };
+    const filters = {};
+    for (const key of ['keyword', 'mobile']) {
+      if (options[key] === undefined) continue;
+      const value = options[key];
+      if (typeof value !== 'string' || value.trim() !== value || !value ||
+          (key === 'keyword' ? value.length > 200 : !/^\+?\d{5,20}$/.test(value))) {
+        throw new Error('invalid text');
+      }
+      filters[key] = value;
+    }
+    if (filters.keyword !== undefined && filters.mobile !== undefined) throw new Error('conflict');
+    for (const key of ['isMember', 'hasLevel', 'hasBenefitCard']) {
+      if (options[key] !== undefined) filters[key] = boolean(options[key]);
+    }
+    for (const key of ['tagIds', 'levelIds', 'benefitCardIds']) {
+      if (options[key] !== undefined) filters[key] = ids(options[key]);
+    }
+    for (const key of ['created', 'memberCreated', 'lastTrade']) {
+      if (options[key] !== undefined) filters[key] = range(options[key], time, true);
+    }
+    for (const [key, parse] of [['points', integer], ['tradeCount', value => integer(value, 2147483647)],
+      ['tradeAmount', money], ['storedBalance', money]]) {
+      if (options[key] !== undefined) filters[key] = range(options[key], parse);
+    }
+    if (filters.hasLevel === false && filters.levelIds ||
+        filters.hasBenefitCard === false && filters.benefitCardIds) throw new Error('conflict');
+    const created = filters.created;
+    if (!created?.start || !created.end || created.start >= created.end ||
+        parseDateTime(created.end) - parseDateTime(created.start) > 366 * 86400000) {
+      throw new Error('invalid scan window');
+    }
+    const input = { ...scope, filters, limits: {
+      maxItems: integer(options.maxItems ?? '200', 2000, 1),
+      maxRequests: integer(options.maxRequests ?? '20', 200, 2)
+    } };
+    try { resolveTargetShop(options, context, command); }
+    catch (error) { throw adaptError(error, scope); }
+    for (const value of Object.values(filters)) {
+      if (value && typeof value === 'object') Object.freeze(value);
+    }
+    Object.freeze(filters);
+    Object.freeze(input.limits);
+    return Object.freeze(input);
+  } catch (error) {
+    if (error.cliDetails) throw error;
+    throw reject('validation', 'input', scope);
+  }
+}
+
+function bodyFor(filters, window, pageNo = 1) {
+  const body = { page_no: pageNo, page_size: 50 };
+  for (const key of ['keyword', 'mobile']) {
+    if (filters[key] !== undefined) body[key] = filters[key];
+  }
+  if (filters.isMember !== undefined) body.is_member = filters.isMember ? 1 : 0;
+  for (const [key, field] of [['hasLevel', 'has_level'], ['hasBenefitCard', 'has_card']]) {
+    if (filters[key] !== undefined) body[field] = filters[key];
+  }
+  for (const [key, field] of [['tagIds', 'all_match_tag_ids'], ['levelIds', 'level_ids'], ['benefitCardIds', 'card_ids']]) {
+    if (filters[key] !== undefined) body[field] = filters[key].map(Number);
+  }
+  for (const [key, prefix] of [['created', 'created_at'], ['memberCreated', 'created_member_at'], ['lastTrade', 'last_trade_time']]) {
+    const bounds = key === 'created' && window ? window : filters[key];
+    if (!bounds) continue;
+    for (const side of ['start', 'end']) {
+      if (bounds[side] !== undefined) body[`${prefix}_${side}`] = typeof bounds[side] === 'number' ?
+        bounds[side] : parseDateTime(bounds[side]) / 1000;
+    }
+  }
+  for (const [key, prefix] of [['tradeCount', 'total_trade_count'], ['points', 'points'],
+    ['tradeAmount', 'total_trade_amount'], ['storedBalance', 'stored_balance']]) {
+    if (!filters[key]) continue;
+    for (const side of ['min', 'max']) {
+      if (filters[key][side] !== undefined) body[`${prefix}_${side}`] =
+        ['tradeAmount', 'storedBalance'].includes(key) ? Number(cents(filters[key][side])) : filters[key][side];
+    }
+  }
+  return body;
+}
+
+module.exports = { buildInput, bodyFor, reject, adaptError, searchPath, command, range, integer, money, time };

package/src/commands/native/customer/shared/search-page.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { object } = require('../../../../execution/query-api');
+const { formatDateTime, parseDateTime } = require('../../../../execution/datetime');
+const { reject } = require('./search-input');
+
+function projectPage(data, pageNo, originalWindow, scope, facts) {
+  const invalid = () => { throw reject('protocol', 'search', scope, 'sent', facts); };
+  if (!object(data) || !Array.isArray(data.record_list) || data.record_list.length > 50) invalid();
+  for (const [field, expected] of [['page_no', pageNo], ['page_size', 50]]) {
+    if (Object.hasOwn(data, field) && data[field] !== expected) invalid();
+  }
+  const total = data.total;
+  if (Object.hasOwn(data, 'total') && (!Number.isSafeInteger(total) || total < 0)) invalid();
+  if (total !== undefined && data.record_list.length &&
+      (pageNo - 1) * 50 + data.record_list.length > total) invalid();
+  const customers = data.record_list.map(source => {
+    if (!object(source) || typeof source.yz_open_id !== 'string' || !source.yz_open_id ||
+        source.yz_open_id.trim() !== source.yz_open_id) invalid();
+    const customer = { yzOpenId: source.yz_open_id };
+    for (const [field, key] of [['name', 'name'], ['show_name', 'showName'], ['mobile', 'mobile']]) {
+      if (!Object.hasOwn(source, field)) continue;
+      if (typeof source[field] !== 'string') invalid();
+      customer[key] = source[field];
+    }
+    for (const [field, key] of [['gender', 'gender'], ['trade_count', 'tradeCount'], ['points', 'points']]) {
+      if (!Object.hasOwn(source, field)) continue;
+      if (!Number.isSafeInteger(source[field]) ||
+          field === 'trade_count' && (source[field] < 0 || source[field] > 2147483647)) invalid();
+      customer[key] = source[field];
+    }
+    if (Object.hasOwn(source, 'is_member')) {
+      if (![0, 1].includes(source.is_member)) invalid();
+      customer.isMember = source.is_member === 1;
+    }
+    if (Object.hasOwn(source, 'is_mobile_auth')) {
+      if (typeof source.is_mobile_auth !== 'boolean') invalid();
+      customer.isMobileAuthorized = source.is_mobile_auth;
+    }
+    for (const [field, key] of [['created_at', 'createdAt'], ['created_member_at', 'memberCreatedAt']]) {
+      if (!Object.hasOwn(source, field)) continue;
+      const value = source[field];
+      if (field === 'created_member_at' && value === 0) { customer[key] = 0; continue; }
+      if (!Number.isSafeInteger(value) || value <= 0 || !Number.isSafeInteger(value * 1000)) invalid();
+      try { customer[key] = formatDateTime(value * 1000); } catch { invalid(); }
+      if (field === 'created_at' && (parseDateTime(customer[key]) / 1000 < originalWindow.start ||
+          parseDateTime(customer[key]) / 1000 > originalWindow.end)) invalid();
+    }
+    return customer;
+  });
+  return { customers, total };
+}
+
+module.exports = { projectPage };

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

@@ -0,0 +1,73 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+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 = 'customer.tag.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+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');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数；须与凭证店铺一致；省略时使用当前上下文店铺')
+    .requiredOption('--tag-id <id>', '必填：标签定义正安全整数 ID；不是标签组 ID')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览目标、店铺核验和标签请求，不读凭证、不联网')
+    .addHelpText('after', `
+时间点统一输出北京时间 YYYY-MM-DD HH:mm:ss.SSS，字段声明的业务哨兵保留。
+返回 data.tag；名称与主键必需，其余选定明细缺失时保持省略，不推断无值。
+标签状态 0 不可用、1 可用；不套用标签组的状态方向。
+只支持官方声明的微商城单店；at=shop 不承诺零售、总部或连锁分店。
+先核验凭证店铺，再直读标签；不搜索名称、不遍历列表、不重试或切换接口。
+真实执行需四字段上下文和同店授权凭证，店铺回读不证明员工 OAuth。
+契约：zan-saas schema customer.tag.get
+示例：zan-saas customer tag get --kdt-id 63077 --tag-id 123 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try {
+        if (!/^[1-9]\d*$/.test(options.tagId)) throw new Error('invalid tag ID');
+        input = { ...scope, tagId: Number(options.tagId) };
+        validateCommandValue(schema, 'input', input);
+      } catch { throw reject('parameter', 'input', scope); }
+      const preview = {
+        method: 'POST', path: schema.api.path, body: { tag_id: input.tagId },
+        scope, prerequisites: [{ method: 'POST', path: bindingPath, body: {} }]
+      };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const { data, facts } = await read(preview.path, preview.body, 'tag');
+        if (!object(data) || data.tag_id !== input.tagId) {
+          throw reject('target_mismatch', 'tag-model', scope, 'sent', facts);
+        }
+        const tag = Object.fromEntries(Object.keys(schema.definitions.tag.properties)
+          .filter(field => Object.hasOwn(data, field)).map(field => [field, data[field]]));
+        output = { data: { tag } };
+        try {
+          output.data.tag = normalizeTimes(tag, schema.definitions.tag, schema.definitions);
+          validateCommandValue(schema, 'output', output);
+        }
+        catch { throw reject('protocol', 'tag-model', scope, 'sent', facts); }
+      }
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'shop', createCommand: withTargetShopDefault(createCommand) };