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

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

@@ -0,0 +1,108 @@
+'use strict';
+
+const { apiSeconds, parseDateTime, formatDateTime } = require('../../../../../execution/datetime');
+const { object } = require('../../../../../execution/query-api');
+const { reject } = require('./query');
+
+const listPath = 'youzan.trade.refund.search/3.0.1';
+const filterOptions = [
+  ['orderNo', 'order-no', 'tid'], ['caseId', 'case-id', 'refund_id'],
+  ['yzOpenId', 'yz-open-id', 'yz_open_id'], ['buyerPhone', 'buyer-phone', 'buyer_phone'],
+  ['demand', 'demand', 'demand'], ['status', 'status', 'status'], ['type', 'type', 'type'],
+  ['phase', 'phase', 'phase'], ['handlingStatus', 'handling-status', 'search_tag'],
+  ['serviceStatus', 'service-status', 'cs_status'], ['itemTitle', 'item-title', 'goods_title'],
+  ['skuNo', 'sku-no', 'sku_no'], ['deliveryStatus', 'delivery-status', 'delivery_status'],
+  ['refundMode', 'refund-mode', 'refund_mode'], ['returnStockStatus', 'return-stock-status', 'return_stock_status'],
+  ['saleWay', 'sale-way', 'sale_way'], ['payType', 'pay-type', 'pay_type']
+];
+
+function toRequestBody(input, pageNo = 1) {
+  const body = { page_no: pageNo, page_size: Math.min(20, input.limits.maxItems) };
+  for (const [name, , upstream] of filterOptions) {
+    if (Object.hasOwn(input.filters, name)) body[upstream] = input.filters[name];
+  }
+  for (const [name, upstream] of [['created', 'create'], ['updated', 'update']]) {
+    if (!input.range[name]) continue;
+    body[`${upstream}_time_start`] = apiSeconds(input.range[name].start);
+    body[`${upstream}_time_end`] = apiSeconds(input.range[name].end);
+  }
+  return body;
+}
+
+function toPreviewBody(input) {
+  const body = toRequestBody(input);
+  for (const field of ['yz_open_id', 'buyer_phone', 'goods_title']) {
+    if (Object.hasOwn(body, field)) body[field] = '***';
+  }
+  return body;
+}
+
+function text(value) {
+  if (typeof value !== 'string' || !value || value.trim() !== value || /[\s\p{Cc}]/u.test(value)) {
+    throw new Error('invalid identifier');
+  }
+  return value;
+}
+
+function positiveId(value) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error('invalid shop');
+  return value;
+}
+
+function amount(value) {
+  if (typeof value !== 'string' || !/^(0|[1-9]\d*)(\.\d+)?$/.test(value)) {
+    throw new Error('invalid amount');
+  }
+  const [yuan, fraction = ''] = value.split('.');
+  if (/[1-9]/.test(fraction.slice(2))) throw new Error('inexact amount');
+  const cents = BigInt(yuan) * 100n + BigInt(fraction.slice(0, 2).padEnd(2, '0'));
+  if (cents > 9223372036854775807n) throw new Error('amount overflow');
+  return `${cents / 100n}.${String(cents % 100n).padStart(2, '0')}`;
+}
+
+function projectCase(source, scope, facts) {
+  if (!object(source)) throw new Error('invalid row');
+  const row = {
+    caseId: text(source.refund_id), orderNo: text(source.tid),
+    kdtId: positiveId(source.kdt_id), status: text(source.status), amount: amount(source.refund_fee)
+  };
+  if (row.kdtId !== scope.kdtId) throw reject('scope_unresolved', 'cases', scope, 'sent', facts);
+  if (Object.hasOwn(source, 'node_kdt_id')) row.nodeKdtId = positiveId(source.node_kdt_id);
+  if (Object.hasOwn(source, 'return_goods')) {
+    if (typeof source.return_goods !== 'boolean') throw new Error('invalid return flag');
+    row.hasReturnGoods = source.return_goods;
+  }
+  for (const [key, upstream] of [['createdAt', 'created'], ['updatedAt', 'modified']]) {
+    if (Object.hasOwn(source, upstream)) row[key] = formatDateTime(parseDateTime(source[upstream]));
+  }
+  for (const [key, upstream] of [['serviceStatus', 'cs_status'], ['deliveryStatus', 'delivery_status']]) {
+    if (!Object.hasOwn(source, upstream)) continue;
+    if (!Number.isSafeInteger(source[upstream])) throw new Error('invalid status');
+    row[key] = source[upstream];
+  }
+  return row;
+}
+
+function adaptPage(data, input, pageNo, facts = {}) {
+  try {
+    const pageSize = Math.min(20, input.limits.maxItems);
+    if (!object(data) || !Array.isArray(data.refunds) || data.refunds.length > pageSize) {
+      throw new Error('invalid page');
+    }
+    const total = Object.hasOwn(data, 'total') ? data.total : null;
+    if (Object.hasOwn(data, 'total') && (!Number.isSafeInteger(total) || total < 0)) {
+      throw new Error('invalid total');
+    }
+    const offset = (pageNo - 1) * pageSize;
+    if (total !== null && ((data.refunds.length > 0 && offset + data.refunds.length > total) ||
+        (offset < total && data.refunds.length === 0))) throw new Error('contradictory page');
+    const cases = data.refunds.map(source => projectCase(source, input.scope, facts));
+    if (new Set(cases.map(row => row.caseId)).size !== cases.length) throw new Error('page duplicates');
+    return { cases, total };
+  } catch (error) {
+    if (error.cliDetails) throw error;
+    throw reject('protocol', 'output-model', input.scope, 'sent', facts);
+  }
+}
+
+module.exports = { listPath, filterOptions, toRequestBody, toPreviewBody, adaptPage, amount };

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

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 3,
+  "domain": "aftersale",
+  "businessCommands": [
+    {
+      "path": "aftersale.case.get",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "aftersale/case/get/command.js",
+      "fingerprint": "c9e21d47c9da5eea5590a057dfe410ea08279eaaf75280ab4dc9916913ab8308"
+    },
+    {
+      "path": "aftersale.case.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "aftersale/case/list/command.js",
+      "fingerprint": "978c490a65bad5c348f700aa5b900604876ba3a7833207f677c35cf9b486d375"
+    },
+    {
+      "path": "aftersale.case.scan",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "aftersale/case/scan/command.js",
+      "fingerprint": "7b5fae46b975e3dc77d67751da87f3be22cac491770c0d9f3cd97126e78ec215"
+    },
+    {
+      "path": "aftersale.refund.list",
+      "kind": "atomic",
+      "risk": "read",
+      "availability": "available",
+      "at": "shop",
+      "module": "aftersale/refund/list/command.js",
+      "fingerprint": "f010665436b41eacd7d4d54c98b0a8d811a5e2a96ec722663af4bc16588a6e4e"
+    }
+  ]
+}

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

@@ -0,0 +1,3 @@
+{
+  "description": "售后：售后单查询、预算内扫描与退款资金记录"
+}

package/src/commands/native/aftersale/refund/list/command.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { bindingPath, targetScope, createQuery, reject, serialize } = require('./query');
+const { caseSummary, refunds, identifier } = require('./projection');
+const schema = require('./schema.json');
+
+const command = 'aftersale.refund.list';
+
+function buildInput(options, context) {
+  const target = targetScope(options, context, command);
+  let caseId;
+  try { caseId = identifier(options.caseId); }
+  catch { throw reject(command, 'validation', 'input', target); }
+  const input = { scope: Object.freeze({ ...target, caseId }) };
+  validateCommandValue(schema, 'input', input);
+  return input;
+}
+
+function preview(input) {
+  const result = { requests: [
+    { method: 'POST', path: bindingPath, body: {} },
+    { method: 'POST', path: schema.api.path, body: { refund_id: input.scope.caseId } }
+  ] };
+  validateCommandValue(schema, 'preview', result);
+  return result;
+}
+
+function adapt(data, scope, facts) {
+  let parent;
+  try { parent = caseSummary(data); }
+  catch { throw reject(command, 'protocol', 'case', scope, 'sent', facts); }
+  if (parent.caseId !== scope.caseId || parent.kdtId !== scope.kdtId) {
+    throw reject(command, 'scope_unresolved', 'case', scope, 'sent', facts);
+  }
+  let funds;
+  try { funds = refunds(data.refund_fund_list); }
+  catch { throw reject(command, 'protocol', 'refunds', scope, 'sent', facts); }
+  const output = { data: { case: parent, refunds: funds } };
+  try { validateCommandValue(schema, 'output', output); }
+  catch { throw reject(command, 'protocol', 'output-model', scope, 'sent', facts); }
+  return output;
+}
+
+function single(value, previous) {
+  if (previous !== undefined) throw reject(command, 'validation', 'input');
+  return value;
+}
+
+function createCommand({ context } = {}) {
+  const seen = new Set();
+  function once(name) {
+    if (seen.has(name)) throw reject(command, 'validation', 'input');
+    seen.add(name);
+  }
+  return new Command('list')
+    .description('查询已知售后单本次返回的逐笔退款资金记录，不办理退款或承诺到账')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject(command, 'validation', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺正安全整数；省略时使用当前上下文店铺', single)
+    .requiredOption('--case-id <id>', '必填：父售后号，1..128 字符，无空白或控制字符', single)
+    .addOption(new Option('--format <format>', 'json 或 pretty，仅改变缩进').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '纯本地预览，不读凭证、不联网')
+    .on('option:format', () => once('format'))
+    .on('option:dry-run', () => once('dry-run'))
+    .addHelpText('after', `
+执行需要有效店铺四字段上下文，显式店铺须等于 context.shopId；总部拒绝。
+先核验凭证绑定店铺，再读父售后，最多两请求；预览不证明权限或对象存在。
+只返回 data.case 与 data.refunds，无分页，不保证全生命周期全集。
+缺失或 null 资金数组失败，明确空数组才输出 []；坏行或重复流水号整体失败。
+售后号、资金流水号和资金元素退款 ID 不互换；售后成功不能证明资金到账。
+资金金额默认 CNY，分整数精确转两位元字符串；不求和、不四舍五入。
+资金状态 0 退款中、1 失败、2 成功，未知安全整数保留；模式 3 仅保留原码。
+累计响应上限 10MiB，最终 UTF-8 JSON 含换行上限 5MiB，超限取消、不裁切。
+不重试、重定向、换店、换身份或发起退款；失败 stdout 空、stderr 一份安全 JSON。
+执行前请登录并选择店铺，或由受控环境提供上下文和凭证。
+示例：zan-saas aftersale refund list --kdt-id 63077 --case-id example-case --dry-run
+`)
+    .action(async options => {
+      const input = buildInput(options, context);
+      if (options.dryRun) {
+        console.log(JSON.stringify(preview(input), null, options.format === 'pretty' ? 2 : 0));
+        return;
+      }
+      const read = await createQuery(input.scope, command);
+      const { data, facts } = await read(schema.api.path, { refund_id: input.scope.caseId }, 'case');
+      console.log(serialize(adapt(data, input.scope, facts), options.format, command, input.scope));
+    });
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'shop', createCommand: withTargetShopDefault(createCommand), buildInput, preview, adapt };

package/src/commands/native/aftersale/refund/list/money.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { parseExactJson } = require('../../../../../execution/exact-json');
+const maxCents = 9223372036854775807n;
+
+function decodeEnvelope(rawBody) {
+  return parseExactJson(rawBody, literal => {
+    if (/^-?\d{16,19}$/.test(literal) && !Number.isSafeInteger(Number(literal))) return BigInt(literal);
+    return parseExactJson(literal);
+  });
+}
+
+function centsToYuan(value) {
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value) || Object.is(value, -0)) throw new Error('invalid cents');
+    value = BigInt(value);
+  } else if (typeof value === 'string') {
+    if (!/^(?:0|[1-9]\d{0,18})$/.test(value)) throw new Error('invalid cents');
+    value = BigInt(value);
+  }
+  if (typeof value !== 'bigint' || value < 0n || value > maxCents) throw new Error('invalid cents');
+  return `${value / 100n}.${String(value % 100n).padStart(2, '0')}`;
+}
+
+module.exports = { centsToYuan, decodeEnvelope };

package/src/commands/native/aftersale/refund/list/projection.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { object } = require('../../../../../execution/query-api');
+const { centsToYuan } = require('./money');
+
+function text(value, nonempty = false) {
+  if (typeof value !== 'string' || (nonempty && !value.trim())) throw new Error('invalid text');
+  return value;
+}
+
+function identifier(value) {
+  if (typeof value !== 'string' || !/^[^\s\u0000-\u001f\u007f-\u009f]{1,128}$/u.test(value)) {
+    throw new Error('invalid identifier');
+  }
+  return value;
+}
+
+function integer(value) {
+  if (!Number.isSafeInteger(value)) throw new Error('invalid integer');
+  return value;
+}
+
+function caseSummary(source) {
+  if (!object(source)) throw new Error('missing case');
+  const kdtId = integer(source.kdt_id);
+  if (kdtId < 1) throw new Error('invalid shop');
+  return { caseId: identifier(source.refund_id), orderNo: text(source.tid, true), kdtId,
+    demand: integer(source.demand), status: text(source.status, true) };
+}
+
+function refunds(source) {
+  if (!Array.isArray(source)) throw new Error('missing funds');
+  const seen = new Set();
+  return source.map(entry => {
+    if (!object(entry)) throw new Error('invalid fund');
+    const refundNo = identifier(entry.refund_no);
+    if (seen.has(refundNo)) throw new Error('duplicate fund');
+    seen.add(refundNo);
+    const result = { refundNo, amount: centsToYuan(entry.refund_fee), status: integer(entry.status) };
+    for (const [target, field, convert] of [
+      ['refundId', 'refund_id', value => text(value, true)], ['mode', 'refund_mode', integer],
+      ['message', 'message', text], ['payWayText', 'pay_way_desc', text], ['payWayLabel', 'pay_way_str', text]
+    ]) {
+      if (Object.hasOwn(entry, field)) result[target] = convert(entry[field]);
+    }
+    return result;
+  });
+}
+
+module.exports = { caseSummary, refunds, identifier };

package/src/commands/native/aftersale/refund/list/query.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readContext } = require('../../../../../identity/context');
+const { readApiEnvelope, assertApiSuccess, object } = require('../../../../../execution/query-api');
+const { failure, bindingPath } = require('../../../../../execution/shop-query');
+const { snapshotApiEnvironment } = require('../../../../../transport/api');
+const { decodeEnvelope } = require('./money');
+
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+
+function reject(command, category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, requestState, facts);
+  error.cliDetails.nextStep = stage === 'shop-binding' ?
+    '父售后请求尚未发送。核对原凭证绑定店铺与显式目标，不自动重试、切店或换身份。' :
+    category === 'limit' ? '结果超出字节限制，未输出部分资金；停止并核对原范围，不截断或自动重试。' :
+      '核对原店铺、售后单号、上下文与服务端授权；不自动重试、切店、换身份或发起退款。';
+  return error;
+}
+
+function targetScope(options, context, command) {
+  let scope;
+  try { scope = resolveTargetShop(options, context, command); }
+  catch (error) {
+    const details = error.cliDetails;
+    if (!details) throw error;
+    throw reject(command, details.category, ['validation', 'scope'].includes(details.stage) ? 'input' : details.stage,
+      details.targetScope);
+  }
+  const state = readContext(context);
+  if (state.status === 'ready' && state.context.orgType !== 'shop') {
+    throw reject(command, 'permission', 'context', scope);
+  }
+  return scope;
+}
+
+async function createQuery(scope, command, { responseLimit = RESPONSE_LIMIT } = {}) {
+  let env;
+  try { env = await snapshotApiEnvironment(undefined, scope.kdtId); }
+  catch { throw reject(command, 'configuration', 'configuration', scope); }
+  let responseBytes = 0;
+  async function read(path, body, stage) {
+    const { result, rawBody, facts } = await readApiEnvelope(path, body,
+      (category, details, state, at) => reject(command, category,
+        ['configuration', 'transport', 'response'].includes(at) ? at : stage, scope, state, details), env,
+      response => { responseBytes += response.responseBytes; },
+      { maxResponseBytes: () => responseLimit - responseBytes });
+    assertApiSuccess(result, category => {
+      const code = String(facts.businessCode);
+      const mapped = category === 'business_rejected' && stage === 'case' && !Object.hasOwn(result, 'gw_err_resp') ?
+        code === '103010054' ? 'permission' : stage === 'case' && code === '103011024' ? 'not_found' : category : category;
+      throw reject(command, mapped, stage, scope, 'sent', facts);
+    }, [200, '200']);
+    return { data: decodeEnvelope(rawBody).data, facts };
+  }
+  const binding = await read(bindingPath, {}, 'shop-binding');
+  if (!object(binding.data) || !Number.isSafeInteger(binding.data.sid) || binding.data.sid < 1) {
+    throw reject(command, 'protocol', 'shop-binding', scope, 'sent', binding.facts);
+  }
+  if (binding.data.sid !== scope.kdtId) throw reject(command, 'scope_unresolved', 'shop-binding', scope, 'sent', binding.facts);
+  return read;
+}
+
+function serialize(output, format, command, scope, outputLimit = OUTPUT_LIMIT) {
+  const json = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`, 'utf8') > outputLimit) {
+    throw reject(command, 'limit', 'output-model', scope, 'sent');
+  }
+  return json;
+}
+
+module.exports = { bindingPath, targetScope, createQuery, reject, serialize, RESPONSE_LIMIT, OUTPUT_LIMIT };

package/src/commands/native/aftersale/refund/list/schema.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "api": { "method": "POST", "path": "youzan.trade.refund.get/3.0.1" },
+  "input": {
+    "type": "object", "required": ["scope"], "additionalProperties": false,
+    "description": "解析后的业务输入；format 与 dry-run 是展示和执行选项，不进入业务 input。",
+    "properties": {
+      "scope": {
+        "type": "object", "required": ["kdtId", "caseId"], "additionalProperties": false,
+        "properties": { "kdtId": { "$ref": "#/definitions/shopId" }, "caseId": { "$ref": "#/definitions/identifier" } }
+      }
+    }
+  },
+  "output": {
+    "type": "object", "required": ["data"], "additionalProperties": false,
+    "properties": {
+      "data": {
+        "type": "object", "required": ["case", "refunds"], "additionalProperties": false,
+        "properties": {
+          "case": {
+            "type": "object", "required": ["caseId", "orderNo", "kdtId", "demand", "status"], "additionalProperties": false,
+            "description": "核验同店且与输入父售后号一致的售后摘要，不代表资金到账。",
+            "properties": {
+              "caseId": { "$ref": "#/definitions/identifier", "description": "父售后号，不是资金流水号或资金元素退款 ID。" },
+              "orderNo": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "父售后关联的交易订单号。" },
+              "kdtId": { "$ref": "#/definitions/shopId" },
+              "demand": {
+                "$ref": "#/definitions/safeInteger",
+                "description": "售后诉求：1 仅退款；2 退货退款；3 换货。未来未知安全整数保留，不推断流程。"
+              },
+              "status": {
+                "type": "string", "minLength": 1, "pattern": "\\S",
+                "description": "售后状态：WAIT_SELLER_AGREE 买家已申请、等待卖家同意；WAIT_BUYER_RETURN_GOODS 卖家已同意、等待买家退货；WAIT_SELLER_CONFIRM_GOODS 买家已退货、等待卖家确认收货；SELLER_REFUSE_BUYER 卖家拒绝退款；SELLER_REFUSE_BUYER_RETURN_GOODS 卖家未收到货、拒绝退款；SELLER_RETURN_GOODS 商家确认收货并发送换货；CLOSED 售后退款关闭；SUCCESS 售后退款成功，不代表资金到账。未来非空字符串原样保留。"
+              }
+            }
+          },
+          "refunds": {
+            "type": "array", "items": { "$ref": "#/definitions/refund" },
+            "description": "本次父售后返回的资金条目，可明确为空；缺失、null、坏行或重复资金流水号均失败。无分页，不保证全部生命周期或账户交易全集。"
+          }
+        }
+      }
+    }
+  },
+  "preview": {
+    "type": "object", "required": ["requests"], "additionalProperties": false,
+    "properties": {
+      "requests": {
+        "type": "array", "minItems": 2, "maxItems": 2, "additionalItems": false,
+        "items": [
+          {
+            "type": "object", "required": ["method", "path", "body"], "additionalProperties": false,
+            "properties": {
+              "method": { "const": "POST" }, "path": { "const": "youzan.shop.basic.get/3.0.0" },
+              "body": { "type": "object", "additionalProperties": false, "maxProperties": 0 }
+            }
+          },
+          {
+            "type": "object", "required": ["method", "path", "body"], "additionalProperties": false,
+            "properties": {
+              "method": { "const": "POST" }, "path": { "const": "youzan.trade.refund.get/3.0.1" },
+              "body": {
+                "type": "object", "required": ["refund_id"], "additionalProperties": false,
+                "properties": { "refund_id": { "$ref": "#/definitions/identifier" } }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "error": {
+    "type": "object", "required": ["success", "code", "message"], "additionalProperties": false,
+    "properties": {
+      "success": { "const": false }, "code": { "const": -10001 },
+      "message": { "type": "string", "minLength": 1 },
+      "details": {
+        "type": "object", "required": ["category", "stage", "command", "targetScope", "requestState", "nextStep"],
+        "additionalProperties": false,
+        "properties": {
+          "category": { "enum": ["validation", "configuration", "authentication", "permission", "scope_unresolved", "http", "business_rejected", "not_found", "protocol", "transport", "limit"] },
+          "stage": { "enum": ["input", "context", "configuration", "shop-binding", "case", "refunds", "output-model", "transport", "response"] },
+          "command": { "const": "aftersale.refund.list" },
+          "targetScope": {
+            "type": "object", "additionalProperties": false,
+            "properties": { "kdtId": { "$ref": "#/definitions/shopId" }, "caseId": { "$ref": "#/definitions/identifier" } }
+          },
+          "requestState": { "enum": ["not_sent", "sent", "unknown"], "description": "not_sent 当前阶段请求未发送；sent 已发送并取得响应；unknown 无法确定请求结果。不自动重放。" },
+          "nextStep": { "type": "string", "minLength": 1 },
+          "api": { "type": "string", "minLength": 1 },
+          "httpStatus": { "type": "integer", "minimum": 100, "maximum": 599 },
+          "businessCode": { "$ref": "#/definitions/diagnosticCode" },
+          "gatewayCode": { "$ref": "#/definitions/diagnosticCode" },
+          "trace_id": { "$ref": "#/definitions/diagnosticId" },
+          "request_id": { "$ref": "#/definitions/diagnosticId" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "shopId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "显式目标店铺，须等于当前店铺上下文及凭证绑定店铺。" },
+    "identifier": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]+$", "description": "原始标识字符串，无空白或控制字符，保留前导零。" },
+    "safeInteger": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
+    "refund": {
+      "type": "object", "required": ["refundNo", "amount", "status"], "additionalProperties": false,
+      "properties": {
+        "refundNo": { "$ref": "#/definitions/identifier", "description": "本次数组内不重复的资金流水号。" },
+        "refundId": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "资金元素退款 ID，保持原始字符串，不推断与父售后号或资金流水号等价。缺失省略，null 或错型失败。" },
+        "amount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)\\.[0-9]{2}$", "description": "含邮费本条退款金额，默认 CNY，元，两位小数。精确范围 0.00..92233720368547758.07，不表示已到账，不跨条求和。" },
+        "status": { "$ref": "#/definitions/safeInteger", "description": "资金状态：0 退款中，三方失败结果可能延迟回写，长期为 0 也不能证明没有失败；1 退款失败；2 退款成功，不推断银行账户到账时间。未来未知安全整数保留。资金失败不等于查询失败。" },
+        "mode": { "$ref": "#/definitions/safeInteger", "description": "退款模式：0 原路退；1 现金退；2 标记退。3 语义未确定，只保留原码；未来未知安全整数同样保留，不推断动作。缺失省略，null 或错型失败。" },
+        "message": { "type": "string", "description": "资金处理说明，保留空串，不据此判断成功。缺失省略，null 或错型失败。" },
+        "payWayText": { "type": "string", "description": "资金支付渠道说明。缺失省略，空串保留，null 或错型失败。" },
+        "payWayLabel": { "type": "string", "description": "资金支付渠道描述标识。缺失省略，空串保留，null 或错型失败。" }
+      }
+    },
+    "diagnosticCode": { "anyOf": [{ "$ref": "#/definitions/safeInteger" }, { "type": "string", "pattern": "^-?\\d{1,12}$" }] },
+    "diagnosticId": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$" }
+  },
+  "success": { "rule": "同店父售后身份核验通过，且确实取得完整、有效的本次资金数组后一次返回。" },
+  "errors": { "recovery": "核对原店铺、父售后号与授权；不自动重试、切店、换身份或办理退款。缺资金数组不能解释为没有资金记录。" },
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "执行仅限有效店铺上下文，显式店铺与当前 shopId 一致；总部拒绝。无上下文只允许显式目标本地预览，已给出的无效上下文始终失败。",
+    "预览不读取凭证、不联网，不证明权限或对象存在。实际先核验店铺，再读取父售后，最多两请求，不读取其他售后补齐。",
+    "仅查询本次父售后返回集合，无分页或到账承诺。不返回未选择的商品、协商、资金合计或不透明扩展。",
+    "累计原始响应上限 10MiB，最终 UTF-8 JSON 含换行上限 5MiB；超限取消、整体失败，不截断或输出部分成功。",
+    "应用 token 路径不证明员工 OAuth 或权限隔离通过。"
+  ]
+}

package/src/commands/native/aftersale/shared/query.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../execution/target-shop');
+const { createShopQuery, bindingPath, failure } = require('../../../../execution/shop-query');
+
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+
+function reject(command, category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, requestState, facts);
+  error.cliDetails.nextStep = stage === 'shop-binding' ?
+    '列表请求未发送。核对原凭证绑定店铺与显式目标，不自动重试、切店或换身份。' :
+    '停止并核对原店铺、筛选范围及服务端授权，不自动重试、切店或换身份；超限时不输出部分结果。';
+  return error;
+}
+
+function adaptError(error, command, scope) {
+  if (!error.cliDetails) return error;
+  const details = error.cliDetails;
+  const stage = ['scope', 'validation'].includes(details.stage) ? 'input' :
+    details.category === 'transport' ? 'transport' : details.stage;
+  return reject(command, details.category === 'parameter' ? 'validation' : details.category,
+    stage, scope, details.requestState, Object.fromEntries(
+      ['api', 'httpStatus', 'businessCode', 'gatewayCode', 'trace_id', 'request_id']
+        .filter(key => Object.hasOwn(details, key)).map(key => [key, details[key]])));
+}
+
+function targetScope(options, context, command) {
+  if (!Object.hasOwn(options, 'kdtId')) throw reject(command, 'validation', 'input');
+  try { return resolveTargetShop(options, context, command); }
+  catch (error) {
+    throw adaptError(error, command, error.cliDetails?.targetScope || {});
+  }
+}
+
+async function createAftersaleQuery(scope, command, { responseLimit = RESPONSE_LIMIT } = {}) {
+  let responseBytes = 0;
+  try {
+    const read = await createShopQuery(scope, command, {
+      onResponse(response) { responseBytes += response.responseBytes; },
+      transportOptions: { maxResponseBytes: () => responseLimit - responseBytes }
+    });
+    return async (path, body, stage = 'cases') => {
+      try { return await read(path, body, stage, [200, '200']); }
+      catch (error) { throw adaptError(error, command, scope); }
+    };
+  } catch (error) { throw adaptError(error, command, scope); }
+}
+
+function serialize(output, format, command, scope, outputLimit = OUTPUT_LIMIT) {
+  const json = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`, 'utf8') > outputLimit) {
+    throw reject(command, 'limit', 'output-model', scope, 'sent');
+  }
+  return json;
+}
+
+module.exports = { bindingPath, reject, targetScope, createAftersaleQuery, serialize };