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

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

@@ -0,0 +1,122 @@
+'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 { queryDefinition, validateCommandValue } = require('../../../../../execution/command-schema');
+const { parseIncludeModules, validateRequiredModules } = require('../../../../../execution/command-io');
+const { readApi, ItemQueryError, object } = require('../../shared/api');
+const { normalizeItem } = require('../../shared/normalize');
+const { attachH5, SHOP_API, ORG_API, PAGE_SIZE, MAX_PAGES } = require('../../shared/h5');
+
+const { contentRequest, readContent } = require('../../shared/content');
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const DETAIL_API = schema.api.path;
+const GROUP_API = 'youzan.item.itemgroup.get/1.0.0';
+const { baseModules, includeModules: allowedModules } = queryDefinition(schema);
+
+function buildInput(options, context) {
+  const kdtId = Object.hasOwn(options, 'kdtId') ? options.kdtId :
+    String(resolveTargetShop(options, context, 'item.item.get').kdtId);
+  const scope = diagnostics.itemScope({ ...options, kdtId }, schema);
+  return withInputScope(scope, () => {
+    if (options.include !== undefined && options.include.split(',').some(value => !value.trim())) {
+      throw inputIssue('/include', 'invalid_format', { type: 'array', items: { enum: allowedModules } });
+    }
+    if (options.include?.split(',').some(value => !allowedModules.includes(value.trim()))) {
+      throw inputIssue('/include', 'invalid_choice', { type: 'array', items: { enum: allowedModules } });
+    }
+    const modules = parseIncludeModules(options.include, allowedModules);
+    validateCommandValue(schema, 'input', { ...scope, include: [...modules] });
+    return { scope, modules, body: { request: { kdt_id: scope.kdtId, item_id: scope.item_id, channel: scope.channel } } };
+  });
+}
+function preview(input) {
+  const requests = [{ method: 'POST', path: DETAIL_API, body: input.body }];
+  if (input.modules.has('group')) requests.push({ method: 'POST', path: GROUP_API, body: input.body });
+  requests.push({ method: 'POST', path: SHOP_API, body: {} });
+  if (input.modules.has('content')) requests.push(contentRequest(input.scope));
+  const result = {
+    requests,
+    conditionalRequests: [{
+      condition: '授权店铺为总部且与目标店铺不同：按页查询目标角色，找到即停；失败则停止后续请求。',
+      request: { method: 'POST', path: ORG_API, body: { page_num: 1, page_size: PAGE_SIZE } },
+      maxPages: MAX_PAGES
+    }]
+  };
+  validateCommandValue(schema, 'preview', result);
+  return result;
+}
+async function execute(input) {
+  const { scope, body, modules } = input;
+  const raw = await readApi(DETAIL_API, body, 'item', scope);
+  const invalidIdentity = () => new ItemQueryError(raw == null ? 'not_found' : 'protocol', 'item', scope, { api: DETAIL_API }, 'sent');
+  if (!object(raw)) throw diagnostics.outputIssue(invalidIdentity, schema, '/data/item', 'invalid_type');
+  for (const [field, expected] of [['item_id', scope.item_id], ['kdt_id', scope.kdtId], ['channel', scope.channel]]) {
+    if ((field === 'item_id' || raw[field] != null) && raw[field] !== expected) {
+      throw diagnostics.outputIssue(invalidIdentity, schema, `/data/item/${field}`);
+    }
+  }
+  const data = {};
+  // Validate before auxiliary requests; diagnostic paths never contain received values.
+  const invalidItem = () => new ItemQueryError('protocol', 'item-model', scope, { api: DETAIL_API }, 'sent');
+  data.item = diagnostics.normalize(normalizeItem(raw), schema, '/data/item', invalidItem);
+  delete data.item.group;
+  delete data.item.content;
+  delete data.item.components;
+  diagnostics.validateOutput(schema, { data: { item: { ...data.item, h5_url: null } } }, invalidItem);
+  if (modules.has('group')) {
+    data.group = await readApi(GROUP_API, body, 'group', scope);
+    if (!Array.isArray(data.group)) throw new ItemQueryError('protocol', 'group', scope, { api: GROUP_API }, 'sent');
+  }
+  await attachH5(data.item, scope);
+  if (modules.has('content')) {
+    data.content = await readContent(scope);
+  }
+  validateRequiredModules(data, modules, baseModules);
+  const result = { data };
+  diagnostics.validateOutput(schema, result, () => new ItemQueryError('protocol', 'output-model', scope, {}, 'sent'));
+  return result;
+}
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('get', { path: 'item.item.get', schema, parameterCategory: 'parameter', optionPaths: { '/item_id': 'itemId' } })
+    .description('查询指定店铺和渠道的单个商品，含规格、SKU 和适用的 H5 链接')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺 ID；省略时使用当前上下文店铺')
+    .requiredOption('--item-id <id>', '必填：新版商品 ID，同一商品在分店和渠道间保持相同；不是渠道商品 ID')
+    .option('--channel <channel>', '渠道：0 网店，1 门店', '0')
+    .option('--include <modules>', `追加模块：${allowedModules.join(', ')}；始终保留商品基本信息`)
+    .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.item，不返回库存数量；当前版本只提供库存变化日志，尚无当前库存数量查询入口。
+商品 item_id、规格 sku_id 为统一标识；channel_item_id、channel_sku_id 为目标店铺渠道的标识。
+以商品 ID 和渠道定位，不接收渠道商品 ID 作为替代；输出缺少渠道标识时不使用统一标识补造。
+已定义金额统一为元、固定两位小数字符串；划线价已为元不再除100，原空串/null/省略保留。
+--include group 追加 data.group 分组数组；content 追加 data.content 图文对象。
+默认 H5 需查询店铺角色，总部查目标分店时还需分页查询组织（50/页，最多100页）。
+任何必需查询失败则整体失败，stdout 为空；不将未知角色当作无链接。
+网店/门店渠道不可任意互查，适用范围见同版 Skill reference。
+
+示例：
+  zan-saas item item get --kdt-id 63077 --item-id 123
+  zan-saas item item get --kdt-id 63077 --item-id 123 --include group,content
+  zan-saas item item get --kdt-id 63077 --item-id 123 --channel 1 --dry-run
+
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+at: all 允许总部和非总部位置；目标店铺可显式指定或取当前上下文，由服务端校验用户和店铺权限。
+缺少上下文时可本地 --dry-run；提供了无效上下文时拒绝预览和真实调用。
+无自动重试，不自动切换店铺、渠道或凭证。`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      const result = options.dryRun ? preview(input) : await execute(input);
+      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);