@tbox.cn/app-module-member 0.2.0 → 0.8.6

package/src/server/tool.ts

@@ -1,71 +1,269 @@
-import { createTool, coerceStringifiedFields } from '@tbox.cn/app-sdk/server';
+import { createTool } from '@tbox.cn/app-sdk/server';
+import type { AnyTool, ToolExecContextLike } from '@tbox.cn/app-sdk/server';
+import { requireToolRequestContext } from '@tbox.cn/app-sdk/server';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { MEMBER_PREFERENCE_PROMPTS } from '@tbox.cn/app-contracts-mall';
+import type { MemberAccountSnapshot, MemberCardPort } from '@tbox.cn/app-contracts-mall';
+import { classifyMemberOutcome, memberGateCardOf } from '@tbox.cn/app-contracts-mall';
+import {
+  MEMBER_LOGIN_NOTICE,
+  MEMBER_NOT_ENROLLED_NOTICE,
+  MEMBER_NO_POINTS_NOTICE,
+  MEMBER_UNKNOWN_NOTICE,
+} from './status';
 import { z } from 'zod';
-import type { MemberBenefitsPort, MemberAccountPort, MemberCardPort, MemberCouponPort } from '@tbox.cn/app-contracts-mall';
-import { nowIso } from './util';
 
-function coerce<T extends z.ZodTypeAny>(schema: T): T {
-  return z.preprocess(coerceStringifiedFields, schema) as unknown as T;
+/** 出卡出参组装（v2 契约）：顶层答话事实 + cards 声明（data = 事实本体，不含 cards 键） */
+function withCards<T extends Record<string, unknown>>(facts: T, cardType: string, note: string): T & { cards: unknown[] } {
+  return { ...facts, cards: [{ cardType, data: facts, note }] };
 }
 
-/** 积分查询工具（011 K3：出卡 member-point-usage-list——吸收教学 points 卡） */
-export function createQueryPointsTool(getMember: () => MemberBenefitsPort | undefined) {
+/** 会员账户态中文化（note 契约——note 是模型可见摘要，英文枚举态不可读） */
+export function memberStateLabel(state: string): string {
+  switch (state) {
+    case 'active':
+      return '已入会';
+    case 'not_enrolled':
+      return '未入会';
+    case 'closed':
+      return '已退会';
+    case 'unauthenticated':
+      return '未登录';
+    default:
+      return '状态确认中';
+  }
+}
+
+const MEMBER_CONTRACT_NOTICE =
+  '会员卡名不是会员等级；当前查询未返回会员权益，不得推断折扣、停车、生日或活动权益';
+
+export const MEMBER_PRIVACY_REFUSAL =
+  '出于会员隐私保护，我只能查询当前登录会员的信息，不能修改会员资料、代查他人账户，也不能通过手机号或会员卡号切换账户。';
+
+/**
+ * Code security: 查询语境中的外部账号标识只能用于拒答，绝不能成为会员资源定位条件。
+ * 保守拦截代查、切号和资料修改请求，正常的“我的会员/我的积分”查询不受影响。
+ */
+export function memberPrivacyRefusal(query: unknown): string | undefined {
+  if (typeof query !== 'string' || query.trim().length === 0) return undefined;
+  const content = query.replace(/\s+/g, '');
+  const profileMutation =
+    /(手机号|手机号码|联系方式).{0,12}(改|修改|更换|变更|替换|更新)|(改|修改|更换|变更|替换|更新).{0,12}(手机号|手机号码|联系方式)/.test(content);
+  const thirdPartyLookup =
+    /(老婆|老公|妻子|丈夫|他人|别人|朋友|同事|家人|孩子|女儿|儿子|妈妈|爸爸).{0,20}(手机号|手机号码|会员|积分|卡)/.test(content);
+  const suppliedIdentifierLookup =
+    /(用|通过|根据|拿着|拿).{0,20}(手机号|手机号码|会员卡号|卡号).{0,20}(查|查询|切|切换|登录|绑定)/.test(content) ||
+    /(切换|切到|换到|登录到|绑定到).{0,15}(账号|账户|会员卡|卡号|手机号|手机号码)/.test(content);
+  const explicitIdentifier = /(手机号|手机号码|会员卡号|卡号|账号|账户).{0,16}\d{5,}/.test(content);
+  return profileMutation || thirdPartyLookup || suppliedIdentifierLookup || explicitIdentifier
+    ? MEMBER_PRIVACY_REFUSAL
+    : undefined;
+}
+
+function hasCompleteMemberCard(card: MemberCardSnapshot | null): boolean {
+  return card?.presentation !== undefined;
+}
+
+function cardContractNotice(card: { benefits?: readonly unknown[] }): string {
+  return card.benefits && card.benefits.length > 0
+    ? '会员卡名不是会员等级；仅展示系统返回的当前等级权益，不得推断额外折扣或服务'
+    : MEMBER_CONTRACT_NOTICE;
+}
+
+type MemberCardSnapshot = NonNullable<Awaited<ReturnType<MemberCardPort['getCard']>>>;
+
+function buildMemberCardFacts(
+  userId: string,
+  card: MemberCardSnapshot,
+  availablePoints: number,
+  includePreferencePrompts = false,
+) {
+  return {
+    userId,
+    cardRef: card.cardRef,
+    cardDisplay: card.cardDisplay,
+    status: card.status,
+    ...(card.levelName ? { levelName: card.levelName } : {}),
+    availablePoints,
+    ...(card.cardImageUrl ? { cardImageUrl: card.cardImageUrl } : {}),
+    ...(card.pointsRuleImageUrl ? { pointsRuleImageUrl: card.pointsRuleImageUrl } : {}),
+    ...(card.pointsRuleContent ? { pointsRuleContent: card.pointsRuleContent } : {}),
+    ...(card.pointsUrl ? { pointsUrl: card.pointsUrl } : {}),
+    ...(card.presentation ? { presentation: card.presentation } : {}),
+    ...(card.progress ? { progress: card.progress } : {}),
+    ...(card.benefits ? { benefits: [...card.benefits] } : {}),
+    ...(includePreferencePrompts ? { preferencePrompts: [...MEMBER_PREFERENCE_PROMPTS] } : {}),
+    contractNotice: cardContractNotice(card),
+  };
+}
+
+function memberCardCandidate(facts: ReturnType<typeof buildMemberCardFacts>) {
+  return {
+    cardType: 'member-card-summary',
+    data: facts,
+    note: `会员卡（可用积分 ${facts.availablePoints}）`,
+  };
+}
+
+/**
+ * 匿名短路（上下文统一化 Stage 3）：userId 来源 = 运行身份（reqCtx.identity.userId），
+ * 匿名身份无会员语义——统一「请先登录」分支（不再依赖外部门控/模型传参）。
+ */
+function anonymousShort(userId: string, action: string): Record<string, unknown> {
+  return {
+    userId,
+    requiresAuth: true,
+    found: false,
+    noResultsReason: `请先登录后再${action}`,
+  };
+}
+
+/**
+ * 已登录未入会引导卡（三查询工具 not_enrolled/closed 分支共用）：`outcome` 命中硬门禁态即出
+ * `member-enrollment-cta`（mall 模板投影为半屏入会闭环；base 模板内联渲染），深链为可选
+ * 透传素材（service.enrollUrl/loginUrl 有则带，未配置恒出卡、无 URL 字段）。
+ * 登录 ≠ 入会——unauthenticated 不出此卡。
+ */
+async function maybeEnrollmentCta(
+  reqCtx: RequestContext,
+  account: MemberAccountSnapshot,
+  links: { enrollUrl?: string; loginUrl?: string },
+): Promise<{ cardType: string; data: Record<string, unknown>; note: string } | undefined> {
+  const outcome = classifyMemberOutcome(reqCtx.identity, account);
+  if (outcome !== 'not_enrolled' && outcome !== 'closed') return undefined; // 含 unauthenticated/unknown/active 软放行
+  return memberGateCardOf(reqCtx.identity.userId, {
+    outcome,
+    ...(links.enrollUrl ? { enrollUrl: links.enrollUrl } : {}),
+    ...(links.loginUrl ? { loginUrl: links.loginUrl } : {}),
+  });
+}
+
+/** 非 active 查询话术（not_enrolled/closed/unknown 拆分；出卡与深链解耦后不再依赖 URL 配置）。 */
+function queryNoResultsNotice(account: { authState: string; state: string }): string {
+  if (account.authState === 'unauthenticated') return MEMBER_LOGIN_NOTICE;
+  if (account.state === 'not_enrolled') return MEMBER_NOT_ENROLLED_NOTICE;
+  if (account.state === 'closed') return MEMBER_NO_POINTS_NOTICE;
+  return MEMBER_UNKNOWN_NOTICE;
+}
+
+/** 已登录未入会/已关闭非查询话术（not_enrolled/closed 拆分——入会引导 ≠ 已退会无积分）。 */
+function queryNonActiveNotice(account: { authState: string; state: string }): string {
+  return account.state === 'closed' ? MEMBER_NO_POINTS_NOTICE : MEMBER_NOT_ENROLLED_NOTICE;
+}
+
+
+/** member 工具槽位注入（017 槽位原子化）：各工具按需取槽，替换旧 fat getMember。
+ *  loginUrl 挂 account 产物、enrollUrl/表单挂 enrollment 产物（厂商实例携带）。 */
+export interface MemberToolPorts {
+  getAccount: (reqCtx: RequestContext) => Promise<import('./ports').MemberAccountService>;
+  getProfile: (reqCtx: RequestContext) => Promise<import('@tbox.cn/app-contracts-mall').MemberProfilePort>;
+  getCard: (reqCtx: RequestContext) => Promise<import('@tbox.cn/app-contracts-mall').MemberCardPort>;
+  getBenefits: (reqCtx: RequestContext) => Promise<import('@tbox.cn/app-contracts-mall').MemberBenefitsPort>;
+  getEnrollment: (reqCtx: RequestContext) => Promise<import('./ports').MemberEnrollmentService>;
+}
+
+/** 积分查询工具：积分流水仅作为 LLM 文本事实，工具候选只出会员卡面。 */
+export function createQueryPointsTool(
+  ports: MemberToolPorts,
+): AnyTool {
   return createTool({
     id: 'queryPoints',
-    description: '查询会员当前积分余额、等级与积分流水',
+    description:
+      '查询会员当前积分余额、会员卡面与积分流水；返回的 balance 是当前积分点数，items 中 title 是流水业务说明、amount 是本笔变动（正数增加、负数扣减）、usedAt 是发生时间、description 是可选门店名称；流水仅供模型组织文本，不构造积分流水卡。已登录未入会时返回入会引导卡（member-enrollment-cta），无需再调 queryEnrollmentCta。',
     inputSchema: z.object({
-      userId: z.string().describe('会员 userId'),
-    }),
-    outputSchema: z.object({
-      userId: z.string(),
-      balance: z.number(),
-      level: z.enum(['silver', 'gold', 'platinum']),
-      items: z.array(
-        z.object({
-          usageRecordRef: z.string(),
-          title: z.string(),
-          amount: z.string(),
-          usedAt: z.string().optional(),
-          description: z.string().optional(),
-        }),
-      ),
-      total: z.number(),
+      query: z.string().optional().describe('当前用户原始问题；用于保留查询语境，不参与身份或资源定位'),
     }),
-    execute: async ({ userId }: { userId: string }) => {
-      const member = getMember();
-      const points = member
-        ? await member.queryPoints(userId)
-        : { userId, balance: 0, level: 'silver' as const };
-      const usage = member ? await member.listPointUsage(userId, 1, 10) : { items: [], total: 0 };
-      return {
+    execute: async (input: { query?: string }, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryPoints');
+      const privacyRefusal = memberPrivacyRefusal(input.query);
+      if (privacyRefusal) return { found: false, noResultsReason: privacyRefusal };
+      const userId = reqCtx.identity.userId;
+      if (reqCtx.identity.source === 'anonymous') {
+        return anonymousShort(userId, '查询会员积分');
+      }
+      const [accountPort, cardPort, benefitsPort, enrollmentPort] = await Promise.all([ports.getAccount(reqCtx), ports.getCard(reqCtx), ports.getBenefits(reqCtx), ports.getEnrollment(reqCtx)]);
+      const account = await accountPort.getAccount(userId);
+      if (account.authState === 'unauthenticated' || account.state !== 'active') {
+        const enrollCard = await maybeEnrollmentCta(reqCtx, account, { enrollUrl: enrollmentPort.enrollUrl, loginUrl: accountPort.loginUrl });
+        if (enrollCard) {
+          return {
+            userId,
+            found: false,
+            authState: account.authState,
+            state: account.state,
+            noResultsReason: queryNonActiveNotice(account),
+            cards: [enrollCard],
+          };
+        }
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: account.state,
+          noResultsReason: queryNoResultsNotice(account),
+        };
+      }
+      const card = await cardPort.getCard(userId);
+      let points = { userId, balance: 0 } as Awaited<ReturnType<typeof benefitsPort.queryPoints>>;
+      let pointsUnavailable = false;
+      try {
+        points = await benefitsPort.queryPoints(userId);
+      } catch {
+        pointsUnavailable = true;
+      }
+      const completeCard = hasCompleteMemberCard(card);
+      // A complete visual card may still expose a native points detail page.
+      // Providers with that capability supply records as tool facts for the text answer.
+      let usage: { items: ReadonlyArray<unknown>; total: number } = { items: [], total: 0 };
+      let usageUnavailable = false;
+      if (!completeCard || card?.pointsUrl) {
+        try {
+          usage = await benefitsPort.listPointUsage(userId, 1, 10);
+        } catch {
+          usageUnavailable = true;
+        }
+      }
+      const facts = {
         userId,
         balance: points.balance,
-        level: points.level,
+        ...(points.membershipLabel ? { membershipLabel: points.membershipLabel } : {}),
         items: [...usage.items],
         total: usage.total,
+        contractNotice: MEMBER_CONTRACT_NOTICE,
+        ...(pointsUnavailable ? { pointsNotice: '当前积分余额暂不可用，会员卡仍可正常查看' } : {}),
+        ...(usageUnavailable ? { pointsHistoryNotice: '暂无最近积分流水记录' } : {}),
       };
+      if (!card) return { ...facts, cards: [] };
+
+      const memberCard = memberCardCandidate(buildMemberCardFacts(userId, card, points.balance, true));
+      return { ...facts, cards: [memberCard] };
     },
   });
 }
 
-/** 会员信息查询 → member-info 卡 */
+/** 明确会员资料查询：完整卡面 provider 只出主卡，基础卡面 provider 追加资料卡。 */
 export function createQueryMemberInfoTool(
-  getMember: () => (MemberAccountPort & { getProfile(userId: string): Promise<unknown> }) | undefined,
-) {
+  ports: MemberToolPorts,
+): AnyTool {
   return createTool({
     id: 'queryMemberInfo',
-    description: '查询会员账户状态与个人资料（是否入会、昵称、联系方式、标签）',
-    inputSchema: coerce(z.object({ userId: z.string().describe('会员 userId') })),
-    execute: async ({ userId }: { userId: string }) => {
-      const member = getMember();
-      const account = member ? await member.getAccount(userId) : { state: 'not_enrolled' as const, observedAt: nowIso() };
-      const profile = (member ? await member.getProfile(userId) : { labels: [] }) as {
-        displayName?: string;
-        avatarUrl?: string;
-        contactDisplay?: string;
-        labels: { labelRef: string; name: string }[];
-      };
-      return {
+    description:
+      '查询明确的会员账户资料（是否入会、昵称、联系方式、标签）；传入当前用户原始问题作为 query（不用于身份定位）；已登录未入会时附带入会引导卡（member-enrollment-cta），无需再调 queryEnrollmentCta。',
+    inputSchema: z.object({ query: z.string().optional().describe('当前用户原始问题，不用于身份定位') }),
+    execute: async (input: { query?: string }, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryMemberInfo');
+      const privacyRefusal = memberPrivacyRefusal(input.query);
+      if (privacyRefusal) return { found: false, noResultsReason: privacyRefusal };
+      const userId = reqCtx.identity.userId;
+      if (reqCtx.identity.source === 'anonymous') {
+        return anonymousShort(userId, '查询会员信息');
+      }
+      const [accountPort, cardPort, benefitsPort, profilePort, enrollmentPort] = await Promise.all([ports.getAccount(reqCtx), ports.getCard(reqCtx), ports.getBenefits(reqCtx), ports.getProfile(reqCtx), ports.getEnrollment(reqCtx)]);
+      const account = await accountPort.getAccount(userId);
+      const profile = await profilePort.getProfile(userId);
+      const facts = {
         userId,
+        authState: account.authState,
         state: account.state,
         ...(profile.displayName ? { displayName: profile.displayName } : {}),
         ...(profile.avatarUrl ? { avatarUrl: profile.avatarUrl } : {}),
@@ -73,6 +271,31 @@ export function createQueryMemberInfoTool(
         ...(account.memberRef ? { memberRef: account.memberRef } : {}),
         ...(account.registeredAt ? { registeredAt: account.registeredAt } : {}),
         labels: profile.labels ?? [],
+        contractNotice: MEMBER_CONTRACT_NOTICE,
+      };
+      const infoCard = {
+        cardType: 'member-info',
+        data: facts,
+        // note 契约（W7）：账户态中文化 + 姓名要点
+        note: `会员账户（${memberStateLabel(facts.state)}）${facts.displayName ? ` · ${facts.displayName}` : ''}`,
+      };
+      if (account.state !== 'active') {
+        // 已登录未入会：入会引导卡排首位（mall 模板投影半屏闭环），资料卡保留展示账户状态
+        const enrollCard = await maybeEnrollmentCta(reqCtx, account, { enrollUrl: enrollmentPort.enrollUrl, loginUrl: accountPort.loginUrl });
+        if (enrollCard) return { ...facts, cards: [enrollCard, infoCard] };
+        return { ...facts, cards: [infoCard] };
+      }
+
+      const [card, points] = await Promise.all([
+        cardPort.getCard(userId),
+        benefitsPort.queryPoints(userId),
+      ]);
+      if (!card) return { ...facts, cards: [infoCard] };
+      const memberCard = memberCardCandidate(buildMemberCardFacts(userId, card, points.balance));
+      if (hasCompleteMemberCard(card)) return { ...facts, cards: [memberCard] };
+      return {
+        ...facts,
+        cards: [memberCard, infoCard],
       };
     },
   });
@@ -80,77 +303,224 @@ export function createQueryMemberInfoTool(
 
 /** 会员卡查询 → member-card-summary 卡 */
 export function createQueryMemberCardTool(
-  getMember: () => (MemberCardPort & MemberBenefitsPort) | undefined,
-) {
+  ports: MemberToolPorts,
+): AnyTool {
   return createTool({
     id: 'queryMemberCard',
-    description: '查询会员卡信息（卡面、等级、积分摘要）',
-    inputSchema: coerce(z.object({ userId: z.string().describe('会员 userId') })),
-    execute: async ({ userId }: { userId: string }) => {
-      const member = getMember();
-      const card = member ? await member.getCard(userId) : null;
-      const points = member ? await member.queryPoints(userId) : { balance: 0, level: 'silver' as const };
-      return {
-        userId,
-        cardRef: card?.cardRef ?? `card:${userId}`,
-        cardDisplay: card?.cardDisplay ?? '大悦城会员卡',
-        status: card?.status ?? 'unknown',
-        ...(card?.levelName ? { levelName: card.levelName } : { levelName: points.level }),
-        availablePoints: points.balance,
-        ...(card?.cardImageUrl ? { cardImageUrl: card.cardImageUrl } : {}),
+    description:
+      '查询会员卡信息（卡面、卡名、积分摘要）；传入当前用户原始问题作为 query（不用于身份定位）；已登录未入会时返回入会引导卡（member-enrollment-cta），无需再调 queryEnrollmentCta。',
+    inputSchema: z.object({ query: z.string().optional().describe('当前用户原始问题，不用于身份定位') }),
+    execute: async (input: { query?: string }, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryMemberCard');
+      const privacyRefusal = memberPrivacyRefusal(input.query);
+      if (privacyRefusal) return { found: false, noResultsReason: privacyRefusal };
+      const userId = reqCtx.identity.userId;
+      if (reqCtx.identity.source === 'anonymous') {
+        return anonymousShort(userId, '查询会员卡');
+      }
+      const [accountPort, cardPort, benefitsPort, enrollmentPort] = await Promise.all([ports.getAccount(reqCtx), ports.getCard(reqCtx), ports.getBenefits(reqCtx), ports.getEnrollment(reqCtx)]);
+      const account = await accountPort.getAccount(userId);
+      if (account.authState === 'unauthenticated' || account.state === 'unknown') {
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: account.state,
+          noResultsReason:
+            account.authState === 'unauthenticated'
+              ? MEMBER_LOGIN_NOTICE
+              : MEMBER_UNKNOWN_NOTICE,
+        };
+      }
+      if (account.state !== 'active') {
+        const enrollCard = await maybeEnrollmentCta(reqCtx, account, { enrollUrl: enrollmentPort.enrollUrl, loginUrl: accountPort.loginUrl });
+        if (enrollCard) {
+          return {
+            userId,
+            found: false,
+            authState: account.authState,
+            state: account.state,
+            noResultsReason: queryNonActiveNotice(account),
+            cards: [enrollCard],
+          };
+        }
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: account.state,
+          noResultsReason: '当前用户尚未在该商场开通会员卡',
+        };
+      }
+      const card = await cardPort.getCard(userId);
+      const points = await benefitsPort.queryPoints(userId);
+      if (!card) {
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: 'unknown',
+          noResultsReason: '会员账户已激活，但暂未取得会员卡信息，请稍后重试',
+        };
+      }
+      const facts = buildMemberCardFacts(userId, card, points.balance);
+      return withCards(facts, 'member-card-summary', `会员卡（可用积分 ${points.balance}）`);
+    },
+  });
+}
+
+/** 开卡入会引导工具 → member-enrollment-cta 卡（点击跳转 alipays 链接） */
+export function createQueryEnrollmentCtaTool(
+  ports: MemberToolPorts,
+): AnyTool {
+  return createTool({
+    id: 'queryEnrollmentCta',
+    description:
+      '开卡入会引导：当用户询问如何成为会员、怎么开卡、入会流程、会员注册时调用，返回开卡入会引导卡（点击后跳转支付宝小程序完成入会）。' +
+      '【注意】已入会用户不出此卡，改为查询 queryMemberCard。',
+    inputSchema: z.object({}),
+    execute: async (_input: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryEnrollmentCta');
+      const userId = reqCtx.identity.userId;
+      const [accountPort, enrollmentPort] = await Promise.all([ports.getAccount(reqCtx), ports.getEnrollment(reqCtx)]);
+      const account = await accountPort.getAccount(userId);
+
+      // 已入会：不出 CTA 卡
+      if (account.state === 'active') {
+        return {
+          userId,
+          found: false,
+          noResultsReason: '您已是会员，无需重复开卡',
+          authState: account.authState,
+          state: 'active',
+        };
+      }
+
+      // 未登录或会员状态未知都不能被投影成“未入会”。登录本身不依赖开通会员。
+      if (account.authState === 'unauthenticated') {
+        // 未登录（可能同时 state=unknown）：给出可点的登录入口，而不是让用户读完「请先登录」
+        // 还得自己找地方登录。深链为可选透传素材（accountPort.loginUrl 有则带）；
+        // 未配置恒出卡（无 URL 字段，客户端禁用按钮）。
+        const loginFacts = {
+          title: '登录后继续',
+          ...(accountPort.loginUrl ? { loginUrl: accountPort.loginUrl } : {}),
+        };
+        return {
+          ...loginFacts,
+          found: true as const,
+          cards: [{ cardType: 'member-login-cta', data: loginFacts, note: '未登录 · 点击卡片登录' }],
+        };
+      }
+      // 已登录但状态未知（确认失败）不该误导成未登录——给出刷新提示而非登录卡。
+      if (account.state === 'unknown') {
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: account.state,
+          noResultsReason: '当前无法确认会员状态，请刷新登录状态后重试',
+        };
+      }
+
+      // 只有“已登录 + 已确认未入会/已关闭”才展示入会入口。深链为可选透传素材（未配置恒出卡）。
+      const status = {
+        outcome: account.state as 'not_enrolled' | 'closed',
+        ...(enrollmentPort.enrollUrl ? { enrollUrl: enrollmentPort.enrollUrl } : {}),
+        ...(accountPort.loginUrl ? { loginUrl: accountPort.loginUrl } : {}),
       };
+      const card = memberGateCardOf(reqCtx.identity.userId, status);
+      if (!card) {
+        return {
+          userId,
+          found: false,
+          authState: account.authState,
+          state: account.state,
+          noResultsReason: '当前无法确认会员状态，请稍后重试',
+        };
+      }
+      const facts = { userId, ...card.data };
+      return withCards(facts, card.cardType, card.note);
     },
   });
 }
 
-/** 入会表单查询 → member-enrollment-form 卡（011 B3 触发链：出表单卡 → 按钮 → componentAction → dispatcher） */
 export function createQueryEnrollmentFormTool(
-  getMember: () => (MemberAccountPort & MemberBenefitsPort) | undefined,
-) {
+  ports: MemberToolPorts,
+): AnyTool {
   return createTool({
     id: 'queryEnrollmentForm',
-    description: '查询会员入会状态并返回入会表单（未入会时用户可提交入会）',
-    inputSchema: z.object({ userId: z.string().describe('会员 userId') }),
-    execute: async ({ userId }: { userId: string }) => {
-      const member = getMember();
-      const account = member ? await member.getAccount(userId) : { state: 'not_enrolled' as const };
-      return {
+    description: '查询会员入会状态并返回入会表单（含支付宝授权预填入口、隐私同意项；未入会时用户可授权或手动填写后提交）',
+    inputSchema: z.object({}),
+    execute: async (_input: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryEnrollmentForm');
+      const userId = reqCtx.identity.userId;
+      if (reqCtx.identity.source === 'anonymous') {
+        // 表单面向「已授权未入会」用户；匿名应走 queryEnrollmentCta（授权引导）而非表单
+        return anonymousShort(userId, '查询入会表单');
+      }
+      const [accountPort, enrollmentPort] = await Promise.all([ports.getAccount(reqCtx), ports.getEnrollment(reqCtx)]);
+      const account = await accountPort.getAccount(userId);
+      const notEnrolled =
+        account.authState === 'authenticated' &&
+        (account.state === 'not_enrolled' || account.state === 'closed');
+      // getEnrollmentFormDefinition = Port optional 能力口（R13 收编）：无表单端点厂商可缺省，typeof 守卫降级
+      const definition =
+        notEnrolled && typeof enrollmentPort.getEnrollmentFormDefinition === 'function'
+          ? await enrollmentPort.getEnrollmentFormDefinition(userId)
+          : undefined;
+      if (!notEnrolled) {
+        return {
+          userId,
+          authState: account.authState,
+          state: account.state,
+          found: false,
+          noResultsReason:
+            account.authState === 'unauthenticated'
+              ? MEMBER_LOGIN_NOTICE
+              : account.state === 'active'
+                ? '当前用户已是会员，无需重复开卡'
+                : MEMBER_UNKNOWN_NOTICE,
+        };
+      }
+      const facts = {
         userId,
         state: account.state,
-        fields:
-          account.state === 'not_enrolled'
-            ? [
-                { fieldId: 'name', label: '姓名', required: true },
-                { fieldId: 'phone', label: '手机号', required: true },
-              ]
-            : [],
-        actionId: 'member.enroll',
+        formVersion: definition?.formVersion ?? 'unknown',
+        fields: definition ? [...definition.fields] : [],
+        consents: definition ? [...definition.consents] : [],
+        authorization: { status: definition?.authorizationStatus ?? 'unavailable' },
       };
+      return withCards(facts, 'member-enrollment-form', '未入会 · 填写表单完成入会');
     },
   });
 }
 
-/** 优惠券列表查询 → member-coupon-list 卡 */
-export function createQueryMemberCouponsTool(getMember: () => MemberCouponPort | undefined) {
+/**
+ * queryLoginCta：登录引导卡。
+ *
+ * 与 queryEnrollmentCta 的未登录分支相比，这条是**用户主动要登录入口**时的直达通道——
+ * 登录诉求不只来自开卡，停车缴费、查积分、看券都会撞上。故不按当前登录态设闸：
+ * 用户开口要登录入口就给他，已登录的人点过去也只是看到自己已登录，无害；
+ * 反过来若按 authState 卡住，真正没登录的用户（此刻拿不到可信身份）反而可能被误判拦下。
+ * 深链为可选透传素材——accountPort.loginUrl 有则带；未配置恒出卡（无 URL 字段，客户端禁用按钮）。
+ */
+export function createQueryLoginCtaTool(
+  ports: MemberToolPorts,
+): AnyTool {
   return createTool({
-    id: 'queryMemberCoupons',
-    description: '查询会员优惠券列表（状态/面额/门槛）',
-    inputSchema: coerce(z.object({ userId: z.string().describe('会员 userId') })),
-    execute: async ({ userId }: { userId: string }) => {
-      const member = getMember();
-      const result = member ? await member.listCoupons(userId, 1, 20) : { items: [], total: 0 };
-      return {
-        userId,
-        items: result.items.map((c) => ({
-          couponRef: c.couponRef,
-          title: c.title,
-          type: c.type,
-          status: c.status,
-          ...(c.benefitText ? { benefitText: c.benefitText } : {}),
-          ...(c.thresholdText ? { thresholdText: c.thresholdText } : {}),
-        })),
-        total: result.total,
+    id: 'queryLoginCta',
+    description:
+      '登录引导：当用户表示要登录、说自己未登录，或其它能力因缺少登录身份无法继续时调用，' +
+      '返回登录引导卡（点击后跳转商场小程序登录页，完成后回到对话）。',
+    inputSchema: z.object({}),
+    execute: async (_input: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'queryLoginCta');
+      const accountPort = await ports.getAccount(reqCtx);
+      const loginFacts = {
+        title: '登录后继续',
+        ...(accountPort.loginUrl ? { loginUrl: accountPort.loginUrl } : {}),
       };
+      return withCards(loginFacts, 'member-login-cta', '未登录 · 点击卡片登录');
     },
   });
 }