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

package/src/commands/native/fulfillment/waybill/get/command.js

@@ -0,0 +1,193 @@
+'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 { readWaybill } = require('./response');
+const schema = require('./schema.json');
+
+const command = 'fulfillment.waybill.get';
+const path = schema.api.path;
+const nextStep = '核对物流公司 ID、运单号和平台发货记录；失败时停止，不自动切换店铺、身份或接口。';
+const reject = (category, stage, scope, state = 'not_sent', facts = {}) => {
+  const error = failure(command, category, stage, scope, state, facts);
+  error.cliDetails.nextStep = nextStep;
+  return error;
+};
+const safeNumber = value => typeof value === 'number' && Number.isSafeInteger(value);
+
+function scopeFor(input) {
+  return { kdtId: input.kdtId, carrierId: input.carrierId,
+    waybillSuffix: input.waybillNo.slice(-4) };
+}
+
+function addScope(error, input) {
+  if (error?.cliDetails) {
+    error.cliDetails.targetScope = scopeFor(input);
+  }
+  return error;
+}
+
+function maskedWaybill(waybillNo) {
+  const suffix = waybillNo.slice(-4);
+  return `${'*'.repeat(Math.max(0, waybillNo.length - suffix.length))}${suffix}`;
+}
+
+function buildInput(options, context) {
+  const scope = resolveTargetShop(options, context, command);
+  try {
+    if (typeof options.waybillNo !== 'string' || /[\u0000-\u001f\u007f-\u009f]/u.test(options.waybillNo)) {
+      throw new TypeError('invalid waybill number');
+    }
+    const input = {
+      ...scope,
+      carrierId: Number(options.carrierId),
+      waybillNo: options.waybillNo
+    };
+    if (!/^[1-9]\d*$/.test(options.carrierId) || !safeNumber(input.carrierId)) throw new TypeError('invalid carrier id');
+    validateCommandValue(schema, 'input', input);
+    return Object.freeze(input);
+  } catch {
+    throw reject('parameter', 'input', scope);
+  }
+}
+
+function projectEvent(item, scope, facts) {
+  if (!object(item) || typeof item.context !== 'string') {
+    throw reject('protocol', 'events', scope, 'sent', facts);
+  }
+  const event = { description: item.context };
+  for (const [source, target] of [['status', 'statusText'], ['time', 'timeText']]) {
+    if (item[source] !== undefined && item[source] !== null) {
+      if (typeof item[source] !== 'string') throw reject('protocol', 'events', scope, 'sent', facts);
+      event[target] = item[source];
+    }
+  }
+  return event;
+}
+
+function project(data, input, facts) {
+  const scope = scopeFor(input);
+  try {
+    if (!object(data) || !['1', ''].includes(data.status)) {
+      const category = data?.status === '0' ? 'data_unavailable' :
+        data?.status === '2' ? 'upstream_query_failed' : 'protocol';
+      throw reject(category, 'query-status', scope, 'sent', facts);
+    }
+    if (data.nu !== input.waybillNo || data.express_id !== input.carrierId) {
+      throw reject('scope_unresolved', 'waybill-model', scope, 'sent', facts);
+    }
+    if (!safeNumber(data.state) || data.state < 0) {
+      throw reject('protocol', 'waybill-model', scope, 'sent', facts);
+    }
+    if (typeof data.data !== 'string' || Buffer.byteLength(data.data, 'utf8') > 1024 * 1024) {
+      throw reject('protocol', 'events', scope, 'sent', facts);
+    }
+    let rawEvents;
+    try { rawEvents = JSON.parse(data.data); } catch { throw reject('protocol', 'events', scope, 'sent', facts); }
+    if (!Array.isArray(rawEvents) || rawEvents.length > 1000) {
+      throw reject('protocol', 'events', scope, 'sent', facts);
+    }
+    const waybill = {
+      waybillNo: data.nu,
+      carrierId: data.express_id,
+      state: data.state,
+      events: rawEvents.map(item => projectEvent(item, scope, facts))
+    };
+    for (const [source, target] of [['name', 'carrierName'], ['com', 'carrierCode']]) {
+      if (data[source] !== undefined && data[source] !== null) {
+        if (typeof data[source] !== 'string') throw reject('protocol', 'waybill-model', scope, 'sent', facts);
+        waybill[target] = data[source];
+      }
+    }
+    const output = { data: { waybill } };
+    if (Buffer.byteLength(JSON.stringify(output), 'utf8') > 5 * 1024 * 1024) {
+      throw reject('protocol', 'waybill-model', scope, 'sent', facts);
+    }
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch (error) {
+    if (error?.cliDetails) throw error;
+    throw reject('protocol', 'waybill-model', scope, 'sent', facts);
+  }
+}
+
+async function execute(input) {
+  try {
+    const read = await createShopQuery(input, command, {
+      transportOptions: {
+        maxResponseBytes: () => 10 * 1024 * 1024,
+        timeoutMs: 30000,
+        limitCategory: 'protocol',
+        limitStage: currentPath => currentPath === bindingPath ? 'shop-binding' : 'waybill-response'
+      }
+    });
+    const response = await read(path, {
+      express_id: input.carrierId,
+      express_no: input.waybillNo
+    }, 'waybill');
+    if (response.responseBytes > 10 * 1024 * 1024) {
+      throw reject('protocol', 'waybill-response', scopeFor(input), 'sent', response.facts);
+    }
+    let data;
+    try { data = readWaybill(response.rawBody); }
+    catch { throw reject('protocol', 'waybill-model', scopeFor(input), 'sent', response.facts); }
+    return project(data, input, response.facts);
+  } catch (error) {
+    addScope(error, input);
+    const details = error.cliDetails;
+    if (details?.category === 'business_rejected' && details.stage === 'waybill' &&
+        details.api === path && !Object.hasOwn(details, 'gatewayCode') &&
+        [120009001, '120009001'].includes(details.businessCode)) {
+      details.category = 'not_found_in_scope';
+      error.message = '查询失败：not_found_in_scope（waybill）';
+    }
+    throw error;
+  }
+}
+
+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');
+    })
+    .requiredOption('--carrier-id <id>', '有赞快递公司正整数 ID，不接受公司名称或编码')
+    .requiredOption('--waybill-no <no>', '运单号字符串，保留大小写和前导零，长度 1 至 128')
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略取有效上下文 shopId')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '本地预览请求计划；不读取凭证、不联网')
+    .addHelpText('after', `
+输出 data.waybill：waybillNo、carrierId、state 和固定 events 轨迹数组。
+轨迹来自同一次 goodsexpress.get 响应，不能用 --include 关闭；timeText 保留承运商原文。每次请求最多等待 30 秒。
+先核验凭证店铺 sid，再发送一次运单查询；最多两次请求，不重试、切店或调用电子面单接口。
+查询命中不证明订单、配送单或售后归属；失败 stdout 为空，stderr 为安全错误 JSON。
+契约：zan-saas schema fulfillment.waybill.get
+示例：zan-saas fulfillment waybill get --kdt-id 63077 --carrier-id 6 --waybill-no 73179966 --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const preview = {
+        scope: { kdtId: input.kdtId, carrierId: input.carrierId, waybillNo: maskedWaybill(input.waybillNo) },
+        prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [{ method: 'POST', path, body: {
+          express_id: input.carrierId, express_no: maskedWaybill(input.waybillNo)
+        } }],
+        condition: '仅在店铺核验返回的 sid 等于目标 kdtId 时发送运单请求。轨迹固定解析，不支持关闭。'
+      };
+      validateCommandValue(schema, 'preview', preview);
+      const result = options.dryRun ? preview : await execute(input);
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = {
+  kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand), buildInput, project, execute
+};

package/src/commands/native/fulfillment/waybill/get/response.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { parseExactJson } = require('../../../../../execution/exact-json');
+
+class NumericToken {
+  constructor(text) { this.text = text; }
+}
+
+function parseResponse(text) {
+  JSON.parse(text);
+  const tokens = text.match(/"(?:[^"\\]|\\.)*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\]:,]/g);
+  let index = 0;
+  function value() {
+    const token = tokens[index++];
+    if (token === '{') {
+      const result = Object.create(null);
+      while (tokens[index] !== '}') {
+        const key = JSON.parse(tokens[index++]);
+        index++;
+        result[key] = value();
+        if (tokens[index] !== ',') break;
+        index++;
+      }
+      index++;
+      return result;
+    }
+    if (token === '[') {
+      const result = [];
+      while (tokens[index] !== ']') {
+        result.push(value());
+        if (tokens[index] !== ',') break;
+        index++;
+      }
+      index++;
+      return result;
+    }
+    return /^-?\d/.test(token) ? new NumericToken(token) : JSON.parse(token);
+  }
+  return value();
+}
+
+function integer(value, minimum = 0) {
+  if (!(value instanceof NumericToken)) throw new Error('Expected numeric token');
+  const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(value.text);
+  const fraction = match[3] || '';
+  const significant = `${match[2]}${fraction}`.replace(/^0+/, '');
+  const digits = significant.replace(/0+$/, '');
+  if (!digits) {
+    if (minimum > 0) throw new Error('Invalid integer');
+    return 0;
+  }
+  const scale = Number(match[4] || 0) - fraction.length + significant.length - digits.length;
+  if (match[1] || scale < 0 || digits.length + scale > 16) throw new Error('Invalid integer');
+  const exact = BigInt(digits) * 10n ** BigInt(scale);
+  if (exact > BigInt(Number.MAX_SAFE_INTEGER) || exact < BigInt(minimum)) throw new Error('Invalid integer');
+  return Number(exact);
+}
+
+function readWaybill(rawBody) {
+  const data = parseExactJson(rawBody, text => new NumericToken(text)).data;
+  if (data && ['1', ''].includes(data.status)) {
+    data.express_id = integer(data.express_id, 1);
+    data.state = integer(data.state);
+  }
+  return data;
+}
+
+module.exports = { readWaybill };

package/src/commands/native/fulfillment/waybill/get/schema.json

@@ -0,0 +1,190 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": ["kdtId", "carrierId", "waybillNo"],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": { "$ref": "#/definitions/shopId" },
+      "carrierId": { "$ref": "#/definitions/carrierId" },
+      "waybillNo": { "$ref": "#/definitions/waybillNo" }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入。"
+  },
+  "output": {
+    "type": "object",
+    "required": ["data"],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": ["waybill"],
+        "additionalProperties": false,
+        "properties": {
+          "waybill": { "$ref": "#/definitions/waybill" }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": ["scope", "prerequisites", "requests", "condition"],
+    "additionalProperties": false,
+    "properties": {
+      "scope": {
+        "type": "object",
+        "required": ["kdtId", "carrierId", "waybillNo"],
+        "additionalProperties": false,
+        "properties": {
+          "kdtId": { "$ref": "#/definitions/shopId" },
+          "carrierId": { "$ref": "#/definitions/carrierId" },
+          "waybillNo": { "type": "string", "minLength": 1, "maxLength": 128 }
+        }
+      },
+      "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", "maxProperties": 0 }
+          }
+        }
+      },
+      "requests": {
+        "type": "array",
+        "minItems": 1,
+        "maxItems": 1,
+        "items": {
+          "type": "object",
+          "required": ["method", "path", "body"],
+          "additionalProperties": false,
+          "properties": {
+            "method": { "const": "POST" },
+            "path": { "const": "youzan.logistics.goodsexpress.get/3.0.0" },
+            "body": {
+              "type": "object",
+              "required": ["express_id", "express_no"],
+              "additionalProperties": false,
+              "properties": {
+                "express_id": { "$ref": "#/definitions/carrierId" },
+                "express_no": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      },
+      "condition": { "const": "仅在店铺核验返回的 sid 等于目标 kdtId 时发送运单请求。轨迹固定解析，不支持关闭。" }
+    }
+  },
+  "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_in_scope", "data_unavailable", "upstream_query_failed"]
+          },
+          "stage": { "type": "string", "minLength": 1 },
+          "command": { "const": "fulfillment.waybill.get" },
+          "targetScope": {
+            "anyOf": [
+              { "type": "object", "maxProperties": 0 },
+              {
+                "type": "object",
+                "required": ["kdtId"],
+                "additionalProperties": false,
+                "properties": {
+                  "kdtId": { "$ref": "#/definitions/shopId" },
+                  "carrierId": { "$ref": "#/definitions/carrierId" },
+                  "waybillSuffix": { "type": "string", "minLength": 1, "maxLength": 4, "pattern": "^[^\\s]+$" }
+                }
+              }
+            ]
+          },
+          "requestState": { "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/code" },
+          "gatewayCode": { "$ref": "#/definitions/code" },
+          "trace_id": { "$ref": "#/definitions/trace" },
+          "request_id": { "$ref": "#/definitions/trace" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "carrierId": { "type": "integer", "minimum": 1, "maximum": 2147483647 },
+    "waybillNo": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]+$" },
+    "text": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "event": {
+      "type": "object",
+      "required": ["description"],
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "statusText": { "type": "string" },
+        "timeText": { "type": "string" }
+      }
+    },
+    "waybill": {
+      "type": "object",
+      "required": ["waybillNo", "carrierId", "state", "events"],
+      "additionalProperties": false,
+      "properties": {
+        "waybillNo": { "$ref": "#/definitions/text" },
+        "carrierId": { "$ref": "#/definitions/carrierId" },
+        "state": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "$comment": "来源为 youzan.logistics.goodsexpress.get/3.0.0 的 data.state。",
+          "description": "运输状态，已知 JSON 数字值：0 收件、1 揽件、2 疑难、3 签收、4 退签、5 派送中、7 运输中、8 已取消。未知非负安全整数原样保留，不赋予业务含义，不作为封闭枚举校验。"
+        },
+        "carrierName": { "type": "string" },
+        "carrierCode": { "type": "string" },
+        "events": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/definitions/event" } }
+      }
+    },
+    "code": {
+      "anyOf": [
+        { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+        { "type": "string", "pattern": "^-?[0-9]{1,12}$" }
+      ]
+    },
+    "trace": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }
+  },
+  "modules": {
+    "waybill": {
+      "base": true,
+      "upstreamPath": "data",
+      "required": true,
+      "description": "按物流公司 ID 与运单号读取当前运输状态和固定轨迹有限视图。"
+    }
+  },
+  "api": { "method": "POST", "path": "youzan.logistics.goodsexpress.get/3.0.0" },
+  "success": { "description": "店铺核验和上游业务成功，运单锚点、状态和轨迹满足有限模型。" },
+  "errors": { "description": "失败 stdout 为空，stderr 返回安全错误 JSON；不输出上游自由消息或原始轨迹。" },
+  "notes": [
+    "轨迹固定返回，不提供 --include；不调用电子面单或外部快递接口。",
+    "carrierCode 是来源编码文本，不能替代 carrierId；waybillNo 保留大小写和前导零。",
+    "timeText 保留承运商原文，不猜测时区、格式或精度。",
+    "查询命中不证明订单、配送单或售后归属。"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 3,
+  "domain": "interaction",
+  "businessCommands": [
+    {
+      "path": "interaction.lottery.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "interaction/lottery/get/command.js",
+      "fingerprint": "3db3d36bc577a110d917ee52ea9b9c2a6ba6eb39c306b2e4328dcc4d2417d1cf"
+    },
+    {
+      "path": "interaction.lottery.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "interaction/lottery/list/command.js",
+      "fingerprint": "18ba912db0600f674f6e9d0cf30f62487f292b0ff515a5bf54d8f342a80bc7cf"
+    }
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "互动营销：抽奖活动配置与活动查询"
+}

package/src/commands/native/interaction/lottery/get/command.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { parseIntegerOption } = require('../../../../../execution/error-details');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { bindingPath, failure } = require('../../../../../execution/shop-query');
+const { executeLottery } = require('./query');
+const schema = require('./schema.json');
+
+const command = 'interaction.lottery.get';
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('get', { path: command, schema, parameterCategory: 'parameter' })
+    .description('按活动 ID 读取同店抽奖活动的参与、奖项、转盘及页面配置')
+    .allowExcessArguments(false)
+    .requiredOption('--activity-id <id>', 'integer，必填。抽奖活动 ID，须为正安全整数，不接受别名或奖项 ID。')
+    .option('--kdt-id <id>', 'integer，可选，默认 context.shopId。目标店铺 ID，须为正安全整数。')
+    .addOption(new Option('--format <format>', 'string，可选，默认 json。输出格式：json 紧凑，pretty 缩进。')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', 'boolean，可选，默认 false。仅预览查询计划，不读凭证、不联网。')
+    .addHelpText('after', `
+输出 data.lottery；活动、奖项定义和转盘槽位不是客户参与、中奖或到账记录。
+配置默认投影，未返回的可选字段省略；不提供 include、fields 或 kind 参数。
+活动概率为万分比，奖项概率为百分比；槽位概率单位未证，不输出。
+保留槽位顺序及重复奖项引用；不计算当前状态、客户资格或实际中奖概率。
+仅支持已核实的微商城单店；at: all 不证明产品、员工或对象授权。
+先以同一凭证核验店铺，再按活动 ID 单次读取，不扫描列表，不重试、换店或换身份。
+店铺核验响应限 512 KiB，主响应限 8 MiB，超限整体失败，不裁剪或输出部分结果。
+真实执行需有效四字段上下文和同店授权凭证；失败 stdout 为空，stderr 为一份脱敏错误 JSON。
+契约：zan-saas schema interaction.lottery.get
+示例：zan-saas interaction lottery get --activity-id 1001 --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const scope = resolveTargetShop(options, context, command);
+      let input;
+      try {
+        input = Object.freeze({ ...scope, activityId: parseIntegerOption(options.activityId, schema, '/activityId') });
+        validateCommandValue(schema, 'input', input);
+      } catch (error) {
+        error.inputScope = scope;
+        error.cliDetails = failure(command, 'validation', 'input', scope).cliDetails;
+        throw error;
+      }
+      const preview = {
+        scope,
+        prerequisites: ['context', 'token-shop-binding'],
+        requests: [{ method: 'POST', api: bindingPath, body: {} },
+          { method: 'POST', api: schema.api.path, body: { activity_id: input.activityId } }],
+        limits: { maxBusinessRequests: 2, bindingResponseBytes: 524288, queryResponseBytes: 8388608 }
+      };
+      validateCommandValue(schema, 'preview', preview);
+      const output = options.dryRun ? preview : await executeLottery(input);
+      process.stdout.write(`${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };