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

package/src/commands/native/customer/tag/get/schema.json

@@ -0,0 +1,339 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object",
+    "required": [
+      "kdtId",
+      "tagId"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "kdtId": {
+        "$ref": "#/definitions/shopId"
+      },
+      "tagId": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991,
+        "description": "必填：标签定义正安全整数 ID；不是标签组 ID"
+      }
+    },
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "tag"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "tag": {
+            "$ref": "#/definitions/tag"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body",
+      "scope",
+      "prerequisites"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.scrm.tag.get/1.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "tag_id"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "tag_id": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          }
+        }
+      },
+      "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.tag.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
+    },
+    "tag": {
+      "type": "object",
+      "required": [
+        "tag_id",
+        "tag_name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "tag_id": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "tag_name": {
+          "type": "string"
+        },
+        "tag_customer_num": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "tag_category_id": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "status": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ],
+          "description": "0 不可用，1 可用；方向不同于标签组状态。"
+        },
+        "tag_biz_type": {
+          "type": "string"
+        },
+        "tag_type": {
+          "type": "integer",
+          "enum": [
+            1,
+            2
+          ],
+          "description": "1 手动标签，2 自动标签。"
+        },
+        "created_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "beijing-date-time-ms"
+            },
+            {
+              "const": ""
+            }
+          ],
+          "$comment": "upstream-time:text:empty",
+          "description": "日期时间；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+        },
+        "updated_at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "format": "beijing-date-time-ms"
+            },
+            {
+              "const": ""
+            }
+          ],
+          "$comment": "upstream-time:text:empty",
+          "description": "日期时间；北京时间 YYYY-MM-DD HH:mm:ss.SSS。业务哨兵原值保留：['']。"
+        },
+        "is_deleted": {
+          "type": "integer",
+          "enum": [
+            0,
+            1
+          ],
+          "description": "0 未删除，1 已删除。"
+        },
+        "tag_source": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "标签来源整数码，未知值保留，不自行解释。"
+        }
+      }
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.scrm.tag.get/1.0.0"
+  },
+  "success": {
+    "description": "店铺核验通过，标签 ID 精确匹配且名称及出现的已选字段满足模型后成功。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。"
+  },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "查询指定店铺的标签定义，不是客户标签关系；必须提供标签 ID；店铺省略时使用当前上下文，不搜索名称或补查标签组。",
+    "标签 ID 和名称为成功必需项；其他选定明细缺失省略，已出现字段 null 或错型失败。",
+    "仅承诺微商城单店；at=shop 不表示零售、总部或所有连锁分店均受支持。",
+    "本地 --dry-run 不读取凭证、不联网；预览只证明构造计划，不证明对象存在或权限有效。真实执行仍需有效上下文及目标范围授权，at 声明不替代服务端授权。"
+  ]
+}

package/src/commands/native/customer/tagcategory/get/command.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command } = require('commander');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { queryTagCategory, failure } = require('./query');
+const schema = require('./schema.json');
+
+function parameterError() {
+  const error = failure('parameter', 'input');
+  error.message = '标签组查询参数无效，请查看 zan-saas customer tagcategory get --help。';
+  return error;
+}
+
+function positiveId(value) {
+  if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value) ||
+      !Number.isSafeInteger(Number(value))) throw parameterError();
+  return Number(value);
+}
+
+function buildInput(options, context) {
+  const input = {
+    kdtId: positiveId(options.kdtId), tagCategoryId: positiveId(options.tagCategoryId)
+  };
+  if (!['json', 'pretty'].includes(options.format)) throw parameterError();
+  validateCommandValue(schema, 'input', input);
+  const targetScope = { kdtId: input.kdtId };
+  if (context?.orgType === 'shop' && String(input.kdtId) !== context.shopId) {
+    throw failure('permission', 'context', targetScope);
+  }
+  return {
+    targetScope,
+    request: {
+      method: 'POST', path: schema.api.path, body: { tag_category_id: input.tagCategoryId }
+    }
+  };
+}
+
+function createCommand({ context } = {}) {
+  return new Command('get')
+    .description('按店铺和标签组 ID 读取一个标签组及本次返回的组内标签')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw parameterError();
+    })
+    .option('--kdt-id <id>', '目标店铺 ID；当前调用范围须与目标店铺一致；省略时使用当前上下文店铺')
+    .requiredOption('--tag-category-id <id>', '标签组 ID；不能使用标签 ID 代替')
+    .option('--format <format>', 'json 或 pretty（仅改变缩进）', 'json')
+    .option('--dry-run', '纯本地预览目标范围和请求，不读凭证、不联网')
+    .addHelpText('after', `
+返回 data.tag_category；组状态与组内标签状态均为 0 正常、1 禁用。
+空 tags 表示本次返回为空；缺失 tags 失败，不补造标签全集或历史快照。
+只有一次详情请求，无分页、名称搜索、include、列表降级或自动重试。
+支持微商城单店、零售单店及接口声明的连锁 D/L 总部；at: all 只表示组织位置。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+非总部目标须匹配上下文 shopId。上下文不是授权证明；API 不发送 kdt_id，
+当前调用须具备目标店铺的服务端授权，不能仅靠返回 kdt_id 或本地上下文代证。
+尚未确认目标范围时停止真实调用；参数校验和本地预览不证明远端准入。
+dry-run 无上下文也可本地预览；已有无效或冲突上下文时拒绝。失败 stdout 为空，stderr 为脱敏错误 JSON。
+
+示例：
+  zan-saas customer tagcategory get --kdt-id 63077 --tag-category-id 10355
+  zan-saas customer tagcategory get --kdt-id 63077 --tag-category-id 10355 --dry-run
+`)
+    .action(async options => {
+      let input;
+      try { input = buildInput(options, context); }
+      catch (error) {
+        if (error.cliDetails) throw error;
+        throw parameterError();
+      }
+      const output = options.dryRun ? input : await queryTagCategory(input);
+      if (options.dryRun) validateCommandValue(schema, 'preview', 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) };

package/src/commands/native/customer/tagcategory/get/query.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { requestApi, ApiConfigurationError } = require('../../../../../transport/api');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const schema = require('./schema.json');
+
+const commandPath = 'customer.tagcategory.get';
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function failure(category, stage, scope = {}, facts = {}, requestState = 'not_sent') {
+  const error = new Error(`标签组查询失败：${category}（${stage}）`);
+  error.cliDetails = {
+    category, stage, command: commandPath, targetScope: scope, requestState,
+    nextStep: '核对同版 schema、目标店铺、标签组 ID 和服务端店铺授权；不自动重试、换店或换身份。',
+    ...facts
+  };
+  return error;
+}
+
+function safeFacts(response, result) {
+  const facts = { api: schema.api.path, httpStatus: response.httpStatus };
+  if (Number.isSafeInteger(result?.code) ||
+      (typeof result?.code === 'string' && /^-?\d{1,12}$/.test(result.code))) {
+    facts.businessCode = result.code;
+  }
+  for (const field of ['trace_id', 'request_id']) {
+    const value = result?.[field] ?? result?.gw_err_resp?.[field];
+    if (typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value)) {
+      facts[field] = value;
+    }
+  }
+  if (object(result?.gw_err_resp) &&
+      /^(?:\d{1,12})$/.test(String(result.gw_err_resp.err_code))) {
+    facts.gatewayCode = result.gw_err_resp.err_code;
+  }
+  return facts;
+}
+
+function selectFields(value, definition) {
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.keys(definition.properties)
+    .filter(field => Object.hasOwn(value, field))
+    .map(field => [field, value[field]]));
+}
+
+async function queryTagCategory(input) {
+  const { targetScope, request } = input;
+  let response;
+  try {
+    response = await requestApi(request);
+  } catch (error) {
+    if (error instanceof ApiConfigurationError) {
+      throw failure('configuration', 'configuration', targetScope);
+    }
+    throw failure('transport', 'request', targetScope, {}, 'unknown');
+  }
+  let result;
+  const withinBudget = Buffer.byteLength(response.body, 'utf8') <= MAX_RESPONSE_BYTES;
+  if (withinBudget) {
+    try { result = JSON.parse(response.body); }
+    catch { result = null; }
+  }
+  const facts = safeFacts(response, result);
+  const invalid = stage => failure('protocol', stage, targetScope, facts, 'sent');
+  if (!response.ok) {
+    const category = response.httpStatus === 401 ? 'authentication' :
+      response.httpStatus === 403 ? 'permission' : 'http';
+    throw failure(category, 'response', targetScope, facts, 'sent');
+  }
+  if (!withinBudget) throw invalid('response-budget');
+  if (!object(result)) throw invalid('response');
+  if (facts.gatewayCode !== undefined) {
+    if (result.success === true || result.code === 200) throw invalid('response');
+    throw failure('business_rejected', 'response', targetScope, facts, 'sent');
+  }
+  if (result.success === false ||
+      (Number.isSafeInteger(result.code) && result.code !== 200)) {
+    throw failure('business_rejected', 'response', targetScope, facts, 'sent');
+  }
+  if (result.success !== true || result.code !== 200) throw invalid('success-signals');
+  if (!object(result.data) || result.data.kdt_id !== targetScope.kdtId ||
+      result.data.tag_category_id !== request.body.tag_category_id) throw invalid('identity');
+  const category = selectFields(result.data, schema.definitions.tagCategory);
+  if (Array.isArray(category.tags)) {
+    category.tags = category.tags.map(tag => selectFields(tag, schema.definitions.tag));
+  }
+  const output = { data: { tag_category: category } };
+  try { validateCommandValue(schema, 'output', output); }
+  catch { throw invalid('model'); }
+  if (Buffer.byteLength(JSON.stringify(output), 'utf8') > MAX_OUTPUT_BYTES) {
+    throw invalid('output-budget');
+  }
+  return output;
+}
+
+module.exports = { queryTagCategory, failure, MAX_RESPONSE_BYTES, MAX_OUTPUT_BYTES };