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

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

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": 3,
+  "domain": "member",
+  "businessCommands": [
+    {
+      "path": "member.customer-level.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/customer-level/get/command.js",
+      "fingerprint": "063b35ccc6b58b76177ee9a795e1af587ff6a9359cd8d21f1fc92467bbe44621"
+    },
+    {
+      "path": "member.growth.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/growth/get/command.js",
+      "fingerprint": "63a83688cf2d6f04a7bc7c93ee4a56d825e559cdf68534404cb8ce99aecf7c12"
+    },
+    {
+      "path": "member.growth-log.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/growth-log/list/command.js",
+      "fingerprint": "94201dd01aa8de4189604afe7cd451975830555fea5f1d348239e5eab98ec935"
+    },
+    {
+      "path": "member.level.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/level/get/command.js",
+      "fingerprint": "75de5b4aeab1b821d50cbb285011f9dfe06fbc94cecb0d74c98768ce8d74ac0a"
+    },
+    {
+      "path": "member.level.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/level/list/command.js",
+      "fingerprint": "63315ed21f4222807353fa592caa73986d588200dc6a37974b10fbdcd7626874"
+    },
+    {
+      "path": "member.membership.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "member/membership/get/command.js",
+      "fingerprint": "9844185dc0e14890211624538193a8546a61d05f14a426fa86532ac46fead7da"
+    }
+  ]
+}

package/src/commands/native/member/customer-level/get/command.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const schema = require('./schema.json');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const {
+  QueryError, readApiEnvelope, object, assertSafeNumbers, diagnosticCode
+} = require('../../../../../execution/query-api');
+
+const commandPath = 'member.customer-level.get';
+const nextStep = '核对本命令 help/schema、原店铺、客户标识和服务端授权；不自动重试、切店、换身份或创建客户。';
+
+function failure(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  return new QueryError(category, stage, scope, facts, requestState, commandPath, nextStep);
+}
+
+function buildInput(options, context) {
+  const scope = resolveTargetShop(options, context, commandPath);
+  try {
+    const input = { ...scope, yzOpenId: options.yzOpenId.trim() };
+    validateCommandValue(schema, 'input', input);
+    return Object.freeze(input);
+  } catch {
+    throw failure('parameter', 'input', scope);
+  }
+}
+
+function assertSuccess(result, scope, facts) {
+  const reject = category => {
+    throw failure(category, 'customer-level', scope, 'sent', facts);
+  };
+  if (Object.hasOwn(result, 'gw_err_resp')) {
+    if (result.success === true || result.code === 200) reject('protocol');
+    if (object(result.gw_err_resp) && diagnosticCode(result.gw_err_resp.err_code)) {
+      reject('business_rejected');
+    }
+    reject('protocol');
+  }
+  if (result.success === false) {
+    reject(result.code === 200 ? 'protocol' : 'business_rejected');
+  }
+  if (result.success === undefined && Number.isSafeInteger(result.code) &&
+      ![0, 200].includes(result.code)) reject('business_rejected');
+  if (result.success !== true || result.code !== 200) reject('protocol');
+}
+
+function adaptLevels(result, input, facts) {
+  const invalid = () => failure('protocol', 'customer-level-model',
+    { kdtId: input.kdtId }, 'sent', facts);
+  if (!object(result.data) || result.data.yz_open_id !== input.yzOpenId ||
+      !Array.isArray(result.data.level_infos)) throw invalid();
+  try {
+    const levelInfos = result.data.level_infos.map(record => {
+      if (!object(record)) throw invalid();
+      return Object.fromEntries(['level_alias', 'level_name', 'level_type', 'level_value']
+        .filter(field => Object.hasOwn(record, field)).map(field => [field, record[field]]));
+    });
+    const output = { data: { customer_level: { level_infos: levelInfos } } };
+    assertSafeNumbers(output);
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch {
+    throw invalid();
+  }
+}
+
+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');
+    })
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId，非空字符串；不是手机号')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地校验并预览，不读取凭证、不联网')
+    .addHelpText('after', `
+仅返回 data.customer_level.level_infos；不返回客户档案、成长值或推断会员身份。
+固定请求 fields=level，不提供 --fields/--include，不附加其他模块或辅助请求。
+保留全部免费/付费记录、顺序和重复；不取第一条、不排序、不从成长值推算。
+客户标识必须匹配，明确 [] 才是无等级；缺字段、null、错型或模块失败整体失败。
+每条记录必须包含 level_alias、level_name、level_type、level_value，其他源字段忽略。
+只接受 success=true、数字 code=200、扁平 data，不用整数 data.level 回填。
+--kdt-id 显式值优先，非法显式值不回退；非总部须匹配上下文 shopId。
+总部默认当前总部店铺，不遍历下属店铺；范围授权由服务端校验，不以本地目标解析证明。
+真实执行需有效四字段上下文并满足目标范围授权；没有上下文时，仅显式店铺可本地预览。
+一次调用最多一个业务请求，不重试、跟随重定向、切换店铺或身份。
+保留服务端查询扩展点默认值；只读分类不证明自定义扩展点无副作用。
+成功/预览 stdout 为一份 JSON；失败 stdout 为空，stderr 为安全结构化错误。
+完整字段和验证边界见 zan-saas schema member.customer-level.get。
+
+示例：
+  zan-saas member customer-level get --yz-open-id customer-1
+  zan-saas member customer-level get --yz-open-id customer-1 --kdt-id 63077 --format pretty
+  zan-saas member customer-level get --yz-open-id customer-1 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const request = { method: 'POST', path: schema.api.path,
+        body: { kdt_id: input.kdtId, yz_open_id: input.yzOpenId, fields: 'level' } };
+      let output;
+      if (options.dryRun) {
+        validateCommandValue(schema, 'preview', request);
+        output = request;
+      } else {
+        const scope = { kdtId: input.kdtId };
+        const { result, facts } = await readApiEnvelope(request.path, request.body,
+          (category, details, state, stage) => failure(category, stage, scope, state, details));
+        assertSuccess(result, scope, facts);
+        output = adaptLevels(result, input, facts);
+      }
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/member/customer-level/get/schema.json

@@ -0,0 +1,300 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "yzOpenId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId",
+        "description": "显式 --kdt-id 优先；省略取本次有效 context.shopId，不是静态默认。"
+      },
+      "yzOpenId": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "\\S",
+        "description": "去除首尾空白后的有赞客户 yzOpenId，不接受手机号或其他帐号替代。"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "customer_level"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "customer_level": {
+            "type": "object",
+            "required": [
+              "level_infos"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "level_infos": {
+                "type": "array",
+                "description": "原序保留所有免费及付费等级、重复记录，不推算。仅成功且客户主键匹配时明确 [] 表示无等级；缺失/null/非数组失败。",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "level_alias",
+                    "level_name",
+                    "level_type",
+                    "level_value"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "level_alias": {
+                      "type": "string",
+                      "description": "等级别名设置，原样保留，不作唯一性推断。"
+                    },
+                    "level_name": {
+                      "type": "string",
+                      "description": "等级名称，原样保留。"
+                    },
+                    "level_type": {
+                      "type": "integer",
+                      "enum": [
+                        1,
+                        2
+                      ],
+                      "description": "1 免费等级，2 付费等级；未知类型失败，不转换成无等级。"
+                    },
+                    "level_value": {
+                      "$ref": "#/definitions/safeInteger",
+                      "description": "等级值，保留整数 0；不是成长值或稳定等级 ID。"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.customer.detail.get/1.0.1"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "kdt_id",
+          "yz_open_id",
+          "fields"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdt_id": {
+            "$ref": "#/definitions/shopId"
+          },
+          "yz_open_id": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "fields": {
+            "const": "level"
+          }
+        }
+      }
+    }
+  },
+  "error": {
+    "type": "object",
+    "required": [
+      "success",
+      "code",
+      "message",
+      "details"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "success": {
+        "const": false
+      },
+      "code": {
+        "const": -10001
+      },
+      "message": {
+        "type": "string",
+        "minLength": 1
+      },
+      "details": {
+        "type": "object",
+        "required": [
+          "category",
+          "stage",
+          "command",
+          "targetScope",
+          "requestState",
+          "nextStep"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string",
+            "enum": [
+              "parameter",
+              "validation",
+              "configuration",
+              "permission",
+              "authentication",
+              "http",
+              "transport",
+              "business_rejected",
+              "protocol"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "enum": [
+              "input",
+              "validation",
+              "context",
+              "scope",
+              "configuration",
+              "http",
+              "transport",
+              "response",
+              "customer-level",
+              "customer-level-model"
+            ]
+          },
+          "command": {
+            "const": "member.customer-level.get"
+          },
+          "targetScope": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/scope"
+              },
+              {
+                "type": "object",
+                "maxProperties": 0
+              }
+            ]
+          },
+          "requestState": {
+            "type": "string",
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string",
+            "minLength": 1
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "gatewayCode": {
+            "$ref": "#/definitions/diagnosticCode"
+          },
+          "trace_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          },
+          "request_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "safeInteger": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "$ref": "#/definitions/shopId"
+        }
+      }
+    },
+    "diagnosticCode": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/safeInteger"
+        },
+        {
+          "type": "string",
+          "pattern": "^-?\\d{1,12}$"
+        }
+      ]
+    }
+  },
+  "modules": {
+    "customer_level": {
+      "base": true,
+      "upstreamPath": "data",
+      "required": true,
+      "description": "目标客户的等级关系有限视图，不是等级定义或入会状态。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.customer.detail.get/1.0.1"
+  },
+  "success": {
+    "description": "客户 ID 精确匹配，等级集合明确取得且每条四字段完整后整体输出。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "只返回目标客户当前等级关系的有限视图，不推导会员身份或等级定义；每条等级的四个字段均必需。",
+    "等级集合必须明确读取成功；缺失或 null 不补空数组，未取得不表示无等级。",
+    "--kdt-id 省略取有效上下文 shopId，显式非法值不回退；非总部不切店，总部不自动遍历。",
+    "本地目标校验不证明凭证店铺绑定或员工授权；应用样本不能代替员工链路验收。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "会员：身份、等级、成长值与变更记录"
+}

package/src/commands/native/member/growth/get/command.js

@@ -0,0 +1,64 @@
+'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 command = 'member.growth.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('查询一个客户的当前成长值，不推算等级或积分')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .requiredOption('--yz-open-id <id>', '必填：客户 yzOpenId；不是手机号、微信 openId 或员工 ID')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验和成长值请求，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.growth_account.growth，保留 0 和负整数；客户不存在不能补成 0。
+先核验凭证店铺，再读取一个客户；固定账号类型，不自动切换编码、身份或店铺。
+最多一次店铺核验与一次成长值请求，不读取流水、不重试，保留扩展点默认行为。
+真实执行需有效四字段上下文和同店授权凭证；店铺核验不证明员工 OAuth。
+契约：zan-saas schema member.growth.get
+示例：zan-saas member growth get --yz-open-id customer-1 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try {
+        input = { ...scope, yzOpenId: options.yzOpenId.trim() };
+        validateCommandValue(schema, 'input', input);
+      } catch { throw reject('parameter', 'input', scope); }
+      const preview = {
+        method: 'POST', path: schema.api.path,
+        body: { params: { user: { account_type: 5, account_id: input.yzOpenId } } },
+        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, 'growth-account');
+        if (!object(data) || !Number.isSafeInteger(data.growth)) {
+          throw reject('protocol', 'growth-account-model', scope, 'sent', facts);
+        }
+        output = { data: { growth_account: { growth: data.growth } } };
+        validateCommandValue(schema, 'output', output);
+      }
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };