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

package/src/commands/system/api.js

@@ -32,7 +32,7 @@ function createApiCommand() {
     .option('--yes', '确认本次请求的未知副作用并发送')
     .addHelpText('after', `
 目标可以是已登记或未登记的 API，不接收任意 URL。
-默认先使用 auth login 保存的个人凭证；受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证。
+默认优先使用 auth login 保存的个人凭证；无个人记录时使用环境token。明确使用环境身份配置 ZAN_SAAS_AUTH_SOURCE=env。
 发送须 --yes，仅确认未知副作用，不证明服务端授权。
 退出0、HTTP 2xx 和 sent=true 只说明收到响应，不证明业务成功、异步完成或写入完成。
 body 是脱敏后的原始文本；即使 HTTP 200 正文含 success=false，也不按业务失败改变退出码。

package/src/commands/system/auth.js

@@ -19,23 +19,33 @@ function localTime(iso) {
 }
 
 const cloudAccountHint = '有赞云账号开通未确认，不影响本次个人登录。请先核对账号接口状态。';
+function credentialLine(value) {
+  if (value.credentialSource === 'login') {
+    return `默认使用个人登录凭证${value.environmentTokenIgnored ? '，已忽略环境 token' : ''}。`;
+  }
+  if (value.credentialSource === 'env') return '本次配置使用环境 token；个人登录状态与环境凭证有效性分别判断。';
+  return value.credentialSource === 'missing' ? '当前没有选中的请求凭证。' : '';
+}
 
 const text = {
   login: value => {
     const lines = [value.refreshExpiresAt
       ? `登录成功，凭证有效期至 ${localTime(value.refreshExpiresAt)}。` : '登录成功。'];
     if (value.cloudAccount?.ensured === false) lines.push(cloudAccountHint);
+    if (credentialLine(value)) lines.push(credentialLine(value));
     lines.push(value.shopId ? `当前店铺上下文：kdtId ${value.shopId}。` : '当前没有有效的店铺上下文。',
       shopSelectionHint);
     return lines.join('\n');
   },
   status: value => {
-    if (!value.loggedIn) return `未登录（${value.server}）。执行 zan-saas auth login 登录。`;
+    if (!value.loggedIn) return `未登录（${value.server}）。执行 zan-saas auth login 登录。` +
+      (credentialLine(value) ? `\n${credentialLine(value)}` : '');
     const lines = [`已登录（${value.server}）`];
     if (value.loginAt) lines.push(`登录时间：${localTime(value.loginAt)}`);
     if (value.refreshExpiresAt) lines.push(`有效期至：${localTime(value.refreshExpiresAt)}`);
     if (value.shopId) lines.push(`当前店铺：${value.shopId}`);
     else lines.push('当前没有有效的店铺上下文。');
+    if (credentialLine(value)) lines.push(credentialLine(value));
     lines.push(shopSelectionHint);
     return lines.join('\n');
   },
@@ -83,7 +93,8 @@ function createAuthCommand(impl = defaults) {
 --no-browser 只跳过自动打开浏览器，仍等待授权回调并保存个人凭证，默认超时5分钟。
 人机交接：Agent 启动命令并把输出的登录地址交给用户；用户在浏览器确认后，Agent 等待本命令回调，再执行 zan-saas auth status 确认。用户取消或超时后重新执行本命令。
 登录成功后执行 zan-saas shop current 查看当前店铺。
-首次选店或需要切店时，先执行 zan-saas shop list，由用户选定 kdtId，再执行 zan-saas shop use <kdtId>。
+宿主会话首次使用执行 shop session init，恢复时加 --resume；账号选店、连锁组织切换及本次临时查询按共享指引分别处理。
+默认优先使用已保存的个人凭证；仅受控调用明确配置 ZAN_SAAS_AUTH_SOURCE=env 时使用环境 token。
 执行 zan-saas shop current 确认实际生效的店铺，再开始业务查询；切店无需重新登录。
 登录后尝试开通有赞云账号，未确认开通时不影响本次个人登录，应核对账号接口状态。
 浏览器授权完成后仍须成功换取并保存凭证；本命令失败时停止，不进入选店或业务查询。

package/src/commands/system/contracts.js

@@ -2,6 +2,7 @@
 
 const { attachCommandSchema } = require('../../execution/command-schema');
 const { parserErrorModel } = require('../../execution/parser-error');
+const shopModels = require('./shop-contracts');
 
 function object(properties, required = Object.keys(properties)) {
   return { type: 'object', additionalProperties: false, required, properties };
@@ -83,9 +84,11 @@ const skill = object({
 const serverField = { type: 'string', description: '授权服务地址的 origin，默认生产环境，ZAN_SAAS_OAUTH_BASE_URL 可覆盖；凭证按它分开保存。' };
 const time = { type: ['string', 'null'], description: 'ISO 8601 时间，服务端未返回有效期时为 null。' };
 const credentialStatus = object({
-  loggedIn: { type: 'boolean', description: '本机保存个人凭证且已知刷新有效期未到期；未知有效期时保留已有登录记录。不表示环境覆盖凭证或服务端权限有效。' },
+  loggedIn: { type: 'boolean', description: '本机个人登录未标记需要重新登录，且已知刷新有效期未到期；未知有效期时保留已有记录。不表示环境token或服务端权限有效。' },
   server: serverField,
-  clientId: text, tool: text, loginAt: time, accessExpiresAt: time, refreshExpiresAt: time
+  clientId: text, tool: text, loginAt: time, accessExpiresAt: time, refreshExpiresAt: time,
+  credentialSource: { enum: ['login', 'env', 'missing'], description: '按当前配置选中的凭证来源：个人登录、环境token或缺失。离线状态不证明服务端有效。' },
+  environmentTokenIgnored: { type: 'boolean', description: '已选个人登录且同时存在环境token时为true；环境token不会覆盖该登录。' }
 }, ['loggedIn', 'server']);
 const shopIdField = {
   type: ['string', 'null'], description: '业务命令当前使用的店铺 ID；没有有效上下文时为 null。'
@@ -108,7 +111,7 @@ const savedShop = object({
   context: { $ref: '#/definitions/context' }, shopName: { type: ['string', 'null'] }
 });
 const accountNote = '调用账号接口网关，不需要店铺；默认生产环境，ZAN_SAAS_ACCOUNT_API_BASE_URL 可覆盖，token 规则与业务命令相同。';
-const contextNote = '上下文优先级：环境变量 ZAN_SAAS_CONTEXT（即使无效）高于 shop use 保存的店铺；按授权服务地址分开保存。';
+const contextNote = '上下文优先级：显式程序注入、ZAN_SAAS_CONTEXT、宿主会话保存位置；无会话ID时使用本机共享选择。无效显式输入不回退。';
 
 const contracts = {
   install: {
@@ -214,7 +217,7 @@ const contracts = {
       'token 写入 ~/.zan-saas/credentials.json（权限 0600），按授权服务地址分开保存；输出不含 token。',
       '用户取消或超时（5 分钟）时失败退出，不自动重试。',
       '登录后用短超时尝试开通有赞云账号，未确认时只记录 ensured: false，不因此要求重新登录。',
-      '登录成功后用 shop current 查看当前店铺；首次选店或切换时用 shop list 查候选，按用户选择执行 shop use <kdtId>，再用 shop current 核对实际生效的上下文。',
+      '登录成功后按宿主生命周期初始化或恢复会话，再用 shop current 查看实际位置。账号选店、连锁内切换和临时目标分别读取 shop use、shop unit use、shop resolve 契约。',
       '浏览器授权完成不代表本命令成功；换取凭证失败时未保存新凭证，停止后续选店和业务请求，按错误核查版本、配置及授权服务路由。'
     ]
   },
@@ -232,8 +235,9 @@ const contracts = {
         server: serverField,
         localCredential: { enum: ['deleted', 'delete_failed'],
           description: 'deleted 表示当前个人凭证已在本机清除或已不存在；delete_failed 表示本地清理未成功。' },
-        remoteRevocation: { enum: ['revoked', 'failed', 'unknown'],
-          description: 'revoked 已取得撤销成功响应；failed 撤销接口返回失败，不推断会话仍有效；unknown 请求或响应未能确认。' },
+        remoteRevocation: { enum: ['revoked', 'failed', 'unknown', 'not_attempted'],
+          description: 'revoked 已确认撤销；failed 接口拒绝；unknown 无法确认结果；not_attempted 表示没有个人凭证可撤销。' },
+        localContext: { enum: ['delete_failed'], description: '选店记录清理失败时出现；凭证清理与远端撤销仍已分别尝试。' },
         httpStatus: { type: 'integer', minimum: 100, maximum: 599,
           description: '仅取得撤销接口失败 HTTP 响应时出现，不回显响应正文。' }
       }, ['command', 'server', 'localCredential', 'remoteRevocation'])
@@ -295,17 +299,17 @@ const contracts = {
     ]
   },
   'shop.use': {
-    input: object({ kdtId: id }),
-    output: object({
+    input: object({ kdtId: id, sessionOnly: { type: 'boolean', description: '只更新本会话，不更新最近位置；需要会话ID。' } }, ['kdtId']),
+    output: { oneOf: [object({
       context: { $ref: '#/definitions/context' }, shopName: { type: ['string', 'null'] },
       overriddenByEnv: { type: 'boolean', description: '为 true 时 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。' }
-    }),
+    }), shopModels.chosenOutput('use_root')] },
     definitions: { context },
     notes: [
       accountNote,
       '先查询当前用户，再在其店铺列表中确认该店铺，只接受总部或单店；hq 与 shopId 都取该店铺 ID。',
-      '当前用户在该店铺的员工账号已停用时拒绝；员工状态查询失败不阻止选择。',
-      '上下文写入 ~/.zan-saas/context.json（权限 0600），不含凭证；本地上下文不是权限证明，服务端仍校验。',
+      '当前用户在该店铺的员工账号已停用时拒绝。共享模式员工状态查询失败保留旧兼容行为；会话模式要求核实成功，失败不保存选择。',
+      '无会话ID时写入 ~/.zan-saas/context.json；会话模式独立保存并默认更新供新会话继承的位置。上下文不含凭证，不证明权限。',
       '首次选择与切换店铺均使用本命令，无需重新登录；保存后用 shop current 确认实际店铺，overriddenByEnv 为 true 时不能声称当前上下文已切换。',
       contextNote
     ]
@@ -313,19 +317,23 @@ const contracts = {
   'shop.current': {
     input: empty,
     output: object({
-      source: { enum: ['env', 'saved', 'missing'] },
+      source: { enum: ['env', 'saved', 'missing', 'program'] },
       status: { enum: ['ready', 'invalid', 'missing'] },
       context: nullableContext,
       saved: { anyOf: [savedShop, { type: 'null' }] },
-      requestShopId: { type: ['string', 'null'], description: '环境变量 ZAN_SAAS_KDT_ID 的有效值；未设置或无效时为 null。不代表所有命令的最终请求店铺。' }
-    }),
+      requestShopId: { type: ['string', 'null'], description: '环境变量 ZAN_SAAS_KDT_ID 的有效值；未设置或无效时为 null。不代表所有命令的最终请求店铺。' },
+      binding: shopModels.binding,
+      selection: { anyOf: [shopModels.selection, { type: 'null' }] }
+    }, ['source', 'status', 'context', 'saved', 'requestShopId']),
     definitions: { context },
     notes: ['只读本地文件和环境变量，不联网。requestShopId 是环境变量值；部分命令按其目标店铺设置请求头，具体以命令契约为准。', contextNote]
   },
   'shop.clear': {
-    input: empty,
-    output: object({ cleared: { type: 'boolean', description: '本地有保存的店铺并已删除时为 true。' }, server: serverField }),
-    notes: ['只删除当前授权服务地址下保存的店铺，不联网，不影响 ZAN_SAAS_CONTEXT。']
+    input: object({ recent: { type: 'boolean', description: '同时清除该账号环境的最近位置；仅会话模式支持。' } }, []),
+    output: object({ cleared: { type: 'boolean', description: '已清除选中的店铺；重复清除为false。' }, server: serverField,
+      binding: shopModels.binding, currentChanged: { type: 'boolean' }, recentChanged: { type: 'boolean' } },
+    ['cleared', 'server']),
+    notes: ['会话模式保留cleared记录，避免重新继承；默认不影响其他会话或最近位置。原文件内改写，不删除或替换上下文文件。']
   },
   'skills.list': {
     input: empty,
@@ -356,7 +364,7 @@ const contracts = {
     }),
     notes: [
       '按明确的 API 名和版本发送 POST，可以是已登记或未登记的接口。风险未知，发送需 --yes；不继承领域命令的对象校验、风险分级和业务结果保证。',
-      '默认发送到生产开放 API 网关，ZAN_SAAS_API_BASE_URL 可覆盖；默认使用 auth login 保存的凭证，受控环境配置 ZAN_SAAS_USER_ACCESS_TOKEN 时使用环境凭证；不接受任意目标 URL。',
+      '默认发送到生产开放 API 网关，ZAN_SAAS_API_BASE_URL 可覆盖。默认优先使用已存个人登录，仅无个人记录时使用环境token；显式 ZAN_SAAS_AUTH_SOURCE=env 可选择环境凭证，不接受任意目标 URL。',
       '退出0、HTTP 2xx 和 sent=true 只表示收到响应；即使正文报告业务失败也不改变退出码，不证明业务成功或写入完成。超时或断连时结果未知，不自动重试。',
       '不提供 --dry-run，不自动应用业务金额或日期转换。'
     ]
@@ -364,7 +372,7 @@ const contracts = {
 };
 
 function withSystemSchema(command, name) {
-  const schema = { schemaVersion: 1, error, ...contracts[name] };
+  const schema = { schemaVersion: 1, error, ...(contracts[name] || shopModels.contracts[name]) };
   schema.error = { anyOf: [schema.error, structuredClone(parserErrorModel)] };
   attachCommandSchema(command, schema);
   return command;

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

@@ -0,0 +1,97 @@
+'use strict';
+
+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。' };
+const context = object({
+  userId: { type: 'string', minLength: 1, description: '已核实的账号 ID，不是客户或员工记录 ID。' },
+  hq: { ...id, description: '租户根组织 ID；单店取自身。' },
+  shopId: { ...id, description: '当前操作组织 ID，不自动代表全部连锁。' },
+  orgType: { enum: ['hq', 'shop'], description: '总部位置或受支持的非总部位置，不是详细组织角色。' }
+});
+const selection = object({
+  tenantRootKdtId: id, tenantName: nullableText, currentUnitKdtId: id, unitName: nullableText,
+  position: { enum: ['hq', 'shop'], description: '总部或非总部执行位置。' },
+  role: { type: ['integer', 'null'], minimum: 0, description: '有来源的组织角色：0单店、1总部、2001门店、2002网店；未知或未核实为null。' }
+});
+const binding = object({
+  mode: { enum: ['session', 'shared'], description: '宿主独立会话或本机共享选择。' },
+  sessionRef: { type: ['string', 'null'], description: '会话摘要短引用，共享模式为null。' },
+  state: { enum: ['uninitialized', 'needs_selection', 'ready', 'cleared', 'identity_pending', 'invalid'],
+    description: '分别为尚未初始化、待选店、就绪、已清除、待核实账号、无效。只有就绪的保存绑定提供上下文。' },
+  revision: { type: ['integer', 'null'], minimum: 1, maximum: Number.MAX_SAFE_INTEGER,
+    description: '绑定版本；无记录为null，冲突不覆盖较新选择。' },
+  origin: { enum: ['explicit', 'inherited', 'legacy_import', 'none'],
+    description: '明确选择、初始化继承、旧共享记录导入或无位置来源。' },
+  initializedAt: nullableText, selectedAt: nullableText
+});
+const nullable = value => ({ anyOf: [value, { type: 'null' }] });
+const effect = action => object({
+  action: { const: action },
+  currentChanged: { type: 'boolean', description: '本次是否改变当前会话绑定。' },
+  recentChanged: { type: 'boolean', description: '本次是否改变供新会话继承的位置。' }
+});
+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。' }
+};
+const optionalInput = properties => ({ ...object(properties), required: [] });
+const contracts = {
+  'shop.session.init': {
+    input: optionalInput({ resume: { type: 'boolean', description: '恢复原会话，缺记录则失败；省略为false。' } }),
+    output: chosenOutput('init'), notes: [...notes,
+      '显式初始化可核实当前账号并创建绑定。首次继承一次；无最近位置返回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, ...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, ...locationNotes, '不保存当前位置。把返回context固定为本次任务每次调用的显式上下文；任务结束后丢弃。']
+  }
+};
+
+module.exports = { binding, selection, chosenOutput, contracts };

package/src/commands/system/shop.js

@@ -10,12 +10,31 @@ const {
 const { withSystemSchema } = require('./contracts');
 const { createPrinter, formatOption } = require('./printer');
 const { shopSelectionHint } = require('./shop-guidance');
+const sessions = require('../../identity/session-store');
+const locations = require('../../identity/shop-location');
+const { snapshotApiIdentity } = require('../../transport/api');
+const { withFileLock } = require('../../auth/credential-store');
 
 const idPattern = /^[1-9]\d*$/;
-const orgLabels = { hq: '总部', shop: '单店' };
+const orgLabels = { hq: '总部', shop: '非总部组织' };
 const roleLabel = role => account.shopRoles[role] || '未知类型';
 const envNote = '环境变量 ZAN_SAAS_CONTEXT 已设置，业务命令仍以它为准。';
 
+function sharedResult(value, savedEntry) {
+  const context = value.context;
+  const same = context && savedEntry && ['userId', 'hq', 'shopId', 'orgType']
+    .every(field => context[field] === savedEntry.context[field]);
+  return { ...value,
+    binding: { mode: 'shared', sessionRef: null, state: savedEntry ? 'ready' : 'needs_selection',
+      revision: null, origin: savedEntry ? 'explicit' : 'none',
+      initializedAt: null, selectedAt: savedEntry?.savedAt ?? null },
+    selection: context ? locations.selection(context, {
+      tenantName: same && context.hq === context.shopId ? savedEntry.shopName : null,
+      unitName: same ? savedEntry.shopName : null
+    }) : null
+  };
+}
+
 function positiveInteger(name, max = Number.MAX_SAFE_INTEGER) {
   return value => {
     if (!idPattern.test(value) || Number(value) > max) {
@@ -65,10 +84,11 @@ async function checkStaffStatuses(items, env, concurrency = 5) {
 // Hides the shops where the user's staff account is disabled, unless --all; total stays the server's count.
 async function listShops(options = {}, env = process.env) {
   const name = typeof options.name === 'string' ? options.name.trim() : '';
+  const { environment } = await snapshotApiIdentity(env);
   const page = await account.listShops({
     ...(name ? { name } : {}), pageNum: options.pageNo ?? 1, pageSize: options.pageSize ?? 20,
     lineOfBusinesses: options.lineOfBusiness ?? account.defaultLineOfBusinesses
-  }, env);
+  }, environment);
   // Staff filtering may hide the entire page; only the server's unfiltered total determines continuation.
   const hasMore = page.total === null ? null :
     BigInt(page.pageNum) * BigInt(page.pageSize) < BigInt(page.total);
@@ -77,7 +97,7 @@ async function listShops(options = {}, env = process.env) {
     windowLimitReached: hasMore !== false && page.pageNum === Number.MAX_SAFE_INTEGER });
   if (options.all) return { ...page, totalScope: 'before_staff_filter', hidden: 0,
     hiddenReason: null, nextStep: null, unchecked: [], uncheckedReason: null };
-  const checks = await checkStaffStatuses(page.items, env);
+  const checks = await checkStaffStatuses(page.items, environment);
   const items = page.items.filter((_, index) => checks[index].status !== account.staffStatuses.disabled);
   const unchecked = page.items.filter((_, index) => checks[index].error).map(item => item.kdtId);
   const failed = checks.find(check => check.error);
@@ -92,12 +112,15 @@ async function listShops(options = {}, env = process.env) {
 }
 
 // Confirms the shop through the user's own shop list before saving it as the context.
-async function useShop(kdtId, env = process.env) {
+async function useShop(kdtId, env = process.env, options = {}, explicitContext) {
+  if (sessions.sessionId(env)) return locations.select(kdtId, options, env, explicitContext);
+  if (options.sessionOnly) throw sessions.fail('session_missing', '--session-only 需要宿主会话标识。');
   if (typeof kdtId !== 'string' || !idPattern.test(kdtId) || !Number.isSafeInteger(Number(kdtId))) {
     throw new Error('kdtId 必须是正整数店铺 ID。');
   }
-  const user = await account.whoami(env);
-  const page = await account.listShops({ includeKdtIds: [kdtId], pageNum: 1, pageSize: 1 }, env);
+  const actor = await locations.identify(env);
+  const user = actor.user;
+  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 查看可选店铺。`);
@@ -106,28 +129,54 @@ async function useShop(kdtId, env = process.env) {
     throw new Error(`店铺 ${kdtId} 是${roleLabel(shop.shopRole)}，暂时只能选择总部或单店。`);
   }
   // A failed check does not block: the business gateway still verifies the user against the shop.
-  const status = await account.staffStatus(kdtId, env).catch(() => null);
+  const status = await account.staffStatus(kdtId, actor.pinned).catch(() => null);
   if (status === account.staffStatuses.disabled) {
     throw new Error(`你在店铺 ${kdtId} 的员工账号已停用，不能选择。`);
   }
-  const context = saveContext({ userId: user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType },
-    { shopName: shop.shopName }, env);
+  const context = await withFileLock(env, async () => {
+    locations.assertIdentity(actor, env);
+    return saveContext({ userId: user.userId, hq: kdtId, shopId: kdtId, orgType: shop.orgType },
+      { shopName: shop.shopName }, env);
+  });
   return { context, shopName: shop.shopName, overriddenByEnv: Boolean(env.ZAN_SAAS_CONTEXT) };
 }
 
-function currentShop(env = process.env) {
+function currentShop(env = process.env, explicitContext) {
+  if (sessions.sessionId(env)) {
+    const snapshot = sessions.snapshot(env);
+    const location = snapshot.binding?.location;
+    const saved = location ? { context: location.context, shopName: locations.displayName(location) } : null;
+    const source = explicitContext !== undefined ? 'program' :
+      env.ZAN_SAAS_CONTEXT ? 'env' : saved ? 'saved' : 'missing';
+    const state = readContext(source === 'program' ? explicitContext :
+      source === 'env' ? env.ZAN_SAAS_CONTEXT : location?.context);
+    const context = state.context ?? null;
+    return { source, status: state.status, context, saved, requestShopId: requestShopIdOf(env),
+      binding: sessions.publicBinding(snapshot),
+      selection: context ? (location && ['userId', 'hq', 'shopId', 'orgType']
+        .every(field => context[field] === location.context[field])
+        ? location.selection : locations.selection(context)) : null };
+  }
   const savedEntry = readSavedContext(env);
   const saved = savedEntry ? { context: savedEntry.context, shopName: savedEntry.shopName } : null;
   const requestShopId = requestShopIdOf(env);
-  if (env.ZAN_SAAS_CONTEXT) {
-    const state = readContext(env.ZAN_SAAS_CONTEXT);
-    return { source: 'env', status: state.status, context: state.context ?? null, saved, requestShopId };
+  if (explicitContext !== undefined || env.ZAN_SAAS_CONTEXT) {
+    const state = readContext(explicitContext !== undefined ? explicitContext : env.ZAN_SAAS_CONTEXT);
+    return sharedResult({ source: explicitContext !== undefined ? 'program' : 'env',
+      status: state.status, context: state.context ?? null, saved, requestShopId }, savedEntry);
   }
-  return saved ? { source: 'saved', status: 'ready', context: saved.context, saved, requestShopId } :
-    { source: 'missing', status: 'missing', context: null, saved: null, requestShopId };
+  return sharedResult(saved ? { source: 'saved', status: 'ready', context: saved.context, saved, requestShopId } :
+    { source: 'missing', status: 'missing', context: null, saved: null, requestShopId }, savedEntry);
 }
 
-function clearShop(env = process.env) {
+function clearShop(env = process.env, options = {}, explicitContext) {
+  if (sessions.sessionId(env)) {
+    locations.rejectOverride(env, explicitContext);
+    const effect = sessions.clear(options, env);
+    return { ...effect, server: oauthConfig(env).server,
+      binding: sessions.publicBinding(sessions.snapshot(env)) };
+  }
+  if (options.recent) throw sessions.fail('session_missing', '--recent 需要宿主会话标识。');
   return { cleared: deleteContext(env), server: oauthConfig(env).server };
 }
 
@@ -154,42 +203,71 @@ const text = {
     if (value.items.some(item => item.orgType)) lines.push(shopSelectionHint);
     return lines.join('\n');
   },
-  use: value => `${value.overriddenByEnv ? '已保存店铺' : '已切换到店铺'} ${describe(value.context, value.shopName)}。` +
+  use: value => value.effect
+    ? `已切换到店铺 ${locations.displayName(value) || value.context.shopId}。\n` +
+      `${value.effect.recentChanged ? '已更新供新会话继承的位置。' : '其他会话保持各自位置。'}\n确认当前店铺：zan-saas shop current`
+    : `${value.overriddenByEnv ? '已保存店铺' : '已切换到店铺'} ${describe(value.context, value.shopName)}。` +
     (value.overriddenByEnv ? `\n${envNote}` : '') +
     '\n确认当前店铺：zan-saas shop current',
   current: value => {
+    if (value.binding?.mode === 'session') {
+      const name = value.selection && locations.displayName({ selection: value.selection });
+      const states = { uninitialized: '尚未初始化', identity_pending: '当前账号尚未核实',
+        needs_selection: '尚未选择店铺', cleared: '已清除选择', invalid: '记录无效', ready: '就绪' };
+      return `${value.context ? `当前店铺：${name || value.context.shopId}` : '当前没有有效店铺。'}\n` +
+        `会话状态：${states[value.binding.state]}；位置来源：${value.source}。` +
+        (value.source === 'env' || value.source === 'program' ? '\n显式上下文覆盖保存的位置。' : '') +
+        (value.requestShopId ? `\n请求店铺头覆盖：${value.requestShopId}，具体目标须按命令核验。` : '');
+    }
     const requestNote = value.requestShopId
       ? `\n环境变量 ZAN_SAAS_KDT_ID 设置为 ${value.requestShopId}；具体请求店铺以所用命令和目标参数为准。`
       : '';
-    if (value.source === 'env') {
+    if (value.source === 'env' || value.source === 'program') {
       const head = value.status === 'ready'
-        ? `当前上下文来自环境变量 ZAN_SAAS_CONTEXT（kdtId ${value.context.shopId}，${orgLabels[value.context.orgType]}）。`
+        ? `当前上下文来自${value.source === 'env' ? '环境变量 ZAN_SAAS_CONTEXT' : '程序注入'}（kdtId ${value.context.shopId}，${orgLabels[value.context.orgType]}）。`
         : '环境变量 ZAN_SAAS_CONTEXT 无效，业务命令会拒绝执行。';
       return `${value.saved ? `${head}\n已保存的店铺 ${describe(value.saved.context, value.saved.shopName)} 被它覆盖。` : head}${requestNote}`;
     }
     if (value.source === 'saved') {
-      return `当前店铺：${describe(value.context, value.saved.shopName)}${requestNote}\n${shopSelectionHint}`;
+      return `当前店铺：${describe(value.context, value.saved.shopName)}${requestNote}\n${shopSelectionHint}\n当前使用本机共享选店，其他会话切店可能影响后续调用。`;
     }
     return `未选择店铺。${requestNote}\n${shopSelectionHint}`;
   },
-  clear: value => (value.cleared ? '已清除保存的店铺。' : '没有保存的店铺。')
+  clear: value => (value.cleared ? '已清除保存的店铺。' : '没有保存的店铺。') +
+    (value.binding ? '\n本会话保留清除状态，不会自动继承最近位置。' : ''),
+  init: value => value.context
+    ? `本会话当前店铺：${locations.displayName(value) || value.context.shopId}。`
+    : '本会话已初始化，请明确选择店铺。',
+  resolve: value => `本次目标：${locations.displayName(value) || value.context.shopId}。\n当前位置和最近位置均未改变。`
 };
 const printer = createPrinter(text);
 
 const defaults = {
-  list: options => listShops(options), use: kdtId => useShop(kdtId), current: () => currentShop(),
-  clear: () => clearShop(), currentShopId: () => shopIdOf(process.env)
+  list: options => listShops(options), use: (kdtId, options) => useShop(kdtId, process.env, options),
+  current: () => currentShop(), clear: options => clearShop(process.env, options),
+  init: options => locations.initialize(options),
+  unit: (kdtId, options) => locations.select(kdtId, { ...options, unit: true }),
+  resolve: (kdtId, options) => locations.resolve(kdtId, options),
+  currentShopId: () => shopIdOf(process.env)
 };
 
-function createShopCommand(impl = defaults) {
+function createShopCommand(impl, { context } = {}) {
+  impl ||= { ...defaults,
+    use: (kdtId, options) => useShop(kdtId, process.env, options, context),
+    unit: (kdtId, options) => locations.select(kdtId, { ...options, unit: true }, process.env, context),
+    current: () => currentShop(process.env, context),
+    clear: options => clearShop(process.env, options, context) };
   const shop = new Command('shop').description('查看可用店铺并设置当前店铺')
     .addHelpText('after', `
-登录成功后，首次选店或切换店铺使用同一流程，无需重新登录：
+登录成功后查看当前位置，再按本次意图选路，无需重新登录：
+  会话首次使用：zan-saas shop session init；恢复时加 --resume
   1. 查看可选店铺：zan-saas shop list
   2. 用户选定目标后：zan-saas shop use <kdtId>
   3. 确认当前店铺：zan-saas shop current
 将 <kdtId> 替换为目标店铺 ID；店铺较多时可用 shop list --name <keyword> 查找。
 浏览器中切换店铺不会改变 CLI 保存的选择。
+连锁内切换组织：zan-saas shop unit use <kdtId>
+临时查询其他店铺：zan-saas shop resolve <kdtId>，使用返回的 context 执行本次任务。
 ZAN_SAAS_CONTEXT 会覆盖保存的店铺，切换后以 shop current 显示的实际来源为准。
 `);
   withSystemSchema(shop.command('list')
@@ -216,21 +294,44 @@ windowLimitReached 为 true 表示达到 CLI 可表示的页码上限，请缩
   withSystemSchema(shop.command('use')
     .description('选择当前用户的店铺并保存为上下文')
     .argument('<kdtId>', 'shop list 返回的总部或单店 kdtId')
+    .option('--session-only', '只改变本会话，不更新新会话继承的位置')
     .addOption(formatOption())
     .addHelpText('after', `
 先确认店铺属于当前账号，再把 userId、hq、shopId、orgType 保存到本地；业务命令随后用它选择店铺。
 已有有效上下文时沿用当前店铺；用户按店名明确选择且唯一匹配，或确认候选后，使用对应 kdtId 执行；本地上下文不是业务接口授权证明。
 环境变量 ZAN_SAAS_CONTEXT 设置时优先于保存的店铺。
 `)
-    .action(async (kdtId, options) => { printer('use', options.format)(await impl.use(kdtId)); }), 'shop.use');
+    .action(async (kdtId, options) => { printer('use', options.format)(await impl.use(kdtId, options)); }), 'shop.use');
   withSystemSchema(shop.command('current')
     .description('查看业务命令使用的店铺上下文，不访问网络')
     .addOption(formatOption())
     .action(options => { printer('current', options.format)(impl.current()); }), 'shop.current');
   withSystemSchema(shop.command('clear')
     .description('清除本机保存的店铺上下文，不访问网络')
+    .option('--recent', '同时清除供新会话继承的位置；需要会话模式')
+    .addOption(formatOption())
+    .action(options => { printer('clear', options.format)(impl.clear(options)); }), 'shop.clear');
+  const session = shop.command('session').description('初始化或恢复宿主会话的选店记录');
+  withSystemSchema(session.command('init')
+    .description('首次继承最近位置；已有会话保持自己的选择')
+    .option('--resume', '恢复原会话；记录缺失时失败，不重新继承')
+    .addOption(formatOption())
+    .action(async options => printer('init', options.format)(await impl.init(options))), 'shop.session.init');
+  const unit = shop.command('unit').description('切换当前连锁内的操作组织');
+  withSystemSchema(unit.command('use')
+    .description('保留当前连锁根，切换到已核实的门店、网店或总部')
+    .argument('<kdtId>', '当前连锁内目标组织的正整数 ID')
+    .option('--session-only', '只改变本会话，不更新新会话继承的位置')
+    .addOption(formatOption())
+    .action(async (kdtId, options) => printer('use', options.format)(await impl.unit(kdtId, options))),
+  'shop.unit.use');
+  withSystemSchema(shop.command('resolve')
+    .description('核实本次临时目标并返回上下文，不改变保存的位置')
+    .argument('<kdtId>', '目标店铺根或组织的正整数 ID')
+    .option('--root-kdt-id <id>', '目标所属连锁根 ID；省略时目标须为账号层根')
     .addOption(formatOption())
-    .action(options => { printer('clear', options.format)(impl.clear()); }), 'shop.clear');
+    .action(async (kdtId, options) => printer('resolve', options.format)(await impl.resolve(kdtId, options))),
+  'shop.resolve');
   return shop;
 }