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

package/src/identity/shop-location.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const account = require('../transport/account-api');
+const { oauthConfig } = require('../auth/config');
+const { readCredential } = require('../auth/credential-store');
+const { authSource } = require('../auth/credential-source');
+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');
+
+function id(value) {
+  if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+    throw sessions.fail('invalid_target', 'kdtId 必须是正整数店铺 ID。');
+  }
+  return value;
+}
+
+function selection(context, { tenantName = null, unitName = null, role = null } = {}) {
+  return {
+    tenantRootKdtId: context.hq, tenantName, currentUnitKdtId: context.shopId,
+    unitName, position: context.orgType, role
+  };
+}
+
+async function identify(env) {
+  const { environment: pinned, source, credentialRef: ref } = await snapshotApiIdentity(env);
+  const user = await account.whoami(pinned);
+  const actor = { user, pinned, ref, source };
+  assertIdentity(actor, env);
+  return actor;
+}
+
+function assertIdentity(actor, env) {
+  const credential = authSource(env) === 'env' ? null : readCredential(oauthConfig(env).server, env);
+  if (actor.ref !== sessions.credentialRef(env, credential)) {
+    throw sessions.fail('context_conflict', '登录状态在核实账号期间发生变化，请重新查看当前身份。');
+  }
+}
+
+function rejectOverride(env, explicitContext) {
+  if (env.ZAN_SAAS_CONTEXT || explicitContext !== undefined) {
+    throw sessions.fail('context_override_conflict',
+      '本次上下文由显式输入覆盖，请使用会话调用环境切店后核对 shop current。');
+  }
+}
+
+async function rootLocation(kdtId, actor) {
+  id(kdtId);
+  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, actor.pinned);
+  const shop = page.items.find(item => item.kdtId === kdtId);
+  if (!shop) throw new Error(`当前账号下没有可选店铺 ${kdtId}。执行 zan-saas shop list 查看可选店铺。`);
+  if (!shop.orgType) throw new Error(`店铺 ${kdtId} 不是本版支持的总部或单店入口。`);
+  const status = await account.staffStatus(kdtId, actor.pinned);
+  if (status === account.staffStatuses.disabled) throw new Error(`你在店铺 ${kdtId} 的员工账号已停用，不能选择。`);
+  const context = createContext({
+    userId: actor.user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType
+  });
+  return { context, selection: selection(context, {
+    tenantName: shop.shopName, unitName: shop.shopName, role: shop.shopRole
+  }) };
+}
+
+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 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', '本版仅支持已核实的连锁门店或网店位置。');
+  }
+  const context = createContext({ ...root.context, shopId: kdtId, orgType: 'shop' });
+  return { context, selection: selection(context, {
+    tenantName: root.selection.tenantName,
+    unitName: typeof data.name === 'string' && data.name.trim() ? data.name : null, role: data.role
+  }) };
+}
+
+function displayName(location) {
+  const { tenantName, unitName, currentUnitKdtId, tenantRootKdtId } = location.selection;
+  if (currentUnitKdtId === tenantRootKdtId) return tenantName || unitName;
+  return tenantName && unitName ? `${tenantName} / ${unitName}` : unitName || tenantName;
+}
+
+function result(action, effect, env) {
+  const state = sessions.snapshot(env);
+  const location = state.binding?.location;
+  return { context: location?.context ?? null, selection: location?.selection ?? null,
+    binding: sessions.publicBinding(state), effect: { action, ...effect } };
+}
+
+async function initialize(options = {}, env = process.env) {
+  if (!sessions.sessionId(env)) throw sessions.fail('session_missing', '会话初始化需要 ZAN_SAAS_SESSION_ID。');
+  rejectOverride(env);
+  const actor = await identify(env);
+  let legacy = null;
+  const existing = sessions.snapshot(env, { userId: actor.user.userId, credentialRef: actor.ref });
+  if (!options.resume && !existing.binding && !existing.recent && !existing.legacyChecked &&
+      !env.ZAN_SAAS_ACCOUNT_API_BASE_URL && !env.ZAN_SAAS_API_BASE_URL) {
+    const saved = readSavedContext(env);
+    if (saved?.context.userId === actor.user.userId && saved.context.hq === saved.context.shopId) {
+      const root = await rootLocation(saved.context.hq, actor);
+      if (JSON.stringify(root.context) === JSON.stringify(saved.context)) legacy = root;
+    }
+  }
+  const currentChanged = sessions.initialize({ ...options, legacy,
+    verifiedIdentity: { userId: actor.user.userId, credentialRef: actor.ref } }, env);
+  return result('init', { currentChanged, recentChanged: false }, env);
+}
+
+async function select(kdtId, options = {}, env = process.env, explicitContext) {
+  id(kdtId);
+  if (!sessions.sessionId(env)) throw sessions.fail('session_missing', '会话切换需要 ZAN_SAAS_SESSION_ID。');
+  rejectOverride(env, explicitContext);
+  if (env.ZAN_SAAS_KDT_ID && env.ZAN_SAAS_KDT_ID !== kdtId) {
+    throw sessions.fail('context_override_conflict', '请求店铺头覆盖与切换目标不同，未改变当前位置。');
+  }
+  const expected = sessions.snapshot(env);
+  if (!expected.binding) throw sessions.fail('session_uninitialized', '请先执行 zan-saas shop session init。');
+  const actor = await identify(env);
+  if (actor.user.userId !== expected.identity?.userId || actor.ref !== expected.identity?.credentialRef) {
+    throw sessions.fail('context_conflict', '登录身份已改变，请重新初始化本会话。');
+  }
+  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, 'shop.unit.use') : root;
+  const effect = sessions.commit(location, expected, options, env);
+  return result(options.unit ? 'use_unit' : 'use_root', effect, env);
+}
+
+async function resolve(kdtId, options = {}, env = process.env) {
+  id(kdtId);
+  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, 'shop.resolve');
+  return { ...location, effect: { action: 'resolve', currentChanged: false, recentChanged: false },
+    revision: null };
+}
+
+module.exports = { selection, identify, assertIdentity, initialize, select, resolve, displayName, rejectOverride };

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

@@ -11,6 +11,8 @@ const { runWithRequestState, beginRequest } = require('../execution/request-stat
 
 const apiPathPattern = /^\/?([a-z][a-z0-9._-]*)\/([0-9]+\.[0-9]+\.[0-9]+)$/;
 const apiSessions = new AsyncLocalStorage();
+const boundTargets = new WeakMap();
+const pinnedCredentials = new WeakMap();
 
 function runWithApiSession(action, environment) {
   return runWithRequestState(() =>
@@ -20,10 +22,22 @@ function runWithApiSession(action, environment) {
 function apiEnvironment() {
   const session = apiSessions.getStore();
   if (!session) return Object.freeze({ ...process.env });
-  session.env ||= Object.freeze({ ...(session.environment || process.env) });
+  session.env ||= Object.freeze({
+    ...(session.environment || process.env),
+    ...(Object.hasOwn(session, 'context') ? { ZAN_SAAS_CONTEXT: session.context } : {})
+  });
   return session.env;
 }
 
+function bindApiContext(context, environment = process.env) {
+  const session = apiSessions.getStore();
+  if (session) {
+    session.environment = environment;
+    session.context = JSON.stringify(context ?? null);
+    session.env = undefined;
+  }
+}
+
 // Business APIs select the shop per request; account APIs serve the user and send no shop.
 const gateways = {
   business: { key: 'ZAN_SAAS_API_BASE_URL', base: defaultApiBaseUrl, label: 'API base URL', shop: true },
@@ -46,14 +60,15 @@ class ApiResponseLimitError extends Error {
   }
 }
 
-async function accessToken(env) {
+async function accessCredential(env) {
   try {
+    if (pinnedCredentials.has(env)) return pinnedCredentials.get(env);
     const session = apiSessions.getStore();
     if (session && env === session.env) {
       session.credential ||= resolveAccessToken(env);
-      return (await session.credential).token;
+      return await session.credential;
     }
-    return (await resolveAccessToken(env)).token;
+    return await resolveAccessToken(env);
   } catch (error) {
     if (error instanceof AuthRequiredError || error instanceof AuthConfigurationError) {
       throw new ApiConfigurationError(error.message,
@@ -63,6 +78,20 @@ async function accessToken(env) {
   }
 }
 
+function pinEnvironment(env, credential, overrides = {}) {
+  const snapshot = Object.freeze({ ...env, ...overrides });
+  pinnedCredentials.set(snapshot, credential);
+  if (boundTargets.has(env)) boundTargets.set(snapshot, boundTargets.get(env));
+  return snapshot;
+}
+
+async function snapshotApiIdentity(env = apiEnvironment()) {
+  requestAddress('youzan.user.info.get/1.0.0', env, gateways.account);
+  const credential = await accessCredential(env);
+  return { environment: pinEnvironment(env, credential), source: credential.source,
+    credentialRef: credential.credentialRef };
+}
+
 // Personal tokens select the shop per request: ZAN_SAAS_KDT_ID, else the shopId of ZAN_SAAS_CONTEXT,
 // else the shop saved by `zan-saas shop use`.
 function shopHeader(env) {
@@ -76,7 +105,7 @@ function shopHeader(env) {
   return state.status === 'ready' ? state.context.shopId : undefined;
 }
 
-async function endpoint(path, env, gateway = gateways.business) {
+function requestAddress(path, env, gateway) {
   const base = env[gateway.key] || gateway.base;
   const match = apiPathPattern.exec(path);
   if (!match) throw new ApiConfigurationError('API path must be <api-name>/<version>');
@@ -88,19 +117,47 @@ async function endpoint(path, env, gateway = gateways.business) {
       url.password || url.search || url.hash || url.origin === 'null') {
     throw new ApiConfigurationError(`${gateway.label} must be an HTTPS URL without credentials, query or fragment`);
   }
-  // Resolve the token last so invalid configuration never triggers a login or refresh.
-  const token = await accessToken(env);
   const requestUrl = new URL(
     `${url.pathname.replace(/\/$/, '')}/${match[1]}/${match[2]}`, url.origin
   );
+  return requestUrl;
+}
+
+async function endpoint(path, env, gateway = gateways.business) {
+  const requestUrl = requestAddress(path, env, gateway);
+  // Resolve the token last so invalid configuration never triggers a login or refresh.
+  const credential = await accessCredential(env);
+  const { token } = credential;
   requestUrl.searchParams.set('access_token', token);
-  return { requestUrl, token };
+  return { requestUrl, token, credential };
 }
 
 async function requestApi({ path, body }, env = apiEnvironment(), options = {}) {
   const target = gateways[options.gateway || 'business'];
   if (!target) throw new ApiConfigurationError(`Unknown API gateway: ${options.gateway}`);
   const kdtId = target.shop ? shopHeader(env) : undefined;
+  if (target.shop && env.ZAN_SAAS_SESSION_ID !== undefined && options.identityCheck !== false) {
+    const state = readContext(contextInput(env));
+    if (state.status !== 'ready') {
+      throw new ApiConfigurationError('会话没有有效上下文，请先初始化并选择店铺。', 'session_uninitialized');
+    }
+    if (env.ZAN_SAAS_KDT_ID && env.ZAN_SAAS_KDT_ID !== state.context.shopId &&
+        boundTargets.get(env) !== env.ZAN_SAAS_KDT_ID) {
+      throw new ApiConfigurationError('请求店铺头与会话位置冲突，业务请求未发送。', 'context_override_conflict');
+    }
+    const { credential } = await endpoint(path, env, target);
+    env = pinEnvironment(env, credential);
+    let user;
+    try { user = await require('./account-api').whoami(env); }
+    catch { throw new ApiConfigurationError('无法核实当前凭证账号，业务请求未发送。', 'context_identity_mismatch'); }
+    if (user.userId !== state.context.userId) {
+      throw new ApiConfigurationError('当前凭证账号与任务上下文不一致或无法核实，业务请求未发送。', 'context_identity_mismatch');
+    }
+  }
+  if (!pinnedCredentials.has(env)) {
+    const { credential } = await endpoint(path, env, target);
+    env = pinEnvironment(env, credential);
+  }
   const send = () => sendApi(path, body, env, target, kdtId, options);
   const response = await send();
   if (!kdtId || env.ZAN_SAAS_SHOP_APP_INIT === '0' || options.shopApp === false) return response;
@@ -189,11 +246,21 @@ async function readResponseBody(response, maxResponseBytes) {
 }
 
 async function snapshotApiEnvironment(env = apiEnvironment(), kdtId) {
-  const { token } = await endpoint('youzan.shop.basic.get/3.0.0', env);
-  return Object.freeze({ ...env, ZAN_SAAS_USER_ACCESS_TOKEN: token, ZAN_SAAS_KDT_ID: String(kdtId) });
+  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');
+  }
+  const context = contextInput(env);
+  const { credential } = await endpoint('youzan.shop.basic.get/3.0.0', env);
+  const snapshot = pinEnvironment(env, credential, {
+    ZAN_SAAS_KDT_ID: String(kdtId),
+    ZAN_SAAS_CONTEXT: typeof context === 'string' ? context : JSON.stringify(context ?? null)
+  });
+  boundTargets.set(snapshot, String(kdtId));
+  return snapshot;
 }
 
 module.exports = {
   requestApi, snapshotApiEnvironment, runWithApiSession, ApiConfigurationError,
-  ApiResponseLimitError, readResponseBody
+  ApiResponseLimitError, readResponseBody, bindApiContext, snapshotApiIdentity
 };

package/src/transport/shop-app.js

@@ -5,6 +5,10 @@ const { callAccountApi, paths } = require('./account-api');
 // The business gateway answers 1106 when the selected shop has no usable app. The request never
 // reached the API, so it is safe to send again once the app is ready.
 const noAppCode = '1106';
+// bifrost-gateway maps the oauth 1106 to its own 4204 and keeps only the message. 4204 also covers
+// other permission failures, so it counts as "no app" only together with this message.
+const noAppGatewayCode = '4204';
+const noAppMessage = '该店铺下没有可用的应用';
 // CloudAppStateEnums: only 2 is ready; 4, 5 and 6 never become ready without a person stepping in.
 const appStates = Object.freeze({ 1: '审核中', 2: '已创建', 3: '初始化中', 4: '初始化失败', 5: '审核驳回', 6: '已删除' });
 const readyState = 2;
@@ -16,7 +20,10 @@ function isNoAppResponse(response) {
   try { json = JSON.parse(response.body); } catch { return false; }
   if (!json || typeof json !== 'object') return false;
   const source = json.gw_err_resp && typeof json.gw_err_resp === 'object' ? json.gw_err_resp : json;
-  return String(source.code ?? source.err_code) === noAppCode;
+  const code = String(source.code ?? source.err_code);
+  if (code === noAppCode) return true;
+  const message = source.err_msg ?? source.message ?? source.msg;
+  return code === noAppGatewayCode && typeof message === 'string' && message.includes(noAppMessage);
 }
 
 const stateText = app => (app ? `应用 ${app.appId} ${appStates[app.appState] || `状态 ${app.appState}`}` : '应用尚未生成');