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

package/src/commands/native/item/shared/content.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { readApi, ItemQueryError, object } = require('./api');
+const CONTENT_API = 'youzan.item.itemdesc.get/1.0.0';
+
+function contentRequest(scope) {
+  return { method: 'POST', path: CONTENT_API,
+    body: { request: { kdt_id: scope.kdtId, item_id: scope.item_id, channel: scope.channel } } };
+}
+
+async function readContent(scope, command = 'item.item.get') {
+  const request = contentRequest(scope);
+  const content = await readApi(request.path, request.body, 'content', scope, command);
+  if (!object(content)) {
+    throw new ItemQueryError('protocol', 'content', scope, { api: CONTENT_API }, 'sent', command);
+  }
+  return content;
+}
+
+module.exports = { CONTENT_API, contentRequest, readContent };

package/src/commands/native/item/shared/diagnostics.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { parseIntegerOption, inputIssue, constraints, modelAt } = require('../../../../execution/error-details');
+const { normalizeMoney } = require('../../../../execution/money');
+const { normalizeTimes } = require('../../../../execution/datetime');
+const { validateCommandValue } = require('../../../../execution/command-schema');
+
+function integer(raw, schema, path) {
+  return parseIntegerOption(typeof raw === 'string' ? raw.trim() : raw, schema, path);
+}
+function itemScope(options, schema) {
+  const scope = { kdtId: integer(options.kdtId, schema, '/kdtId'),
+    item_id: integer(options.itemId, schema, '/item_id'), channel: Number(options.channel) };
+  if (!['0', '1'].includes(options.channel)) {
+    throw inputIssue('/channel', 'invalid_choice', constraints(modelAt(schema, 'input', '/channel')));
+  }
+  validateCommandValue(schema, 'input', scope);
+  return scope;
+}
+function outputIssue(failure, schema, path, reason = 'constraint') {
+  const error = failure();
+  error.issues = [{ source: 'output', path, reason,
+    expected: constraints(modelAt(schema, 'output', path)) }];
+  return error;
+}
+// Traverse only declared fields. Paths contain static model names and array indexes, never data keys.
+function normalize(value, schema, path, failure) {
+  const model = modelAt(schema, 'output', path);
+  if (!model || value == null) return value;
+  if (model.$comment?.startsWith('upstream-money:') || model.$comment?.startsWith('upstream-time:')) {
+    try { return normalizeTimes(normalizeMoney(value, model), model, schema.definitions); }
+    catch { throw outputIssue(failure, schema, path, 'invalid_format'); }
+  }
+  if (Array.isArray(value) && model.items) {
+    return value.map((entry, index) => normalize(entry, schema, `${path}/${index}`, failure));
+  }
+  if (typeof value === 'object' && !Array.isArray(value) && model.properties) {
+    const result = { ...value };
+    for (const key of Object.keys(model.properties)) {
+      if (Object.hasOwn(value, key)) result[key] = normalize(value[key], schema, `${path}/${key}`, failure);
+    }
+    return result;
+  }
+  return value;
+}
+function validateOutput(schema, result, failure) {
+  try { validateCommandValue(schema, 'output', result); }
+  catch (cause) {
+    const error = failure();
+    if (cause.issues) error.issues = cause.issues;
+    if (cause.issuesTruncated) error.issuesTruncated = true;
+    throw error;
+  }
+}
+function pagination(pageNo, returned, hasMore, total) {
+  return { pageNo, pageSize: 20, returned, hasMore,
+    ...(total === null ? {} : { total }),
+    nextPageNo: hasMore === true && pageNo < 2147483647 ? pageNo + 1 : null,
+    windowLimitReached: hasMore !== false && pageNo === 2147483647 };
+}
+module.exports = { integer, itemScope, outputIssue, normalize, validateOutput, pagination };

package/src/commands/native/item/shared/h5.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const { ItemQueryError, readApi, object } = require('./api');
+const SHOP_API = 'youzan.shop.basic.get/3.0.0';
+const ORG_API = 'youzan.shop.chain.descendent.organization.list/1.0.1';
+const PAGE_SIZE = 50;
+const MAX_PAGES = 100;
+const knownRoles = new Set([0, 1, 2001, 2002, 3, 4, 6, 7]);
+
+async function resolveRole(scope, command) {
+  const failure = (category, stage, facts = {}) =>
+    new ItemQueryError(category, stage, scope, facts, 'sent', command);
+  const basic = await readApi(SHOP_API, {}, 'shop-role', scope, command);
+  if (!object(basic) || !knownRoles.has(basic.role) ||
+      !Number.isSafeInteger(basic.sid ?? basic.kdt_id)) {
+    throw failure('protocol', 'shop-role', { api: SHOP_API });
+  }
+  if ((basic.sid ?? basic.kdt_id) === scope.kdtId) return basic.role;
+  if (basic.role !== 1) {
+    throw failure('scope_unresolved', 'shop-role');
+  }
+  const seen = new Set();
+  let read = 0;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const data = await readApi(ORG_API, { page_num: page, page_size: PAGE_SIZE }, 'organization-role', scope, command);
+    if (!object(data) || !Array.isArray(data.organization_list)) {
+      throw failure('protocol', 'organization-role', { api: ORG_API });
+    }
+    const total = data.total ?? data.paginator?.total_count;
+    if (total != null && (!Number.isSafeInteger(total) || total < 0)) {
+      throw failure('protocol', 'organization-role', { api: ORG_API });
+    }
+    let added = 0;
+    for (const org of data.organization_list) {
+      if (!object(org) || !Number.isSafeInteger(org.kdt_id) || !knownRoles.has(org.role)) {
+        throw failure('protocol', 'organization-role', { api: ORG_API });
+      }
+      if (org.kdt_id === scope.kdtId) return org.role;
+      if (!seen.has(org.kdt_id)) { seen.add(org.kdt_id); added++; }
+    }
+    read += data.organization_list.length;
+    if (data.organization_list.length < PAGE_SIZE || (total != null && read >= total)) break;
+    if (added === 0) throw failure('pagination_stalled', 'organization-role');
+    if (page === MAX_PAGES) throw failure('budget_exceeded', 'organization-role');
+  }
+  throw failure('scope_unresolved', 'organization-role');
+}
+async function attachH5(item, scope) {
+  await attachH5Items([item], scope);
+}
+async function attachH5Items(items, scope, command = 'item.item.get') {
+  if (items.length === 0) return;
+  const role = await resolveRole(scope, command);
+  const applicable = role === 0 || (role === 2002 && scope.channel === 0);
+  for (const item of items) {
+    if (!applicable) { item.h5_url = null; continue; }
+    if (typeof item.alias !== 'string' || !item.alias.trim()) {
+      throw new ItemQueryError('missing_alias', 'h5-link', scope, {}, 'sent', command);
+    }
+    item.h5_url = `https://h5.youzan.com/v2/goods/${item.alias.trim()}`;
+  }
+}
+module.exports = { attachH5, attachH5Items, SHOP_API, ORG_API, PAGE_SIZE, MAX_PAGES };

package/src/commands/native/item/shared/identity.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const detailPath = 'youzan.item.itemdetail.get/1.0.0';
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function mappingRequest(scope) {
+  return { method: 'POST', path: detailPath, body: { request: {
+    kdt_id: Number(scope.kdtId), item_id: Number(scope.item_id), channel: scope.channel
+  } } };
+}
+
+function channelIdentity(source, scope, { skuMapping = false } = {}) {
+  if (!object(source) || source.item_id !== Number(scope.item_id) ||
+      !Number.isSafeInteger(source.channel_item_id) || source.channel_item_id < 1 ||
+      (source.kdt_id != null && source.kdt_id !== Number(scope.kdtId)) ||
+      (source.channel != null && source.channel !== scope.channel)) {
+    throw new Error('Product identity mismatch');
+  }
+  const skus = new Map();
+  const unified = new Set();
+  if (skuMapping && source.skus != null) {
+    if (!Array.isArray(source.skus)) throw new Error('Invalid SKU identities');
+    for (const sku of source.skus) {
+      if (!object(sku)) throw new Error('Invalid SKU identity');
+      if (sku.sku_id == null || sku.channel_sku_id == null) continue;
+      if (!Number.isSafeInteger(sku.sku_id) || sku.sku_id < 0 ||
+          !Number.isSafeInteger(sku.channel_sku_id) || sku.channel_sku_id < 0 ||
+          skus.has(sku.channel_sku_id) || unified.has(sku.sku_id)) {
+        throw new Error('Ambiguous SKU identities');
+      }
+      skus.set(sku.channel_sku_id, sku.sku_id);
+      unified.add(sku.sku_id);
+    }
+  }
+  return { item_id: source.item_id, channel_item_id: source.channel_item_id, skus };
+}
+
+function legacyLog(source, identity) {
+  if (!object(source) || source.item_id !== identity.channel_item_id ||
+      (Object.hasOwn(source, 'unified_item_id') && source.unified_item_id !== identity.item_id)) {
+    throw new Error('Log identity mismatch');
+  }
+  const { item_id, sku_id, unified_item_id, unified_sku_id, channel_item_id, channel_sku_id, ...rest } = source;
+  if ((channel_item_id !== undefined && channel_item_id !== item_id) ||
+      (channel_sku_id !== undefined && channel_sku_id !== sku_id)) throw new Error('Conflicting log identities');
+  const output = { ...rest, item_id: identity.item_id, channel_item_id: item_id };
+  if (Object.hasOwn(source, 'sku_id')) {
+    if (!Number.isSafeInteger(sku_id)) throw new Error('Invalid log SKU');
+    output.channel_sku_id = sku_id;
+    if (identity.skus.has(sku_id)) output.sku_id = identity.skus.get(sku_id);
+  }
+  if (Object.hasOwn(source, 'unified_sku_id')) {
+    if (!Number.isSafeInteger(unified_sku_id) || unified_sku_id < 0 ||
+        (output.sku_id !== undefined && output.sku_id !== unified_sku_id)) {
+      throw new Error('Conflicting unified SKU');
+    }
+    output.sku_id = unified_sku_id;
+  }
+  return output;
+}
+
+module.exports = { detailPath, mappingRequest, channelIdentity, legacyLog };

package/src/commands/native/item/shared/normalize.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { object } = require('./api');
+
+// Inventory quantities belong to independent inventory queries, including nested combo SKUs.
+const inventoryFields = new Set([
+  'stock_num', 'stock_num_str', 'spot_stock_num', 'spot_stock_num_str',
+  'plan_stock_num', 'plan_stock_num_str', 'total_stock', 'total_stock_str',
+  'stock_display_note', 'stockNum', 'stockNumStr', 'spotStockNum', 'spotStockNumStr',
+  'planStockNum', 'planStockNumStr', 'totalStock', 'totalStockStr', 'stockDisplayNote',
+  'stock_count', 'stock_quantity', 'available_stock', 'available_stock_num',
+  'freeze_stock', 'freeze_stock_num', 'frozen_stock', 'frozen_stock_num',
+  'stockCount', 'stockQuantity', 'availableStock', 'availableStockNum',
+  'freezeStock', 'freezeStockNum', 'frozenStock', 'frozenStockNum'
+]);
+function withoutInventory(value) {
+  if (Array.isArray(value)) return value.map(withoutInventory);
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !inventoryFields.has(key)).map(([key, child]) => [key, withoutInventory(child)]));
+}
+function firstText(values) {
+  for (const value of values) {
+    if (value != null && String(value).trim()) return String(value).trim();
+  }
+}
+function hasSpecs(list) {
+  return Array.isArray(list) && list.some(entry => object(entry) &&
+    ((Array.isArray(entry.spec_values) && entry.spec_values.length > 0) ||
+      firstText([entry.spec_name, entry.spec_value_name, entry.name, entry.value]) != null));
+}
+function normalizeItem(raw) {
+  const item = withoutInventory(raw);
+  if (item.item_code == null) {
+    const code = firstText([item.item_no, item.outer_item_code, item.outer_item_id, item.goods_code, item.code]);
+    if (code !== undefined) item.item_code = code;
+  }
+  const skus = Array.isArray(item.skus) ? item.skus : [];
+  for (const sku of skus) {
+    if (!object(sku) || sku.sku_code != null) continue;
+    const code = firstText([sku.sku_no, sku.outer_sku_code, sku.outer_sku_id, sku.code]);
+    if (code !== undefined) sku.sku_code = code;
+  }
+  item.is_multi_sku = skus.length > 1 || hasSpecs(item.specs) || skus.some(sku => hasSpecs([sku]));
+  item.is_multi_unit = object(item.ability_mark?.item_mark?.multi_unit_mark);
+  return item;
+}
+
+module.exports = { normalizeItem, withoutInventory, inventoryFields };

package/src/commands/native/item/shared/scope.js

@@ -0,0 +1,22 @@
+'use strict';
+
+function positiveId(raw, flag) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+    throw new Error(`${flag} 须为正整数且不超过 9007199254740991`);
+  }
+  return Number(value);
+}
+
+function itemScope(options) {
+  const scope = {
+    kdtId: positiveId(options.kdtId, '--kdt-id'),
+    item_id: positiveId(options.itemId, '--item-id'),
+    channel: Number(options.channel)
+  };
+  if (!['0', '1'].includes(options.channel)) throw new Error('--channel 仅支持 0 或 1');
+  if (!['json', 'pretty'].includes(options.format)) throw new Error('--format 仅支持 json 或 pretty');
+  return scope;
+}
+
+module.exports = { itemScope, positiveId };

package/src/commands/native/item/shared/search-command.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { DiagnosticCommand } = require('../../../../cli/diagnostic-command');
+const { ItemQueryError } = require('./api');
+const { buildInput, apiInput, addFilters } = require('./search-options');
+const { execute, preview } = require('./search');
+const { validateCommandValue } = require('../../../../execution/command-schema');
+const { resolveTargetShop } = require('../../../../execution/target-shop');
+function createSearchCommand(mode, schema, context) {
+  const path = `item.item.${mode}`;
+  const parameter = () => {
+    const failure = new ItemQueryError('parameter', 'input', {}, {}, 'not_sent', path);
+    failure.message = `商品搜索参数无效，请查看 zan-saas item item ${mode} --help。`;
+    return failure;
+  };
+  let command = addFilters(new DiagnosticCommand(mode, { path, schema, parameterCategory: 'parameter', optionPaths: { '/item_ids': 'itemIds' } }), mode)
+    .description(mode === 'list' ? '查询指定店铺和渠道的一页商品' : '按创建时间分片遍历商品；预算不足时整体失败，不返回部分结果')
+    .allowExcessArguments(false);
+
+  if (mode === 'list') command = command.option('--page-no <n>', '页码，从 1 开始；page-no × page-size ≤ 5000', '1')
+    .option('--page-size <n>', '每页 1 至 50 条', '20')
+    .option('--sorts <values>', '官方排序枚举列表，如 ACTUAL_SOLD_NUM_DESC；最多20项');
+  else command = command.option('--max-items <n>', '去重结果预算，1 至 50000；超限整体失败', '1000')
+    .option('--max-requests <n>', '搜索与探测预算，1 至 2000；不含后续 H5 角色和组织查询', '100');
+  return command.addHelpText('after', `
+默认补适用 H5，不返回库存数量；不根据缺失 SKU 推断规格标记。
+筛选和返回的 item_id 是分店、渠道间统一的商品 ID，channel_item_id 是目标店铺渠道的商品 ID。
+需要商品详情或图文时，继续使用 item_id 和相同店铺、渠道，不把 channel_item_id 填入 --item-id。
+已定义金额统一为元、固定两位小数字符串；price从分精确转换，origin_price仅规范小数位，原空串保留。
+不提供 group/content 扩展；需要关联详情时使用已发布的 item item get。
+${mode === 'list' ? '只读取当前页；匹配总数见 pagination.total，未提供时为null。nextPageNo非null时保留筛选和pageSize继续；windowLimitReached=true时缩小筛选，或明确完整创建时间窗口后用scan。' :
+'固定50/页、创建时间与ID降序；必须显式提供完整创建窗口且开始早于结束，时间闭区间二分，其他筛选始终保留。\n成功返回 data.items 与 data.scope，表示本次声明范围的扫描已完成，不保证并发更新时的快照全集。超预算不输出部分商品；缩小时间/筛选或显式调整有界预算后重新查询。'}
+搜索 JSON 数据累计最多10MiB，完整输出最多5MiB；角色查询另至多1+100次，找到目标即停。
+时间输入统一为北京时间 YYYY-MM-DD HH:mm:ss，可追加 1 至 3 位毫秒；不接受时间戳、T 或时区后缀。
+区间使用 --created-at/--updated-at "START..END"，必须包含 ..；省略边界不会补值。
+已定义时间点输出为 YYYY-MM-DD HH:mm:ss.SSS；请求预览展示接口使用的毫秒整数。
+必需查询失败时 stdout 为空、stderr 为错误 JSON；无自动重试，不切换目标。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+at: all 允许总部和非总部位置；目标店铺可显式指定或取当前上下文，由服务端校验用户和店铺权限。
+缺少上下文时可本地 --dry-run；提供了无效上下文时拒绝预览和真实调用。
+
+示例：
+  zan-saas item item ${mode} --kdt-id 101919147 --item-ids 5399188439 ${mode === 'scan' ? '--created-at "2026-10-01 00:00:00..2026-11-01 00:00:00" ' : ''}--dry-run
+  zan-saas item item ${mode} --kdt-id 101919147 ${mode === 'list' ? '--page-size 10 --sorts ACTUAL_SOLD_NUM_DESC' : '--created-at "2026-10-01 00:00:00..2026-11-01 00:00:00" --max-items 1000 --max-requests 100'}
+`).action(async options => {
+    let input;
+    try {
+      const kdtId = Object.hasOwn(options, 'kdtId') ? options.kdtId :
+        String(resolveTargetShop(options, context, path).kdtId);
+      input = buildInput({ ...options, kdtId }, mode, schema);
+      validateCommandValue(schema, 'input', input);
+      input = apiInput(input, mode);
+    }
+    catch (error) { if (error.issues || error.cliDetails) throw error; throw parameter(); }
+    let result;
+    if (options.dryRun) { result = preview(input, mode); validateCommandValue(schema, 'preview', result); }
+    else result = await execute(input, mode, schema);
+    process.stdout.write(`${JSON.stringify(result, null, options.format === 'pretty' ? 2 : 0)}\n`);
+  });
+}
+module.exports = { createSearchCommand };

package/src/commands/native/item/shared/search-options.js

@@ -0,0 +1,150 @@
+'use strict';
+
+const { Option } = require('commander');
+const { parseDateTime } = require('../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../execution/range');
+const { inputIssue, modelAt, constraints } = require('../../../../execution/error-details');
+const API = 'youzan.item.base.search/1.0.0';
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const sortEnums = ['CREATED_TIME_DESC', 'CREATED_TIME_ASC', 'PRICE_DESC', 'PRICE_ASC',
+  'STOCK_NUM_DESC', 'STOCK_NUM_ASC', 'ID_DESC', 'ID_ASC', 'ACTUAL_SOLD_NUM_DESC', 'ACTUAL_SOLD_NUM_ASC'];
+const typeCodes = {
+  实物商品: '00000000000000000', 蛋糕烘焙: '01000000000100000', 生鲜果蔬: '01000000004204200',
+  海淘商品: '01000000004304300', 虚拟商品: '00000000000000002', 电子卡券: '00000000000000003',
+  付费优惠券: '01000000005100002', 酒店商品: '00000000003503500',
+  付费会员卡: '00000000002002002', 权益卡: '00000000002002002', 服务商品: '10000000000000002'
+};
+const filterFields = [
+  ['classificationIds', 'classification_ids', 1], ['item_ids', 'item_ids', 1],
+  ['groupIds', 'group_ids', 1], ['secondGroupIds', 'second_group_ids', 1],
+  ['notExcludeAbilityCodes', 'not_exclude_ability_codes', 0, 2147483647],
+  ['isDisplays', 'is_displays', 0, 1], ['soldStatusList', 'sold_status_list', 0, 3]
+];
+function integer(raw, name, minimum = 1, maximum = Number.MAX_SAFE_INTEGER) {
+  if ((typeof raw !== 'string' && typeof raw !== 'number') || !/^-?\d+$/.test(String(raw).trim())) {
+    throw new Error(`${name} 须为范围内的整数，详见 help/schema`);
+  }
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`${name} 须为范围内的整数，详见 help/schema`);
+  }
+  return value;
+}
+function list(raw, name, parse) {
+  let values;
+  try {
+    const text = raw.trim();
+    if (!text) throw new Error();
+    values = text.startsWith('[') ? JSON.parse(text) : text.split(/[,\s]+/);
+    if (!Array.isArray(values) || !values.length || values.length > 20) throw new Error();
+    values = values.map(parse);
+  } catch { throw new Error(`${name} 须为 1 至 20 项的有效列表，详见 help/schema`); }
+  return [...new Set(values)];
+}
+function buildInput(options, mode, schema = require(`../item/${mode}/schema.json`)) {
+  function field(name, action) {
+    try { return action(); }
+    catch (error) {
+      const path = `/${name}`;
+      const model = modelAt(schema, 'input', path);
+      const expected = constraints(model);
+      if (model?.items?.enum) expected.items = { enum: model.items.enum };
+      if (name === 'createdAt' || name === 'updatedAt') {
+        expected.format = '北京时间 YYYY-MM-DD HH:mm:ss[.SSS]，区间必须包含 ..';
+      }
+      throw inputIssue(path, expected.enum || expected.items?.enum ? 'invalid_choice' :
+        expected.type === 'integer' && /^-?\d+$/.test(String(options[name])) ? 'out_of_range' : 'invalid_format', expected);
+    }
+  }
+  const input = { kdtId: field('kdtId', () => integer(options.kdtId, '--kdt-id')), channel: field('channel', () => integer(options.channel, '--channel', 0, 1)) };
+  if (!['json', 'pretty'].includes(options.format)) throw new Error('--format 仅支持 json 或 pretty');
+  if (mode === 'list') {
+    input.pageNo = field('pageNo', () => integer(options.pageNo, '--page-no'));
+    input.pageSize = field('pageSize', () => integer(options.pageSize, '--page-size', 1, 50));
+    if (input.pageNo * input.pageSize > 5000) throw inputIssue('/pageNo', 'constraint', { maximum: Math.floor(5000 / input.pageSize),
+      format: '页码 × 每页条数不能超过 5000；请缩小筛选范围。需要跨页扫描时，使用 item item scan 并明确完整创建时间范围。' }, ['/pageSize']);
+  } else {
+    input.maxItems = field('maxItems', () => integer(options.maxItems, '--max-items', 1, 50000));
+    input.maxRequests = field('maxRequests', () => integer(options.maxRequests, '--max-requests', 1, 2000));
+  }
+  for (const [option, key, min, max] of filterFields) {
+    const value = options[option === 'item_ids' ? 'itemIds' : option];
+    if (value !== undefined) input[option] = field(option, () => list(value, `--${key.replaceAll('_', '-')}`,
+      value => integer(value, key, min, max)));
+  }
+  if (options.keyword !== undefined) {
+    if (!options.keyword.trim()) throw inputIssue('/keyword', 'invalid_format', {type: 'string', minLength: 1});
+    input.keyword = options.keyword;
+  }
+  if (options.itemType !== undefined) {
+    const value = typeCodes[options.itemType.trim()] ?? options.itemType.trim();
+    if (!/^\d{17}$/.test(value) || ['10000000000000003', '10000000000000004'].includes(value)) {
+      throw inputIssue('/itemType', 'invalid_format', { type: 'string', pattern: '^\\d{17}$' });
+    }
+    input.itemType = value;
+  }
+  if (options.sorts !== undefined) input.sorts = field('sorts', () => list(options.sorts, '--sorts', value => {
+    if (typeof value !== 'string' || !sortEnums.includes(value)) throw new Error();
+    return value;
+  }));
+  for (const option of ['createdAt', 'updatedAt']) {
+    if (options[option] !== undefined) {
+      const range = field(option, () => parseDateTimeRange(options[option], { precision: 'milliseconds',
+        requireBoth: mode === 'scan' && option === 'createdAt',
+        strictOrder: mode === 'scan' && option === 'createdAt' }));
+      if (Object.values(range).some(value => parseDateTime(value) < 0)) {
+        throw inputIssue(`/${option}`, 'out_of_range', { format: '北京时间，不早于 1970-01-01 08:00:00' });
+      }
+      input[option] = range;
+    }
+  }
+  if (mode === 'scan' && !input.createdAt) throw inputIssue('/createdAt', 'required');
+  return input;
+}
+function apiInput(input, mode) {
+  const body = {
+    kdt_id: input.kdtId, channel: input.channel,
+    page_no: mode === 'scan' ? 1 : input.pageNo,
+    page_size: mode === 'scan' ? 50 : input.pageSize
+  };
+  for (const [option, key] of filterFields) {
+    if (input[option] !== undefined) body[key] = input[option];
+  }
+  for (const [option, key] of [['keyword', 'keyword'], ['itemType', 'publish_code'], ['sorts', 'sorts']]) {
+    if (input[option] !== undefined) body[key] = input[option];
+  }
+  if (mode === 'scan') body.sorts = ['CREATED_TIME_DESC', 'ID_DESC'];
+  for (const [option, kind] of [['createdAt', 'create'], ['updatedAt', 'update']]) {
+    if (!input[option]) continue;
+    body.item_range_query ??= {};
+    for (const [field, prefix] of [['start', 'min'], ['end', 'max']]) {
+      if (input[option][field] !== undefined) body.item_range_query[`${prefix}_${kind}_time`] = parseDateTime(input[option][field]);
+    }
+  }
+  return { scope: { kdtId: input.kdtId, channel: input.channel }, body, limits: {
+    maxItems: mode === 'scan' ? input.maxItems : input.pageSize,
+    maxRequests: mode === 'scan' ? input.maxRequests : 1,
+    maxResponseBytes: MAX_RESPONSE_BYTES, maxOutputBytes: MAX_OUTPUT_BYTES
+  } };
+}
+function addFilters(command, mode) {
+  const filtered = command.option('--kdt-id <id>', '目标店铺 ID；省略时使用当前上下文店铺')
+    .option('--channel <channel>', '渠道：0 网店，1 门店；各渠道商品可能重叠，数量不能直接相加', '0')
+    .option('--classification-ids <ids>', '商品分类 ID 列表，最多 20 项')
+    .option('--item-ids <ids>', '新版商品 ID 列表，最多 20 项；不是渠道商品 ID')
+    .option('--group-ids <ids>', '一级分组 ID 列表，最多 20 项')
+    .option('--second-group-ids <ids>', '二级分组 ID 列表，最多 20 项')
+    .option('--not-exclude-ability-codes <codes>', '不排除的能力标，10033 使套餐可被搜索，不是只选套餐')
+    .option('--is-displays <values>', '上下架筛选列表：0 仓库中，1 出售中/已售罄')
+    .option('--sold-status-list <values>', '销售状态筛选列表：0、1、2、3，组合规则见 schema')
+    .option('--keyword <text>', '搜索商品标题、商品/SKU 编码及条码')
+    .option('--item-type <type>', '商品类型文案或17位发布码；兼容映射及边界见 schema')
+    .option('--updated-at <range>', '更新时间闭区间 START..END，可省略一端；北京时间，可带毫秒')
+    .addOption(new Option('--format <format>', 'json 或 pretty').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览请求、条件和预算，不读凭证、不联网');
+  return mode === 'scan'
+    ? filtered.requiredOption('--created-at <range>', '必填：创建时间闭区间 START..END，必须两端且开始早于结束；北京时间，可带毫秒')
+    : filtered.option('--created-at <range>', '创建时间闭区间 START..END，可省略一端；北京时间，可带毫秒');
+}
+module.exports = { API, sortEnums, typeCodes, buildInput, apiInput, addFilters, MAX_RESPONSE_BYTES, MAX_OUTPUT_BYTES };

package/src/commands/native/item/shared/search.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const { readApi, ItemQueryError, object } = require('./api');
+const { withoutInventory } = require('./normalize');
+const { normalizeMoney } = require('../../../../execution/money');
+const { normalizeTimes } = require('../../../../execution/datetime');
+const { attachH5Items, SHOP_API, ORG_API, PAGE_SIZE, MAX_PAGES } = require('./h5');
+const { API } = require('./search-options');
+const { validateCommandValue } = require('../../../../execution/command-schema');
+const { constraints, modelAt } = require('../../../../execution/error-details');
+
+function failure(input, mode, category, stage, sent = 'sent') {
+  return new ItemQueryError(category, stage, input.scope, { api: API }, sent, `item.item.${mode}`);
+}
+function preview(input, mode) {
+  const search = { method: 'POST', path: API, body: input.body };
+  return {
+    requests: [search],
+    conditionalRequests: [
+      { condition: '搜索返回商品时，默认读取授权店铺角色以补 H5；空列表不查角色。',
+        request: { method: 'POST', path: SHOP_API, body: {} }, maxRequests: 1 },
+      { condition: '授权店铺是总部且目标不同：按页查目标角色，找到即停。',
+        request: { method: 'POST', path: ORG_API, body: { page_num: 1, page_size: PAGE_SIZE } }, maxRequests: MAX_PAGES }
+    ],
+    mode, limits: input.limits,
+    strategy: mode === 'list' ? '单页搜索，不自动翻页。' :
+      '串行按50/页读取；每片探测总数达到5000时按创建时间闭区间二分，保留其他全部筛选；ID去重，短页才结束，预算耗尽整体失败。'
+  };
+}
+async function execute(input, mode, schema) {
+  const command = `item.item.${mode}`;
+  let requests = 0, responseBytes = 0;
+  const resultItems = [], seen = new Set();
+  let itemBytes = 2;
+  async function page(body) {
+    if (requests >= input.limits.maxRequests) throw failure(input, mode, 'budget_exceeded', 'search-requests', 'not_sent');
+    requests++;
+    const raw = await readApi(API, body, 'search', input.scope, command);
+    responseBytes += Buffer.byteLength(JSON.stringify(raw) ?? '');
+    if (responseBytes > input.limits.maxResponseBytes) throw failure(input, mode, 'budget_exceeded', 'response-bytes');
+    if (!object(raw) || !Array.isArray(raw.items) || raw.items.length > body.page_size ||
+        (raw.paginator != null && !object(raw.paginator))) throw failure(input, mode, 'protocol', 'search-page');
+    const paginator = raw.paginator || {};
+    for (const [key, expected] of [['page_no', body.page_no], ['page_size', body.page_size]]) {
+      if (paginator[key] != null && paginator[key] !== expected) throw failure(input, mode, 'protocol', 'search-page');
+    }
+    if (paginator.total_count != null && (!Number.isSafeInteger(paginator.total_count) || paginator.total_count < 0)) {
+      throw failure(input, mode, 'protocol', 'search-page');
+    }
+    function invalidItem(index, field, stage, reason = 'constraint') {
+      const path = `/data/items/${index}${field ? `/${field}` : ''}`;
+      const error = failure(input, mode, 'protocol', stage);
+      error.cliDetails.pageNo = body.page_no;
+      error.issues = [{ source: 'output', path, reason,
+        expected: constraints(modelAt(schema, 'output', path)) }];
+      return error;
+    }
+    const items = raw.items.map((item, index) => {
+      if (!object(item)) throw invalidItem(index, '', 'search-item', 'invalid_type');
+      if (!Number.isSafeInteger(item.item_id) || item.item_id <= 0) {
+        throw invalidItem(index, 'item_id', 'search-item', 'invalid_type');
+      }
+      for (const [field, expected] of [['kdt_id', input.scope.kdtId], ['channel', input.scope.channel]]) {
+        if (item[field] != null && item[field] !== expected) throw invalidItem(index, field, 'search-item');
+      }
+      if (body.item_ids && !body.item_ids.includes(item.item_id)) throw invalidItem(index, 'item_id', 'search-item');
+      if (mode === 'scan' && item.created_time != null &&
+          (item.created_time < body.item_range_query.min_create_time || item.created_time > body.item_range_query.max_create_time)) {
+        throw invalidItem(index, 'created_time', 'search-time-range');
+      }
+      const value = withoutInventory(item);
+      // Normalize declared fields separately so failures identify a static field, never its raw value.
+      for (const [field, model] of Object.entries(schema.definitions.item.properties)) {
+        if (!Object.hasOwn(value, field) || field === 'h5_url') continue;
+        try { value[field] = normalizeTimes(normalizeMoney(value[field], model), model, schema.definitions); }
+        catch { throw invalidItem(index, field, 'search-item-model', 'invalid_format'); }
+      }
+      // H5 is always generated from the verified role, never copied from an extension.
+      delete value.h5_url;
+      try { validateCommandValue(schema, 'output', output([{ ...value, h5_url: null }], null)); }
+      catch (cause) {
+        const error = failure(input, mode, 'protocol', 'search-item-model');
+        error.cliDetails.pageNo = body.page_no;
+        error.issues = (cause.issues || []).map(issue => ({ ...issue,
+          path: issue.path.replace(/^\/data\/items\/0(?=\/|$)/, `/data/items/${index}`) }));
+        if (cause.issuesTruncated) error.issuesTruncated = true;
+        throw error;
+      }
+      return value;
+    });
+    return { items, total: paginator.total_count ?? null };
+  }
+  function output(items, pagination) {
+    if (mode === 'scan') return { data: { items, scope: input.scope } };
+    return { data: { items, pagination: pagination || {
+        pageNo: input.body.page_no, pageSize: input.body.page_size,
+        returned: items.length, hasMore: null, nextPageNo: null, windowLimitReached: false
+      }, scope: input.scope } };
+  }
+  function append(items) {
+    let added = 0;
+    for (const item of items) {
+      if (seen.has(item.item_id)) continue;
+      seen.add(item.item_id);
+      if (resultItems.length >= input.limits.maxItems) throw failure(input, mode, 'budget_exceeded', 'result-items');
+      itemBytes += Buffer.byteLength(JSON.stringify(item)) + 1;
+      if (itemBytes > input.limits.maxOutputBytes) throw failure(input, mode, 'budget_exceeded', 'output-bytes');
+      resultItems.push(item); added++;
+    }
+    return added;
+  }
+  let hasMore, total = null;
+  if (mode === 'list') {
+    const data = await page(input.body);
+    // A list is one page. Preserve rows rather than hiding duplicates in its page.
+    resultItems.push(...data.items);
+    total = data.total;
+    hasMore = data.total === null ? null : data.total > input.body.page_no * input.body.page_size;
+  } else {
+    const initial = input.body.item_range_query;
+    const pending = [{ start: initial.min_create_time, end: initial.max_create_time }];
+    while (pending.length) {
+      const range = pending.pop();
+      const base = { ...input.body, item_range_query: { ...initial, min_create_time: range.start, max_create_time: range.end } };
+      const first = await page(base);
+      if (first.total != null && first.total > input.limits.maxItems) throw failure(input, mode, 'budget_exceeded', 'estimated-items');
+      if (first.total != null && first.total >= 5000) {
+        if (range.start >= range.end) throw failure(input, mode, 'pagination_limit', 'indivisible-window');
+        const mid = range.start + Math.floor((range.end - range.start) / 2);
+        // Descending traversal; closed inclusive intervals do not overlap.
+        pending.push({ start: range.start, end: mid }, { start: mid + 1, end: range.end });
+        continue;
+      }
+      let current = first;
+      for (let pageNo = 1; ; pageNo++) {
+        const added = append(current.items);
+        if (current.items.length < 50) break;
+        if (added === 0) throw failure(input, mode, 'pagination_stalled', 'search-pages');
+        if (pageNo === 100) throw failure(input, mode, 'pagination_limit', 'search-pages');
+        current = await page({ ...base, page_no: pageNo + 1 });
+        if (current.total != null && current.total > 5000) throw failure(input, mode, 'pagination_limit', 'search-changed');
+      }
+    }
+  }
+  await attachH5Items(resultItems, input.scope, command);
+  const result = output(resultItems, mode === 'list' ? {
+    pageNo: input.body.page_no, pageSize: input.body.page_size,
+    returned: resultItems.length, hasMore, ...(total === null ? {} : { total }),
+    nextPageNo: hasMore === true && (input.body.page_no + 1) * input.body.page_size <= 5000
+      ? input.body.page_no + 1 : null,
+    windowLimitReached: hasMore !== false && (input.body.page_no + 1) * input.body.page_size > 5000
+  } : undefined);
+  if (Buffer.byteLength(JSON.stringify(result)) > input.limits.maxOutputBytes) throw failure(input, mode, 'budget_exceeded', 'output-bytes');
+  try { validateCommandValue(schema, 'output', result); }
+  catch { throw failure(input, mode, 'protocol', 'output-model'); }
+  return result;
+}
+module.exports = { execute, preview };