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

package/src/commands/native/stock/commands.index.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 3,
+  "domain": "stock",
+  "businessCommands": [
+    {
+      "path": "stock.log.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "all",
+      "module": "stock/log/list/command.js",
+      "fingerprint": "a03ba88d7a29f5b61a1451874f0c3ab8681c78fc56c0432f3fa317fe8025b8a9"
+    }
+  ]
+}

package/src/commands/native/stock/domain.json

@@ -0,0 +1,3 @@
+{
+  "description": "库存：库存变化记录"
+}

package/src/commands/native/stock/log/list/command.js

@@ -0,0 +1,207 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Option } = require('commander');
+const { DiagnosticCommand } = require('../../../../../cli/diagnostic-command');
+const { inputIssue, parseIntegerOption, withInputScope, constraints, modelAt } = require('../../../../../execution/error-details');
+const schema = require('./schema.json');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { apiDateTime, normalizeTimes } = require('../../../../../execution/datetime');
+const { parseDateTimeRange } = require('../../../../../execution/range');
+const { requestApi, ApiConfigurationError } = require('../../../../../transport/api');
+const { mappingRequest, channelIdentity, legacyLog } = require('../../../item/shared/identity');
+
+const commandPath = 'stock.log.list';
+const SHOP = 'youzan.shop.basic.get/3.0.0';
+const LOG = 'youzan.item.stock.log.query/1.0.0';
+const MAX_PAGE = 2147483647;
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nextStep = '核对当前店铺、商品和时间范围；失败时停止，不自动切店或重试。';
+
+function failure(category, stage, scope = {}, state = 'not_sent', facts = {}) {
+  const error = new Error(`库存日志查询失败：${category}（${stage}）`);
+  error.cliDetails = { category, stage, command: commandPath, targetScope: scope,
+    requestState: state, nextStep, ...facts };
+  return error;
+}
+function integer(raw, path) {
+  return parseIntegerOption(typeof raw === 'string' ? raw.trim() : raw, schema, path);
+}
+function buildInput(options) {
+  const scope = { kdtId: integer(options.kdtId, '/kdtId'), item_id: integer(options.itemId, '/item_id'), channel: Number(options.channel) };
+  return withInputScope(scope, () => {
+    if (!['0', '1'].includes(options.channel)) {
+      throw inputIssue('/channel', 'invalid_choice', constraints(modelAt(schema, 'input', '/channel')));
+    }
+    let createdAt;
+    try { createdAt = parseDateTimeRange(options.createdAt, { precision: 'seconds', requireBoth: true }); }
+    catch {
+      throw inputIssue('/createdAt', 'invalid_format', {
+        format: '北京时间 YYYY-MM-DD HH:mm:ss，START..END 必须两端，开始不得晚于结束，仅支持秒精度，非零毫秒不支持'
+      });
+    }
+    const input = { ...scope, createdAt,
+      pageNo: integer(options.pageNo, '/pageNo'), pageSize: integer(options.pageSize, '/pageSize') };
+    validateCommandValue(schema, 'input', input);
+    const body = { begin_date: apiDateTime(createdAt.start), end_date: apiDateTime(createdAt.end),
+      page_no: input.pageNo, page_size: input.pageSize };
+    return { scope, pageNo: input.pageNo, pageSize: input.pageSize, body };
+  });
+}
+
+function safeNumbers(value) {
+  if (typeof value === 'number' && (!Number.isFinite(value) ||
+      (Number.isInteger(value) && !Number.isSafeInteger(value)))) throw new Error('unsafe number');
+  if (Array.isArray(value)) value.forEach(safeNumbers);
+  else if (object(value)) Object.values(value).forEach(safeNumbers);
+}
+async function read(path, body, stage, scope, responseLimit) {
+  let response;
+  try {
+    response = await requestApi({ path, body }, undefined,
+      responseLimit ? { maxResponseBytes: () => responseLimit } : {});
+  }
+  catch (error) {
+    throw failure(error instanceof ApiConfigurationError ? 'configuration' : 'transport', stage, scope,
+      error instanceof ApiConfigurationError ? 'not_sent' : 'unknown', { api: path });
+  }
+  const facts = { api: path, httpStatus: response.httpStatus };
+  let result;
+  try { result = JSON.parse(response.body); if (!object(result)) result = null; }
+  catch { result = null; }
+  if (Number.isSafeInteger(result?.code) ||
+      (typeof result?.code === 'string' && /^-?\d{1,12}$/.test(result.code))) facts.businessCode = result.code;
+  for (const key of ['trace_id', 'request_id']) {
+    const value = result?.[key] ?? result?.gw_err_resp?.[key];
+    if (typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value)) facts[key] = value;
+  }
+  if (object(result?.gw_err_resp) && /^\d{1,12}$/.test(String(result.gw_err_resp.err_code))) {
+    facts.gatewayCode = result.gw_err_resp.err_code;
+  }
+  if (!response.ok) {
+    throw failure(response.httpStatus === 401 ? 'authentication' : response.httpStatus === 403 ? 'permission' : 'http',
+      stage, scope, 'sent', facts);
+  }
+  if (!result) throw failure('protocol', stage, scope, 'sent', facts);
+  if (result.success === false || !(result.success === true || [0, 200].includes(result.code))) {
+    throw failure('business_rejected', stage, scope, 'sent', facts);
+  }
+  try { safeNumbers(result); }
+  catch { throw failure('protocol', stage, scope, 'sent', facts); }
+  if (!Object.hasOwn(result, 'data')) throw failure('protocol', stage, scope, 'sent', facts);
+  if (Buffer.byteLength(JSON.stringify(result.data) ?? '') > MAX_RESPONSE_BYTES) {
+    throw failure('budget_exceeded', stage, scope, 'sent', facts);
+  }
+  return result.data;
+}
+async function execute({ scope, pageNo, pageSize, body }, format) {
+  const shop = await read(SHOP, {}, 'shop-preflight', scope);
+  if (!object(shop) || !Number.isSafeInteger(shop.sid) || shop.sid < 1) {
+    throw failure('protocol', 'shop-preflight', scope, 'sent', { api: SHOP });
+  }
+  if (shop.sid !== scope.kdtId) {
+    throw failure('scope_unresolved', 'shop-preflight', scope, 'sent', {
+      api: SHOP, nextStep: '凭据所属店铺与 --kdt-id 不一致；先取得该店铺的有效授权，再查询。'
+    });
+  }
+  const mapping = mappingRequest(scope);
+  const product = await read(mapping.path, mapping.body, 'product-identity', scope);
+  let identity;
+  try { identity = channelIdentity(product, scope, { skuMapping: true }); }
+  catch { throw failure('scope_unresolved', 'product-identity', scope, 'sent', { api: mapping.path }); }
+  const raw = await read(LOG, { item_id: identity.channel_item_id, ...body }, 'logs', scope,
+    MAX_RESPONSE_BYTES);
+  const invalid = () => failure('protocol', 'logs-model', scope, 'sent', { api: LOG });
+  if (!object(raw) || !Array.isArray(raw.items) || raw.items.length > pageSize ||
+      (raw.paginator !== undefined && !object(raw.paginator))) throw invalid();
+  const paginator = raw.paginator || {};
+  if ((paginator.page !== undefined && paginator.page !== pageNo) ||
+      (paginator.page_size !== undefined && paginator.page_size !== pageSize) ||
+      (paginator.total_count != null &&
+        (!Number.isSafeInteger(paginator.total_count) || paginator.total_count < 0))) throw invalid();
+  let logs;
+  try { logs = raw.items.map(log => {
+    if (!object(log) || log.kdt_id !== scope.kdtId) throw invalid();
+    return legacyLog(log, identity);
+  }); } catch { throw invalid(); }
+  const total = paginator.total_count ?? null;
+  const hasMore = total === null ? null : total > pageNo * pageSize;
+  const exhausted = hasMore === false;
+  const nextPage = !exhausted && pageNo < MAX_PAGE ? pageNo + 1 : null;
+  const result = { data: { logs, pagination: {
+    pageNo, pageSize, returned: raw.items.length, ...(total === null ? {} : { total }), hasMore, nextPage,
+    continuation: exhausted ? 'none' : nextPage === null ? 'page_limit' : 'next_page',
+    paginationExhausted: exhausted, snapshot: false
+  } } };
+  try {
+    result.data.logs = normalizeTimes(logs, { type: 'array', items: { $ref: '#/definitions/log' } },
+      schema.definitions);
+    validateCommandValue(schema, 'output', result);
+  }
+  catch { throw invalid(); }
+  const text = `${JSON.stringify(result, null, format === 'pretty' ? 2 : 0)}\n`;
+  if (Buffer.byteLength(text) > MAX_OUTPUT_BYTES) {
+    throw failure('budget_exceeded', 'output-bytes', scope, 'sent', { api: LOG });
+  }
+  return text;
+}
+function createCommand({ context } = {}) {
+  return new DiagnosticCommand('list', { path: commandPath, schema, parameterCategory: 'parameter',
+    optionPaths: { '/item_id': 'itemId' } })
+    .description('查询指定商品在一段时间内的库存变化记录')
+    .allowExcessArguments(false)
+    .option('--kdt-id <id>', '目标店铺 ID，必须是当前上下文和凭据所属店铺；省略时使用当前上下文店铺')
+    .requiredOption('--item-id <id>', '必填：OneID 商品 ID；内部转换为目标店铺渠道商品 ID')
+    .option('--channel <channel>', '商品渠道：0 网店，1 门店；默认0', '0')
+    .requiredOption('--created-at <range>', '必填：日志时间 START..END，必须两端，北京时间 YYYY-MM-DD HH:mm:ss；开始不得晚于结束，仅支持秒精度')
+    .option('--page-no <n>', '页码，从1开始，最大2147483647', '1')
+    .option('--page-size <n>', '每页条数，默认20，CLI预算上限100（不是API上限）', '20')
+    .addOption(new Option('--format <format>', 'json 或 pretty（仅改变缩进）').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地预览核店、商品映射及条件日志请求，不读凭据、不联网')
+    .addHelpText('after', `
+--kdt-id 必须等于当前 context.shopId，包括总部上下文，不自动跨店或查询下级组织。
+先用同一凭据调用 youzan.shop.basic.get/3.0.0，sid 匹配才查询日志；失败或不匹配即停止。
+日志请求不另传店铺字段，执行前须核对当前调用店铺与目标一致。
+核店后读取商品渠道映射，再查询日志，最多3个只读请求，不自动重试或翻页。
+输入 item_id 是 OneID，旧日志商品和规格标识输出为 channel_item_id/channel_sku_id。
+日志 sku_id 仅在取得当前唯一规格映射或源明确统一字段时返回；历史规格无法映射时省略统一规格。
+映射失败停止，不用 OneID 充当旧商品 ID；真实产品和权限范围以服务端为准。
+at: all 只表示不按本地组织位置排除，不表示所有产品可用或任意跨店授权。
+返回 data.logs 和 data.pagination，保留接口顺序及重复日志，不推算当前库存或库存增减数。
+stock_change 是变更详情字符串，column_events 是字符串数组；不解析或改写。
+时间输入为北京时间 YYYY-MM-DD HH:mm:ss；可带全零毫秒，非零毫秒在请求前拒绝。
+区间必须包含 ..，省略边界不补值；可用相同两端表示同一秒，不承诺端点包含性。
+时间点输出为 YYYY-MM-DD HH:mm:ss.SSS；日期必须有效，开始时间不得晚于结束时间。
+缺少总数时 hasMore=null，不用空页或短页推定取完；page_limit 不代表查完，snapshot=false。
+每步解包data解析后最多10MiB，最终stdout最多5MiB，超额整体失败，不输出部分日志。
+执行需要有效的用户、组织与店铺上下文，可通过登录后选店或 ZAN_SAAS_CONTEXT 提供；目标范围和服务端授权按本命令契约校验，公共调用前置见 zan-saas skills read zan-saas-shared。
+缺少上下文仍可本地预览；提供无效或目标冲突上下文则拒绝。失败stdout为空，stderr为错误JSON。
+
+示例：
+  zan-saas stock log list --kdt-id 63077 --item-id 123 --created-at "2026-09-01 00:00:00..2026-09-02 23:59:59"
+  zan-saas stock log list --kdt-id 63077 --item-id 123 --created-at "2026-09-01 00:00:00..2026-09-02 23:59:59" --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options);
+      if (context && String(input.scope.kdtId) !== context.shopId) {
+        throw failure('permission', 'target', input.scope, 'not_sent', {
+          nextStep: '--kdt-id 必须等于当前 context.shopId；请先明确并配置要查询的店铺。'
+        });
+      }
+      if (options.dryRun) {
+        const plan = { steps: [
+          { method: 'POST', path: SHOP, body: {} },
+          mappingRequest(input.scope),
+          { method: 'POST', path: LOG, body: input.body, bodyFrom: { item_id: 'steps[1].data.channel_item_id' } }
+        ], condition: '核店及商品渠道映射匹配后才读取日志；日志 item_id 来自商品响应的 channel_item_id。' };
+        validateCommandValue(schema, 'preview', plan);
+        process.stdout.write(`${JSON.stringify(plan, 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);