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

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

@@ -0,0 +1,173 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object", "required": ["kdtId", "deliveryId"], "additionalProperties": false,
+    "properties": {
+      "kdtId": { "$ref": "#/definitions/shopId" },
+      "deliveryId": { "$ref": "#/definitions/deliveryId" }
+    },
+    "description": "参数解析后的配送单查询业务输入。无 include、订单号或货单号输入。"
+  },
+  "output": {
+    "type": "object", "required": ["data"], "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object", "required": ["delivery"], "additionalProperties": false,
+        "properties": { "delivery": { "$ref": "#/definitions/delivery" } }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "additionalProperties": false,
+    "required": ["scope", "prerequisites", "requests", "conditionalRequest", "result"],
+    "properties": {
+      "scope": {
+        "type": "object", "required": ["kdtId"], "additionalProperties": false,
+        "properties": { "kdtId": { "$ref": "#/definitions/shopId" } }
+      },
+      "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.online.distorder.query.querybydistid/3.0.0" },
+            "body": {
+              "type": "object", "required": ["dist_id"], "additionalProperties": false,
+              "properties": { "dist_id": { "type": "string", "pattern": "^\\*\\*\\*[^\\s\\u0000-\\u001f\\u007f-\\u009f]{1,4}$(?![\\s\\S])" } }
+            }
+          }
+        }
+      },
+      "conditionalRequest": {
+        "type": "object", "required": ["when", "method", "path", "bodyFrom", "fixedBody"],
+        "additionalProperties": false,
+        "properties": {
+          "when": { "const": "deliveryType 为 11/12/14" }, "method": { "const": "POST" },
+          "path": { "const": "youzan.trade.dc.query.querybyorderno/1.0.1" },
+          "bodyFrom": {
+            "type": "object", "required": ["tid"], "additionalProperties": false,
+            "properties": { "tid": { "const": "data.delivery.orderNo" } },
+            "description": "只记录待取得的业务字段来源，不是可发送的订单号或占位请求。"
+          },
+          "fixedBody": {
+            "type": "object", "additionalProperties": false,
+            "required": ["include_dist_order", "include_all_dist_order", "open_query_requestinclude_dist_order_and_detail"],
+            "properties": {
+              "include_dist_order": { "const": true }, "include_all_dist_order": { "const": true },
+              "open_query_requestinclude_dist_order_and_detail": { "const": true }
+            }
+          }
+        }
+      },
+      "result": { "const": "类型和订单待主查询取得；21/23 本地投影同城摘要，11/12/14 补查运单引用，其他类型仅返回基础内容。" }
+    }
+  },
+  "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", "additionalProperties": false,
+        "required": ["category", "stage", "command", "targetScope", "requestState", "nextStep"],
+        "if": { "properties": { "requestState": { "enum": ["sent", "unknown"] } } },
+        "then": {
+          "properties": {
+            "targetScope": {
+              "type": "object", "required": ["kdtId"], "additionalProperties": false,
+              "properties": { "kdtId": { "$ref": "#/definitions/shopId" } }
+            }
+          }
+        },
+        "properties": {
+          "category": { "enum": ["validation", "parameter", "configuration", "authentication", "permission", "scope_unresolved", "transport", "http", "business_rejected", "protocol", "not_found_in_scope", "module_unavailable", "budget_exceeded"] },
+          "stage": { "type": "string", "minLength": 1 },
+          "command": { "const": "fulfillment.delivery.get" },
+          "targetScope": {
+            "type": "object", "additionalProperties": false,
+            "properties": { "kdtId": { "$ref": "#/definitions/shopId" } },
+            "description": "目标尚未解析且未发送请求时允许空对象，不推造店铺；已解析时保留合法 kdtId，已发送或发送结果未知时必须包含该店铺。"
+          },
+          "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, "description": "目标店铺正安全整数，须与当前店铺及凭证店铺相同。" },
+    "deliveryId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]+$(?![\\s\\S])", "description": "有赞配送单号，保留原始编码和前导零，不是货单或服务商单号。" },
+    "text": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "code": { "anyOf": [{ "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "pattern": "^-?\\d{1,12}$" }] },
+    "trace": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_-]+$" },
+    "time": { "type": "string", "format": "beijing-date-time-ms", "description": "北京时间完整时间 YYYY-MM-DD HH:mm:ss.SSS，缺省或空值时省略，不推断事件未发生。", "$comment": "upstream-time:milliseconds" },
+    "localDelivery": {
+      "type": "object", "required": ["providerName", "providerOrderNo", "statusText"], "additionalProperties": false,
+      "properties": {
+        "providerName": { "$ref": "#/definitions/text", "description": "第三方配送公司名称，不据此推断供应商 ID。" },
+        "providerOrderNo": { "$ref": "#/definitions/text", "description": "同城服务商详情单号，不等于有赞配送单号或货单号。" },
+        "statusText": { "$ref": "#/definitions/text", "description": "服务商原始展示状态，不转换为有赞配送单状态。" },
+        "cancelReason": { "type": "string", "description": "原始取消原因，可为空串，缺省或空值时省略，不能据此推断是否取消。" }
+      }
+    },
+    "waybill": {
+      "type": "object", "required": ["waybillNo", "carrierId"], "additionalProperties": false,
+      "properties": {
+        "waybillNo": { "$ref": "#/definitions/text", "description": "当前快递运单号，用于后续运单查询，不承诺子母件全集。" },
+        "carrierId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "有赞快递公司 ID，后续查询需与该运单号一起使用。" }
+      }
+    },
+    "delivery": {
+      "type": "object", "additionalProperties": false,
+      "required": ["deliveryId", "shipmentNo", "orderNo", "kdtId", "status", "deliveryMethod", "deliveryType"],
+      "properties": {
+        "deliveryId": { "$ref": "#/definitions/deliveryId" },
+        "shipmentNo": { "$ref": "#/definitions/text", "description": "所属发货单编号，不是运单号或服务商单号。" },
+        "orderNo": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]+$(?![\\s\\S])", "description": "所属原始订单号，不按前缀或位数判断有效性；保留原值用于补查和关联核对，不含空白或控制字符。" },
+        "kdtId": { "$ref": "#/definitions/shopId" },
+        "status": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "0 未发货，NON_DELIVERY；1 发货中，DELIVERING；2 已发货，DELIVERED；3 已取消，CANCELED。未知非负安全整数原值保留，不补含义。已发货不证明物流签收、买家收货或售后确认。" },
+        "deliveryMethod": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "1 快递；2 同城送；3 自提。未知非负安全整数保留原值，不猜含义。已知执行类型须与方式一致。" },
+        "deliveryType": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "11 快递、系统呼叫；12 快递、商家呼叫；13 快递、无需物流；14 快递、电子面单；21 同城送、商家呼叫第三方；22 同城送、商家自主配送；23 同城送、系统呼叫第三方；24 自提、核销提货；91 自提、有码提货；92 自提、无码提货。未知非负安全整数保留原值，不推断补查路径。" },
+        "createdAt": { "$ref": "#/definitions/time", "description": "配送创建时间，北京时间毫秒精度，缺省或空值时省略。", "$comment": "upstream-time:milliseconds" },
+        "updatedAt": { "$ref": "#/definitions/time", "description": "配送更新时间，不是包裹发货时间，北京时间毫秒精度，缺省或空值时省略。", "$comment": "upstream-time:milliseconds" },
+        "localDelivery": { "$ref": "#/definitions/localDelivery", "description": "类型 21/23 的必需默认同城摘要，其他类型省略。" },
+        "waybill": { "$ref": "#/definitions/waybill", "description": "类型 11/12/14 的必需默认快递引用，其他类型省略。" }
+      },
+      "allOf": [
+        { "if": { "properties": { "deliveryType": { "enum": [21, 23] } } }, "then": { "required": ["localDelivery"], "properties": { "localDelivery": true } }, "else": { "properties": { "localDelivery": false } } },
+        { "if": { "properties": { "deliveryType": { "enum": [11, 12, 14] } } }, "then": { "required": ["waybill"], "properties": { "waybill": true } }, "else": { "properties": { "waybill": false } } },
+        { "if": { "properties": { "deliveryType": { "enum": [11, 12, 13, 14] } } }, "then": { "properties": { "deliveryMethod": { "const": 1 } } } },
+        { "if": { "properties": { "deliveryType": { "enum": [21, 22, 23] } } }, "then": { "properties": { "deliveryMethod": { "const": 2 } } } },
+        { "if": { "properties": { "deliveryType": { "enum": [24, 91, 92] } } }, "then": { "properties": { "deliveryMethod": { "const": 3 } } } }
+      ]
+    }
+  },
+  "api": { "method": "POST", "path": "youzan.logistics.online.distorder.query.querybydistid/3.0.0" },
+  "success": { "rule": "同店核验、目标与关联匹配，基础内容及类型适用的默认内容全部通过后才返回 data.delivery。" },
+  "errors": { "recovery": "失败 stdout 为空，stderr 为错误信封，退出码 1。保留原店铺与对象排查，不能把业务拒绝或默认内容缺失解释成没有配送，不自动重试、换店或换身份。" },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "订单号通常为 E/V/C 开头加 23 位数字，仅供核对，不限定前缀、数字组合或 24 位长度；按原值传递。仅保留非空、无空白或控制字符和最多 128 字符的文本保护；服务端仍判断支持范围和对象归属。",
+    "仅支持当前店铺四字段上下文和同店凭证，店铺核验不证明员工授权通过。无 include、分页、商品、骑手、位置、费用、日志或轨迹。",
+    "快递类型 11/12/14 最多三次请求，其他类型最多两次。每请求超时 10 秒，无重试或回退。",
+    "每响应读取后最多 10 MiB，不是流式读取硬限制；最多检查 1000 张货单及每张 1000 条配送，输出最多 5 MiB，超限整体失败不截断。",
+    "类型专属字段省略表示未进入对应已知类型分支，不表示已确认不存在其他关联。主对象或所需引用未取得时不输出部分成功。"
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "履约：发货单、配送单与物流轨迹"
+}

package/src/commands/native/fulfillment/shipment/list/command.js

@@ -0,0 +1,83 @@
+'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 { readContext } = require('../../../../../identity/context');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+const { project } = require('./projection');
+const schema = require('./schema.json');
+
+const command = 'fulfillment.shipment.list';
+const reject = (category, stage, scope, state, facts) =>
+  failure(command, category, stage, scope, state, facts);
+
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: command, schema, parameterCategory: 'parameter' })
+    .description('查询指定订单本次返回的发货单集合，默认包含商品明细和配送引用')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺正安全整数，必须与当前上下文店铺相同；省略时使用当前上下文店铺')
+    .requiredOption('--order-no <no>', '必填：原始订单号，最多 128 字符；不限定前缀或位数')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览脱敏请求计划，不读凭证、不联网')
+    .addHelpText('after', `
+输出 data.shipments 数组，零张、一张、多张均不改变形状。
+订单号通常为 E/V/C 开头加 23 位数字，仅供核对；不按该格式拒绝输入或响应，订单与店铺关联仍须一致。
+默认包含每张货单的 items 和 deliveries，不查询配送详情、轨迹或日志。
+空数组只表示本次未返回货单，不证明订单不存在、无需发货或履约完成。
+没有分页，不提供 --include、--shipment-no 或旧参数别名。
+最多一次店铺核验与一次订单查询，不重试、不切换店铺或身份。
+每个集合最多 1000 条，主响应读取后最多 10 MiB，最终输出最多 5 MiB。
+超预算整体失败，不截断；响应预算不是流式网络读取硬上限。
+真实执行需有效四字段上下文和同店授权凭证，店铺核验不证明员工授权通过。
+契约：zan-saas schema fulfillment.shipment.list
+示例：zan-saas fulfillment shipment list --kdt-id 63077 --order-no E20200413232015099300005 --dry-run
+`)
+    .action(async options => {
+      if (String(Number(options.kdtId)) !== options.kdtId) {
+        const error = inputIssue('/kdtId', 'invalid_format', constraints(modelAt(schema, 'input', '/kdtId')));
+        error.cliDetails = reject('validation', 'input').cliDetails;
+        throw error;
+      }
+      const scope = resolveTargetShop(options, context, command);
+      const state = readContext(context);
+      if (state.status === 'ready' && String(scope.kdtId) !== state.context.shopId) {
+        throw reject('permission', 'scope', scope);
+      }
+      const input = { ...scope, orderNo: options.orderNo };
+      withInputScope(scope, () => validateCommandValue(schema, 'input', input));
+      const body = { tid: input.orderNo, include_item_delivery_status: true, include_dist_order: true };
+      const preview = {
+        scope, prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [{ method: 'POST', path: schema.api.path,
+          body: { ...body, tid: `***${Array.from(input.orderNo).slice(-4).join('')}` } }],
+        result: { collection: 'data.shipments', items: true, deliveries: true, pagination: false }
+      };
+      validateCommandValue(schema, 'preview', preview);
+      let output = preview;
+      let facts = {};
+      if (!options.dryRun) {
+        const read = await createShopQuery(scope, command);
+        const response = await read(schema.api.path, body, 'shipment-list');
+        const { rawBody } = response;
+        facts = response.facts;
+        if (response.responseBytes > 10 * 1024 * 1024) {
+          throw reject('budget_exceeded', 'response-bytes', scope, 'sent', facts);
+        }
+        try { output = project(rawBody, input); }
+        catch (error) { throw reject(error.category || 'protocol', 'shipment-list-model', scope, 'sent', facts); }
+      }
+      const text = `${JSON.stringify(output, null, options.format === 'pretty' ? 2 : 0)}\n`;
+      if (Buffer.byteLength(text) > 5 * 1024 * 1024) {
+        throw reject('budget_exceeded', 'output-bytes', scope, 'sent', facts);
+      }
+      process.stdout.write(text);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/fulfillment/shipment/list/projection.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { object } = require('../../../../../execution/query-api');
+const schema = require('./schema.json');
+
+class NumericToken {
+  constructor(text) { this.text = text; }
+}
+
+function parseNumbers(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);
+  }
+  JSON.parse(text);
+  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 identifier(value) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('Invalid identifier');
+  return value;
+}
+
+function collection(value) {
+  if (!Array.isArray(value)) throw new Error('Missing collection');
+  if (value.length > 1000) {
+    const error = new Error('Collection budget exceeded');
+    error.category = 'budget_exceeded';
+    throw error;
+  }
+  return value;
+}
+
+function project(rawBody, input) {
+  const envelope = parseNumbers(rawBody);
+  const shipmentNumbers = new Set();
+  const deliveryIds = new Set();
+  const shipments = collection(envelope.data).map(shipment => {
+    if (!object(shipment)) throw new Error('Invalid shipment');
+    const shipmentNo = identifier(shipment.delivery_no);
+    if (shipmentNumbers.has(shipmentNo)) throw new Error('Duplicate shipment');
+    shipmentNumbers.add(shipmentNo);
+    function relation(row) {
+      if (!object(row) || row.tid !== input.orderNo ||
+          row.delivery_no !== shipmentNo || integer(row.kdt_id, 1) !== input.kdtId) {
+        throw new Error('Relation mismatch');
+      }
+    }
+    relation(shipment);
+    const result = {
+      shipmentNo, orderNo: shipment.tid, kdtId: integer(shipment.kdt_id, 1),
+      status: integer(shipment.status), deliveryMethod: integer(shipment.dist_type),
+      items: collection(shipment.delivery_order_items).map(item => {
+        relation(item);
+        if (!(item.item_id instanceof NumericToken) || !/^[1-9]\d*$/.test(item.item_id.text)) {
+          throw new Error('Invalid order item ID');
+        }
+        return { orderItemId: item.item_id.text, quantity: integer(item.num) };
+      }),
+      deliveries: collection(shipment.dist_order_d_t_os).map(delivery => {
+        relation(delivery);
+        const deliveryId = identifier(delivery.dist_id);
+        if (deliveryIds.has(deliveryId)) throw new Error('Duplicate delivery');
+        deliveryIds.add(deliveryId);
+        return { deliveryId, status: integer(delivery.status), deliveryMethod: integer(delivery.dist_type) };
+      })
+    };
+    for (const [source, target] of [['flow_type', 'flowType'], ['delivery_mode', 'mode']]) {
+      if (shipment[source] !== undefined && shipment[source] !== null) result[target] = integer(shipment[source]);
+    }
+    const hasPointId = shipment.delivery_point_id !== undefined && shipment.delivery_point_id !== null;
+    const hasPointType = shipment.delivery_point_type !== undefined && shipment.delivery_point_type !== null;
+    if (hasPointId !== hasPointType) throw new Error('Incomplete delivery point');
+    if (hasPointId) result.deliveryPoint = {
+      id: String(integer(shipment.delivery_point_id, 1)), type: integer(shipment.delivery_point_type)
+    };
+    if (shipment.remark !== undefined && shipment.remark !== null) {
+      if (typeof shipment.remark !== 'string') throw new Error('Invalid remark');
+      result.remark = shipment.remark;
+    }
+    return result;
+  });
+  const output = { data: { shipments } };
+  validateCommandValue(schema, 'output', output);
+  return output;
+}
+
+module.exports = { project };