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

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

@@ -0,0 +1,105 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { withInputScope } = require('../../../../../execution/error-details');
+const diagnostics = require('../../shared/diagnostics');
+const schema = require('./schema.json');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { readApi, ItemQueryError, object } = require('../../shared/api');
+
+const commandPath = 'item.classification.list';
+const API = 'youzan.item.classification.search/1.0.0';
+const PAGE_SIZE = 20;
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const nextStep = '核对当前命令的 schema、目标零售店铺和页码；接口拒绝时核对服务端授权，不自动切换目标。';
+
+function failure(category, stage, scope = {}, sent = 'not_sent', facts = {}) {
+  return new ItemQueryError(category, stage, scope, { ...facts, nextStep }, sent, commandPath);
+}
+function buildInput(options) {
+  const scope = { kdtId: diagnostics.integer(options.kdtId, schema, '/kdtId') };
+  return withInputScope(scope, () => {
+    const pageNo = diagnostics.integer(options.pageNo, schema, '/pageNo');
+    const input = { ...scope, pageNo };
+    validateCommandValue(schema, 'input', input);
+    const body = { request: { kdt_id: scope.kdtId, page_no: pageNo } };
+    return { scope, pageNo, request: { method: 'POST', path: API, body } };
+  });
+}
+async function execute({ scope, pageNo, request }, format) {
+  let raw;
+  try { raw = await readApi(API, request.body, 'classifications', scope, commandPath); }
+  catch (error) {
+    if (error instanceof ItemQueryError) error.cliDetails.nextStep = nextStep;
+    throw error;
+  }
+  if (Buffer.byteLength(JSON.stringify(raw) ?? '') > MAX_RESPONSE_BYTES) {
+    throw failure('budget_exceeded', 'response-bytes', scope, 'sent', { api: API });
+  }
+  const invalid = () => failure('protocol', 'classifications-model', scope, 'sent', { api: API });
+  if (!object(raw) || !Array.isArray(raw.items) ||
+      (raw.paginator !== undefined && !object(raw.paginator)) || raw.items.length > PAGE_SIZE) throw invalid();
+  const paginator = raw.paginator || {};
+  // The official field table uses page_no; its success example and Paginator use page.
+  for (const key of ['page_no', 'page']) {
+    if (paginator[key] !== undefined && paginator[key] !== pageNo) throw invalid();
+  }
+  if ((paginator.page_size !== undefined && paginator.page_size !== PAGE_SIZE) ||
+      (paginator.total_count != null &&
+        (!Number.isSafeInteger(paginator.total_count) || paginator.total_count < 0))) throw invalid();
+  for (const classification of raw.items) {
+    if (!object(classification) || classification.kdt_id !== scope.kdtId) throw invalid();
+  }
+  // Every record counts toward this fixed-size page, regardless of hierarchy level.
+  const total = paginator.total_count ?? null;
+  const hasMore = total === null ? null : total > pageNo * PAGE_SIZE;
+  const result = { data: { classifications: raw.items, pagination: diagnostics.pagination(pageNo, raw.items.length, hasMore, total) } };
+  diagnostics.validateOutput(schema, result, invalid);
+  const output = `${JSON.stringify(result, null, format === 'pretty' ? 2 : 0)}\n`;
+  if (Buffer.byteLength(output) > MAX_OUTPUT_BYTES) {
+    throw failure('budget_exceeded', 'output-bytes', scope, 'sent', { api: API });
+  }
+  return output;
+}
+function createCommand() {
+  return new DiagnosticCommand('list', { path: commandPath, schema, parameterCategory: 'parameter' })
+    .description('查询零售店铺商品分类目录，返回分类及其父分类标识')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标零售店铺 ID；省略时使用当前上下文店铺')
+    .option('--page-no <n>', '页码，从1开始，最大2147483647；每页固定20条分类', '1')
+    .addOption(new Option('--format <format>', 'json 或 pretty（仅改变缩进）').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览一次分页请求，不读凭证、不联网')
+    .addHelpText('after', `
+返回 data.classifications 平铺分类列表和 data.pagination，不自动翻页、不拼树或去重。
+一页可包含不同层级的分类，每页固定20条；父分类可能不在本页，不能当作完整分类树。
+保留接口顺序、分类 ID 和父分类 ID；parent_classification_id=0 表示一级分类。
+pagination.total 为上游报告的匹配总记录数，未取得时省略；有总数时据此判断下一页；缺少总数时 hasMore=null，空页或短页也不推定结束。
+按 nextPageNo 保留店铺继续；windowLimitReached=true 时停止，不表示已取完。
+分页结束仅依据上游报告总数，不保证并发更新下的全集或快照。
+不支持 --name 或 --parent-id，不能把用户的名称或父分类筛选条件静默丢掉。
+适用于接口支持的零售单店、连锁总部和分店；商品分类不是商品分组或平台类目。
+一次查询最多1个业务请求；解包data的JSON最多10MiB，最终stdout最多5MiB，超额整体失败。
+字节预算在响应读取并解析后检查，不是流式网络读取上限。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+缺少上下文可以本地预览，提供无效上下文则拒绝。失败stdout为空，stderr为错误JSON。
+无自动重试、身份/目标切换；不提供 --channel、--page-size、--include、--timeout 或 --retry。
+
+示例：
+  zan-saas item classification list --kdt-id 63077
+  zan-saas item classification list --kdt-id 63077 --page-no 2
+  zan-saas item classification list --kdt-id 63077 --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options);
+      if (options.dryRun) {
+        validateCommandValue(schema, 'preview', input.request);
+        process.stdout.write(`${JSON.stringify(input.request, null, options.format === 'pretty' ? 2 : 0)}\n`);
+      } else process.stdout.write(await execute(input, options.format));
+    });
+}
+module.exports = { kind: 'atomic', risk: 'read', at: 'all' };
+module.exports.createCommand = withTargetShopDefault(createCommand);