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

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

@@ -0,0 +1,114 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, 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.brand.list';
+const API = 'youzan.item.brand.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 };
+    if (options.name !== undefined) {
+      if (typeof options.name !== 'string') throw inputIssue('/name', 'invalid_type', { type: 'string' });
+      input.name = options.name.trim();
+    }
+    validateCommandValue(schema, 'input', input);
+    const body = { request: { kdt_id: scope.kdtId, page_no: pageNo } };
+    if (input.name !== undefined) body.request.name = input.name;
+    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, 'brands', 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', 'brands-model', scope, 'sent', { api: API });
+  if (!object(raw) || !Array.isArray(raw.items) ||
+      (raw.paginator !== undefined && !object(raw.paginator))) 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 brand of raw.items) {
+    if (!object(brand) || brand.kdt_id !== scope.kdtId) throw invalid();
+  }
+  // Total counts first-level brands; items also includes their lower-level brands.
+  const total = paginator.total_count ?? null;
+  const hasMore = total === null ? null : total > pageNo * PAGE_SIZE;
+  const result = { data: { brands: raw.items, pagination: diagnostics.pagination(pageNo, raw.items.length, hasMore, null) } };
+  result.data.brands = diagnostics.normalize(raw.items, schema, '/data/brands', invalid);
+  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('--name <text>', '一级品牌名称关键词；附带的下级品牌不再按名称筛选')
+    .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', `
+时间点统一输出北京时间 YYYY-MM-DD HH:mm:ss.SSS，字段声明的业务哨兵保留。
+返回 data.brands 平铺品牌列表和 data.pagination，不自动翻页、不拼树或去重。
+接口按每页20个一级品牌分页，并附带这些一级品牌的下级品牌；返回行数可能大于20。
+total 按一级品牌计数，结果数组包含下级品牌，两者不能直接比较。
+接口只提供一级品牌总数，不能代表含下级品牌的列表总数，因此省略 total。
+hasMore 按一级品牌分页判断；无法确认时为 null，空页或短页不推定结束。
+按 nextPageNo 保留店铺和名称条件继续；windowLimitReached=true 时停止，不表示已取完。
+分页结束仅为上游报告信号，不保证并发数据的快照或完整品牌树。
+保留品牌ID、parent_brand_id、毫秒时间戳和接口顺序；不把商品数量当库存。
+仅适用接口支持的零售单店、连锁总部和分店；at: all 不表示任意跨店权限。
+一次查询最多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 brand list --kdt-id 63077
+  zan-saas item brand list --kdt-id 63077 --name 安踏 --page-no 2
+  zan-saas item brand 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);