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

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

@@ -0,0 +1,259 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "yzOpenId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "yzOpenId": {
+        "$ref": "#/definitions/customerId"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "yzOpenId",
+          "tags"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "yzOpenId": {
+            "$ref": "#/definitions/customerId"
+          },
+          "tags": {
+            "type": "array",
+            "description": "本次响应的客户标签关系集合；明确空数组有效，不保证独立快照或服务端可见范围之外的完整性。",
+            "items": {
+              "type": "object",
+              "required": [
+                "tagId",
+                "tagName",
+                "tagCategoryId"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "tagId": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 9007199254740991,
+                  "description": "标签定义 ID，不接受有损整数。"
+                },
+                "tagName": {
+                  "type": "string",
+                  "description": "标签名称。"
+                },
+                "tagCategoryId": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991,
+                  "description": "标签组 ID，0 表示未分组。"
+                },
+                "tagCategoryName": {
+                  "type": "string",
+                  "description": "标签组名称，未取得或为 null 时省略，空字符串保留。"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.tagrelation.query/1.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "account",
+          "display_type",
+          "filter_invalid_tag",
+          "filter_category_tag"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "account": {
+            "type": "object",
+            "required": [
+              "account_id",
+              "account_type"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "account_id": {
+                "$ref": "#/definitions/customerId"
+              },
+              "account_type": {
+                "const": 5
+              }
+            }
+          },
+          "display_type": {
+            "const": 2
+          },
+          "filter_invalid_tag": {
+            "const": false
+          },
+          "filter_category_tag": {
+            "const": false
+          }
+        }
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "required": [
+      "success",
+      "code",
+      "message"
+    ],
+    "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": [
+              "input",
+              "configuration",
+              "authentication",
+              "permission",
+              "http",
+              "business_rejected",
+              "transport",
+              "protocol"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "arguments",
+              "kdtId",
+              "yzOpenId",
+              "format",
+              "context",
+              "configuration",
+              "request",
+              "response"
+            ]
+          },
+          "command": {
+            "const": "customer.customer-tag.list"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "失败诊断不回显客户标识或自由文本。"
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "const": "youzan.scrm.tagrelation.query/1.0.0"
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "gatewayCode": {
+            "anyOf": [{ "type": "integer" }, { "type": "string", "pattern": "^-?\\d{1,12}$" }]
+          },
+          "trace_id": {
+            "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "显式目标店铺 ID；本地上下文准入不能替代服务端授权。"
+    },
+    "customerId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "首尾空白处理后的 yzOpenId；响应必须完全匹配该值。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.tagrelation.query/1.0.0"
+  },
+  "success": {
+    "description": "客户 ID 精确匹配且标签集合明确取得，每项满足模型后成功。"
+  },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "保留既有 list 契约，返回 data.yzOpenId 和 data.tags；新调用获取一个客户的标签集合推荐 customer-tag get，不互为别名或失败降级入口。",
+    "不分页、不截断标签集合，不承诺快照；缺核心字段或不安全整数失败。",
+    "分类名称未取得或为 null 时省略，空字符串保留；标签组 ID 为 0 表示未分组。",
+    "真实调用前须独立确认凭证与目标店铺绑定；本地上下文、客户匹配和本地模拟不证明远端授权或编码已验收。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ],
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  }
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "客户：档案、行为、标签与分群"
+}

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

@@ -0,0 +1,96 @@
+'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 { reject, readPage, serialize, bindingPath } = require('./query');
+const schema = require('./schema.json');
+
+function buildInput(options, context) {
+  let target;
+  try { target = resolveTargetShop(options, context, 'customer.segment.list'); }
+  catch (error) {
+    const { category, stage, targetScope } = error.cliDetails;
+    const scope = targetScope.kdtId ? { kdtId: String(targetScope.kdtId) } : {};
+    throw reject(category, ['scope', 'validation'].includes(stage) ? 'input' : stage, scope);
+  }
+  const input = { kdtId: String(target.kdtId) };
+  for (const [name, fallback, maximum] of [['pageNo', '1', 10000], ['pageSize', '20', 100]]) {
+    const value = options[name] === undefined ? fallback : options[name];
+    if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value) || Number(value) > maximum) {
+      throw reject('validation', 'input');
+    }
+    input[name] = Number(value);
+  }
+  if (Object.hasOwn(options, 'keyword')) {
+    if (typeof options.keyword !== 'string') throw reject('validation', 'input');
+    input.keyword = options.keyword.trim();
+    if (!input.keyword || Array.from(input.keyword).length > 200) throw reject('validation', 'input');
+  }
+  if (options.format !== undefined && !['json', 'pretty'].includes(options.format)) throw reject('validation', 'input');
+  try { validateCommandValue(schema, 'input', input); }
+  catch { throw reject('validation', 'input'); }
+  return input;
+}
+
+function requestBody(input, redact = false) {
+  const request = { page_no: input.pageNo, page_size: input.pageSize };
+  if (Object.hasOwn(input, 'keyword')) request.keyword = redact ? '***' : input.keyword;
+  return { request: JSON.stringify(request) };
+}
+
+function preview(input) {
+  const plan = { requests: [
+    { method: 'POST', path: bindingPath, body: {} },
+    { method: 'POST', path: schema.api.path, body: requestBody(input, true) }
+  ] };
+  validateCommandValue(schema, 'preview', plan);
+  return plan;
+}
+
+function createCommand({ context } = {}) {
+  const seen = new Set();
+  const command = new Command('list')
+    .description('读取一页已保存分群目录，以稳定 segmentId 发现分群，不查询成员或规则')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('validation', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数 ID 文本；默认本次有效 context.shopId，非法显式值不回退')
+    .option('--keyword <text>', '分群名称关键词，去首尾空白后 1..200 字符，不保证精确匹配')
+    .option('--page-no <n>', '本次页码 1..10000，默认 1，不自动翻页', '1')
+    .option('--page-size <n>', '本页容量 1..100，默认 20，不是总数', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变排版').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地零认证零请求预览，keyword 遮盖为 ***')
+    .addHelpText('after', `
+同店核验后只读一页，最多两次业务请求；每次10秒，不重试、切店、换身份或读取详情。
+执行需要四字段上下文。非总部目标须等于shopId，总部仍需同店核验及服务端授权。
+仅缺少上下文时可显式合法目标预览；无效或冲突上下文即使预览也拒绝。
+分群定义与规则形成动态成员，目录customerCount只是本次报告人数，不是成员快照。
+segmentId是正Long十进制字符串，名称不唯一；不返回未核实的日期、描述或version。
+未取得总数时省略total，hasMore为null，空页和短页不证明取完；第10000页仍有更多时hasMore为null。
+固定data.segments与四字段pagination；响应累计10MiB，含换行输出5MiB，超限整体失败。
+不提供扫描、排序、include、成员、规则、timeout或retry。分群详情及成员查询当前没有入口。
+错误stdout为空，stderr为脱敏JSON。预览和绑定不证明店铺员工权限。
+完整契约：zan-saas schema customer.segment.list
+示例：zan-saas customer segment list --keyword '首购' --page-size 20
+预览：zan-saas customer segment list --kdt-id 63077 --keyword '首购' --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const result = options.dryRun ? preview(input) : await readPage(input, requestBody(input));
+      console.log(serialize(result, options.format, { kdtId: input.kdtId }, options.dryRun ? 'not_sent' : 'sent'));
+    });
+  for (const option of command.options) {
+    command.on(`option:${option.name()}`, () => {
+      if (seen.has(option.name())) throw reject('validation', 'input');
+      seen.add(option.name());
+    });
+  }
+  return command;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), buildInput, requestBody, preview };

package/src/commands/native/customer/segment/list/query.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { readTotal } = require('../../../../../execution/list-total');
+
+const { createBoundShopQuery, bindingPath } = require('../../../../../execution/shop-query');
+const { QueryError, object } = require('../../../../../execution/query-api');
+const { parseExactJson } = require('../../../../../execution/exact-json');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const schema = require('./schema.json');
+
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+const LONG_MAX = 9223372036854775807n;
+
+function reject(category, stage, scope = {}, state = 'not_sent', facts = {}) {
+  return new QueryError(category, stage, scope, facts, state, 'customer.segment.list',
+    '核对原店铺、分页、字段来源与服务端授权；失败不返回部分目录，不自动换店、换身份或重放请求。');
+}
+
+function adaptError(error, scope) {
+  if (!error.cliDetails) return reject('configuration', 'configuration', scope);
+  const { category, stage, requestState, ...details } = error.cliDetails;
+  const facts = {};
+  for (const name of ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']) {
+    if (details[name] !== undefined) facts[name] = details[name];
+  }
+  return reject(category, stage, scope, requestState, facts);
+}
+
+async function readPage(input, body, responseLimit = RESPONSE_LIMIT) {
+  const scope = { kdtId: input.kdtId };
+  let responseBytes = 0;
+  let response;
+  try {
+    const query = await createBoundShopQuery({ kdtId: Number(input.kdtId) }, 'customer.segment.list', 'shop-binding', {
+      onResponse: result => { responseBytes += result.responseBytes; },
+      transportOptions: { maxResponseBytes: () => responseLimit - responseBytes, shopApp: false }
+    });
+    response = await query.read(schema.api.path, body, 'list');
+  } catch (error) { throw adaptError(error, scope); }
+  try {
+    const result = parseExactJson(response.rawBody, token => {
+      if (!/^-?(?:0|[1-9]\d*)$/.test(token)) return NaN;
+      const integer = BigInt(token);
+      return integer >= BigInt(Number.MIN_SAFE_INTEGER) && integer <= BigInt(Number.MAX_SAFE_INTEGER) ?
+        Number(integer) : integer;
+    });
+    return adapt(result.data, input, response.facts);
+  } catch { throw reject('protocol', 'output', scope, 'sent', response.facts); }
+}
+
+function segment(source) {
+  if (!object(source)) throw new Error('segment');
+  const value = source.crowd_id;
+  if (!(typeof value === 'bigint' || typeof value === 'string' || Number.isSafeInteger(value))) throw new Error('id');
+  const segmentId = String(value);
+  if (!/^[1-9]\d{0,18}$/.test(segmentId) || BigInt(segmentId) > LONG_MAX) throw new Error('id');
+  const result = { segmentId, name: source.crowd_name };
+  for (const [name, field] of Object.entries({ customerCount: 'customer_num', type: 'crowd_type', editorMode: 'editor_mode' })) {
+    if (Object.hasOwn(source, field)) result[name] = source[field];
+  }
+  return result;
+}
+
+function adapt(data, input, facts = {}) {
+  try {
+    if (!object(data) || !Array.isArray(data.items) || data.items.length > input.pageSize || !object(data.paginator)) {
+      throw new Error('page');
+    }
+    const page = data.paginator;
+    if (page.page !== input.pageNo || page.page_size !== input.pageSize) throw new Error('pagination');
+    const total = readTotal(page, 'total_count');
+    if (total !== null && total > 2147483647) {
+      throw new Error('total');
+    }
+    const count = data.items.length;
+    const offset = (input.pageNo - 1) * input.pageSize;
+    if (total !== null && (count > 0 ? total < offset + count : total > offset)) throw new Error('contradiction');
+    const segments = data.items.map(segment);
+    if (new Set(segments.map(row => row.segmentId)).size !== segments.length) throw new Error('duplicate');
+    const hasMore = total === null ? null : total <= input.pageNo * input.pageSize ? false : input.pageNo < 10000 ? true : null;
+    const output = { data: { segments, pagination: { pageNo: page.page, pageSize: page.page_size,
+      ...(total === null ? {} : { total }), hasMore } } };
+    validateCommandValue(schema, 'output', output);
+    for (const row of segments) {
+      if (Object.hasOwn(row, 'customerCount') && !Number.isSafeInteger(row.customerCount)) throw new Error('count');
+    }
+    return output;
+  } catch { throw reject('protocol', 'output', { kdtId: input.kdtId }, 'sent', facts); }
+}
+
+function serialize(output, format, scope, state = 'sent', limit = OUTPUT_LIMIT) {
+  const text = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${text}\n`, 'utf8') > limit) throw reject('limit', 'output', scope, state);
+  return text;
+}
+
+module.exports = { readPage, adapt, serialize, reject, bindingPath, RESPONSE_LIMIT, OUTPUT_LIMIT };

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

@@ -0,0 +1,135 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["kdtId", "pageNo", "pageSize"],
+    "description": "规范化业务输入，不是接收 JSON 的参数。目标默认有效上下文店铺，格式与预览控制不进入此模型。",
+    "properties": {
+      "kdtId": { "$ref": "#/definitions/shopId" },
+      "keyword": {
+        "type": "string", "minLength": 1, "maxLength": 200,
+        "pattern": "^\\S(?:[\\s\\S]*\\S)?$",
+        "description": "可选的分群名称关键词，去首尾空白后非空，最多200字符；按原生检索，不承诺分词或精确匹配。"
+      },
+      "pageNo": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "本次页码，默认1，上限10000是CLI预算。" },
+      "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "本页容量，默认20，上限100是CLI预算，不是总数。" }
+    }
+  },
+  "output": {
+    "type": "object", "additionalProperties": false, "required": ["data"],
+    "description": "同店核验后一页分群目录的有限视图，全部校验通过才输出。",
+    "properties": {
+      "data": {
+        "type": "object", "additionalProperties": false, "required": ["segments", "pagination"],
+        "description": "本次范围内的目录和分页，不含成员、逐群规则或完整快照。",
+        "properties": {
+          "segments": {
+            "type": "array", "maxItems": 100, "description": "本页分群，数量不超过pageSize，保留源顺序和同名记录；空数组仅表示本次没有返回条目。",
+            "items": {
+              "type": "object", "additionalProperties": false, "required": ["segmentId", "name"],
+              "description": "以稳定ID引用的已保存分群；可选字段缺省省略，返回null或错型整体失败。",
+              "properties": {
+                "segmentId": { "type": "string", "pattern": "^[1-9]\\d{0,18}$", "description": "分群正Long十进制字符串，1..9223372036854775807，无损保留，同页不允许重复；不是客户ID。" },
+                "name": { "type": "string", "description": "分群名称，合法空串保留，可以重名，名称不证明规则正确。" },
+                "customerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "可选的本次报告客户数，0保留，不是实时成员快照或历史名单。" },
+                "type": { "type": "string", "minLength": 1, "description": "可选分群类型代码。string \"0\"=自定义人群，string \"4\"=系统推荐；未来非空string原样保留，不自动转换number或按类型隐藏记录。" },
+                "editorMode": { "type": "string", "minLength": 1, "description": "可选规则编辑器表现模式。string \"simple_version\"=简单编辑器模式，string \"advance_version\"=高级编辑器模式；未来非空string原样保留，不推定规则版本或引擎。" }
+              }
+            }
+          },
+          "pagination": {
+            "type": "object", "additionalProperties": false, "required": ["pageNo", "pageSize", "hasMore"],
+            "description": "本次响应分页，不补造缺失的源页码或容量；不承诺跨页排序或快照。",
+            "properties": {
+              "pageNo": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "响应页码，必须与本次输入一致。" },
+              "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "description": "响应页容量，必须与本次输入一致。" },
+              "total": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。" },
+              "hasMore": { "type": ["boolean", "null"], "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "additionalProperties": false, "required": ["requests"],
+    "description": "纯本地两请求计划，不读取凭证或认证，不证明权限、对象或总数。关键词遮盖为***。",
+    "properties": {
+      "requests": {
+        "type": "array", "minItems": 2, "maxItems": 2, "additionalItems": false,
+        "description": "固定先绑定店铺、再读一页目录，主请求的request为JSON文本。",
+        "items": [
+          {
+            "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+            "properties": {
+              "method": { "const": "POST", "description": "计划请求方法。" },
+              "path": { "const": "youzan.shop.basic.get/3.0.0", "description": "计划店铺核验路径。" },
+              "body": { "type": "object", "additionalProperties": false, "maxProperties": 0, "description": "空店铺核验请求。" }
+            }
+          },
+          {
+            "type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+            "properties": {
+              "method": { "const": "POST", "description": "计划请求方法。" },
+              "path": { "const": "youzan.crm.crowd.list/1.0.0", "description": "计划目录查询路径。" },
+              "body": {
+                "type": "object", "additionalProperties": false, "required": ["request"],
+                "description": "一页查询计划，无额外店铺字段。",
+                "properties": {
+                  "request": { "type": "string", "description": "JSON对象文本，只含page_no、page_size和可选keyword；预览keyword固定***。" }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "error": {
+    "type": "object", "additionalProperties": false, "required": ["success", "code", "message", "details"],
+    "properties": {
+      "success": { "const": false },
+      "code": { "const": -10001 },
+      "message": { "type": "string", "minLength": 1, "description": "受控错误，不回显关键词、凭证、自由消息或响应原文。" },
+      "details": {
+        "type": "object", "additionalProperties": false,
+        "required": ["category", "stage", "command", "targetScope", "requestState", "nextStep"],
+        "properties": {
+          "category": {
+            "enum": ["validation", "configuration", "authentication", "permission", "scope_unresolved", "http", "business_rejected", "transport", "protocol", "limit"],
+            "description": "validation输入错误；configuration配置不可用；authentication认证失败；permission权限拒绝；scope_unresolved店铺未确认；http请求拒绝；business_rejected业务拒绝；transport传输失败；protocol协议不符；limit超预算。"
+          },
+          "stage": { "enum": ["input", "context", "configuration", "shop-binding", "list", "output"], "description": "input本地输入；context上下文；configuration公共环境；shop-binding同店核验；list目录请求；output视图验证。" },
+          "command": { "const": "customer.segment.list" },
+          "targetScope": { "type": "object", "additionalProperties": false, "description": "已确认的本次目标店铺，尚未确定时为空，不含关键词。", "properties": { "kdtId": { "$ref": "#/definitions/shopId" } } },
+          "requestState": { "enum": ["not_sent", "sent", "unknown"], "description": "not_sent相关失败请求未发送；sent已收到响应但不代表业务成功；unknown发送后结果不明，不重放。" },
+          "nextStep": { "type": "string", "minLength": 1, "description": "保留原目标排查，不自动重试、切店或换身份。" },
+          "api": { "enum": ["youzan.shop.basic.get/3.0.0", "youzan.crm.crowd.list/1.0.0"] },
+          "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": {
+    "shopId": { "type": "string", "pattern": "^[1-9]\\d*$", "maxLength": 16, "description": "目标店铺正安全整数ID文本，1..9007199254740991；默认有效context.shopId，显式非法值不回退。" },
+    "diagnosticCode": { "anyOf": [{ "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "pattern": "^-?\\d{1,12}$" }], "description": "受限业务或网关代码，不包含自由消息。" },
+    "trace": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$", "description": "受限请求追踪标识。" }
+  },
+  "api": { "method": "POST", "path": "youzan.crm.crowd.list/1.0.0" },
+  "success": { "description": "同店核验、一页目录、稳定ID及所选字段、分页和预算全部满足后，一次输出data，不返回部分成功。" },
+  "errors": { "description": "失败stdout为空，stderr为一份脱敏JSON，退出码非零。不重试、重定向、换店、换身份或降级到其他查询。" },
+  "notes": [
+    "分群是已保存的客户分群定义，规则形成动态成员；目录人数只是本次报告数，不代表成员快照或计算截止时间。名称不唯一，不能由名称推断规则正确。",
+    "目录读取不保证覆盖全店所有系统、推荐或其他产品分群；不隐藏返回的已知或未来类型。不提供规则、成员、扫描、排序或include。",
+    "真实执行需要userId、hq、shopId、orgType四字段上下文。非总部目标须匹配shopId，总部仍需同店核验和服务端授权。绑定和at声明不证明员工权限。",
+    "只有缺少上下文时可用显式合法目标本地预览；无效或冲突上下文即使预览也拒绝。关键词遮盖，预览不读取凭证或发认证请求。",
+    "最多两次业务请求，每次10秒，累计业务响应10MiB，最终UTF-8输出含换行5MiB。超限整体失败，不裁剪字段或目录。",
+    "仅读取本页。保留keyword和pageSize，显式递增合法pageNo可继续读取；总数未知时hasMore为null，第10000页不能继续。不保证跨页稳定排序、快照或无遗漏。",
+    "未核实的日期、描述、version不进入结果。当前没有分群详情、成员或写入命令，不能把目录当成员名单。"
+  ]
+}