@youzan-cloud/zan-saas-cli 0.1.0-beta.7 → 0.1.0-beta.8

package/src/commands/system/shop-contracts.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const object = properties => ({
-  type: 'object', additionalProperties: false, required: Object.keys(properties), properties
+const object = (properties, required = Object.keys(properties)) => ({
+  type: 'object', additionalProperties: false, required, properties
 });
 const id = { type: 'string', pattern: '^[1-9][0-9]*$', description: '正整数 ID 文本。' };
 const nullableText = { type: ['string', 'null'], description: '已核实的名称或时间；缺失为 null。' };
@@ -36,10 +36,37 @@ const effect = action => object({
 const chosenOutput = action => object({
   context: nullable(context), selection: nullable(selection), binding, effect: effect(action)
 });
+const diagnosticCode = { anyOf: [
+  { type: 'integer', minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER },
+  { type: 'string', pattern: '^-?\\d{1,12}$' }
+] };
+const trace = { type: 'string', pattern: '^[a-zA-Z0-9_-]{1,128}$' };
+const locationError = command => object({
+  success: { const: false }, code: { const: -10001 }, message: { type: 'string' },
+  details: object({
+    category: { enum: ['validation', 'configuration', 'authentication', 'permission', 'http',
+      'transport', 'protocol', 'business_rejected', 'limit', 'scope_unresolved'] },
+    stage: { enum: ['scope', 'configuration', 'headquarters-binding', 'target-membership'] },
+    command: { const: command },
+    targetScope: object({ kdtId: { anyOf: [id,
+      { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER }
+    ], description: '失败阶段核验的总部或目标店铺，不表示已切换位置。' } }),
+    requestState: { enum: ['not_sent', 'sent', 'unknown'] },
+    nextStep: { type: 'string', minLength: 1 },
+    api: { type: 'string', pattern: '^[a-z][a-z0-9._-]*/\\d+\\.\\d+\\.\\d+$' },
+    httpStatus: { type: 'integer', minimum: 100, maximum: 599 },
+    businessCode: diagnosticCode, gatewayCode: diagnosticCode,
+    trace_id: trace, request_id: trace
+  }, ['category', 'stage', 'command', 'targetScope', 'requestState', 'nextStep'])
+});
 const notes = [
   '上下文及本地保存不证明员工权限；账号、组织关系和业务授权分别核验。失败后不自动换店、换身份或重放。',
   '会话模式由宿主逐次注入 ZAN_SAAS_SESSION_ID。已有会话不跟随其他会话，查询和恢复不更新最近位置。'
 ];
+const locationNotes = [
+  '总部绑定或目录核验失败时可返回受限 details：category、stage、实际 command、targetScope、requestState 和 nextStep；可用时保留 API、HTTP 状态、数字业务码及安全 trace/request 标识，不回显响应正文、凭证或上游自由文本。',
+  'targetScope 是失败检查的对象，总部请求失败时可为总部 ID，不代表已选择目标。失败不改变当前位置或最近位置；旧的本地错误及公共参数解析错误仍保留各自模型。'
+];
 const switchInput = {
   kdtId: id, sessionOnly: { type: 'boolean', description: '仅更新本会话，需要宿主会话标识；省略为false。' }
 };
@@ -51,15 +78,19 @@ const contracts = {
       '显式初始化可核实当前账号并创建绑定。首次继承一次；无最近位置返回needs_selection；恢复已有记录不改时间和最近位置。']
   },
   'shop.unit.use': {
+    error: { anyOf: [object({ success: { const: false }, code: { const: -10001 },
+      message: { type: 'string' } }), locationError('shop.unit.use')] },
     input: { ...object(switchInput), required: ['kdtId'] },
-    output: chosenOutput('use_unit'), notes: [...notes,
+    output: chosenOutput('use_unit'), notes: [...notes, ...locationNotes,
       '需要已初始化会话及当前租户。只支持已核实的当前连锁总部、门店或网店，不改变租户根。']
   },
   'shop.resolve': {
+    error: { anyOf: [object({ success: { const: false }, code: { const: -10001 },
+      message: { type: 'string' } }), locationError('shop.resolve')] },
     input: { ...object({ kdtId: id, rootKdtId: { ...id, description: '目标所属根组织；省略时目标须为账号层根。' } }),
       required: ['kdtId'] },
     output: object({ context, selection, effect: effect('resolve'), revision: { type: 'null' } }),
-    notes: [...notes, '不保存当前位置。把返回context固定为本次任务每次调用的显式上下文；任务结束后丢弃。']
+    notes: [...notes, ...locationNotes, '不保存当前位置。把返回context固定为本次任务每次调用的显式上下文；任务结束后丢弃。']
   }
 };
 

package/src/execution/error-details.js

@@ -3,6 +3,7 @@
 const { executionFor } = require('./request-state');
 const { issueReasons } = require('./error-model');
 const { ParserError } = require('./parser-error');
+const { gatewayGuidance } = require('./gateway-guidance');
 const contexts = new WeakMap();
 const reasons = new Set(issueReasons);
 const constraintKeys = ['type', 'enum', 'const', 'minimum', 'maximum', 'exclusiveMinimum',
@@ -203,7 +204,8 @@ function localContextReason(error, details, execution) {
     execution.observedAttempts === 0 ? error.diagnosticReason : undefined;
 }
 
-function describeRecovery(details, execution, missingAuthentication = false, contextReason, responseReason) {
+function describeRecovery(details, execution, missingAuthentication = false, contextReason, responseReason,
+  gateway = gatewayGuidance(details, undefined, execution)) {
   if (contextReason) return { action: 'stop_and_inspect', nextStep:
     ['context_missing', 'target_missing'].includes(contextReason)
       ? '未登录先执行 zan-saas auth login；登录后用 zan-saas shop list 和 zan-saas shop use <kdtId> 选店。缺少上下文时仅可显式指定店铺做 --dry-run，不自动切店或重放。'
@@ -221,14 +223,13 @@ function describeRecovery(details, execution, missingAuthentication = false, con
   if (details.category === 'provider_unavailable' && details.command === 'privacy.field.decrypt') {
     return { action: 'stop_and_inspect', nextStep: '当前仅支持离线预览，请加 --dry-run；真实解密服务尚未接入。' };
   }
+  if (responseReason) return { action: 'stop_and_inspect',
+    nextStep: `${responseReason.nextStep} 不自动重放、切店或换身份。` };
+  if (gateway) return { action: gateway.action, nextStep: gateway.nextStep };
   if (missingAuthentication || details.category === 'authentication') {
     return { action: 'complete_authentication',
       nextStep: '检查 zan-saas auth status --format json，按公共认证流程完成登录；不在聊天中提供凭证，不自动重放原调用。' };
   }
-  if (gatewayAccessDenied(details)) {
-    return { action: 'request_access_review',
-      nextStep: '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查，不自动重放。' };
-  }
   if (details.category === 'permission') {
     return { action: 'request_access_review',
       nextStep: '核对原账号、目标店铺与服务端授权，可提供脱敏接口及 trace_id 给管理员；不切店、换身份或自动重放。' };
@@ -237,8 +238,6 @@ function describeRecovery(details, execution, missingAuthentication = false, con
     return { action: 'stop_and_inspect',
       nextStep: '店铺核验失败，后续业务请求尚未发送；本次已有核验请求记录，核对原店铺和凭证后停止，不自动切店或重放。' };
   }
-  if (responseReason) return { action: 'stop_and_inspect',
-    nextStep: `${responseReason.nextStep} 不自动重放、切店或换身份。` };
   if (details.requestState === 'sent' && details.category === 'business_rejected') {
     return { action: 'stop_and_inspect',
       nextStep: '接口已拒绝本次查询；将诊断中的 api、businessCode 或 gatewayCode、trace_id 提供给管理员核查服务端原因。错误码本身不能证明是权限或数据问题，不自动重放、切店或换身份。' };
@@ -275,19 +274,14 @@ function businessRejectionMessage(details) {
   return `接口拒绝了本次查询${code ? `（${code}）` : ''}，已停止处理。`;
 }
 
-function gatewayAccessDenied(details) {
-  return details?.requestState === 'sent' &&
-    ['business_rejected', 'permission'].includes(details.category) &&
-    [4204, '4204'].includes(details.gatewayCode);
-}
-
 function finalizeError(error, registeredContext) {
   if (error instanceof ParserError) return structuredClone(error.result);
   const context = contexts.get(error) || registeredContext;
   if (context?.schema.errors?.diagnosticsVersion !== 2) {
-    if (gatewayAccessDenied(error.cliDetails)) {
-      error.message = '网关拒绝访问：没有操作权限。';
-      error.cliDetails.nextStep = '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；可提供接口和 trace_id 给管理员排查。';
+    const gateway = gatewayGuidance(error.cliDetails, context);
+    if (gateway) {
+      error.message = gateway.message;
+      error.cliDetails.nextStep = gateway.nextStep;
     }
     return { success: false, code: -10001, message: error.message,
       ...(error.cliDetails ? { details: error.cliDetails } : {}) };
@@ -372,7 +366,8 @@ function diagnosticError(error, context, execution) {
   if (error.issuesTruncated) details.issuesTruncated = true;
   const contextReason = localContextReason(error, details, execution);
   const responseReason = declaredResponseReason(error, context, details, execution);
-  const recovery = describeRecovery(details, execution, error.diagnosticReason === 'missing_authentication', contextReason, responseReason);
+  const gateway = !inputError && !contextReason && !responseReason ? gatewayGuidance(details, context, execution) : undefined;
+  const recovery = describeRecovery(details, execution, error.diagnosticReason === 'missing_authentication', contextReason, responseReason, gateway);
   const groupConflict = inputError && context.path === 'item.group.list' &&
     issues.some(issue => issue.path === '/parentGroupId' && issue.reason === 'constraint' && issue.relatedPaths?.includes('/title'))
     ? context.schema.errors.parentTitleConflict : undefined;
@@ -382,9 +377,9 @@ function diagnosticError(error, context, execution) {
   const result = { success: false, code: -10001,
     message: inputError ? (groupConflict?.message || issueMessage(issues)) :
       contextReason ? localContextMessages[contextReason] :
-      gatewayAccessDenied(details) ? '网关拒绝访问：没有操作权限。' :
       details.category === 'provider_unavailable' && context.path === 'privacy.field.decrypt' ? '当前仅支持离线预览，真实解密服务尚未接入' :
       responseReason ? responseReason.message :
+      gateway ? gateway.message :
       details.category === 'business_rejected' && details.requestState === 'sent' ? businessRejectionMessage(details) :
       issues.some(issue => issue.source === 'output') ?
         `返回数据字段 ${issues.find(issue => issue.source === 'output').path} 不符合要求，已停止查询` :

package/src/execution/gateway-guidance.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const authenticationStep = '先区分当前凭证来源与目标店铺、应用授权范围；个人登录使用 zan-saas auth login 重新登录授权，显式环境身份由凭证提供方更新或补齐配置。zan-saas auth status 仅查看本地保存状态，不能证明环境 token 有效；不在聊天中提供凭证，不自动切换来源或刷新，不自动重放。';
+const supportStep = '先按同版 help/schema 核对参数契约；参数符合且持续失败时，将诊断中实际保留的 api、gatewayCode 和追踪号提供给支持人员排查，不提供凭证、客户标识或请求 body，不自动重放。';
+const guidance = new Map([
+  [4101, { message: '网关限制了本次请求：调用过于频繁或受限。', action: 'stop_and_inspect',
+    nextStep: '停止本轮后续请求，检查调用频率、并发与可用配额；降低频率后由调用方重新决定是否发起。持续受限时提供诊断中实际保留的 api、gatewayCode 和追踪号排查，不保证固定恢复时间，不自动等待或重试，不自动重放。' }],
+  [4201, { message: '网关拒绝了本次请求：请求凭证无效。', action: 'complete_authentication',
+    nextStep: `核查凭证值以及店铺与应用授权；不能仅凭此码确定密码、员工权限或某一项授权失效。${authenticationStep}` }],
+  [4202, { message: '网关拒绝了本次请求：请求凭证已过期。', action: 'complete_authentication',
+    nextStep: authenticationStep }],
+  [4203, { message: '网关拒绝了本次请求：请求凭证不存在。', action: 'complete_authentication',
+    nextStep: authenticationStep }],
+  [4204, { message: '网关拒绝访问：没有操作权限。', action: 'request_access_review',
+    nextStep: '请检查当前账号是否有该店铺权限，以及店铺应用是否已获该接口的开放能力授权；不能仅凭此码确定根因，持续拒绝时提供诊断中实际保留的 api、gatewayCode 和追踪号给管理员核查服务端限制，不自动申请授权、切店或换身份，不自动重放。' }],
+  [4009, { message: '网关无法解析本次请求的客户标识 open_id。', action: 'stop_and_inspect',
+    nextStep: '按同版契约核对客户标识、标识类型与目标店铺；这不是登录凭证问题，也不能据此认定客户在所有店铺均不存在，不自动登录或切店，不自动重放。' }],
+  [5001, { message: '本次请求失败：网关报告上游系统异常。', action: 'stop_and_inspect', nextStep: supportStep }],
+  [5002, { message: '本次请求失败：网关报告上游业务异常。', action: 'stop_and_inspect', nextStep: supportStep }]
+]);
+
+function gatewayGuidance(details, context, execution) {
+  if (details?.requestState !== 'sent' ||
+      (execution && (execution.requestState !== 'sent' || execution.coverage !== 'complete')) ||
+      details.issues?.length) return undefined;
+  const raw = details.gatewayCode;
+  if (typeof raw !== 'number' && !(typeof raw === 'string' && /^[1-9]\d{3}$/.test(raw))) return undefined;
+  const code = Number(raw);
+  const selected = guidance.get(code);
+  if (!selected) return undefined;
+  const compatible = details.category === 'business_rejected' ||
+    (details.category === 'authentication' && [4201, 4202, 4203].includes(code)) ||
+    (details.category === 'permission' && code === 4204) ||
+    (details.category === 'http' && ((details.httpStatus === 429 && code === 4101) ||
+      (details.httpStatus >= 500 && [5001, 5002].includes(code))));
+  if (!compatible) return undefined;
+  const customerOption = code === 4009 && context?.command?.options.some(option => option.long === '--yz-open-id');
+  const bindingStep = details.stage === 'shop-binding' ? '店铺核验失败，后续业务请求尚未发送。' : '';
+  const customerStep = customerOption ? '核对本命令 --yz-open-id 的客户标识。' : '';
+  return { ...selected, nextStep: `${bindingStep}${customerStep}${selected.nextStep}` };
+}
+
+module.exports = { gatewayGuidance };

package/src/execution/shop-query.js

@@ -12,20 +12,23 @@ function failure(command, category, stage, scope = {}, requestState = 'not_sent'
   return new QueryError(category, stage, scope, facts, requestState, command, nextStep);
 }
 
-async function createBoundShopQuery(target, command, bindingStage = 'shop-binding', { onResponse, transportOptions } = {}) {
+async function createBoundShopQuery(target, command, bindingStage = 'shop-binding', {
+  onResponse, transportOptions, environment, beforeRequest
+} = {}) {
   const scope = Object.freeze({ kdtId: target.kdtId });
   if (!Number.isSafeInteger(scope.kdtId) || scope.kdtId < 1) {
     throw failure(command, 'validation', 'scope');
   }
   let env;
   try {
-    env = await snapshotApiEnvironment(undefined, scope.kdtId);
+    env = await snapshotApiEnvironment(environment, scope.kdtId);
   } catch (error) {
     const rejected = failure(command, 'configuration', 'configuration', scope);
     rejected.diagnosticReason = error.diagnosticReason;
     throw rejected;
   }
   async function read(path, body, stage, successCodes = [200]) {
+    if (beforeRequest) beforeRequest(path, stage);
     const { result, facts, rawBody, responseBytes } = await readApiEnvelope(path, body,
       (category, details, state, at) => failure(command, category,
         at === 'configuration' || category === transportOptions?.limitCategory ? at : stage,
@@ -43,7 +46,7 @@ async function createBoundShopQuery(target, command, bindingStage = 'shop-bindin
   if (data.sid !== scope.kdtId) {
     throw failure(command, 'scope_unresolved', bindingStage, scope, 'sent', facts);
   }
-  return { read, binding };
+  return { read, binding, environment: env };
 }
 
 async function createShopQuery(target, command, options = {}) {

package/src/identity/shop-location.js

@@ -4,7 +4,9 @@ const account = require('../transport/account-api');
 const { oauthConfig } = require('../auth/config');
 const { readCredential } = require('../auth/credential-store');
 const { authSource } = require('../auth/credential-source');
-const { requestApi, snapshotApiIdentity, snapshotApiEnvironment } = require('../transport/api');
+const { snapshotApiIdentity } = require('../transport/api');
+const { createBoundShopQuery, failure } = require('../execution/shop-query');
+const { verifyMembership } = require('./unit-membership');
 const sessions = require('./session-store');
 const { readSavedContext } = require('./context-store');
 const { createContext } = require('./context');
@@ -61,22 +63,25 @@ async function rootLocation(kdtId, actor) {
   }) };
 }
 
-async function unitLocation(kdtId, root, actor) {
+async function unitLocation(kdtId, root, actor, command) {
   id(kdtId);
   if (kdtId === root.context.hq) return root;
   if (root.context.orgType !== 'hq') {
     throw sessions.fail('unit_scope_unresolved', '当前店铺没有已核实的连锁总部，不能进入下级组织。');
   }
-  const response = await requestApi({ path: 'youzan.shop.basic.get/3.0.0', body: {} },
-    await snapshotApiEnvironment(actor.pinned, kdtId),
-    { shopApp: false, identityCheck: false, maxResponseBytes: () => 256 * 1024 });
-  let envelope;
-  try { envelope = JSON.parse(response.body); } catch { /* Report a bounded protocol error below. */ }
-  const data = envelope?.data;
-  if (!response.ok || envelope?.success !== true || envelope.code !== 200 ||
-      !data || data.sid !== Number(kdtId) || data.root_kdt_id !== Number(root.context.hq)) {
-    throw sessions.fail('unit_scope_unresolved', '未能核实目标组织及所属连锁，未改变当前位置。');
+  const scope = { kdtId };
+  const reject = (category, stage, state, facts) => {
+    const error = failure(command, category, stage, scope, state, facts);
+    error.cliDetails.nextStep = '未改变当前位置。核对原总部及目标，目录未读完不代表目标不属于该总部；不自动重试或初始化分店应用。';
+    return error;
+  };
+  const { read, binding } = await createBoundShopQuery({ kdtId: Number(root.context.hq) },
+    command, 'headquarters-binding', { environment: actor.pinned,
+      transportOptions: { shopApp: false, identityCheck: false, maxResponseBytes: () => 256 * 1024 } });
+  if (binding.data.role !== 1) {
+    throw reject('scope_unresolved', 'headquarters-binding', 'sent', binding.facts);
   }
+  const data = await verifyMembership(read, kdtId, reject, { notFoundCategory: 'permission' });
   if (![2001, 2002].includes(data.role)) {
     throw sessions.fail('unit_not_supported', '本版仅支持已核实的连锁门店或网店位置。');
   }
@@ -135,7 +140,7 @@ async function select(kdtId, options = {}, env = process.env, explicitContext) {
   const rootId = options.unit ? expected.binding.location?.context.hq : kdtId;
   if (!rootId) throw sessions.fail('unit_scope_unresolved', '请先选择当前连锁。');
   const root = await rootLocation(rootId, actor);
-  const location = options.unit ? await unitLocation(kdtId, root, actor) : root;
+  const location = options.unit ? await unitLocation(kdtId, root, actor, 'shop.unit.use') : root;
   const effect = sessions.commit(location, expected, options, env);
   return result(options.unit ? 'use_unit' : 'use_root', effect, env);
 }
@@ -145,7 +150,7 @@ async function resolve(kdtId, options = {}, env = process.env) {
   const rootId = options.rootKdtId === undefined ? kdtId : id(options.rootKdtId);
   const actor = await identify(env);
   const root = await rootLocation(rootId, actor);
-  const location = await unitLocation(kdtId, root, actor);
+  const location = await unitLocation(kdtId, root, actor, 'shop.resolve');
   return { ...location, effect: { action: 'resolve', currentChanged: false, recentChanged: false },
     revision: null };
 }

package/src/identity/unit-membership.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { object } = require('../execution/query-api');
+
+const organizationPath = 'youzan.shop.chain.descendent.organization.list/1.0.1';
+const maxOrganizationPages = 20;
+const pageSize = 50;
+
+function organizationBody(pageNo) {
+  return { page_num: pageNo, page_size: pageSize, with_dept_info: false,
+    with_shop_status_and_lifecycle_end_time: false, with_crm_shop: false };
+}
+
+async function verifyMembership(read, targetId, reject, { maxPages = maxOrganizationPages,
+  notFoundCategory = 'scope_unresolved' } = {}) {
+  const seen = new Set();
+  let total;
+  let lastFacts;
+  for (let pageNo = 1; pageNo <= maxPages; pageNo += 1) {
+    const { data, facts } = await read(organizationPath, organizationBody(pageNo), 'target-membership');
+    lastFacts = facts;
+    const invalid = category => reject(category, 'target-membership', 'sent', facts);
+    if (!object(data) || !Array.isArray(data.organization_list) ||
+        data.page_num !== pageNo || data.page_size !== pageSize ||
+        !Number.isSafeInteger(data.total) || data.total < 0 ||
+        data.organization_list.length !== Math.min(pageSize, Math.max(0, data.total - seen.size)) ||
+        (total !== undefined && total !== data.total)) throw invalid('protocol');
+    total = data.total;
+    for (const unit of data.organization_list) {
+      if (!object(unit) || !Number.isSafeInteger(unit.kdt_id) || unit.kdt_id < 1 ||
+          !Number.isSafeInteger(unit.role) || unit.role < 0 || unit.role === 9 ||
+          seen.has(unit.kdt_id)) throw invalid('protocol');
+      seen.add(unit.kdt_id);
+    }
+    const member = data.organization_list.find(unit => String(unit.kdt_id) === String(targetId));
+    if (member) return member;
+    if (seen.size === total) throw invalid(notFoundCategory);
+  }
+  throw reject('scope_unresolved', 'target-membership', 'sent', lastFacts);
+}
+
+module.exports = { organizationPath, organizationBody, maxOrganizationPages, verifyMembership };

package/src/transport/api.js

@@ -246,7 +246,7 @@ async function readResponseBody(response, maxResponseBytes) {
 }
 
 async function snapshotApiEnvironment(env = apiEnvironment(), kdtId) {
-  if (env.ZAN_SAAS_SESSION_ID !== undefined && env.ZAN_SAAS_KDT_ID &&
+  if (!boundTargets.has(env) && env.ZAN_SAAS_SESSION_ID !== undefined && env.ZAN_SAAS_KDT_ID &&
       env.ZAN_SAAS_KDT_ID !== String(kdtId)) {
     throw new ApiConfigurationError('显式请求店铺头与本次命令目标冲突。', 'context_override_conflict');
   }