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

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

@@ -0,0 +1,96 @@
+{
+  "schemaVersion": 3,
+  "domain": "customer",
+  "businessCommands": [
+    {
+      "path": "customer.customer.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/customer/get/command.js",
+      "fingerprint": "2e9565e2ab0891042d85257c31c721746ffc183f7613e2483f1fae8652c6889f"
+    },
+    {
+      "path": "customer.customer.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/customer/list/command.js",
+      "fingerprint": "fba8479d7ba8519d0cd3daf3bbeec97c4c7440241f08ab06db16645a9e46ce0b"
+    },
+    {
+      "path": "customer.customer.scan",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/customer/scan/command.js",
+      "fingerprint": "080a670afe0bc3ad2c3cbb81d42ef6c3010719135b360af08edda39a87de1b10"
+    },
+    {
+      "path": "customer.customer-tag.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/customer-tag/get/command.js",
+      "fingerprint": "4a58ad508c8e58b53eef31c755d7682a44a09da12049dc66486b7b7b6c0dc04e"
+    },
+    {
+      "path": "customer.customer-tag.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/customer-tag/list/command.js",
+      "fingerprint": "60e6f754b729a536d83aa3c01a5f0069a2bdb3d927129cdc4497e6f04cff2b47"
+    },
+    {
+      "path": "customer.segment.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/segment/list/command.js",
+      "fingerprint": "de16f1c293580825ea5ebf4cdf01fccbc8af27de5852027537228ec1467b5171"
+    },
+    {
+      "path": "customer.segment-customer.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/segment-customer/list/command.js",
+      "fingerprint": "280e382e6fed355e6901888a0f7c2fb6923ea6ba809d4ec8e3c1e438b84ac913"
+    },
+    {
+      "path": "customer.tag.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "customer/tag/get/command.js",
+      "fingerprint": "306903ec91ccca08a1a5d52877b2eb253db866b7ef443dc4f6e5607f4d35cc01"
+    },
+    {
+      "path": "customer.tagcategory.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/tagcategory/get/command.js",
+      "fingerprint": "4a205a901d0842b5e39d0455b6d5a8adde3cc480fb9167f21a04e6d8b03feed4"
+    },
+    {
+      "path": "customer.tagcategory.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "customer/tagcategory/list/command.js",
+      "fingerprint": "988fe0d0c3e79b9f3abbb91be159a0d727319bbd5d96ea0406526d7e77828cb5"
+    }
+  ]
+}

package/src/commands/native/customer/customer/get/adapter.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const schema = require('./schema.json');
+const { normalizeMoney } = require('../../../../../execution/money');
+const { normalizeTimes } = require('../../../../../execution/datetime');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { getNestedValue, validateRequiredModules } = require('../../../../../execution/command-io');
+const {
+  QueryError, object, assertSafeNumbers, assertApiSuccess
+} = require('../../../../../execution/query-api');
+
+const command = 'customer.customer.get';
+const nextStep = '核对本条命令的 help/schema、原店铺和客户标识及服务端授权；不自动切换目标、身份或创建客户。';
+const moduleSources = {
+  level_summary: { selector: 'benefit_level' },
+  valuecard_balance: { selector: 'prepaid', balanceField: 'prepaid_balance' },
+  valuecard_gift: { selector: 'giftcard', balanceField: 'giftcard_balance' }
+};
+
+function upstreamModule(name) {
+  return moduleSources[name]?.selector || name;
+}
+
+function failure(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = new QueryError(category, stage, scope, facts, requestState, command, nextStep);
+  error.message = `客户查询失败：${category}（${stage}）。请查看 zan-saas customer customer get --help。`;
+  return error;
+}
+
+function assertCustomerSuccess(result, scope, facts) {
+  assertApiSuccess(result, category => {
+    throw failure(category, 'customer', scope, 'sent', facts);
+  });
+}
+
+function moduleModel(name) {
+  const reference = schema.output.properties.data.properties[name].$ref;
+  return schema.definitions[reference.slice('#/definitions/'.length)];
+}
+
+function projectFields(value, model) {
+  if (model.$ref) model = schema.definitions[model.$ref.slice('#/definitions/'.length)];
+  if (Array.isArray(value) && model.items) {
+    return value.map(item => projectFields(item, model.items));
+  }
+  if (object(value) && model.properties) {
+    return Object.fromEntries(Object.entries(model.properties)
+      .filter(([key]) => Object.hasOwn(value, key))
+      .map(([key, child]) => [key, projectFields(value[key], child)]));
+  }
+  return value;
+}
+
+function adaptCustomer(result, input, facts) {
+  const { include, kdtId, yzOpenId } = input;
+  const scope = { kdtId };
+  const invalid = () => failure('protocol', 'customer-model', scope, 'sent', facts);
+  if (!object(result.data) || result.data.yz_open_id !== yzOpenId) throw invalid();
+  try {
+    const data = {};
+    for (const name of ['user_base', ...include]) {
+      const source = getNestedValue(result, schema.modules[name].upstreamPath);
+      if (!object(source)) throw invalid();
+      const model = moduleModel(name);
+      const balanceField = moduleSources[name]?.balanceField;
+      const fields = balanceField
+        ? (Object.hasOwn(source, balanceField) ? { totalBalance: source[balanceField] } : {})
+        : source;
+      const projected = projectFields(fields, model);
+      assertSafeNumbers(projected);
+      data[name] = normalizeTimes(normalizeMoney(projected, model), model, schema.definitions);
+    }
+    validateRequiredModules(data, new Set(include), ['user_base']);
+    const output = { data };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch {
+    throw invalid();
+  }
+}
+
+module.exports = { failure, assertCustomerSuccess, adaptCustomer, upstreamModule };

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

@@ -0,0 +1,106 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, withInputScope, constraints, modelAt } = require('../../../../../execution/error-details');
+const schema = require('./schema.json');
+const { queryDefinition, validateCommandValue } = require('../../../../../execution/command-schema');
+const { parseIncludeModules } = require('../../../../../execution/command-io');
+const { readApiEnvelope } = require('../../../../../execution/query-api');
+const { failure, assertCustomerSuccess, adaptCustomer, upstreamModule } = require('./adapter');
+
+const { includeModules } = queryDefinition(schema);
+
+function buildInput(options, context) {
+  if (typeof options.kdtId !== 'string' || options.kdtId !== options.kdtId.trim() ||
+      !/^[1-9]\d*$/.test(options.kdtId) || !Number.isSafeInteger(Number(options.kdtId))) {
+    throw inputIssue('/kdtId', 'invalid_format', constraints(modelAt(schema, 'input', '/kdtId')));
+  }
+  const input = withInputScope({ kdtId: Number(options.kdtId) }, () => {
+    if (typeof options.yzOpenId !== 'string') {
+      throw inputIssue('/yzOpenId', 'invalid_type', constraints(modelAt(schema, 'input', '/yzOpenId')));
+    }
+    const normalized = { kdtId: Number(options.kdtId), yzOpenId: options.yzOpenId.trim(),
+      include: [...parseIncludeModules(options.include, includeModules, '/include')] };
+    validateCommandValue(schema, 'input', normalized);
+    return normalized;
+  });
+  const scope = { kdtId: input.kdtId };
+  if (context?.orgType === 'shop' && String(input.kdtId) !== context.shopId) {
+    throw failure('permission', 'scope', scope);
+  }
+  return input;
+}
+
+function requestFor(input) {
+  return {
+    method: 'POST',
+    path: schema.api.path,
+    body: {
+      kdt_id: input.kdtId, yz_open_id: input.yzOpenId,
+      fields: ['user_base', ...input.include.map(upstreamModule)].join(',')
+    }
+  };
+}
+
+async function execute(input, request) {
+  const scope = { kdtId: input.kdtId };
+  const { result, facts } = await readApiEnvelope(request.path, request.body,
+    (category, details, state, stage) => failure(category, stage, scope, state, details));
+  assertCustomerSuccess(result, scope, facts);
+  return adaptCustomer(result, input, facts);
+}
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('get', { path: 'customer.customer.get', schema, parameterCategory: 'parameter' })
+    .description('查询客户基础资料，可追加标签、等级关系、积分、交易及资产摘要')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺 ID，正安全整数；省略时使用当前上下文店铺')
+    .requiredOption('--yz-open-id <id>', '必填：该店铺客户的 yzOpenId，非空字符串；不是手机号')
+    .option('--include <modules>', `追加模块：${includeModules.join(', ')}；始终请求 user_base`)
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地校验并预览请求，不读凭证、不联网')
+    .addHelpText('after', `
+默认返回 data.user_base。--include 追加模块，不替换基础资料；空值、空项和未知模块均拒绝。
+基础视图只选 yz_open_id、name、show_name、mobile、gender、created_at；除客户主键外可省略。
+模块按字段对象组织，如 data.tags.tags、data.level.level_infos、data.credit.points，不重复tag_ids。
+level 是免费/付费等级关系摘要；level_summary 是单值等级摘要，不据此推算等级关系或会员身份。
+valuecard_balance、valuecard_gift 分别是余额卡、礼品卡余额摘要，均以 totalBalance 返回。
+两类摘要的归集范围未明确，不相加为客户总资产，不断言与逐卡余额求和相等。
+benefit_cards 的 id 是客户卡摘要标识，不能当作 cardAlias 或 cardNo 使用。
+时间点统一输出北京时间 YYYY-MM-DD HH:mm:ss.SSS，字段声明的业务哨兵保留。
+behavior只含购买/退款次数、金额和最近购买时间，不含全渠道汇总；credit只含当前points。
+四个已定义金额由接口分整数精确转为元两位字符串，例如 "159.00"，不能再次除以100。
+只返回所选字段，数组元素也按模型裁取；未选择的API字段或新增扩展不影响本视图。
+可选明细缺失时省略，不证明无值；已选字段错型/null或请求模块缺少核心内容时整体失败。
+只支持官方 success=true、数字code=200、扁平data信封，不猜测旧response.customer包装。
+不提供手机号定位、客户列表、入会、发卡或任意字段选择，不派生会员身份。
+完整字段、单位、必需内容和可选明细规则见 zan-saas schema customer.customer.get。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+非总部目标须等于上下文shopId；总部显式目标的归属和权限由服务端校验。
+缺少上下文可本地预览，已提供无效或冲突上下文则拒绝。
+一次调用至多1个业务请求，不自动重试、重定向、切店或换身份。
+保留服务端查询扩展点默认值；只读分类不证明服务端自定义扩展无副作用。
+成功/预览stdout为一份JSON，失败stdout为空、stderr为错误JSON。当前未证明真实员工网关和字段可见性。
+
+示例：
+  zan-saas customer customer get --kdt-id 63077 --yz-open-id customer-1
+  zan-saas customer customer get --kdt-id 63077 --yz-open-id customer-1 --include tags,level --format pretty
+  zan-saas customer customer get --kdt-id 63077 --yz-open-id customer-1 --include credit,valuecard_balance --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const request = requestFor(input);
+      let result;
+      if (options.dryRun) {
+        validateCommandValue(schema, 'preview', request);
+        result = request;
+      } else result = await execute(input, request);
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };