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

package/skills/zan-saas-valuecard/references/transaction-list.md

@@ -0,0 +1,25 @@
+# 储值流水查询边界
+
+需要解释记录金额、关联单号或是否还能继续读取时，先读 `zan-saas schema valuecard.transaction.list`，再按本页判断。
+
+## 选对对象
+
+`zan-saas valuecard transaction list` 只读取目标店铺、一个业务类型、明确业务发生时间范围内的一页记录。它不按客户、卡号或订单筛选，不提供完整客户历史或自动余额对账。
+
+例如，假设用户问“这张卡现在还有多少本金”，应选择 `valuecard card get` 并提供完整系统卡号。若问“本店这段时间的充值流水里本金和赠送金各是多少”，选择流水入口，但一页数据不能解释为该时间内的完整合计。
+
+`billCardNo` 仅是流水记载的卡号，不保证与当前卡资产 `cardNo`、卡面号或汇总号相同。储值流水号、交易单号和外部支付请求号各自表示不同关联，不互相替代。手机号和昵称不作为稳定客户身份。
+
+## 解释金额和记录
+
+本金、赠送金及记录余额默认返回，具体字段与单位读同版 schema。`amount` 保留记录原始符号，不猜统一增减方向。`reportedBalance` 的时点未明确，不据此重建交易前后余额。
+
+充值与充值赠送、退款与充值退款分别表达。有效性不是支付或退款处理状态，无效记录仍保留。未知类型或有效性文本只表示服务端返回了该值，不能补造业务含义。
+
+## 范围与继续读取
+
+按同版 schema 的分页字段判断是否有后页，保持店铺、业务类型、原时间范围和容量。短页或空页不单独证明耗尽；总数未知时也不能把当前页当作完整历史。达到页窗口后缩小时间范围，不自动分片或跨页去重，不承诺稳定排序或快照。
+
+支持的产品范围由服务端决定。微商城单店、零售单店、连锁 D 总部及连锁 L 总部高级版在接口范围内；新储值商家可查询全部卡交易，老储值商家仅支持礼品卡交易。位置适用不授予跨店或员工权限，也不证明历史留存完整。
+
+请求失败或超限时本次不输出部分流水。核对原店铺、时间、分页和权限后重新构造调用，不切换身份或重复发送未知结果的请求。查询成功不代表关联业务已完成。

package/skills/zan-saas-valuecard/references/transaction-scan.md

@@ -0,0 +1,23 @@
+# 有界流水查找
+
+用于按一种业务类型、明确的北京时间范围，寻找带原始手机号、流水卡号、流水号或有赞交易单号的储值流水。先读 `zan-saas schema valuecard.transaction.scan`。四种条件至少一个，多条件为 AND，区分大小写，保留前导零与国家码。条件只在本地精确匹配，不是服务端客户筛选。
+
+例如，商家要找“某流水卡号在指定时间的消费”，使用 `billCardNo`，不能把当前 `card.cardNo` 或客户 `yzOpenId` 换进去。只知道系统卡号时先说明缺少原始流水标识，不能从客户当前持卡推断其历史流水归属。
+
+```sh
+zan-saas valuecard transaction scan --biz-type pay \
+  --occurred-at "2026-11-01 00:00:00..2026-11-11 12:00:00" \
+  --bill-card-no bill-card-demo --kdt-id 63077 --dry-run
+```
+
+实际调用需有效上下文与同店凭证。预览不读取凭证或联网，全部条件值遮盖。请求按页串行，固定最多 200 条匹配记录、21 次业务请求，包含一次店铺绑定。为完整页预留容量，可能不足 200 条即停止。不提供 `--max-items`、`--max-requests` 或其它调参入口。
+
+新储值商家可查全部卡交易，老储值商家仅支持礼品卡流水，不能据此宣称覆盖所有储值资产。
+
+读取 `data.transactions` 和 `data.pagination`，不把原始接口总数当成匹配总数。`scannedRecords` 包含未匹配记录。只有 `stopReason=pages_exhausted` 才表示从本次指定起始页之后走到可观察结束，不表示全历史。`max_items`、`max_requests`、`window_limit`、`total_unknown`、`inconsistent_page` 都表示未完成，匹配数组为空不能解释为没有历史。
+
+未完成且 `nextPageNo` 非空时，保持同店、业务类型、时间、全部条件和 `pageSize`，用 `--page-no` 继续。它不是稳定游标，数据变化可能重复或遗漏；`nextPageNo=null` 不能单独证明耗尽。窗口满时缩小时间范围重查，总数漂移时建议缩小范围从第一页重查。不自动拆分时间，不存在 dump/resume 或快照保证。
+
+结果保留无效记录、重复项及未知非空字典值。六个金额为 CNY 元两位字符串，保留源符号。`amount` 不是统一增减方向，`reportedBalance` 的时点未明确，不能用来推断交易前后余额、可支付余额或自动对账。时间为北京时间固定毫秒文本。`tradeNo` 是有赞交易单号，`externalRequestNo` 是外部支付请求号，不能互换。
+
+单响应最多 10 MiB、累计业务响应最多 20 MiB、最终输出含换行最多 5 MiB。后页业务、网络、模型或限额错误会整体失败，不返回前页匹配记录。失败先核查原店铺、条件与授权，不能自动重试、改店、改身份或把失败当成无记录。当前命令不承诺稳定排序；即使本次观察到时间最晚记录，也不能称客户全历史上次充值。

package/src/auth/credential-source.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { AuthConfigurationError } = require('./config');
+
+function authSource(env) {
+  const source = env.ZAN_SAAS_AUTH_SOURCE ?? 'auto';
+  if (!['auto', 'personal', 'env'].includes(source)) {
+    throw new AuthConfigurationError('ZAN_SAAS_AUTH_SOURCE 只接受 auto、personal 或 env。');
+  }
+  return source;
+}
+
+function credentialChoice(env, credential) {
+  const mode = authSource(env);
+  if (mode !== 'env' && credential) {
+    return { source: 'login', credentialRef: `login:${credential.generation || credential.loginAt || 'legacy'}` };
+  }
+  if (mode !== 'personal' && env.ZAN_SAAS_USER_ACCESS_TOKEN) {
+    const hash = createHash('sha256').update(env.ZAN_SAAS_USER_ACCESS_TOKEN).digest('hex');
+    return { source: 'env', credentialRef: `env:${hash}` };
+  }
+  return { source: 'missing', credentialRef: null };
+}
+
+module.exports = { authSource, credentialChoice };

package/src/auth/credential-store.js

@@ -3,7 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { configDir } = require('./config');
+const { configDir, AuthConfigurationError } = require('./config');
+const { credentialChoice } = require('./credential-source');
 
 const fileName = 'credentials.json';
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -53,16 +54,70 @@ const readAll = env => readStore(fileName, env);
 const writeAll = (data, env) => writeStore(fileName, data, env);
 
 // Credentials are keyed by oauth origin so logins to different environments do not overwrite each other.
+function credentialDocument(env) {
+  let data;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(credentialPath(env), 'r');
+    const stat = fs.fstatSync(descriptor);
+    data = JSON.parse(fs.readFileSync(descriptor, 'utf8'));
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error();
+    return { data, metadata: { mtimeMs: stat.mtimeMs, size: stat.size, ino: stat.ino, dev: stat.dev } };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { data: {}, metadata: null };
+    throw new AuthConfigurationError('个人凭证文件损坏或不可读，请重新登录；未改用环境身份。');
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
 function readCredential(server, env = process.env) {
-  const entry = readAll(env)[server];
-  return entry && typeof entry.accessToken === 'string' && typeof entry.refreshToken === 'string'
-    ? entry : null;
+  const { data } = credentialDocument(env);
+  if (!Object.hasOwn(data, server)) return null;
+  const entry = data[server];
+  if (!entry || typeof entry.accessToken !== 'string' || !entry.accessToken ||
+      typeof entry.refreshToken !== 'string' || !entry.refreshToken) {
+    throw new AuthConfigurationError('个人凭证记录不完整，请重新登录；未改用环境身份。');
+  }
+  return entry;
+}
+
+function syncCredentialPresence(env = process.env) {
+  const filename = 'credential-state.json';
+  const { data, metadata } = credentialDocument(env);
+  const records = Object.fromEntries(Object.entries(data).map(([server, credential]) => [server, {
+    present: true,
+    credentialRef: credential && typeof credential.accessToken === 'string' &&
+      typeof credential.refreshToken === 'string'
+      ? credentialChoice({ ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential).credentialRef : 'login:pending'
+  }]));
+  const next = { schemaVersion: 1, metadata, records };
+  if (JSON.stringify(readStore(filename, env)) === JSON.stringify(next)) return;
+  writeStore(filename, next, env);
+}
+
+// Offline context selection reads only this non-secret index and file metadata.
+function credentialPresence(server, env = process.env) {
+  const stat = fs.existsSync(credentialPath(env)) ? fs.statSync(credentialPath(env)) : null;
+  if (!stat) return { present: false, credentialRef: null };
+  const index = readStore('credential-state.json', env);
+  const metadata = index.metadata;
+  if (index.schemaVersion === 1 && metadata && metadata.mtimeMs === stat.mtimeMs &&
+      metadata.size === stat.size && metadata.ino === stat.ino && metadata.dev === stat.dev &&
+      index.records && typeof index.records === 'object' && !Array.isArray(index.records)) {
+    if (!Object.hasOwn(index.records, server)) return { present: false, credentialRef: null };
+    const entry = index.records[server];
+    if (entry?.present === true && typeof entry.credentialRef === 'string' &&
+        entry.credentialRef.startsWith('login:')) return entry;
+  }
+  return { present: true, credentialRef: 'login:pending' };
 }
 
 function saveCredential(server, credential, env = process.env) {
   const data = readAll(env);
   data[server] = credential;
   writeAll(data, env);
+  syncCredentialPresence(env);
 }
 
 function deleteCredential(server, env = process.env) {
@@ -70,6 +125,7 @@ function deleteCredential(server, env = process.env) {
   if (!Object.hasOwn(data, server)) return false;
   delete data[server];
   writeAll(data, env);
+  syncCredentialPresence(env);
   return true;
 }
 
@@ -105,5 +161,5 @@ async function withFileLock(env, task, { staleMs = 30000, waitMs = 15000 } = {})
 
 module.exports = {
   credentialPath, deleteCredential, readCredential, readStore, saveCredential, storePath, withFileLock,
-  writeStore
+  writeStore, credentialPresence, syncCredentialPresence
 };

package/src/auth/session.js

@@ -8,6 +8,8 @@ const { openBrowser } = require('./browser');
 const { OAuthError, exchangeCode, refreshTokens, revokeToken } = require('./oauth-client');
 const store = require('./credential-store');
 const { deleteContext } = require('../identity/context-store');
+const { randomUUID } = require('node:crypto');
+const { authSource, credentialChoice } = require('./credential-source');
 
 const dayMs = 24 * 60 * 60 * 1000;
 
@@ -29,7 +31,8 @@ function summary(server, credential, now = Date.now()) {
   if (!credential) return { loggedIn: false, server };
   const iso = value => (Number.isFinite(value) ? new Date(value).toISOString() : null);
   return {
-    loggedIn: Number.isFinite(credential.refreshExpiresAt) ? credential.refreshExpiresAt > now : true,
+    loggedIn: !credential.reauthRequired &&
+      (Number.isFinite(credential.refreshExpiresAt) ? credential.refreshExpiresAt > now : true),
     server,
     clientId: credential.clientId,
     tool: credential.tool,
@@ -43,6 +46,7 @@ async function login({
   env = process.env, browser = true, port = defaultPort, log = message => process.stderr.write(`${message}\n`),
   open = openBrowser, timeoutMs
 } = {}) {
+  authSource(env);
   const config = oauthConfig(env);
   const pkce = createPkce();
   const tool = detectTool(env);
@@ -72,38 +76,66 @@ async function login({
     throw error;
   }
   const credential = {
-    ...tokens, clientId: config.clientId, oauthBaseUrl: config.oauthBaseUrl, tool, loginAt: Date.now()
+    ...tokens, clientId: config.clientId, oauthBaseUrl: config.oauthBaseUrl, tool, loginAt: Date.now(),
+    generation: randomUUID()
   };
-  store.saveCredential(config.server, credential, env);
-  return summary(config.server, credential);
+  await store.withFileLock(env, async () => store.saveCredential(config.server, credential, env));
+  require('../identity/session-store').resetIdentity(env, {
+    pendingCredentialRef: credentialChoice({ ...env, ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential).credentialRef
+  });
+  return status({ env });
 }
 
 async function logout({ env = process.env } = {}) {
   const config = oauthConfig(env);
   const credential = store.readCredential(config.server, env);
-  // The selected shop belongs to this login, so it goes with it.
-  deleteContext(env);
-  if (!credential) return { loggedOut: true, revoked: false, server: config.server };
-  let remoteRevocation = 'revoked';
+  let localContext = 'deleted';
+  for (const clear of [
+    () => deleteContext(env),
+    () => require('../identity/session-store').resetIdentity(env, { logout: true })
+  ]) {
+    try { clear(); } catch { localContext = 'delete_failed'; }
+  }
+  if (!credential && localContext === 'deleted') return { loggedOut: true, revoked: false, server: config.server };
+  let remoteRevocation = credential ? 'revoked' : 'not_attempted';
   let httpStatus;
-  try {
-    await revokeToken(config, credential.refreshToken);
-  } catch (error) {
-    httpStatus = error instanceof OAuthError ? error.httpStatus : undefined;
-    remoteRevocation = httpStatus === undefined ? 'unknown' : 'failed';
+  if (credential) {
+    try {
+      await revokeToken(config, credential.refreshToken);
+    } catch (error) {
+      httpStatus = error instanceof OAuthError ? error.httpStatus : undefined;
+      remoteRevocation = httpStatus === undefined ? 'unknown' : 'failed';
+    }
   }
   let localCredential = 'deleted';
+  let loginChanged = false;
   try {
-    store.deleteCredential(config.server, env);
+    await store.withFileLock(env, async () => {
+      const current = store.readCredential(config.server, env);
+      const sameLogin = !current || (credential?.generation
+        ? current.generation === credential.generation
+        : current.loginAt === credential?.loginAt && current.refreshToken === credential?.refreshToken);
+      if (!sameLogin) {
+        loginChanged = true;
+        throw new Error('The current login changed during logout');
+      }
+      store.deleteCredential(config.server, env);
+    });
   } catch {
     localCredential = 'delete_failed';
   }
-  if (remoteRevocation !== 'revoked' || localCredential !== 'deleted') {
-    const error = new Error(localCredential === 'deleted'
+  if (!['revoked', 'not_attempted'].includes(remoteRevocation) ||
+      localCredential !== 'deleted' || localContext !== 'deleted') {
+    const error = new Error(loginChanged
+      ? '退出期间已产生新登录，已保留新凭证；旧凭证的服务端撤销结果请按退出信息核对。'
+      : localContext !== 'deleted'
+      ? '选店记录清理未完成；本机凭证清理与服务端撤销已分别尝试，请按退出结果核对。'
+      : localCredential === 'deleted'
       ? '本机个人凭证已清除，服务端会话撤销未确认；请核对授权服务状态。'
       : '本机个人凭证清理失败；请按退出结果核对本地凭证与服务端会话。');
     error.cliDetails = {
       command: 'auth.logout', server: config.server, localCredential, remoteRevocation,
+      ...(localContext === 'deleted' ? {} : { localContext }),
       ...(httpStatus === undefined ? {} : { httpStatus })
     };
     throw error;
@@ -113,7 +145,10 @@ async function logout({ env = process.env } = {}) {
 
 function status({ env = process.env } = {}) {
   const { server } = oauthConfig(env);
-  return summary(server, store.readCredential(server, env));
+  const credential = store.readCredential(server, env);
+  const choice = credentialChoice(env, credential);
+  return { ...summary(server, credential), credentialSource: choice.source,
+    environmentTokenIgnored: choice.source === 'login' && Boolean(env.ZAN_SAAS_USER_ACCESS_TOKEN) };
 }
 
 function interactive(env) {
@@ -127,17 +162,24 @@ async function refreshIfNeeded(config, env, now) {
     // Another process may have refreshed while this one waited for the lock.
     const credential = store.readCredential(key, env);
     if (!credential) return null;
-    if (!(credential.accessExpiresAt - now < dayMs)) return credential;
-    if (credential.refreshExpiresAt <= now) {
-      store.deleteCredential(key, env);
+    if (credential.reauthRequired || credential.refreshExpiresAt <= now) {
       return null;
     }
+    if (!(credential.accessExpiresAt - now < dayMs)) return credential;
+    const assertUnchanged = () => {
+      const current = store.readCredential(key, env);
+      if (!current || current.generation !== credential.generation ||
+          current.refreshToken !== credential.refreshToken) {
+        throw new AuthRequiredError('个人登录在续期期间改变，请核对当前身份后重试；未改用环境身份。');
+      }
+    };
     let tokens;
     try {
       tokens = await refreshTokens(config, credential.refreshToken);
     } catch (error) {
       if (error instanceof OAuthError && error.oauthError === 'invalid_grant') {
-        store.deleteCredential(key, env);
+        assertUnchanged();
+        store.saveCredential(key, { ...credential, reauthRequired: true }, env);
         return null;
       }
       // Keep using an access token that has not expired yet when refresh is unreachable.
@@ -145,20 +187,29 @@ async function refreshIfNeeded(config, env, now) {
       throw error;
     }
     const next = { ...credential, ...tokens };
+    assertUnchanged();
     store.saveCredential(key, next, env);
     return next;
   });
 }
 
-// Resolves the user token for one request. An explicit ZAN_SAAS_USER_ACCESS_TOKEN keeps priority so
-// existing controlled environments behave as before.
+// Select once before a request; a failed personal login never changes to another identity.
 async function resolveAccessToken(env = process.env, { now = Date.now(), loginImpl = login } = {}) {
-  if (env.ZAN_SAAS_USER_ACCESS_TOKEN) {
-    return { token: env.ZAN_SAAS_USER_ACCESS_TOKEN, source: 'env' };
+  const mode = authSource(env);
+  if (mode === 'env') {
+    if (!env.ZAN_SAAS_USER_ACCESS_TOKEN) throw new AuthRequiredError('环境凭证模式缺少 ZAN_SAAS_USER_ACCESS_TOKEN。');
+    return Object.freeze({ token: env.ZAN_SAAS_USER_ACCESS_TOKEN, ...credentialChoice(env) });
   }
   const config = oauthConfig(env);
   let credential = store.readCredential(config.server, env);
-  if (credential && Number.isFinite(credential.accessExpiresAt) &&
+  const choice = credentialChoice(env, credential);
+  if (choice.source === 'env') {
+    store.syncCredentialPresence(env);
+    return Object.freeze({ token: env.ZAN_SAAS_USER_ACCESS_TOKEN, ...choice });
+  }
+  if (credential?.reauthRequired || credential?.refreshExpiresAt <= now) {
+    credential = null;
+  } else if (credential && Number.isFinite(credential.accessExpiresAt) &&
       credential.accessExpiresAt - now < dayMs) {
     credential = await refreshIfNeeded(config, env, now);
   }
@@ -170,7 +221,9 @@ async function resolveAccessToken(env = process.env, { now = Date.now(), loginIm
     credential = store.readCredential(config.server, env);
     if (!credential) throw new AuthRequiredError('Login did not produce a credential');
   }
-  return { token: credential.accessToken, source: 'login' };
+  store.syncCredentialPresence(env);
+  return Object.freeze({ token: credential.accessToken, ...credentialChoice(
+    { ...env, ZAN_SAAS_AUTH_SOURCE: 'personal' }, credential) });
 }
 
 module.exports = {

package/src/cli/command-paths.js

@@ -101,12 +101,13 @@ function commandContract(path, command) {
   if (['schema', 'doctor', 'skills.list', 'skills.read'].includes(path)) {
     return { kind: 'system', risk: 'read', availability: 'available' };
   }
-  if (['auth.status', 'auth.whoami', 'shop.list', 'shop.current'].includes(path)) {
+  if (['auth.status', 'auth.whoami', 'shop.list', 'shop.current', 'shop.resolve'].includes(path)) {
     return { kind: 'system', risk: 'read', availability: 'available' };
   }
   // Login and logout change the local credential and the server-side session; shop use and clear
   // change the saved context.
-  if (['install', 'auth.login', 'auth.logout', 'shop.use', 'shop.clear'].includes(path)) {
+  if (['install', 'auth.login', 'auth.logout', 'shop.use', 'shop.clear',
+    'shop.session.init', 'shop.unit.use'].includes(path)) {
     return { kind: 'system', risk: 'low', availability: 'available' };
   }
   if (path === 'api') return { kind: 'raw-api', risk: 'unknown', availability: 'available' };

package/src/cli/context-help.js

@@ -60,7 +60,9 @@ function configureContextHelp(program, state, loadDomain) {
     }
     const status = `当前位置：${positionLabels[state.context.orgType]}；实际权限由服务端校验。`;
     if (contract) {
-      return `\n${declared}${status}\n${isAvailable(contract.at, state.context)
+      const scopeHint = state.context.orgType === 'hq' && command.options.some(option => option.long === '--kdt-id')
+        ? '\n省略 --kdt-id 只查询当前总部本身，不包含分店。显式分店目标是否支持及核验前置，以本命令 help/schema 为准。' : '';
+      return `\n${declared}${status}${scopeHint}\n${isAvailable(contract.at, state.context)
         ? '此命令适用于当前位置。'
         : `当前组织不可使用此命令，需要${positionLabels[contract.at]}上下文。`}`;
     }

package/src/cli/program.js

@@ -22,9 +22,16 @@ const { commandSchema } = require('../execution/command-schema');
 const { commandContract, commandPath } = require('./command-paths');
 const { configureContextHelp, isContextHelp } = require('./context-help');
 const { configureParserPolicy } = require('./parser-policy');
+const { bindApiContext, runWithApiSession } = require('../transport/api');
 
-function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills = skillsRoot,
-  eagerDomains = false, context = contextInput(process.env) } = {}) {
+function createProgram(settings = {}) {
+  const { catalog = openRegistry(), root = nativeRoot, rootSkills = skillsRoot,
+    eagerDomains = false } = settings;
+  const injected = settings.context !== undefined;
+  let context;
+  let contextError;
+  try { context = injected ? settings.context : contextInput(process.env); }
+  catch (error) { contextError = error; context = {}; }
   const { domains, skills, businessCommandCount } = catalog.manifest;
   const domainNames = new Set(domains.map(domain => domain.name));
   const loadedDomains = new Set();
@@ -62,7 +69,7 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   program.addCommand(createDoctorCommand(businessCommandCount));
   program.addCommand(createApiCommand());
   program.addCommand(createAuthCommand());
-  program.addCommand(createShopCommand());
+  program.addCommand(createShopCommand(undefined, { context: injected ? context : undefined }));
   program.addCommand(createSkillsCommand(skills, rootSkills));
   program.addCommand(createInstallCommand());
   function configureSystemErrors(command) {
@@ -83,6 +90,11 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   program.hook('preAction', (_parent, command) => {
     if (isContextHelp(command)) return;
     const contract = commandContract(commandPath(command), command);
+    if ((['atomic', 'task'].includes(contract.kind) && !command.opts().dryRun) ||
+        contract.kind === 'raw-api') {
+      if (contextError) throw contextError;
+      bindApiContext(contextState.context);
+    }
     if (['atomic', 'task'].includes(contract.kind)) {
       const details = commandSchema(command)?.error?.properties?.details;
       const stages = details?.properties?.stage?.enum;
@@ -112,7 +124,7 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
 快速开始：
   1. 登录：zan-saas auth login，按提示在浏览器完成授权
   2. 查看当前店铺：zan-saas shop current；已有有效上下文时沿用
-  3. 需要选店时：zan-saas shop list，按用户指定的店名或选择执行 zan-saas shop use <kdtId>
+  3. 宿主会话先 shop session init；账号选店用 shop use，连锁内切换用 shop unit use，临时查询用 shop resolve
   4. 阅读使用指引：zan-saas skills read zan-saas
 
 查询命令：
@@ -128,6 +140,10 @@ function createProgram({ catalog = openRegistry(), root = nativeRoot, rootSkills
   if (eagerDomains) {
     for (const domain of domains) loadDomain(domain.name);
   }
+  const parseAsync = program.parseAsync;
+  program.parseAsync = function (...args) {
+    return runWithApiSession(() => parseAsync.apply(this, args));
+  };
   return program;
 }
 

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

@@ -9,7 +9,7 @@
       "availability": "available",
       "at": "all",
       "module": "access/role/list/command.js",
-      "fingerprint": "1f1a25bdb5f2252635920dd6f154e7692cefbe5c37bf5c164aff4c0c73a23313"
+      "fingerprint": "9e489554a22cd27edf3fc4c22fcf53dbb820b2f26b030bb558c1df6644c25c75"
     },
     {
       "path": "access.staff-perms.get",

package/src/commands/native/access/role/list/command.js

@@ -10,19 +10,13 @@ const { readApiEnvelope, assertApiSuccess, object } = require('../../../../../ex
 const { failure, bindingPath } = require('../../../../../execution/shop-query');
 const { snapshotApiEnvironment } = require('../../../../../transport/api');
 const schema = require('./schema.json');
+const { organizationPath, organizationBody, maxOrganizationPages,
+  verifyMembership } = require('../../../../../identity/unit-membership');
 
 const command = 'access.role.list';
-const organizationPath = 'youzan.shop.chain.descendent.organization.list/1.0.1';
-const maxOrganizationPages = 20;
-const pageSize = 50;
 const reject = (category, stage, scope, state, facts) =>
   failure(command, category, stage, scope, state, facts);
 
-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 };
-}
-
 function previewFor(input, context) {
   const crossShop = context && String(input.kdtId) !== context.shopId;
   const requests = [{ stage: 'shop-binding', method: 'POST', path: bindingPath, body: {} }];
@@ -34,29 +28,6 @@ function previewFor(input, context) {
   return { scope: input, requests, maxOrganizationPages };
 }
 
-async function verifyMembership(read, input) {
-  const seen = new Set();
-  let total;
-  for (let pageNo = 1; pageNo <= maxOrganizationPages; pageNo += 1) {
-    const { data, facts } = await read(organizationPath, organizationBody(pageNo), 'target-membership');
-    const invalid = category => reject(category, 'target-membership', input, '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);
-    }
-    if (seen.has(input.kdtId)) return;
-    if (seen.size === total || pageNo === maxOrganizationPages) throw invalid('scope_unresolved');
-  }
-}
-
 async function execute(input, context, preview) {
   let env;
   try { env = await snapshotApiEnvironment(undefined, context.shopId); }
@@ -79,7 +50,8 @@ async function execute(input, context, preview) {
     if (context.orgType !== 'hq' || String(binding.data.sid) !== context.hq || binding.data.role !== 1) {
       throw reject('scope_unresolved', 'shop-binding', input, 'sent', binding.facts);
     }
-    await verifyMembership(read, input);
+    await verifyMembership(read, input.kdtId,
+      (category, stage, state, facts) => reject(category, stage, input, state, facts));
   }
   const request = preview.requests.at(-1);
   const { data, facts } = await read(request.path, request.body, request.stage);

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

@@ -45,7 +45,7 @@
       "availability": "available",
       "at": "all",
       "module": "customer/customer-tag/list/command.js",
-      "fingerprint": "60e6f754b729a536d83aa3c01a5f0069a2bdb3d927129cdc4497e6f04cff2b47"
+      "fingerprint": "9847ca5a4011dc084d074f434c0cd4ad24633e12fe6f79395a1dfb173927bd0b"
     },
     {
       "path": "customer.segment.list",

package/src/commands/native/customer/customer-tag/list/command.js

@@ -3,7 +3,7 @@
 const { withTargetShopDefault } = require('../../../../../execution/target-shop-default');
 
 const { Command } = require('commander');
-const { requestApi, ApiConfigurationError } = require('../../../../../transport/api');
+const { requestApi, snapshotApiEnvironment, ApiConfigurationError } = require('../../../../../transport/api');
 const { validateCommandValue } = require('../../../../../execution/command-schema');
 const schema = require('./schema.json');
 
@@ -47,7 +47,7 @@ async function listCustomerTags(options, context) {
   }
   let response;
   try {
-    response = await requestApi(request);
+    response = await requestApi(request, await snapshotApiEnvironment(undefined, input.kdtId));
   } catch (error) {
     if (error instanceof ApiConfigurationError) throw failure('configuration', 'configuration');
     throw failure('transport', 'request', 'unknown');

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

@@ -36,7 +36,7 @@
       "availability": "available",
       "at": "all",
       "module": "member/level/get/command.js",
-      "fingerprint": "75de5b4aeab1b821d50cbb285011f9dfe06fbc94cecb0d74c98768ce8d74ac0a"
+      "fingerprint": "23c8774db6b4525aa8fc978babee0b64da63498f21a0e261f06fa63c7ffaa78d"
     },
     {
       "path": "member.level.list",

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

@@ -9,7 +9,7 @@
       "availability": "available",
       "at": "all",
       "module": "order/order/get/command.js",
-      "fingerprint": "f418c43687be1a520d4ec877e01c36b2d3f4231ae0413423655c1923ba749e5a"
+      "fingerprint": "8b15ec74ec9af89adb9f82ab504a36d9404ab186ad0d7f7e9159a3668d1a7ee7"
     },
     {
       "path": "order.order.list",
@@ -18,7 +18,7 @@
       "availability": "available",
       "at": "all",
       "module": "order/order/list/command.js",
-      "fingerprint": "e724052bb9918a03649b7d53188869d4279f871dc86428f32615da29c5378ae2"
+      "fingerprint": "ea68f35fc0bfe35168751b08ed46247e91a925b244642234770de0f12855907d"
     },
     {
       "path": "order.order.scan",
@@ -27,7 +27,7 @@
       "availability": "available",
       "at": "all",
       "module": "order/order/scan/command.js",
-      "fingerprint": "64e037283116df0e8862be7a01db999de0436c74dace75e688ec819f1adc026d"
+      "fingerprint": "ea25f05e8976c1f2e99e9b7e63fb35757c1b72a1298318dabc428f0ead3886fc"
     }
   ]
 }