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

package/src/commands/native/aftersale/case/scan/command.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { contextInput } = require('../../../../../identity/context-store');
+const { parseDateTime, formatDateTime } = require('../../../../../execution/datetime');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { reject, targetScope, bindingPath, serialize } = require('./query');
+const { filterOptions, listPath, toPreviewBody } = require('./search');
+const { scan } = require('./scan');
+const schema = require('./schema.json');
+
+function buildInput(options, context) {
+  const scope = targetScope(options, context);
+  const fail = () => { throw reject('validation', 'input', scope); };
+  function integer(value) {
+    if (typeof value !== 'string' || !/^(0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value))) fail();
+    return Number(value);
+  }
+  function timeRange(startValue, endValue) {
+    try {
+      const start = parseDateTime(startValue);
+      const end = parseDateTime(endValue);
+      if (start % 1000 !== 0 || end % 1000 !== 0 || start >= end) fail();
+      return { start: formatDateTime(start), end: formatDateTime(end) };
+    } catch { return fail(); }
+  }
+  const range = { created: timeRange(options.startCreated, options.endCreated) };
+  if (options.startUpdated !== undefined || options.endUpdated !== undefined) {
+    range.updated = timeRange(options.startUpdated, options.endUpdated);
+  }
+  const filters = {};
+  for (const [name] of filterOptions) {
+    if (options[name] === undefined) continue;
+    const definition = schema.input.properties.filters.properties[name];
+    filters[name] = definition.type === 'integer' ? integer(options[name]) : options[name];
+  }
+  const input = { scope, filters, range, limits: {
+    maxItems: integer(options.maxItems), maxRequests: integer(options.maxRequests)
+  } };
+  try { validateCommandValue(schema, 'input', input); }
+  catch { fail(); }
+  return input;
+}
+
+function preview(input) {
+  const output = {
+    requests: [
+      { method: 'POST', path: bindingPath, body: {} },
+      { method: 'POST', path: listPath, body: toPreviewBody(input) }
+    ],
+    strategy: {
+      pageSize: Math.min(20, input.limits.maxItems), startPageNo: 1, maxPageNo: 100,
+      maxDepth: 3000, ...input.limits, autoSplit: false, autoRetry: false
+    }
+  };
+  try { validateCommandValue(schema, 'preview', output); }
+  catch { throw reject('protocol', 'output-model', input.scope); }
+  return output;
+}
+
+function createCommand({ context } = {}) {
+  const instance = new Command('scan')
+    .description('在显式创建时间与预算内串行观察售后摘要，不保证无遗漏')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (error.code === 'commander.helpDisplayed') throw error;
+      throw reject('validation', 'input');
+    });
+  const supplied = new Set();
+  function option(flags, description, required = false, defaultValue) {
+    const definition = new Option(flags, description).makeOptionMandatory(required);
+    if (defaultValue !== undefined) definition.default(defaultValue);
+    definition.argParser(value => {
+      if (supplied.has(flags)) throw reject('validation', 'input');
+      supplied.add(flags);
+      return value;
+    });
+    instance.addOption(definition);
+  }
+  option('--kdt-id <id>', '当前店铺正安全整数 ID；省略时使用当前上下文店铺');
+  option('--start-created <time>', '必填：创建开始，北京时间，秒精度', true);
+  option('--end-created <time>', '必填：创建结束，严格晚于开始', true);
+  option('--max-items <n>', '必填：唯一摘要预算 1..2000，不裁切整页', true);
+  option('--max-requests <n>', '必填：请求预算 2..101，含一次店铺核验', true);
+  for (const [name, flag] of filterOptions) {
+    option(`--${flag} <value>`, schema.input.properties.filters.properties[name].description);
+  }
+  option('--start-updated <time>', '更新开始，北京时间秒精度，须与结束成对');
+  option('--end-updated <time>', '更新结束，仍同时限定创建范围');
+  option('--format <format>', 'json 或 pretty，仅改变缩进', false, 'json');
+  instance.option('--dry-run', '纯本地预览，客户标识、电话及商品搜索文本遮盖，不读凭证、不联网')
+    .addHelpText('after', '\n仅限店铺上下文。固定页大小 min(20,maxItems)，不自动二分、重试或恢复。分页走完也不保证完整或快照一致。\n示例：zan-saas aftersale case scan --kdt-id 63077 --start-created "2026-10-01 00:00:00" --end-created "2026-10-02 00:00:00" --max-items 20 --max-requests 2 --dry-run')
+    .action(async options => {
+      if (!['json', 'pretty'].includes(options.format)) throw reject('validation', 'input');
+      const input = buildInput(options, context ?? contextInput());
+      let output;
+      if (options.dryRun) output = preview(input);
+      else {
+        output = await scan(input);
+        try { validateCommandValue(schema, 'output', output); }
+        catch { throw reject('protocol', 'output-model', input.scope, 'sent'); }
+      }
+      console.log(serialize(output, options.format, input.scope));
+    });
+  return instance;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'shop', createCommand: withTargetShopDefault(createCommand), buildInput, preview };

package/src/commands/native/aftersale/case/scan/query.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readContext } = require('../../../../../identity/context');
+const { createShopQuery, failure, bindingPath } = require('../../../../../execution/shop-query');
+
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+const command = 'aftersale.case.scan';
+
+function reject(category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, requestState, facts);
+  error.cliDetails.nextStep = '停止并核对原店铺、范围、售后标识和授权；不自动重试、换店或换身份。进度不是可靠恢复游标，未输出部分业务行。';
+  return error;
+}
+
+function adaptError(error, scope) {
+  if (!error.cliDetails) return reject('protocol', 'output-model', scope, 'sent');
+  const details = error.cliDetails;
+  const stage = ['scope', 'validation'].includes(details.stage) ? 'input' :
+    details.category === 'transport' ? 'transport' : details.stage;
+  const facts = {};
+  for (const field of ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']) {
+    if (Object.hasOwn(details, field)) facts[field] = details[field];
+  }
+  return reject(details.category, stage, scope, details.requestState, facts);
+}
+
+function targetScope(options, context) {
+  let scope;
+  try { scope = resolveTargetShop(options, context, command); }
+  catch (error) { throw adaptError(error, error.cliDetails?.targetScope || {}); }
+  const state = readContext(context);
+  if (state.status === 'ready' && state.context.orgType !== 'shop') {
+    throw reject('permission', 'context', scope);
+  }
+  return scope;
+}
+
+async function createQuery(scope, { onRequest, responseLimit = RESPONSE_LIMIT } = {}) {
+  let bytes = 0;
+  try {
+    const read = await createShopQuery(scope, command, {
+      onResponse(response) { bytes += response.responseBytes; },
+      transportOptions: { onRequest, maxResponseBytes: () => responseLimit - bytes }
+    });
+    return async (...args) => {
+      try { return await read(...args); }
+      catch (error) { throw adaptError(error, scope); }
+    };
+  } catch (error) { throw adaptError(error, scope); }
+}
+
+function serialize(output, format, scope, limit = OUTPUT_LIMIT) {
+  const json = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`, 'utf8') > limit) {
+    throw reject('limit', 'output-model', scope, 'sent');
+  }
+  return json;
+}
+
+module.exports = { reject, targetScope, createQuery, serialize, bindingPath, RESPONSE_LIMIT, OUTPUT_LIMIT };

package/src/commands/native/aftersale/case/scan/scan.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { createQuery, reject } = require('./query');
+const { listPath, toRequestBody, adaptPage } = require('./search');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const schema = require('./schema.json');
+
+const pageSchema = {
+  schemaVersion: schema.schemaVersion,
+  input: schema.input,
+  output: schema.output.properties.data.properties.cases,
+  definitions: schema.definitions
+};
+
+function nextStopReason(count, pagination, pageNo) {
+  if (pagination.maxItems - count < pagination.pageSize) return 'max_items';
+  if (pagination.requests >= pagination.maxRequests) return 'max_requests';
+  if (pageNo > 100 || pageNo * pagination.pageSize > 3000) return 'page_window';
+  return null;
+}
+
+async function scan(input, readerFactory = createQuery, hooks = {}) {
+  const cases = [];
+  const seen = new Set();
+  const { maxItems, maxRequests } = input.limits;
+  const pageSize = Math.min(20, maxItems);
+  const pagination = {
+    maxItems, maxRequests, requests: 0, pages: 0, duplicates: 0, pageSize,
+    total: null, paginationExhausted: false, stopReason: '', lastRead: null,
+    lastCommittedPageNo: null
+  };
+  const stop = reason => {
+    pagination.stopReason = reason;
+    pagination.paginationExhausted = reason === 'range_exhausted';
+    return { data: { cases, pagination } };
+  };
+  try {
+    const read = await readerFactory(input.scope, {
+      ...hooks, onRequest() { pagination.requests++; }
+    });
+    let firstTotal;
+    for (let pageNo = 1; ; pageNo++) {
+      const reason = nextStopReason(cases.length, pagination, pageNo);
+      if (reason) return stop(reason);
+      const { data, facts } = await read(listPath, toRequestBody(input, pageNo), 'cases', [200, '200']);
+      const page = adaptPage(data, input, pageNo, facts);
+      try { validateCommandValue(pageSchema, 'output', page.cases); }
+      catch { throw reject('protocol', 'output-model', input.scope, 'sent', facts); }
+      pagination.total = page.total;
+      pagination.lastRead = { pageNo, pageSize };
+      if (firstTotal !== undefined && page.total !== null && page.total !== firstTotal) {
+        return stop('collection_changed');
+      }
+      if (firstTotal === undefined && page.total !== null) firstTotal = page.total;
+      const added = page.cases.filter(row => !seen.has(`${row.kdtId}:${row.caseId}`));
+      if (cases.length + added.length > maxItems) return stop('max_items');
+      for (const row of added) {
+        seen.add(`${row.kdtId}:${row.caseId}`);
+        cases.push(row);
+      }
+      pagination.pages++;
+      pagination.duplicates += page.cases.length - added.length;
+      pagination.lastCommittedPageNo = pageNo;
+      if (page.total === null) return stop('total_unknown');
+      if (page.cases.length > 0 && added.length === 0) return stop('no_progress');
+      if (pageNo * pageSize >= page.total) return stop('range_exhausted');
+    }
+  } catch (error) {
+    const failure = error.cliDetails ? error : reject('protocol', 'output-model', input.scope, 'sent');
+    failure.cliDetails.progress = {
+      requests: pagination.requests, pages: pagination.pages,
+      lastCommittedPageNo: pagination.lastCommittedPageNo
+    };
+    throw failure;
+  }
+}
+
+module.exports = { scan, nextStopReason };