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

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

@@ -0,0 +1,104 @@
+'use strict';
+
+const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
+
+const { Command, Option } = require('commander');
+const { contextInput } = require('../../../../../identity/context-store');
+const { validateCommandValue } = require('../../../../../execution/command-schema');
+const { parseIncludeModules } = require('../../../../../execution/command-io');
+const { bindingPath, reject, targetScope, createQuery, serialize } = require('./query');
+const projection = require('./projection');
+const schema = require('./schema.json');
+
+const command = 'aftersale.case.get';
+
+function buildInput(options, context) {
+  const target = targetScope(options, context, command);
+  let caseId;
+  try { caseId = projection.identifier(options.caseId); }
+  catch { throw reject(command, 'validation', 'input', target); }
+  const scope = Object.freeze({ ...target, caseId });
+  try {
+    const input = { scope, include: [...parseIncludeModules(options.include, ['consultation'])] };
+    validateCommandValue(schema, 'input', input);
+    return input;
+  } catch { throw reject(command, 'validation', 'input', scope); }
+}
+
+function preview(input) {
+  const body = { refund_id: input.scope.caseId };
+  if (input.include.includes('consultation')) body.query_option = JSON.stringify({ include_all_consult_message: true });
+  const result = { requests: [{ method: 'POST', path: bindingPath, body: {} },
+    { method: 'POST', path: schema.api.path, body }] };
+  validateCommandValue(schema, 'preview', result);
+  return result;
+}
+
+function adapt(source, input, facts) {
+  const { scope } = input;
+  try {
+    const record = projection.caseRecord(source);
+    if (record.caseId !== scope.caseId || record.kdtId !== scope.kdtId) {
+      throw reject(command, 'scope_unresolved', 'case', scope, 'sent', facts);
+    }
+    const data = { case: record, items: projection.items(source.refund_order_item, scope) };
+    const logistics = projection.logistics(source);
+    if (logistics) data.logistics = logistics;
+    if (Object.hasOwn(source, 'refund_fund_list')) data.refunds = projection.refunds(source.refund_fund_list);
+    if (input.include.includes('consultation')) data.consultation = projection.consultation(source.consult_message, record);
+    const output = { data };
+    validateCommandValue(schema, 'output', output);
+    return output;
+  } catch (error) {
+    if (error.cliDetails) throw error;
+    throw reject(command, 'protocol', 'output-model', scope, 'sent', facts);
+  }
+}
+
+function createCommand({ context } = {}) {
+  const parser = new Command('get')
+    .description('按目标店铺和售后单号读取售后详情、商品行及已有运输和资金引用')
+    .allowExcessArguments(false)
+    .exitOverride(error => {
+      if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) throw error;
+      throw reject(command, 'validation', 'input');
+    })
+    .option('--kdt-id <id>', '目标店铺规范十进制正安全整数；省略时使用当前上下文店铺')
+    .requiredOption('--case-id <id>', '必填：售后单号，1..128 字符，无空白和控制符，保留前导零')
+    .option('--include <modules>', '追加 consultation 请求完整协商；逗号分隔去重')
+    .addOption(new Option('--format <format>', '仅 JSON 缩进不同').choices(['json', 'pretty']).default('json'))
+    .option('--dry-run', '仅本地校验和两步请求计划，不读凭证、不联网')
+    .addHelpText('after', `
+默认返回售后、订单商品行及响应已有的运输和资金引用；只有请求 consultation 才校验并输出协商。
+只允许同店 shop 位置，执行需要有效四字段上下文。先核验凭证绑定店铺，再核对售后号和返回店铺。
+售后状态不是资金状态；缺资金数组不能证明没有退款，运单引用不证明签收或商家确认收货。
+默认 CNY，金额为元字符串、固定两位；时间为北京时间 YYYY-MM-DD HH:mm:ss.SSS。
+每次最多两请求，不重试、重定向、切店、换身份、解密或下载附件。
+累计响应 10MiB，传输读取时取消超限响应；最终输出含换行 5MiB，超限不裁切。
+缺可选字段省略，null/错型失败，实际零、false、空文本和空数组保留。未知状态保留不推断。
+失败 stdout 为空，stderr 一份安全 JSON；应用 token 测试不证明员工 OAuth 或权限隔离。
+示例：zan-saas aftersale case get --kdt-id 63077 --case-id 000123 --include consultation --dry-run
+字段及状态字典见 zan-saas schema aftersale.case.get。
+`)
+    .action(async options => {
+      const input = buildInput(options, context === undefined ? contextInput() : context);
+      const plan = preview(input);
+      let output = plan;
+      if (!options.dryRun) {
+        const read = await createQuery(input.scope, command);
+        const request = plan.requests[1];
+        const { data, facts } = await read(request.path, request.body, 'case');
+        output = adapt(data, input, facts);
+      }
+      console.log(serialize(output, options.format, command, input.scope));
+    });
+  for (const name of ['kdtId', 'caseId', 'include', 'format', 'dryRun']) {
+    let occurrences = 0;
+    parser.on(`option:${name === 'dryRun' ? 'dry-run' : name === 'kdtId' ? 'kdt-id' : name === 'caseId' ? 'case-id' : name}`, () => {
+      if (++occurrences > 1) throw reject(command, 'validation', 'input');
+    });
+  }
+  return parser;
+}
+
+module.exports = { kind: 'atomic', risk: 'read', at: 'shop', createCommand: withTargetShopDefault(createCommand), buildInput, preview, adapt };

package/src/commands/native/aftersale/case/get/exact-json.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { parseExactJson } = require('../../../../../execution/exact-json');
+
+function parseLongJson(text) {
+  JSON.parse(text);
+  let index = 0;
+  const stack = [];
+  let root;
+  const numberPattern = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+  function append(value) {
+    const parent = stack[stack.length - 1];
+    if (!parent) { root = value; return; }
+    if (Array.isArray(parent.value)) parent.value.push(value);
+    else Object.defineProperty(parent.value, parent.key, { value, enumerable: true, configurable: true, writable: true });
+    parent.key = null;
+  }
+  while (index < text.length) {
+    const token = text[index++];
+    if (token.charCodeAt(0) <= 32 || token === ':' || token === ',') continue;
+    if (token === '{' || token === '[') {
+      const value = token === '{' ? {} : [];
+      append(value);
+      stack.push({ value, key: null });
+    } else if (token === '}' || token === ']') {
+      stack.pop();
+    } else if (token === '"') {
+      const start = index - 1;
+      while (index < text.length) {
+        const character = text[index++];
+        if (character === '\\') index++;
+        else if (character === '"') break;
+      }
+      const parent = stack[stack.length - 1];
+      if (parent && !Array.isArray(parent.value) && parent.key === null) {
+        parent.key = JSON.parse(text.slice(start, index));
+      } else append(JSON.parse(text.slice(start, index)));
+    } else if (token === 't' || token === 'f' || token === 'n') {
+      index += token === 'f' ? 4 : 3;
+      append(token === 't' ? true : token === 'f' ? false : null);
+    } else {
+      numberPattern.lastIndex = index - 1;
+      const source = numberPattern.exec(text)[0];
+      index = numberPattern.lastIndex;
+      const value = Number(source);
+      append(/^-?\d+$/.test(source) && !Number.isSafeInteger(value) ? BigInt(source) : parseExactJson(source));
+    }
+  }
+  return root;
+}
+
+module.exports = { parseLongJson };

package/src/commands/native/aftersale/case/get/money.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const MAX_CENTS = 9223372036854775807n;
+
+function formatCents(value) {
+  if (value < 0n || value > MAX_CENTS) throw new Error('amount outside long range');
+  return `${value / 100n}.${String(value % 100n).padStart(2, '0')}`;
+}
+
+function cents(value) {
+  if (typeof value === 'bigint') return formatCents(value);
+  if (!Number.isSafeInteger(value)) throw new Error('invalid integer cents');
+  return formatCents(BigInt(value));
+}
+
+function centsText(value) {
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) throw new Error('invalid cents text');
+  return formatCents(BigInt(value));
+}
+
+function yuan(value) {
+  if (typeof value !== 'string' || !/^\d+(?:\.\d+)?$/.test(value)) throw new Error('invalid yuan');
+  const [whole, fraction = ''] = value.split('.');
+  if (/[1-9]/.test(fraction.slice(2))) throw new Error('inexact yuan');
+  return formatCents(BigInt(whole) * 100n + BigInt(fraction.slice(0, 2).padEnd(2, '0')));
+}
+
+module.exports = { cents, centsText, yuan };

package/src/commands/native/aftersale/case/get/projection.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const { object } = require('../../../../../execution/query-api');
+const { formatDateTime, parseDateTime } = require('../../../../../execution/datetime');
+const { cents, centsText, yuan } = require('./money');
+
+function text(value) {
+  if (typeof value !== 'string') throw new Error('invalid text');
+  return value;
+}
+function nonempty(value) {
+  if (!text(value).trim()) throw new Error('empty identity');
+  return value;
+}
+function identifier(value) {
+  if (!/^[^\s\x00-\x1f\x7f-\x9f]{1,128}$/u.test(text(value))) throw new Error('invalid identifier');
+  return value;
+}
+function integer(value) {
+  if (!Number.isSafeInteger(value)) throw new Error('invalid integer');
+  return value;
+}
+function nonnegative(value) {
+  if (integer(value) < 0) throw new Error('negative value');
+  return value;
+}
+function shop(value) {
+  if (integer(value) < 1) throw new Error('invalid shop');
+  return value;
+}
+function boolean(value) {
+  if (typeof value !== 'boolean') throw new Error('invalid boolean');
+  return value;
+}
+function version(value) {
+  if (typeof value !== 'bigint') integer(value);
+  if (value < -9223372036854775808n || value > 9223372036854775807n) throw new Error('invalid version');
+  return String(value);
+}
+function time(value, alternate = false) {
+  text(value);
+  if (alternate && /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}$/.test(value)) {
+    value = `${value.slice(0, 10)} ${value.slice(11).replaceAll('-', ':')}`;
+  }
+  if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)) throw new Error('invalid source time');
+  return formatDateTime(parseDateTime(value));
+}
+function project(source, fields, required = []) {
+  if (!object(source)) throw new Error('invalid object');
+  const result = {};
+  for (const [target, [field, convert]] of Object.entries(fields)) {
+    if (Object.hasOwn(source, field)) result[target] = convert(source[field]);
+    else if (required.includes(target)) throw new Error('missing field');
+  }
+  return result;
+}
+function array(source, convert) {
+  if (!Array.isArray(source)) throw new Error('invalid array');
+  return source.map(convert);
+}
+function caseRecord(source) {
+  return project(source, {
+    caseId: ['refund_id', identifier], orderNo: ['tid', nonempty], kdtId: ['kdt_id', shop],
+    status: ['status', nonempty], demand: ['demand', integer], demandText: ['demand_desc', text],
+    type: ['refund_type', nonempty], amount: ['refund_fee', yuan], postage: ['refund_postage', yuan],
+    partType: ['part_type', integer], description: ['desc', text], hasReturnGoods: ['return_goods', boolean],
+    isNewExchange: ['is_new_exchange', boolean], serviceStatus: ['cs_status', integer], version: ['version', version],
+    createdAt: ['created', value => time(value, true)], updatedAt: ['modified', value => time(value, true)],
+    succeededAt: ['refund_success_time', time]
+  }, ['caseId', 'orderNo', 'kdtId', 'status', 'demand', 'amount']);
+}
+function items(source, scope) {
+  return array(source, entry => {
+    const item = project(entry, { orderItemId: ['oid', nonempty], kdtId: ['kdt_id', shop],
+      quantity: ['item_num', nonnegative], amount: ['refund_fee', cents], weightGrams: ['weight', nonnegative] },
+    ['orderItemId', 'quantity']);
+    if (Object.hasOwn(item, 'kdtId') && item.kdtId !== scope.kdtId) throw new Error('item shop mismatch');
+    return item;
+  });
+}
+function refunds(source) {
+  const seen = new Set();
+  return array(source, entry => {
+    const refund = project(entry, { refundNo: ['refund_no', identifier], refundId: ['refund_id', nonempty],
+      amount: ['refund_fee', cents], status: ['status', integer], mode: ['refund_mode', integer],
+      message: ['message', text], payWayText: ['pay_way_desc', text], payWayLabel: ['pay_way_str', text] },
+    ['refundNo', 'amount', 'status']);
+    if (seen.has(refund.refundNo)) throw new Error('duplicate refund');
+    seen.add(refund.refundNo);
+    return refund;
+  });
+}
+function logistics(source) {
+  const result = {};
+  for (const [direction, field] of [['return', 'logistics'], ['exchange', 'exgLogistics']]) {
+    const entry = source[field];
+    if (entry === undefined || entry === null) continue;
+    if (!object(entry)) throw new Error('invalid logistics');
+    if (!Object.hasOwn(entry, 'logistics_no')) continue;
+    text(entry.logistics_no);
+    if (entry.logistics_no === '') continue;
+    result[direction] = project(entry, { waybillNo: ['logistics_no', nonempty], carrierId: ['company_code', text] }, ['waybillNo']);
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+function consultation(source, parent) {
+  return array(source, entry => {
+    const result = project(entry, { orderNo: ['order_no', nonempty], kdtId: ['kdt_id', shop], role: ['role', integer],
+      stage: ['stage', nonempty], demand: ['demand', integer], content: ['content', text],
+      createdAt: ['create_time', time], attachments: ['attachment', value => array(value, nonempty)],
+      detail: ['message_detail', value => project(value, { reasonText: ['refund_reason', text],
+        refusalCause: ['refusal_cause', text], demandText: ['refund_demand', text], amount: ['refund_fee', centsText],
+        suggestedAmount: ['suggest_refund_fee', centsText], quantity: ['num', nonnegative] })] }, ['role']);
+    if ((Object.hasOwn(result, 'orderNo') && result.orderNo !== parent.orderNo) ||
+        (Object.hasOwn(result, 'kdtId') && result.kdtId !== parent.kdtId)) throw new Error('consultation scope mismatch');
+    return result;
+  });
+}
+
+module.exports = { identifier, caseRecord, items, refunds, logistics, consultation };

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

@@ -0,0 +1,72 @@
+'use strict';
+
+const { resolveTargetShop } = require('../../../../../execution/target-shop');
+const { readContext } = require('../../../../../identity/context');
+const { bindingPath, failure } = require('../../../../../execution/shop-query');
+const { readApiEnvelope, assertApiSuccess, object } = require('../../../../../execution/query-api');
+const { snapshotApiEnvironment } = require('../../../../../transport/api');
+const { parseLongJson } = require('./exact-json');
+
+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) {
+  try {
+    const scope = resolveTargetShop(options, context, command);
+    if (readContext(context).context?.orgType === 'hq') throw reject(command, 'permission', 'context', scope);
+    return scope;
+  } catch (error) {
+    if (!error.cliDetails) throw error;
+    const details = error.cliDetails;
+    throw reject(command, details.category, ['scope', 'validation'].includes(details.stage) ? 'input' : details.stage,
+      details.targetScope);
+  }
+}
+
+async function createQuery(scope, command, { responseLimit = RESPONSE_LIMIT, onRequest } = {}) {
+  let env;
+  try { env = await snapshotApiEnvironment(undefined, scope.kdtId); }
+  catch { throw reject(command, 'configuration', 'configuration', scope); }
+  let bytes = 0;
+  async function read(path, body, stage) {
+    const received = await readApiEnvelope(path, body,
+      (category, facts, state, at) => reject(command, category, at === 'configuration' ? at : stage, scope, state, facts),
+      env, response => { bytes += response.responseBytes; },
+      { onRequest, maxResponseBytes: () => responseLimit - bytes });
+    const { facts } = received;
+    const result = parseLongJson(received.rawBody);
+    assertApiSuccess(result, category => {
+      const code = String(facts.businessCode);
+      if (category === 'business_rejected' && stage === 'case' &&
+          path === 'youzan.trade.refund.get/3.0.1' && !Object.hasOwn(result, 'gw_err_resp')) {
+        if (code === '103011024') category = 'not_found';
+        if (code === '103010054') category = 'permission';
+      }
+      throw reject(command, category, stage, scope, 'sent', facts);
+    }, stage === 'shop-binding' ? [200] : [200, '200']);
+    return { data: result.data, facts };
+  }
+  const { data, facts } = await read(bindingPath, {}, 'shop-binding');
+  if (!object(data) || !Number.isSafeInteger(data.sid) || data.sid < 1) {
+    throw reject(command, 'protocol', 'shop-binding', scope, 'sent', facts);
+  }
+  if (data.sid !== scope.kdtId) throw reject(command, 'scope_unresolved', 'shop-binding', scope, 'sent', facts);
+  return read;
+}
+
+function serialize(output, format, command, scope, limit = OUTPUT_LIMIT) {
+  const json = JSON.stringify(output, null, format === 'pretty' ? 2 : 0);
+  if (Buffer.byteLength(`${json}\n`) > limit) throw reject(command, 'limit', 'output-model', scope, 'sent');
+  return json;
+}
+
+module.exports = { bindingPath, reject, targetScope, createQuery, serialize, RESPONSE_LIMIT, OUTPUT_LIMIT };

package/src/commands/native/aftersale/case/get/schema.json

@@ -0,0 +1,134 @@
+{
+  "schemaVersion": 1,
+  "input": {
+    "type": "object", "additionalProperties": false, "required": ["scope", "include"],
+    "description": "argv 解析后的业务输入；format 和 dry-run 是展示及执行模式，不在业务输入内。",
+    "properties": {
+      "scope": {"$ref": "#/definitions/scope"},
+      "include": {"type": "array", "uniqueItems": true, "items": {"type": "string", "enum": ["consultation"]}, "description": "可选模块 consultation 请求完整协商；逗号分隔，裁首尾空白并去重；空项和未知值拒绝，默认空数组。"}
+    }
+  },
+  "output": {
+    "type": "object", "additionalProperties": false, "required": ["data"],
+    "properties": {"data": {
+      "type": "object", "additionalProperties": false, "required": ["case", "items"],
+      "properties": {
+        "case": {"$ref": "#/definitions/case"},
+        "items": {"type": "array", "items": {"$ref": "#/definitions/item"}, "description": "本次响应实际返回的订单商品行，保留顺序；实际空数组才输出空数组。"},
+        "logistics": {"type": "object", "additionalProperties": false, "minProperties": 1, "properties": {
+          "return": {"$ref": "#/definitions/waybill"}, "exchange": {"$ref": "#/definitions/waybill"}
+        }, "description": "仅返回可识别运单引用；缺失、null、空对象或只有公司和地址时省略该方向，不证明未寄件。"},
+        "refunds": {"type": "array", "items": {"$ref": "#/definitions/refund"}, "description": "本次返回的资金条目；源缺失省略，不表示零笔退款或全生命周期流水。重复 refundNo 整体失败。"},
+        "consultation": {"type": "array", "items": {"$ref": "#/definitions/consultation"}, "description": "仅显式请求 consultation 时必需；请求全部协商，不额外保证服务端保留期限。"}
+      }
+    }}
+  },
+  "preview": {
+    "type": "object", "additionalProperties": false, "required": ["requests"],
+    "properties": {"requests": {
+      "type": "array", "minItems": 2, "maxItems": 2,
+      "items": {"type": "object", "additionalProperties": false, "required": ["method", "path", "body"],
+        "properties": {"method": {"const": "POST"}, "path": {"type": "string", "enum": ["youzan.shop.basic.get/3.0.0", "youzan.trade.refund.get/3.0.1"]},
+          "body": {"oneOf": [
+            {"type": "object", "additionalProperties": false, "maxProperties": 0},
+            {"type": "object", "additionalProperties": false, "required": ["refund_id"], "properties": {
+              "refund_id": {"$ref": "#/definitions/identifier"},
+              "query_option": {"const": "{\"include_all_consult_message\":true}", "description": "请求协商时出现的准确 JSON 编码文本。"}
+            }}
+          ]}
+        }}
+    }}
+  },
+  "error": {
+    "type": "object", "additionalProperties": false, "required": ["success", "code", "message"],
+    "properties": {
+      "success": {"const": false}, "code": {"const": -10001}, "message": {"type": "string", "minLength": 1},
+      "details": {"type": "object", "additionalProperties": false,
+        "required": ["category", "stage", "command", "targetScope", "requestState", "nextStep"],
+        "properties": {
+          "category": {"type": "string", "enum": ["validation", "configuration", "authentication", "permission", "scope_unresolved", "http", "business_rejected", "not_found", "protocol", "transport", "limit"]},
+          "stage": {"type": "string", "enum": ["input", "context", "configuration", "shop-binding", "case", "cases", "refunds", "output-model", "transport", "response"]},
+          "command": {"const": "aftersale.case.get"},
+          "targetScope": {"type": "object", "additionalProperties": false, "properties": {"kdtId": {"$ref": "#/definitions/shopId"}, "caseId": {"$ref": "#/definitions/identifier"}}},
+          "requestState": {"type": "string", "enum": ["not_sent", "sent", "unknown"]}, "nextStep": {"type": "string", "minLength": 1},
+          "api": {"type": "string", "pattern": "^youzan\\.[a-z.]+/[0-9]+\\.[0-9]+\\.[0-9]+$"},
+          "httpStatus": {"type": "integer", "minimum": 100, "maximum": 599},
+          "businessCode": {"$ref": "#/definitions/diagnosticCode"}, "gatewayCode": {"$ref": "#/definitions/diagnosticCode"},
+          "trace_id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$"}, "request_id": {"type": "string", "pattern": "^[a-zA-Z0-9_-]{1,128}$"}
+        }
+      }
+    }
+  },
+  "definitions": {
+    "scope": {"type": "object", "additionalProperties": false, "required": ["kdtId", "caseId"], "properties": {"kdtId": {"$ref": "#/definitions/shopId"}, "caseId": {"$ref": "#/definitions/identifier"}}},
+    "shopId": {"type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "正安全整数店铺 ID；argv 为规范十进制文本且必须显式提供。"},
+    "identifier": {"type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\s\\u0000-\\u001f\\u007f-\\u009f]+$", "description": "售后号或资金流水号，保留前导零，不含空白和 C0/C1 控制符；128 是 CLI 预算。"},
+    "text": {"type": "string", "description": "上游明确返回的文本，允许空串。"},
+    "nonempty": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "非空白文本，保留源值。"},
+    "integer": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991},
+    "quantity": {"type": "integer", "minimum": 0, "maximum": 9007199254740991},
+    "money": {"type": "string", "pattern": "^(?:0|[1-9][0-9]*)\\.[0-9]{2}$", "description": "默认人民币 CNY，元，固定两位小数。非负且精确分值不超过 9223372036854775807；拒绝舍入、空串和类型错误。"},
+    "time": {"type": "string", "format": "beijing-date-time-ms", "$comment": "upstream-time:text", "description": "固定北京时间 YYYY-MM-DD HH:mm:ss.SSS；仅源字段已证实的秒精度文本，校验实际日历。"},
+    "diagnosticCode": {"oneOf": [{"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991}, {"type": "string", "pattern": "^-?[0-9]{1,12}$"}]},
+    "case": {
+      "type": "object", "additionalProperties": false, "required": ["caseId", "orderNo", "kdtId", "status", "demand", "amount"],
+      "properties": {
+        "caseId": {"$ref": "#/definitions/identifier"}, "orderNo": {"$ref": "#/definitions/nonempty"}, "kdtId": {"$ref": "#/definitions/shopId"},
+        "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 售后成功。未知非空字符串保留，不推断到账。"},
+        "demand": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "当前诉求：1 仅退款，2 退货退款，3 换货。未知安全整数保留。"},
+        "demandText": {"$ref": "#/definitions/text"},
+        "type": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "BUYER_APPLY_REFUND 买家申请；SELLER_REFUND 商家主动退款；EXCHANGE_GOODS 线上普通或跨 SKU 换货；SYSTEM_REFUND 一键退款及超卖、支付回调超时等特殊退款；OFFLINE_EXCHANGE_GOODS 线下或零售换货。未知非空值保留。"},
+        "amount": {"$ref": "#/definitions/money", "$comment": "upstream-money:yuan", "description": "含邮费的售后申请退款金额，不是已到账金额。"},
+        "postage": {"$ref": "#/definitions/money", "$comment": "upstream-money:yuan", "description": "退还邮费。"},
+        "partType": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 全额退，1 部分退；未知安全整数保留。"},
+        "description": {"$ref": "#/definitions/text"}, "hasReturnGoods": {"type": "boolean", "description": "上游是否有退货，不推导库存结果。"}, "isNewExchange": {"type": "boolean", "description": "是否跨 SKU 换货。"},
+        "serviceStatus": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1 未介入，2 介入中，3 介入结束；未知安全整数保留。"},
+        "version": {"type": "string", "pattern": "^-?[0-9]+$", "description": "精确十进制 long 版本号，范围 -9223372036854775808 至 9223372036854775807；不表示写入授权。"},
+        "createdAt": {"$ref": "#/definitions/time"}, "updatedAt": {"$ref": "#/definitions/time"}, "succeededAt": {"$ref": "#/definitions/time", "description": "售后成功时间，不是逐笔资金到账时间。"}
+      }
+    },
+    "item": {"type": "object", "additionalProperties": false, "required": ["orderItemId", "quantity"], "properties": {
+      "orderItemId": {"$ref": "#/definitions/nonempty", "description": "订单商品行 oid，不用商品 ID 或顶层首行代替。"}, "kdtId": {"$ref": "#/definitions/shopId"}, "quantity": {"$ref": "#/definitions/quantity"},
+      "amount": {"$ref": "#/definitions/money", "$comment": "upstream-money:cents", "description": "该行含邮费退款金额。"}, "weightGrams": {"$ref": "#/definitions/quantity", "description": "退款商品重量，单位克。"}
+    }},
+    "waybill": {"type": "object", "additionalProperties": false, "required": ["waybillNo"], "properties": {"waybillNo": {"$ref": "#/definitions/nonempty"}, "carrierId": {"$ref": "#/definitions/text", "description": "有赞物流公司标识，不转换其他平台编码。"}}, "description": "已返回运单引用，不证明签收、入库或商家确认收货。"},
+    "refund": {"type": "object", "additionalProperties": false, "required": ["refundNo", "amount", "status"], "properties": {
+      "refundNo": {"$ref": "#/definitions/identifier"}, "refundId": {"$ref": "#/definitions/nonempty", "description": "资金条目自带 ID，不证明等于父售后号。"},
+      "amount": {"$ref": "#/definitions/money", "$comment": "upstream-money:cents", "description": "本资金条目含邮费退款金额。"},
+      "status": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 退款中，可能包含失败回写延迟；1 退款失败；2 退款成功。未知安全整数保留，不推断到账。"},
+      "mode": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0 原路退，1 现金退，2 标记退；3 已观察但含义未证实；未知安全整数保留。"},
+      "message": {"$ref": "#/definitions/text"}, "payWayText": {"$ref": "#/definitions/text"}, "payWayLabel": {"$ref": "#/definitions/text"}
+    }},
+    "consultation": {"type": "object", "additionalProperties": false, "required": ["role"], "properties": {
+      "orderNo": {"$ref": "#/definitions/nonempty", "description": "出现时必须匹配父售后订单。"}, "kdtId": {"$ref": "#/definitions/shopId"},
+      "role": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1 系统，2 买家，3 卖家，4 客服；未知安全整数保留。"},
+      "stage": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "RefundCreate 申请；RefundReject 商家拒绝；RefundCancel 买家撤销；RefundFinish 商家同意退款；RefundReturnGoodsAgree 同意退货；RefundReset 修改重发；RefundReturnGoods 买家填退货物流；RefundReturnGoodsReject 拒绝退货；RefundIntervene 客满介入；MessageAdd 留言；SellerReturnGoods 确认收货并发换货；RefundBuyerAgree 买家同意修改。未知非空字符串保留。"},
+      "demand": {"type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "该记录时诉求：1 仅退款，2 退货退款，3 换货；可与当前诉求不同，未知安全整数保留。"},
+      "content": {"$ref": "#/definitions/text"}, "createdAt": {"$ref": "#/definitions/time"},
+      "attachments": {"type": "array", "items": {"$ref": "#/definitions/nonempty"}, "description": "凭证链接，未下载，不证明可访问。"},
+      "detail": {"type": "object", "additionalProperties": false, "properties": {
+        "reasonText": {"$ref": "#/definitions/text"}, "refusalCause": {"$ref": "#/definitions/text"}, "demandText": {"$ref": "#/definitions/text"},
+        "amount": {"$ref": "#/definitions/money", "$comment": "upstream-money:cents-text"}, "suggestedAmount": {"$ref": "#/definitions/money", "$comment": "upstream-money:cents-text"}, "quantity": {"$ref": "#/definitions/quantity"}
+      }}
+    }}
+  },
+  "modules": {
+    "case": {"base": true, "upstreamPath": "data", "required": true, "description": "售后核心及已取得的可选字段。"},
+    "items": {"base": true, "upstreamPath": "data.refund_order_item", "required": true, "description": "默认订单商品行，必须为数组。"},
+    "logistics": {"base": true, "upstreamPath": "data.logistics,data.exgLogistics", "required": false, "description": "默认已有的有限运单引用，不是轨迹或收货确认。"},
+    "refunds": {"base": true, "upstreamPath": "data.refund_fund_list", "required": false, "description": "默认本次已返回的资金条目，缺失省略。"},
+    "consultation": {"base": false, "upstreamPath": "data.consult_message", "required": true, "description": "请求完整协商后必需；只改变主请求选项，不增加请求。"}
+  },
+  "api": {"method": "POST", "path": "youzan.trade.refund.get/3.0.1"},
+  "success": {"description": "同凭证店铺核验通过，售后号及店铺匹配，核心售后、商品行和所有默认已返回字段及显式协商模型均通过，才一次输出。"},
+  "errors": {"description": "缺失必需字段、null、错型、身份冲突、重复资金流水、金额不精确及时间非法整体失败。103011024 不存在；103010021/103010052 售后号无效；103010002 店铺缺失；103010054 权限拒绝。失败 stdout 为空，stderr 安全 JSON；断连 unknown，不自动重试。"},
+  "notes": [
+    "--kdt-id 省略时使用本次有效上下文 shopId；显式提供的非法值不回退。两者都缺失时拒绝；目标范围、同店核验和服务端权限仍按本命令校验。",
+    "接受售后号和目标店铺；省略店铺时使用当前上下文，显式非法值不回退；执行上下文必须为 shop 且目标等于 context.shopId；总部拒绝。缺上下文只可本地预览，无效上下文始终拒绝。应用身份不证明员工 OAuth 或权限隔离。",
+    "业务输入仅 scope/include。format 默认为 json，可选 pretty；dry-run 默认 false，二者不进入业务 input 或请求。",
+    "可选字段仅源缺失时省略，null 或错型失败；运输 null 及未取得可识别运单引用是省略例外。实际零、false、空文本和空数组保留。未知字段不透传，未请求协商不校验或输出。",
+    "默认 CNY，金额按准确来源单位转换到两位元字符串，不求和或分摊。时间固定北京时间；申请与修改时间兼容文案连字符及正式示例空格格式。",
+    "每次最多两请求，无重试、重定向、身份切换、自动解密或附件下载。累计原始响应 10MiB，读取时取消超限流；最终 UTF-8 输出含换行 5MiB，超限不裁切。",
+    "售后成功不代表每笔资金到账。缺资金数组不证明无退款；资金 mode 3 含义未证实，资金集合不保证全生命周期，未公开到账时间及储值拆分。"
+  ]
+}