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

package/src/commands/native/item/classification/get/command.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const diagnostics = require('../../shared/diagnostics');
+const { withInputScope } = require('../../../../../execution/error-details');
+const schema = require('./schema.json');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { readApi, ItemQueryError, object } = require('../../shared/api');
+
+const commandPath = 'item.classification.get';
+const API = 'youzan.item.classification.get/1.0.0';
+const nextStep = '核对店铺 ID 和分类 ID；接口拒绝时检查授权，不自动换店重查。';
+
+function failure(category, stage, scope = {}, facts = {}, state = 'not_sent') {
+  return new ItemQueryError(category, stage, scope, { ...facts, nextStep }, state, commandPath);
+}
+
+function buildInput(options) {
+  const scope = { kdtId: diagnostics.integer(options.kdtId, schema, '/kdtId') };
+  return withInputScope(scope, () => {
+    scope.classificationId = diagnostics.integer(options.classificationId, schema, '/classificationId');
+    validateCommandValue(schema, 'input', scope);
+    return { scope, request: { method: 'POST', path: API, body: { request: {
+      kdt_id: scope.kdtId, classification_id: scope.classificationId
+    } } } };
+  });
+}
+
+async function execute({ scope, request }) {
+  let classification;
+  try {
+    classification = await readApi(API, request.body, 'classification', scope, commandPath);
+  } catch (error) {
+    if (error instanceof ItemQueryError) {
+      const details = error.cliDetails;
+      details.nextStep = nextStep;
+      if (details.category === 'business_rejected' &&
+          String(details.businessCode) === '401000012') {
+        details.category = 'not_found';
+        details.nextStep = '该分类不存在，请核对店铺 ID 和分类 ID。';
+        error.message = '商品分类不存在。';
+      }
+    }
+    throw error;
+  }
+  const invalid = () => failure('protocol', 'classification-model', scope, { api: API }, 'sent');
+  if (!object(classification) || classification.kdt_id !== scope.kdtId ||
+      classification.classification_id !== scope.classificationId) throw invalid();
+  const result = { data: { classification } };
+  diagnostics.validateOutput(schema, result, invalid);
+  return result;
+}
+
+function createCommand() {
+  return new DiagnosticCommand('get', { path: commandPath, schema, parameterCategory: 'parameter' })
+    .description('查询零售店铺商品分类目录中的单个分类及其父分类标识')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标零售店铺 ID；省略时使用当前上下文店铺')
+    .requiredOption('--classification-id <id>', '必填：该店铺的商品分类 ID')
+    .addOption(new Option('--format <format>', 'json 或 pretty（仅改变缩进）').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览一次分类详情请求，不读凭证、不联网')
+    .addHelpText('after', `
+返回 data.classification，包括分类 ID、店铺 ID 及接口提供的名称、父分类和总部店铺标识。
+分类与商品分组是不同对象；不能用 group_id 或商品 ID 代替分类 ID。
+仅查指定分类，不读取父分类详情、子分类、商品列表或 H5；无渠道、include 或分页参数。
+适用于接口支持的零售单店、连锁总部和分店；at: all 不表示任意跨店权限。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+目标由 --kdt-id 明确指定，服务端校验权限。缺少上下文可本地预览，无效上下文拒绝。
+失败 stdout 为空，stderr 为错误 JSON；分类不存在时保留业务码，不自动重试或切换目标。
+
+示例：
+  zan-saas item classification get --kdt-id 63077 --classification-id 123
+  zan-saas item classification get --kdt-id 63077 --classification-id 123 --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options);
+      const result = options.dryRun ? input.request : await execute(input);
+      if (options.dryRun) validateCommandValue(schema, 'preview', result);
+      process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'all' };
+module.exports.createCommand = withTargetShopDefault(createCommand);

package/src/commands/native/item/classification/get/schema.json

@@ -0,0 +1,596 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "$ref": "#/definitions/scope",
+    "description": "CLI 解析参数并完成必要上下文补全后的业务输入；不是直接传入 CLI 的 JSON。原始选项、必填条件和默认值见 options。"
+  },
+  "output": {
+    "type": "object",
+    "required": [
+      "data"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object",
+        "required": [
+          "classification"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "classification": {
+            "$ref": "#/definitions/classification"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object",
+    "required": [
+      "method",
+      "path",
+      "body"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "method": {
+        "const": "POST"
+      },
+      "path": {
+        "const": "youzan.item.classification.get/1.0.0"
+      },
+      "body": {
+        "type": "object",
+        "required": [
+          "request"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "request": {
+            "type": "object",
+            "required": [
+              "kdt_id",
+              "classification_id"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "kdt_id": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "目标店铺 ID。"
+              },
+              "classification_id": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991,
+                "description": "目标商品分类 ID。"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "scope": {
+      "type": "object",
+      "required": [
+        "kdtId",
+        "classificationId"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kdtId": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "目标零售店铺 ID。"
+        },
+        "classificationId": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "该店铺内的商品分类 ID；不能使用商品 ID 或 group_id。"
+        }
+      }
+    },
+    "classification": {
+      "type": "object",
+      "required": [
+        "kdt_id",
+        "classification_id"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "kdt_id": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "分类所属的店铺 ID，必须等于本次请求的 kdtId。"
+        },
+        "root_kdt_id": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "连锁总部店铺 ID；允许 0，保留原值，不替代目标店铺。"
+        },
+        "classification_id": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "分类 ID，必须等于本次请求的 classificationId。"
+        },
+        "parent_classification_id": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "父分类 ID，0 表示一级分类；不附带父分类详情。"
+        },
+        "name": {
+          "type": "string",
+          "description": "分类名称。"
+        }
+      }
+    },
+    "diagnosticExpected": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [],
+      "properties": {
+        "type": {
+          "anyOf": [
+            {
+              "type": "string",
+              "description": "预期的 JSON 类型。"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "description": "预期的 JSON 类型。"
+              }
+            }
+          ],
+          "description": "同版模型允许的类型。"
+        },
+        "enum": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "契约声明的静态标量约束。"
+          },
+          "description": "同版模型允许的静态值。"
+        },
+        "const": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "契约声明的静态标量约束。"
+        },
+        "minimum": {
+          "type": "number",
+          "description": "包含的最小值。"
+        },
+        "maximum": {
+          "type": "number",
+          "description": "包含的最大值。"
+        },
+        "exclusiveMinimum": {
+          "type": "number",
+          "description": "不包含的最小值。"
+        },
+        "exclusiveMaximum": {
+          "type": "number",
+          "description": "不包含的最大值。"
+        },
+        "minLength": {
+          "type": "integer",
+          "description": "最少字符数。"
+        },
+        "maxLength": {
+          "type": "integer",
+          "description": "最多字符数。"
+        },
+        "minItems": {
+          "type": "integer",
+          "description": "最少元素数。"
+        },
+        "maxItems": {
+          "type": "integer",
+          "description": "最多元素数。"
+        },
+        "format": {
+          "type": "string",
+          "description": "同版模型声明的格式。"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "同版模型声明的字符约束。"
+        },
+        "additionalProperties": {
+          "const": false,
+          "description": "对象拒绝契约以外的属性。"
+        },
+        "contains": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "const"
+          ],
+          "properties": {
+            "const": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "契约声明的静态标量约束。"
+            }
+          }
+        },
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "enum"
+          ],
+          "properties": {
+            "enum": {
+              "type": "array",
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "契约声明的静态标量约束。"
+              },
+              "description": "元素允许的静态值。"
+            }
+          }
+        }
+      }
+    },
+    "diagnosticIssue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source",
+        "reason"
+      ],
+      "properties": {
+        "source": {
+          "enum": [
+            "argv",
+            "input",
+            "context",
+            "output",
+            "preview"
+          ],
+          "description": "问题所属的参数、输入、上下文、结果或预览模型。"
+        },
+        "path": {
+          "type": "string",
+          "description": "对应模型中的 JSON Pointer；不含原始输入或动态字典键。"
+        },
+        "option": {
+          "type": "string",
+          "description": "可定位时给出的已注册 CLI 选项。"
+        },
+        "reason": {
+          "enum": [
+            "required",
+            "invalid_type",
+            "invalid_choice",
+            "out_of_range",
+            "invalid_format",
+            "conditional_required",
+            "constraint",
+            "unexpected_property",
+            "unknown_option",
+            "unknown_command",
+            "excess_arguments",
+            "missing_value"
+          ],
+          "description": "字段违反的约束类型，原始值不回显。"
+        },
+        "expected": {
+          "$ref": "#/definitions/diagnosticExpected",
+          "description": "同版契约的静态预期。"
+        },
+        "relatedPaths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "description": "关联字段的 JSON Pointer。"
+          },
+          "description": "触发条件约束的关联字段。"
+        }
+      }
+    },
+    "diagnosticRecovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "action",
+        "automaticBusinessRetry"
+      ],
+      "properties": {
+        "action": {
+          "enum": [
+            "correct_input",
+            "complete_authentication",
+            "request_access_review",
+            "stop_and_inspect"
+          ],
+          "description": "依次表示修正本地输入、补认证、核对权限或停止核查；仅是说明，不执行操作或授予权限。"
+        },
+        "automaticBusinessRetry": {
+          "const": false,
+          "description": "不据此自动重放业务请求。"
+        }
+      }
+    },
+    "diagnosticExecution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "requestState",
+        "coverage",
+        "observedAttempts"
+      ],
+      "properties": {
+        "requestState": {
+          "enum": [
+            "not_sent",
+            "sent",
+            "unknown"
+          ],
+          "description": "整次调用尚未发送、已有发送记录或无法排除未知请求；不代表业务完成。"
+        },
+        "coverage": {
+          "enum": [
+            "complete",
+            "partial"
+          ],
+          "description": "请求观察覆盖全部已接入路径，或存在未观测路径；部分覆盖不能声明零请求。"
+        },
+        "observedAttempts": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "本地已进入发送边界的观测次数下界，不是服务端执行次数。"
+        }
+      }
+    }
+  },
+  "modules": {
+    "classification": {
+      "base": true,
+      "upstreamPath": "data",
+      "required": true,
+      "description": "本次指定店铺和分类 ID 的单个商品分类。"
+    }
+  },
+  "api": {
+    "method": "POST",
+    "path": "youzan.item.classification.get/1.0.0"
+  },
+  "success": {
+    "description": "分类及店铺 ID 均匹配目标，详情满足模型后输出 data.classification。"
+  },
+  "errors": {
+    "description": "失败 stdout 为空，stderr 为一份脱敏错误 JSON，退出码非零；不返回部分成功，不自动重试、切换身份或目标。按 error 模型及安全下一步处理。 明确业务拒绝 401000012 为 not_found；空或错型对象不代表不存在。",
+    "diagnosticsVersion": 2
+  },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "对象是商家商品分类定义，不是商品分组、平台类目或商品；指定分类 ID，店铺省略时使用当前上下文；无渠道参数。",
+    "成功必须返回并匹配店铺 ID 和分类 ID；其余字段可省略，null 按字段模型判断，不补造。",
+    "parent_classification_id=0 表示一级，root_kdt_id 可为 0；不自动查询父子分类或组装树。",
+    "保留空名称和未知扩展，整数须在安全范围内；一次查询，不附带商品、H5 或角色资料。",
+    "支持零售单店、连锁总部及分店，不表示微商城支持、跨店授权或分类 ID 可跨店互换。",
+    "当前请求编码尚未在真实网关验收，本地预览不证明分类存在或授权有效。",
+    "本地 --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",
+          "errorVersion",
+          "recovery",
+          "execution"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string",
+            "enum": [
+              "parameter",
+              "configuration",
+              "transport",
+              "authentication",
+              "permission",
+              "http",
+              "protocol",
+              "business_rejected",
+              "not_found",
+              "scope_unresolved",
+              "pagination_stalled",
+              "budget_exceeded",
+              "missing_alias"
+            ]
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "command": {
+            "const": "item.classification.get"
+          },
+          "targetScope": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/scope"
+              },
+              {
+                "type": "object",
+                "maxProperties": 0
+              }
+            ]
+          },
+          "requestState": {
+            "type": "string",
+            "enum": [
+              "not_sent",
+              "sent",
+              "unknown"
+            ],
+            "description": "not_sent 确认本步请求未发送；sent 已取得本步响应；unknown 传输中断，无法确定本步结果。不是整个多步查询的发送汇总。"
+          },
+          "nextStep": {
+            "type": "string",
+            "minLength": 1
+          },
+          "api": {
+            "type": "string",
+            "minLength": 1
+          },
+          "httpStatus": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 599
+          },
+          "businessCode": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?\\d{1,12}$"
+              }
+            ]
+          },
+          "gatewayCode": {
+            "oneOf": [
+              {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "pattern": "^-?\\d{1,12}$"
+              }
+            ]
+          },
+          "trace_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          },
+          "request_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]{1,128}$"
+          },
+          "errorVersion": {
+            "const": 2,
+            "description": "本命令采用错误诊断协议第二版。"
+          },
+          "issues": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 16,
+            "items": {
+              "$ref": "#/definitions/diagnosticIssue"
+            },
+            "description": "最多十六个已定位问题，不包含收到的原值。"
+          },
+          "issuesTruncated": {
+            "const": true,
+            "description": "问题超过返回上限，当前列表没有穷尽全部问题。"
+          },
+          "recovery": {
+            "$ref": "#/definitions/diagnosticRecovery",
+            "description": "受限的恢复说明，不会自动执行。"
+          },
+          "execution": {
+            "$ref": "#/definitions/diagnosticExecution",
+            "description": "整次调用的请求观察，独立于失败阶段的 requestState。"
+          }
+        }
+      }
+    }
+  }
+}