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

package/src/commands/native/customer/tagcategory/list/schema.json

@@ -0,0 +1,394 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "pageNo",
+      "pageSize"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "pageNo": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991,
+        "description": "页码正安全整数，从 1 开始"
+      },
+      "pageSize": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 50,
+        "description": "每页 1–50 条，默认 20"
+      },
+      "keyword": {
+        "type": "string",
+        "minLength": 1,
+        "description": "标签组名称关键词，去除首尾空白后不能为空"
+      },
+      "status": {
+        "type": "string",
+        "enum": [
+          "normal",
+          "disabled"
+        ],
+        "description": "标签组状态；省略表示全部"
+      },
+      "addRule": {
+        "type": "string",
+        "enum": [
+          "unique",
+          "repeat"
+        ],
+        "description": "组内标签添加规则；省略表示全部"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "tagCategories",
+          "pagination"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "tagCategories": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "tagCategoryId",
+                "kdtId",
+                "tagCategoryName",
+                "addRule",
+                "tags"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "tagCategoryId": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 9007199254740991
+                },
+                "kdtId": {
+                  "$ref": "#/definitions/shopId"
+                },
+                "tagCategoryName": {
+                  "type": "string"
+                },
+                "addRule": {
+                  "type": "string",
+                  "enum": [
+                    "unique",
+                    "repeat"
+                  ]
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "tagId",
+                      "tagName"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "tagId": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 9007199254740991
+                      },
+                      "tagName": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "maxItems": 50
+          },
+          "pagination": {
+            "type": "object",
+            "required": [
+              "pageNo",
+              "pageSize",
+              "hasMore"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "pageNo": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              "pageSize": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50
+              },
+              "total": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "匹配本次查询条件的总记录数，不是当前页返回条数；上游未提供可确认总数时省略。"
+              },
+              "hasMore": {
+                "type": [
+                  "boolean",
+                  "null"
+                ],
+                "description": "true 表示还有后续页，false 表示已确认没有后续页；无法确定时为 null，不以空页或短页推算。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body",
+      "scope",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.tag.category.list/1.0.1"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "page",
+          "page_size"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "page": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "page_size": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
+          },
+          "tag_category_name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "tag_category_status": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ]
+          },
+          "tag_add_rule": {
+            "type": "integer",
+            "enum": [
+              0,
+              1
+            ]
+          }
+        }
+      },
+      "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",
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": "customer.tagcategory.list"
+          },
+          "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
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.tag.category.list/1.0.1"
+  },
+  "success": {
+    "description": "店铺核验通过，本页组、标签及分页符合模型和目标后成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "每次只查询一页，默认第 1 页、每页 20 条，页大小最多 50；保留筛选及页大小，按 nextPage 继续。",
+    "hasMore 按已报告总数计算；页码、容量、组归属或重复记录矛盾时整体失败。",
+    "normal 表示正常，disabled 表示禁用；unique 表示组内标签仅唯一添加，repeat 表示可重复添加。返回内容不补造筛选状态。",
+    "仅返回本页组和本次组内标签，不保证跨请求快照或组内标签全集。",
+    "支持微商城单店及列明的连锁 L 总部、网店和门店，at=all 不授予跨店权限。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 3,
+  "domain": "fulfillment",
+  "businessCommands": [
+    {
+      "path": "fulfillment.delivery.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "fulfillment/delivery/get/command.js",
+      "fingerprint": "671fca4f8b3cc9c313a89d120fb8da5953fa2dd2d18e2fee7cdfdfbe2ed62043"
+    },
+    {
+      "path": "fulfillment.shipment.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "fulfillment/shipment/list/command.js",
+      "fingerprint": "4a1d655372f602c7afa604af4f8b80052844a82ddeff49bdf61d1e1ed0267c38"
+    },
+    {
+      "path": "fulfillment.waybill.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "fulfillment/waybill/get/command.js",
+      "fingerprint": "bd10d2784139946b7225e22dc2d1aaebd2730919b9c89849dfd6e4a70863bc09"
+    }
+  ]
+}

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

@@ -0,0 +1,107 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+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 { projectDelivery, projectWaybill, expressTypes } = require('./projection');
+const schema = require('./schema.json');
+
+const command = 'fulfillment.delivery.get';
+const conditionalPath = 'youzan.trade.dc.query.querybyorderno/1.0.1';
+const switches = Object.freeze({ include_dist_order: true, include_all_dist_order: true,
+  open_query_requestinclude_dist_order_and_detail: true });
+
+function reject(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, requestState, facts);
+  error.cliDetails.nextStep = '核对原店铺、配送单及服务端授权；默认内容未取得时整体失败，不推断配送不存在，不自动重试、切换身份或店铺。';
+  return error;
+}
+
+function project(response, projector, stage, scope, input) {
+  if (response.responseBytes > 10 * 1024 * 1024) {
+    throw reject('budget_exceeded', 'response-bytes', scope, 'sent', response.facts);
+  }
+  try { return projector(response.rawBody, input); }
+  catch (error) { throw reject(error.category || 'protocol', stage, scope, 'sent', response.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');
+    })
+    .option('--kdt-id <id>', '规范十进制正安全整数，须与当前店铺一致；省略时使用当前上下文店铺')
+    .requiredOption('--delivery-id <id>', '必填：有赞配送单号，1 至 128 字符，不含空白或控制字符，保留前导零')
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进')
+      .choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地预览条件分支，不读取凭证、不联网')
+    .addHelpText('after', `
+输出 data.delivery。配送单是一次交付执行，不专指骑手单。
+所属订单号通常为 E/V/C 开头加 23 位数字，仅供核对；不按该格式拒绝响应，补查沿用主响应的原始订单号。
+类型 21/23 默认返回 localDelivery，同城服务商单号不等于有赞配送单号或货单号。
+类型 11/12/14 根据主查询取得的订单与货单精确补查一个 waybill 引用，不返回轨迹。
+类型 13/22/24/91/92 及未知类型仅返回基础内容，不猜补查路径。
+状态 0 未发货、1 发货中、2 已发货、3 已取消；未知非负安全整数保留原值。
+已发货不证明承运商签收或买家收货。缺少类型要求的默认内容时整体失败。
+无 --include 或旧参数别名，不读取商品、骑手、电话、位置、费用或任意扩展。
+仅支持当前店铺四字段上下文和同店凭证，核店不证明店铺员工授权验收通过。
+快递最多三次请求，其他最多两次；每请求 10 秒，不重试或回退其他 API。
+每响应读取后最多 10 MiB，不是流式读取硬上限；最多 1000 张货单及每张 1000 条配送。
+输出最多 5 MiB，超预算整体失败不截断。失败 stdout 为空。
+契约：zan-saas schema fulfillment.delivery.get
+示例：zan-saas fulfillment delivery get --kdt-id 63077 --delivery-id D-example --dry-run
+`)
+    .action(async options => {
+      if (!/^[1-9]\d*$/.test(options.kdtId) || !Number.isSafeInteger(Number(options.kdtId)) ||
+          String(Number(options.kdtId)) !== options.kdtId) {
+        throw reject('parameter', 'input');
+      }
+      const scope = resolveTargetShop(options, context, command);
+      const state = readContext(context);
+      if (state.status === 'ready' && (state.context.orgType !== 'shop' ||
+          String(scope.kdtId) !== state.context.shopId)) throw reject('permission', 'scope', scope);
+      const input = { ...scope, deliveryId: options.deliveryId };
+      try { validateCommandValue(schema, 'input', input); }
+      catch { throw reject('parameter', 'input', scope); }
+      const preview = {
+        scope, prerequisites: [{ method: 'POST', path: bindingPath, body: {} }],
+        requests: [{ method: 'POST', path: schema.api.path,
+          body: { dist_id: `***${Array.from(input.deliveryId).slice(-4).join('')}` } }],
+        conditionalRequest: { when: 'deliveryType 为 11/12/14', method: 'POST', path: conditionalPath,
+          bodyFrom: { tid: 'data.delivery.orderNo' }, fixedBody: switches },
+        result: '类型和订单待主查询取得；21/23 本地投影同城摘要，11/12/14 补查运单引用，其他类型仅返回基础内容。'
+      };
+      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, { dist_id: input.deliveryId }, 'delivery-get');
+        facts = response.facts;
+        const delivery = project(response, projectDelivery, 'delivery-model', scope, input);
+        if (expressTypes.includes(delivery.deliveryType)) {
+          const conditional = await read(conditionalPath,
+            { tid: delivery.orderNo, ...switches }, 'waybill-reference');
+          facts = conditional.facts;
+          delivery.waybill = project(conditional, projectWaybill, 'waybill-model', scope, delivery);
+        }
+        output = { data: { delivery } };
+        try { validateCommandValue(schema, 'output', output); }
+        catch { throw reject('protocol', 'delivery-output', 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: 'shop', createCommand: withTargetShopDefault(createCommand) };

package/src/commands/native/fulfillment/delivery/get/projection.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const { object } = require('../../../../../execution/query-api');
+const { formatBeijingMilliseconds } = require('../../../../../execution/beijing-time');
+
+const expressTypes = [11, 12, 14];
+const localTypes = [21, 23];
+const methods = new Map([[11, 1], [12, 1], [13, 1], [14, 1], [21, 2], [22, 2],
+  [23, 2], [24, 3], [91, 3], [92, 3]]);
+
+function invalid(category = 'protocol') {
+  const error = new Error('Invalid delivery response');
+  error.category = category;
+  throw error;
+}
+
+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)) invalid();
+  const number = Number(value.text);
+  if (!Number.isSafeInteger(number) || number < minimum) invalid();
+  const match = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(value.text);
+  let digits = `${match[2]}${match[3] || ''}`.replace(/^0+/, '');
+  if (!digits) return number;
+  let scale = Number(match[4] || 0) - (match[3] || '').length;
+  while (digits.endsWith('0')) { digits = digits.slice(0, -1); scale++; }
+  if (scale < 0 || digits.length + scale > 16 ||
+      BigInt(`${match[1]}${digits}`) * 10n ** BigInt(scale) !== BigInt(number)) invalid();
+  return number;
+}
+
+function text(value) {
+  if (typeof value !== 'string' || !value.trim()) invalid();
+  return value;
+}
+
+function collection(value) {
+  if (!Array.isArray(value)) invalid();
+  if (value.length > 1000) invalid('budget_exceeded');
+  return value;
+}
+
+function projectDelivery(rawBody, input) {
+  const source = parseResponse(rawBody).data;
+  if (source === undefined || source === null) invalid('not_found_in_scope');
+  if (!object(source)) invalid();
+  if (text(source.dist_id) !== input.deliveryId || integer(source.kdt_id, 1) !== input.kdtId) {
+    invalid('scope_unresolved');
+  }
+  const result = {
+    deliveryId: source.dist_id, shipmentNo: text(source.delivery_no), orderNo: text(source.order_no),
+    kdtId: input.kdtId, status: integer(source.status), deliveryMethod: integer(source.dist_type),
+    deliveryType: integer(source.delivery_type)
+  };
+  if (Array.from(result.orderNo).length > 128 || /[\s\u0000-\u001f\u007f-\u009f]/u.test(result.orderNo)) invalid();
+  if (methods.has(result.deliveryType) && methods.get(result.deliveryType) !== result.deliveryMethod) invalid();
+  for (const [sourceKey, targetKey] of [['create_time', 'createdAt'], ['update_time', 'updatedAt']]) {
+    if (source[sourceKey] !== undefined && source[sourceKey] !== null) {
+      result[targetKey] = formatBeijingMilliseconds(integer(source[sourceKey], -Number.MAX_SAFE_INTEGER));
+    }
+  }
+  if (localTypes.includes(result.deliveryType)) {
+    try {
+      const info = source.local_delivery_info;
+      if (!object(info) || !object(info.local_delivery_detail)) invalid();
+      const detail = info.local_delivery_detail;
+      result.localDelivery = { providerName: text(info.dist_company_name),
+        providerOrderNo: text(detail.delivery_no), statusText: text(detail.dist_status) };
+      if (detail.cancel_reason !== undefined && detail.cancel_reason !== null) {
+        if (typeof detail.cancel_reason !== 'string') invalid();
+        result.localDelivery.cancelReason = detail.cancel_reason;
+      }
+    } catch { invalid('module_unavailable'); }
+  }
+  return result;
+}
+
+function projectWaybill(rawBody, delivery) {
+  const shipments = collection(parseResponse(rawBody).data);
+  for (const shipment of shipments) {
+    if (!object(shipment)) invalid();
+    collection(shipment.dist_order_d_t_os);
+  }
+  const matches = shipments.filter(shipment => shipment.delivery_no === delivery.shipmentNo);
+  if (!matches.length) invalid('module_unavailable');
+  if (matches.length !== 1) invalid();
+  const shipment = matches[0];
+  function relation(row) {
+    if (row.tid !== delivery.orderNo || row.delivery_no !== delivery.shipmentNo ||
+        integer(row.kdt_id, 1) !== delivery.kdtId) invalid('scope_unresolved');
+  }
+  relation(shipment);
+  const deliveries = shipment.dist_order_d_t_os;
+  if (deliveries.some(row => !object(row))) invalid();
+  const selected = deliveries.filter(row => row.dist_id === delivery.deliveryId);
+  if (!selected.length) invalid('module_unavailable');
+  if (selected.length !== 1) invalid();
+  relation(selected[0]);
+  try {
+    const info = selected[0].express_info;
+    if (!object(info)) invalid();
+    return { waybillNo: text(info.express_no), carrierId: integer(info.express_id, 1) };
+  } catch { invalid('module_unavailable'); }
+}
+
+module.exports = { projectDelivery, projectWaybill, expressTypes };