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

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

@@ -0,0 +1,70 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { createShopQuery, failure } = require('../../../../../execution/shop-query');
+const {
+  buildLevelInvocation, executeLevelInvocation, LevelDefinitionError
+} = require('./query');
+
+const command = 'member.level.get';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('按完整 alias 查询一个等级定义，保留已禁用等级')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .requiredOption('--level-alias <alias>', '必填：完整等级别名；不是等级 ID、名称或序号')
+    .addOption(new Option('--level-type <type>', '1 免费，2 付费；省略时依次查询两类')
+      .choices(['1', '2']))
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览店铺核验和固定查询计划，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.level；alias 唯一匹配才成功，不以等级值或名称替代主键。
+先核验凭证店铺，再请求指定类型一次，或按 1、2 固定请求两次。
+任一必要请求失败、重复匹配或模型不符整体失败；未返回不表示全局不存在。
+不分页、不返回全部权益、不重试、不切换店铺或身份。
+真实执行需有效四字段上下文和同店授权凭证；店铺回读不证明员工 OAuth。
+契约：zan-saas schema member.level.get
+示例：zan-saas member level get --level-alias level-1 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      let invocation;
+      try { invocation = buildLevelInvocation(options, context); }
+      catch (error) {
+        if (error.cliDetails) throw error;
+        throw reject('parameter', 'input');
+      }
+      let output;
+      if (invocation.dryRun) {
+        output = invocation.plan;
+      } else {
+        const scope = invocation.plan.scope;
+        const read = await createShopQuery(scope, command);
+        let facts = {};
+        try {
+          output = await executeLevelInvocation(invocation, async request => {
+            const result = await read(request.path, request.body, 'level');
+            facts = result.facts;
+            return result.data;
+          });
+        } catch (error) {
+          if (!(error instanceof LevelDefinitionError)) throw error;
+          const category = error.code === 'LEVEL_NOT_RETURNED' ? 'not_found' :
+            error.code === 'LEVEL_AMBIGUOUS' ? 'ambiguous' : 'protocol';
+          throw reject(category, error.stage, scope, 'sent', 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/level/get/query.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { bindingPath } = require('../../../../../execution/shop-query');
+const schema = require('./schema.json');
+
+class LevelDefinitionError extends Error {
+  constructor(code, stage, message) {
+    super(message);
+    this.name = 'LevelDefinitionError';
+    this.code = code;
+    this.stage = stage;
+  }
+}
+
+function invalidInput() {
+  return new LevelDefinitionError('LEVEL_PARAMETER', 'selection-input',
+    'Level lookup requires a positive safe target, a nonempty alias, an optional type of exactly 1 or 2 and json or pretty format.');
+}
+
+function parseLevelSelection(options) {
+  if (typeof options?.levelAlias !== 'string' || !options.levelAlias.trim()) {
+    throw invalidInput();
+  }
+  const selection = { levelAlias: options.levelAlias.trim() };
+  if (options.levelType !== undefined) {
+    if (!['1', '2'].includes(options.levelType)) throw invalidInput();
+    selection.levelType = Number(options.levelType);
+  }
+  return selection;
+}
+
+function buildLevelPlan(input) {
+  try { validateCommandValue(schema, 'input', input); }
+  catch { throw invalidInput(); }
+  const scope = Object.freeze({ kdtId: input.kdtId });
+  const selection = Object.freeze({ levelAlias: input.levelAlias });
+  const types = input.levelType === undefined ? [1, 2] : [input.levelType];
+  const requests = Object.freeze(types.map(levelType => Object.freeze({
+    method: 'POST',
+    path: schema.api.path,
+    body: Object.freeze({ level_type: levelType })
+  })));
+  const prerequisites = Object.freeze([Object.freeze({
+    method: 'POST', path: bindingPath, body: Object.freeze({})
+  })]);
+  const plan = Object.freeze({ scope, requests, selection, prerequisites });
+  validateCommandValue(schema, 'preview', plan);
+  return plan;
+}
+
+function buildLevelInvocation(options, context) {
+  const scope = resolveTargetShop(options, context, 'member.level.get');
+  const selection = parseLevelSelection(options);
+  if (options.format !== undefined && !['json', 'pretty'].includes(options.format)) {
+    throw invalidInput();
+  }
+  const input = Object.freeze({ ...scope, ...selection });
+  return Object.freeze({
+    input,
+    plan: buildLevelPlan(input),
+    format: options.format ?? 'json',
+    dryRun: options.dryRun === true
+  });
+}
+
+async function executeLevelInvocation(invocation, readData) {
+  if (invocation.dryRun) return invocation.plan;
+  return getLevelDefinition(invocation.input, readData);
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function invalidList() {
+  return new LevelDefinitionError('LEVEL_PROTOCOL', 'level-list',
+    'Expected data.level_details with nonempty aliases and the requested level type.');
+}
+
+async function getLevelDefinition(input, readData) {
+  const plan = buildLevelPlan(input);
+  if (typeof readData !== 'function') throw new TypeError('A scoped data reader is required');
+  const matches = [];
+  for (const request of plan.requests) {
+    const data = await readData(request, plan.scope);
+    if (!object(data) || !Array.isArray(data.level_details)) throw invalidList();
+    for (const candidate of data.level_details) {
+      if (!object(candidate) || typeof candidate.level_alias !== 'string' ||
+          !candidate.level_alias.trim() || candidate.level_type !== request.body.level_type) {
+        throw invalidList();
+      }
+      if (candidate.level_alias === plan.selection.levelAlias) {
+        matches.push({
+          level_alias: candidate.level_alias,
+          name: candidate.name,
+          level_type: candidate.level_type,
+          level_value: candidate.level_value,
+          is_enabled: candidate.is_enabled
+        });
+      }
+    }
+  }
+  if (!matches.length) {
+    throw new LevelDefinitionError('LEVEL_NOT_RETURNED', 'level-selection',
+      'Alias was not returned in the queried types; verify scope and collection completeness.');
+  }
+  if (matches.length !== 1) {
+    throw new LevelDefinitionError('LEVEL_AMBIGUOUS', 'level-selection',
+      'Alias has multiple matches in the queried level definitions.');
+  }
+  const output = { data: { level: matches[0] } };
+  try { validateCommandValue(schema, 'output', output); }
+  catch {
+    throw new LevelDefinitionError('LEVEL_PROTOCOL', 'level-model',
+      'The matched definition does not satisfy the required base level model.');
+  }
+  return output;
+}
+
+module.exports = {
+  parseLevelSelection, buildLevelPlan, buildLevelInvocation, executeLevelInvocation,
+  getLevelDefinition, LevelDefinitionError
+};

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

@@ -0,0 +1,339 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "levelAlias"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991,
+        "description": "目标店铺 ID，省略选项时取有效上下文 shopId；不表示已经获准访问。"
+      },
+      "levelAlias": {
+        "type": "string",
+        "pattern": "\\S",
+        "description": "完整等级别名，按大小写精确匹配。"
+      },
+      "levelType": {
+        "type": "integer",
+        "enum": [
+          1,
+          2
+        ],
+        "description": "省略时固定依次查询免费和付费类型。"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "level"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "level": {
+            "type": "object",
+            "required": [
+              "level_alias",
+              "name",
+              "level_type",
+              "level_value",
+              "is_enabled"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "level_alias": {
+                "type": "string",
+                "pattern": "\\S",
+                "description": "等级别名，不用 ID、名称或序号替代。"
+              },
+              "name": {
+                "type": "string",
+                "description": "等级名称，空字符串原样保留。"
+              },
+              "level_type": {
+                "type": "integer",
+                "enum": [
+                  1,
+                  2
+                ],
+                "description": "1 为免费、2 为付费，须与请求类型相同。"
+              },
+              "level_value": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "安全整数等级值，不作为主键。"
+              },
+              "is_enabled": {
+                "type": "boolean",
+                "description": "是否启用，false 仍是可读取的等级定义。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "scope",
+      "requests",
+      "selection",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "type": "object",
+        "required": [
+          "kdtId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          }
+        }
+      },
+      "requests": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 2,
+        "items": {
+          "type": "object",
+          "required": [
+            "method",
+            "path",
+            "body"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "const": "POST"
+            },
+            "path": {
+              "const": "youzan.scrm.level.list/3.0.0"
+            },
+            "body": {
+              "type": "object",
+              "required": [
+                "level_type"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "level_type": {
+                  "type": "integer",
+                  "enum": [
+                    1,
+                    2
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "selection": {
+        "type": "object",
+        "required": [
+          "levelAlias"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "levelAlias": {
+            "type": "string",
+            "pattern": "\\S"
+          }
+        }
+      },
+      "prerequisites": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1,
+        "items": {
+          "type": "object",
+          "required": [
+            "method",
+            "path",
+            "body"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "method": {
+              "const": "POST"
+            },
+            "path": {
+              "const": "youzan.shop.basic.get/3.0.0"
+            },
+            "body": {
+              "type": "object",
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.level.list/3.0.0"
+  },
+  "modules": {
+    "level": {
+      "base": true,
+      "upstreamPath": "data.level_details",
+      "required": true,
+      "description": "查询集合中按完整 alias 唯一匹配的等级定义。"
+    }
+  },
+  "notes": [
+    "按完整 alias 唯一匹配等级定义，区分大小写；禁用等级仍可返回，0 和 false 原样保留。",
+    "--level-type 1 为免费等级，2 为付费等级；省略时依次读取两种类型，必要请求失败整体失败。",
+    "只返回基础定义字段，不返回完整权益、不分页；未返回不证明全局不存在。",
+    "店铺默认取有效上下文 shopId，显式非法值不回退，非总部不能跨店；预览零网络。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ],
+  "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": [
+              "validation",
+              "configuration",
+              "parameter",
+              "permission",
+              "authentication",
+              "scope_unresolved",
+              "transport",
+              "http",
+              "protocol",
+              "business_rejected",
+              "not_found",
+              "target_mismatch",
+              "ambiguous"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "member.level.get"
+          },
+          "targetScope": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kdtId": {
+                "$ref": "#/definitions/shopId"
+              }
+            }
+          },
+          "requestState": {
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ]
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string"
+          },
+          "httpStatus": {
+            "type": "integer"
+          },
+          "businessCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "string"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string"
+          },
+          "request_id": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    }
+  },
+  "success": {
+    "description": "必要类型均成功读取，完整 alias 唯一匹配，基础定义满足模型后成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  }
+}

package/src/commands/native/member/level/list/command.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { buildInput, preview, listLevels, serialize, reject } = require('./query');
+
+function createCommand({ context } = {}) {
+  const instance = new Command('list')
+    .description('查询商家当前免费、付费等级定义目录，保留禁用等级')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject('parameter', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取本次有效上下文 shopId')
+    .addOption(new Option('--level-type <type>', '1=免费等级，2=付费等级；省略依次查询两类')
+      .choices(['1', '2']))
+    .addOption(new Option('--format <format>', 'json=单行 JSON，pretty=缩进 JSON，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览目标和完整请求计划，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.levels，先免费再付费，各类保持响应原序，包含禁用及零等级值。
+level_id 仅在源返回时提供，不能用 level_value、alias 或其它 ID 补造。
+目录定义不证明客户实际获得等级；按 alias 读取定义用 member level get。
+默认含店铺核验及两次计费目录请求；指定类型含核验及一次目录请求。
+不分页、不排序、不返回完整权益；任一必要请求、字段或重复同类型 alias 异常整体失败。
+每类最多1000条，合计2000条；每请求10秒，累计响应10MiB，含换行输出5MiB。
+不截断、不重试、不切换店铺或身份。真实执行需有效四字段上下文和同店授权。
+店铺回读和应用身份测试不证明员工 OAuth 或跨店权限。
+契约：zan-saas schema member.level.list
+示例：zan-saas member level list --kdt-id 63077 --dry-run
+示例：zan-saas member level list --level-type 2 --format pretty
+`);
+  const supplied = new Set();
+  for (const option of instance.options) {
+    instance.on(`option:${option.name()}`, () => {
+      if (supplied.has(option.name())) throw reject('parameter', 'input');
+      supplied.add(option.name());
+    });
+  }
+  return instance.action(async options => {
+    const input = buildInput(options, context);
+    const output = options.dryRun ? preview(input) : await listLevels(input);
+    process.stdout.write(serialize(output, options.format, { kdtId: input.kdtId },
+      options.dryRun ? 'not_sent' : 'sent'));
+  });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/member/level/list/query.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { createBoundShopQuery, bindingPath, failure } = require('../../../../../execution/shop-query');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { object } = require('../../../../../execution/query-api');
+const schema = require('./schema.json');
+
+const command = 'member.level.list';
+const responseLimit = 10 * 1024 * 1024;
+const outputLimit = 5 * 1024 * 1024;
+
+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 = {}, stage = 'input', api) {
+  const details = error.cliDetails;
+  if (!details) return reject('protocol', stage, scope, 'unknown', api ? { api } : {});
+  const mappedStage = ['context', 'configuration'].includes(details.stage) ? details.stage : stage;
+  const facts = {};
+  for (const key of ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']) {
+    if (Object.hasOwn(details, key)) facts[key] = details[key];
+  }
+  if (api) facts.api = api;
+  return reject(details.category, mappedStage, details.targetScope ?? scope,
+    details.requestState, facts);
+}
+
+function buildInput(options, context) {
+  let scope;
+  try { scope = resolveTargetShop(options, context, command); }
+  catch (error) { throw adaptError(error); }
+  if (options.levelType !== undefined && !['1', '2'].includes(options.levelType)) {
+    throw reject('validation', 'input', scope);
+  }
+  const input = { ...scope };
+  if (options.levelType !== undefined) input.levelType = Number(options.levelType);
+  validateCommandValue(schema, 'input', input);
+  return Object.freeze(input);
+}
+
+function preview(input) {
+  const types = input.levelType === undefined ? [1, 2] : [input.levelType];
+  return {
+    scope: { kdtId: input.kdtId },
+    requests: [
+      { method: 'POST', path: bindingPath, body: {} },
+      ...types.map(levelType => ({ method: 'POST', path: schema.api.path, body: { level_type: levelType } }))
+    ]
+  };
+}
+
+function projectLevels(data, levelType, scope, facts) {
+  const invalid = () => reject('protocol', 'levels', scope, 'sent', facts);
+  if (!object(data) || !Array.isArray(data.level_details)) throw invalid();
+  if (data.level_details.length > 1000) throw reject('limit', 'levels', scope, 'sent', facts);
+  const seen = new Set();
+  return data.level_details.map(source => {
+    if (!object(source) || typeof source.level_alias !== 'string' || !source.level_alias.trim() ||
+        source.level_type !== levelType || seen.has(source.level_alias)) throw invalid();
+    seen.add(source.level_alias);
+    const level = {
+      level_alias: source.level_alias, name: source.name, level_type: source.level_type,
+      level_value: source.level_value, is_enabled: source.is_enabled
+    };
+    if (Object.hasOwn(source, 'level_id')) {
+      if (!Number.isSafeInteger(source.level_id) || source.level_id < 1) throw invalid();
+      level.level_id = String(source.level_id);
+    }
+    if (Object.hasOwn(source, 'min_growth')) {
+      if (!Number.isSafeInteger(source.min_growth)) throw invalid();
+      level.min_growth = source.min_growth;
+    }
+    try { validateCommandValue(schema, 'output', { data: { levels: [level] } }); }
+    catch { throw invalid(); }
+    return level;
+  });
+}
+
+async function listLevels(input) {
+  const plan = preview(input), scope = plan.scope;
+  let responseBytes = 0, read;
+  try {
+    ({ read } = await createBoundShopQuery(scope, command, 'shop-binding', {
+      onResponse(response) { responseBytes += response.responseBytes; },
+      transportOptions: { shopApp: false, timeoutMs: 10000,
+        maxResponseBytes: () => responseLimit - responseBytes }
+    }));
+  } catch (error) { throw adaptError(error, scope, 'shop-binding', bindingPath); }
+  const levels = [];
+  for (const request of plan.requests.slice(1)) {
+    let result;
+    try { result = await read(request.path, request.body, 'levels'); }
+    catch (error) { throw adaptError(error, scope, 'levels', request.path); }
+    levels.push(...projectLevels(result.data, request.body.level_type, scope, result.facts));
+  }
+  return { data: { levels } };
+}
+
+function serialize(output, format, scope, state = 'sent') {
+  const text = `${JSON.stringify(output, null, format === 'pretty' ? 2 : 0)}\n`;
+  if (Buffer.byteLength(text, 'utf8') > outputLimit) throw reject('limit', 'output', scope, state);
+  return text;
+}
+
+module.exports = { buildInput, preview, listLevels, projectLevels, serialize, reject };