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

package/src/server/cards/member-card-summary/samples.ts

@@ -0,0 +1,272 @@
+/**
+ * member-card-summary 附加预览样本（沉淀自 mall dev-gallery 会员卡面画廊）。
+ *
+ * 方法论（迁移自画廊维护约定）：
+ * - 覆盖基准是组件实际读取的 data 分支（四档 variant / 卡图缺失 / 外链失败 / 跑马灯文案 /
+ *   权益图标失败兜底 / 单条偏好 / 历史态），而非 sampleData 的形状；
+ * - 视觉等价的输入合并为一格，note 列全合并口径；
+ * - 样本即契约：data 必须 dataSchema 校验通过且无 shape 外键（tests/samples.test.ts 双断言）。
+ *
+ * 素材中立化（画廊时期权益图标指向厂商 CDN，模块样本按仓库铁律净化）：
+ * - 卡面底图/积分规则长图：无网络依赖的内联 SVG data URI（画廊原实现随行）；
+ * - 权益图标：内联 SVG 按变体分色——验证的是「图标配色压不压得住卡面底色」与四列网格
+ *   换行（低两档 14 项、高两档 15 项的数量差异照实铺），不是图标的图案还原度
+ *  （真实图标由 provider 运行时下发；图案语义兜底归组件内 ImageWithFallback）；
+ * - 卡图/图标的外链失败分支刻意保留 example.com 占位（该分支本身是合法预览态）。
+ */
+import type { CardSample } from '@tbox.cn/app-contracts';
+import type { MemberCardSummaryCardData } from '@tbox.cn/app-contracts-mall';
+
+/** 卡面底图：底色随 variant 走（前三档浅底深字、black 深底浅字——与模块 CSS 叠字色配对） */
+function cardFace(from: string, to: string): string {
+  // 真实卡图恒自带卡名与「我的积分」字样（labelsEmbedded 恒 true），前端只叠积分数字。
+  // 两块半透明色块代表那两行字的占位——不写真文字是为了不依赖 SVG 内的中文字体，
+  // 要判断的本来也只是「数字有没有压到图上已有元素」。`#` 在 data URI 里须写成 %23。
+  const marks
+    = '<rect x="58" y="52" width="210" height="42" rx="8" fill="%23000000" opacity="0.14"/>'
+    + '<rect x="58" y="130" width="132" height="26" rx="6" fill="%23000000" opacity="0.10"/>';
+  return 'data:image/svg+xml;utf8,'
+    + '<svg xmlns="http://www.w3.org/2000/svg" width="672" height="347">'
+    + '<defs><linearGradient id="f" x1="0" y1="0" x2="1" y2="1">'
+    + `<stop offset="0" stop-color="%23${from}"/><stop offset="1" stop-color="%23${to}"/>`
+    + '</linearGradient></defs>'
+    + '<rect width="672" height="347" fill="url(%23f)"/>'
+    + '<circle cx="548" cy="60" r="150" fill="%23ffffff" opacity="0.16"/>'
+    + marks
+    + '</svg>';
+}
+
+const FACE = {
+  blue: cardFace('dce8fb', 'aecdf5'),
+  silver: cardFace('eef1f7', 'c4cddf'),
+  gold: cardFace('f9ecca', 'e3c283'),
+  black: cardFace('1b1e26', '4a412c'),
+};
+
+/** 积分规则长图占位（弹层内容）：只需一张有高度的图验证弹层滚动与关闭 */
+const POINTS_RULE_IMAGE
+  = 'data:image/svg+xml;utf8,'
+  + '<svg xmlns="http://www.w3.org/2000/svg" width="750" height="1600">'
+  + '<rect width="750" height="1600" fill="%23fffdf8"/>'
+  + '<rect x="60" y="80" width="380" height="44" rx="10" fill="%23e2c78f"/>'
+  + '<rect x="60" y="180" width="630" height="24" rx="8" fill="%23ece7dd"/>'
+  + '<rect x="60" y="230" width="560" height="24" rx="8" fill="%23ece7dd"/>'
+  + '<rect x="60" y="280" width="610" height="24" rx="8" fill="%23ece7dd"/>'
+  + '<rect x="60" y="700" width="630" height="24" rx="8" fill="%23ece7dd"/>'
+  + '<rect x="60" y="1500" width="400" height="24" rx="8" fill="%23ece7dd"/>'
+  + '</svg>';
+
+/**
+ * 权益图标占位（按变体分色）：圆形徽标 + 随 benefitRef 稳定变化的几何图形。
+ * 同一项权益在四个等级下是不同颜色版本的图标——用同一套几何图形配四档配色，
+ * 保留「图标配色 vs 卡面底色」这一四档卡面唯一真正要比的东西。
+ */
+const ICON_COLORS: Record<
+  NonNullable<MemberCardSummaryCardData['presentation']>['variant'],
+  { fg: string; bg: string }
+> = {
+  blue: { fg: '254077', bg: 'dce8fb' },
+  silver: { fg: '303443', bg: 'e8ecf3' },
+  gold: { fg: '683d08', bg: 'f3e3b8' },
+  black: { fg: 'e9d7ac', bg: '2a2d35' },
+};
+
+function benefitIcon(variant: keyof typeof ICON_COLORS, benefitRef: string): string {
+  const { fg, bg } = ICON_COLORS[variant];
+  // 图形随 benefitRef 散列到四条分支（圆/环/方/三角）——同权益跨档同形、跨权益异形
+  let hash = 0;
+  for (const ch of benefitRef) hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
+  const shape = hash % 4;
+  const drawn =
+    shape === 0
+      ? `<circle cx="24" cy="24" r="10" fill="%23${fg}"/>`
+      : shape === 1
+        ? `<circle cx="24" cy="24" r="10" fill="none" stroke="%23${fg}" stroke-width="5"/>`
+        : shape === 2
+          ? `<rect x="15" y="15" width="18" height="18" rx="4" fill="%23${fg}"/>`
+          : `<path d="M24 12 L36 34 L12 34 Z" fill="%23${fg}"/>`;
+  return `data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48"><rect width="48" height="48" rx="12" fill="%23${bg}"/>${drawn}</svg>`;
+}
+
+/** 四档各自的完整权益列表（名称/顺序照画廊采集快照；低两档 14 项，高两档 15 项）。 */
+function benefitsOf(variant: keyof typeof ICON_COLORS): NonNullable<MemberCardSummaryCardData['benefits']> {
+  const BASE_NAMES: ReadonlyArray<{ ref: string; name: string; description?: string }> = [
+    { ref: 'benefit:points', name: '消费积分' },
+    { ref: 'benefit:gifts', name: '积分换礼' },
+    { ref: 'benefit:events', name: '会员活动' },
+    { ref: 'benefit:express', name: '顺丰85折' },
+    { ref: 'benefit:points-parking', name: '积分兑停车' },
+    { ref: 'benefit:storage', name: '物品存储' },
+    { ref: 'benefit:care', name: '暖心守护' },
+    { ref: 'benefit:pet', name: '萌宠驿站' },
+    { ref: 'benefit:service', name: '专属客服' },
+    { ref: 'benefit:umbrella', name: '雨伞租借' },
+    { ref: 'benefit:wheelchair', name: '轮椅租借' },
+    { ref: 'benefit:stroller', name: '婴儿车租借' },
+    { ref: 'benefit:birthday', name: '生日礼遇' },
+    { ref: 'benefit:wifi', name: '免费WIFI' },
+  ];
+  const items = BASE_NAMES.map((b) => ({
+    benefitRef: b.ref,
+    name: b.name,
+    iconUrl: benefitIcon(variant, b.ref),
+  }));
+  // 高两档多出的正是停车那项（金：免 1 小时 / 黑：免 2 小时）——数量差异是卡面该体现的东西
+  if (variant === 'gold' || variant === 'black') {
+    return [
+      {
+        benefitRef: 'benefit:parking',
+        name: '免费停车',
+        iconUrl: benefitIcon(variant, 'benefit:parking'),
+        ...(variant === 'gold' ? { description: '可免1小时' } : { description: '可免2小时' }),
+      },
+      ...items,
+    ];
+  }
+  return items;
+}
+
+const PROGRESS_SHORT = {
+  daySpentCents: 12_345,
+  yearSpentCents: 500_000,
+  percent: 25,
+  message: '今日已消费123.45元',
+};
+
+export const samples: CardSample<MemberCardSummaryCardData>[] = [
+  {
+    label: '卡面·金卡',
+    note: '基准形态：卡名与「我的积分」由卡图自带，前端只叠积分数。带 pointsRuleImageUrl 时触发器是盖在卡图自印按钮上的透明热区（视觉上看不出，弹层态需手动点它）',
+    group: '会员卡面（四档 variant）',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: FACE.gold, pointsRuleImageUrl: POINTS_RULE_IMAGE,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT, benefits: benefitsOf('gold'),
+    },
+  },
+  {
+    label: '卡面·蓝卡',
+    note: 'variant=blue（入门等级）——叠字对比度之外，权益 14 项且无「免费停车」，与金/黑的 15 项对照',
+    group: '会员卡面（四档 variant）',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '悦享卡', status: 'active',
+      availablePoints: 120, cardImageUrl: FACE.blue,
+      presentation: { variant: 'blue', labelsEmbedded: true },
+      progress: { daySpentCents: 0, yearSpentCents: 8_800, percent: 4, message: '年累计已消费88.00元' },
+      benefits: benefitsOf('blue'),
+    },
+  },
+  {
+    label: '卡面·银卡',
+    note: 'variant=silver——浅底最容易压不住白字；权益同为 14 项，图标是银卡配色版',
+    group: '会员卡面（四档 variant）',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '银卡会员', status: 'active',
+      availablePoints: 3_400, cardImageUrl: FACE.silver,
+      presentation: { variant: 'silver', labelsEmbedded: true },
+      progress: { daySpentCents: 4_500, yearSpentCents: 120_000, percent: 48, message: '今日已消费45.00元，年累计已消费1200.00元' },
+      benefits: benefitsOf('silver'),
+    },
+  },
+  {
+    label: '卡面·黑金卡',
+    note: 'variant=black（最高等级）——金色描边与深底的层次；15 项权益，免费停车带「可免2小时」说明',
+    group: '会员卡面（四档 variant）',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '黑金会员', status: 'active',
+      availablePoints: 128_600, cardImageUrl: FACE.black,
+      presentation: { variant: 'black', labelsEmbedded: true },
+      progress: { daySpentCents: 98_800, yearSpentCents: 2_400_000, percent: 100, message: '年累计已消费24000.00元，已达最高等级' },
+      benefits: benefitsOf('black'),
+    },
+  },
+  {
+    label: '卡面·卡图缺失',
+    note: 'presentation 在但 cardImageUrl 缺省——退到渐变兜底底纹，叠字排布应不变',
+    group: '卡面素材分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT, benefits: benefitsOf('gold'),
+    },
+  },
+  {
+    label: '卡面·外链加载失败',
+    note: '线上卡图 404 / 断网的实况——ImageWithFallback 占位不应把卡面撑变形',
+    group: '卡面素材分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: 'https://assets.example.com/member/gold-card.png',
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT, benefits: benefitsOf('gold'),
+    },
+  },
+  {
+    label: '卡面·进度长文案',
+    note: 'progress.message 超 24 字触发 --scroll 跑马灯；percent=0 时进度条应可见轨道',
+    group: '卡面素材分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: FACE.gold,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: {
+        daySpentCents: 0, yearSpentCents: 0, percent: 0,
+        message: '今年还没有消费记录，累计消费满5000.00元可升级为银卡会员',
+      },
+      benefits: benefitsOf('gold'),
+    },
+  },
+  {
+    label: '卡面·无进度无权益',
+    note: 'progress 与 benefits 同时缺省——只剩卡面 + 偏好引导，检查底部收口',
+    group: '卡面素材分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '悦享卡', status: 'active',
+      availablePoints: 0, cardImageUrl: FACE.blue,
+      presentation: { variant: 'blue', labelsEmbedded: true },
+    },
+  },
+  {
+    label: '卡面·权益图标失败',
+    note: 'iconUrl 加载失败 → 按权益名匹配的兜底图标（停车/积分/活动/其它四条分支）',
+    group: '卡面素材分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: FACE.gold,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT,
+      benefits: [
+        { benefitRef: 'b1', name: '免费停车', iconUrl: 'https://assets.example.com/x.png' },
+        { benefitRef: 'b2', name: '消费积分', iconUrl: 'https://assets.example.com/x.png' },
+        { benefitRef: 'b3', name: '会员活动', iconUrl: 'https://assets.example.com/x.png' },
+        { benefitRef: 'b4', name: '生日礼遇', iconUrl: 'https://assets.example.com/x.png' },
+      ],
+    },
+  },
+  {
+    label: '卡面·单条偏好',
+    note: 'preferencePrompts 显式给一项——缺省时组件兜底成 contracts 固定三项，单项时看按钮是否被拉伸',
+    group: '偏好引导分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: FACE.gold,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT, benefits: benefitsOf('gold'),
+      preferencePrompts: [{ value: '我常来吃美食', query: '推荐值得去的餐饮美食门店' }],
+    },
+  },
+  {
+    label: '卡面·历史卡',
+    note: 'isHistory——偏好引导按钮全禁用（点了也不会发消息），卡面与权益区照常渲染',
+    group: '偏好引导分支',
+    data: {
+      userId: 'u_1001', cardRef: 'card:u_1001', cardDisplay: '金卡会员', status: 'active',
+      availablePoints: 860, cardImageUrl: FACE.gold,
+      presentation: { variant: 'gold', labelsEmbedded: true },
+      progress: PROGRESS_SHORT, benefits: benefitsOf('gold'),
+    },
+    isHistory: true,
+  },
+];

package/src/server/cards/member-enrollment-cta/meta.ts

@@ -0,0 +1,19 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberEnrollmentCtaCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberEnrollmentCtaCardDataSchema> = {
+  cardType: 'member-enrollment-cta',
+  dataSchema: memberEnrollmentCtaCardDataSchema,
+  displayName: '开卡入会',
+  description: '开卡入会引导卡——点击后跳转 alipays 链接完成入会',
+  sampleData: {
+    userId: 'u_1001',
+    authState: 'authenticated',
+    state: 'not_enrolled',
+    enrollUrl: 'alipays://platformapi/startapp?appId=demo&page=v/index/index',
+    title: '入会后继续',
+  },
+  schemaVersion: 2,
+};
+
+export default meta;

package/src/server/cards/member-enrollment-form/meta.ts

@@ -0,0 +1,26 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberEnrollmentFormCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberEnrollmentFormCardDataSchema> = {
+  cardType: 'member-enrollment-form',
+  dataSchema: memberEnrollmentFormCardDataSchema,
+  displayName: '入会表单',
+  description: '会员入会表单（支付宝授权预填 + 手动降级；动作 member.request-alipay-authorization / member.enroll）',
+  sampleData: {
+    userId: 'u_1001',
+    state: 'not_enrolled',
+    formVersion: 'v2026.08',
+    fields: [
+      { fieldId: 'mobile', label: '手机号', type: 'tel', required: true, placeholder: '请输入手机号' },
+      { fieldId: 'displayName', label: '姓名', type: 'text', required: false },
+    ],
+    consents: [
+      { consentId: 'privacy', version: '1', title: '隐私政策', required: true },
+      { consentId: 'membership-terms', version: '1', title: '会员服务条款', required: false },
+    ],
+    authorization: { status: 'required' },
+  },
+  schemaVersion: 2,
+};
+
+export default meta;

package/src/server/cards/member-enrollment-status/meta.ts

@@ -0,0 +1,18 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberEnrollmentStatusCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberEnrollmentStatusCardDataSchema> = {
+  cardType: 'member-enrollment-status',
+  dataSchema: memberEnrollmentStatusCardDataSchema,
+  displayName: '入会状态',
+  description: '入会结果状态（pending 态附显式刷新按钮，动作 member.query-enrollment-status）',
+  sampleData: {
+    userId: 'u_1001',
+    attemptRef: 'att_1',
+    state: 'pending_confirmation',
+    message: '厂商确认中，可稍后再刷新',
+  },
+  schemaVersion: 2,
+};
+
+export default meta;

package/src/server/cards/member-info/meta.ts

@@ -0,0 +1,19 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberInfoCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberInfoCardDataSchema> = {
+  cardType: 'member-info',
+  dataSchema: memberInfoCardDataSchema,
+  displayName: '会员信息',
+  description: '会员账户状态与个人资料',
+  sampleData: {
+    userId: 'u_1001',
+    authState: 'authenticated',
+    state: 'active',
+    displayName: '示例会员',
+    labels: [{ labelRef: 'member', name: '会员' }],
+  },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/member-login-cta/meta.ts

@@ -0,0 +1,16 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberLoginCtaCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberLoginCtaCardDataSchema> = {
+  cardType: 'member-login-cta',
+  dataSchema: memberLoginCtaCardDataSchema,
+  displayName: '登录引导',
+  description: '未登录引导卡——点击跳转商场小程序登录页，登录后回到智能体继续',
+  sampleData: {
+    loginUrl: 'alipays://platformapi/startapp?appId=demo&page=v/login/index',
+    title: '登录后继续',
+  },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/member-point-usage-list/meta.ts

@@ -0,0 +1,19 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { memberPointUsageListCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof memberPointUsageListCardDataSchema> = {
+  cardType: 'member-point-usage-list',
+  dataSchema: memberPointUsageListCardDataSchema,
+  displayName: '积分余额与流水',
+  description: '会员积分余额、厂商会员标签与变动流水（吸收教学 points 卡）',
+  sampleData: {
+    userId: 'u_1001',
+    balance: 860,
+    membershipLabel: '悦享卡',
+    items: [{ usageRecordRef: 'r1', title: '消费奖励', amount: '+100', usedAt: '2026-08-13T00:00:00Z' }],
+    total: 1,
+  },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/handler.ts

@@ -1,24 +1,178 @@
-import type { HandlerDefinition } from '@tbox.cn/app-sdk/server';
-import type { MemberQueryPort } from '@tbox.cn/app-contracts-mall';
-import type { ServerContext } from '@tbox.cn/app-sdk/server';
-
 /**
- * member handler：查积分 → 出 points 卡。
- * 由 scenario / intent 路由按需 dispatch；LLM 路径走 queryPoints tool。
+ * member handler（011 K2；015：写动作拆至 action.ts，此处只保留意图路径出卡）。
+ * - 查积分/信息/卡 → 出对应卡（LLM 路径走同名工具）。
+ * - 会员偏好长期记忆（017 PRD）：三项声明式 intent → ctx.memory 保存 + continueWith 续接导购。
+ * - 上下文统一化：userId 来源 = 运行身份（reqCtx.identity.userId，handler 第四参）——
+ *   旧 payload.userId 是模型注入面（P4-3），已删除；偏好分支同经 reqCtx 显式读取。
  */
+import type { HandlerDefinition, ServerContext } from '@tbox.cn/app-sdk/server';
+import {
+  MEMBER_PREFERENCE_PROMPTS,
+  MEMBER_PREFERENCE_RECOMMENDATION_QUERIES,
+  MEMBER_PREFERENCE_VALUES,
+  parseMallScope,
+} from '@tbox.cn/app-contracts-mall';
+import type { MemberPreferenceValue } from '@tbox.cn/app-contracts-mall';
+import { MEMBER_QUERY_NOTICES, resolveMemberStatus } from './status';
+import { memberPrivacyRefusal } from './tool';
+import { resolveMemberBenefitsPort, resolveMemberCardPort } from './ports';
+
+function matchMemberPreference(content: string) {
+  return MEMBER_PREFERENCE_PROMPTS.find((prompt) => content === prompt.query);
+}
+
+/** 偏好确认回执文案（第二人称）：按钮值是用户口吻（写记忆保留第一人称），
+ *  助手复述须转换人称；Record 穷尽性保证枚举扩容时编译期强制补齐。 */
+const MEMBER_PREFERENCE_ACK_TEXTS: Record<MemberPreferenceValue, string> = {
+  '我常来买衣服': '你常来买衣服',
+  '我常带娃来玩': '你常带娃来玩',
+  '我常来吃美食': '你常来吃美食',
+};
+
 export function createMemberHandler(ctx: ServerContext): HandlerDefinition {
   return {
     id: 'member',
-    handle: async (_action, payload) => {
-      const member = ctx.resolveService<MemberQueryPort>('member');
-      if (!member) return { cards: [], text: '会员服务不可用' };
-      const { userId } = (payload ?? {}) as { userId?: string };
-      if (!userId) return { cards: [], text: '缺少 userId' };
-      const points = await member.queryPoints(userId);
-      return {
-        cards: [{ cardType: 'points', data: points as unknown as Record<string, unknown> }],
-        text: `当前积分 ${points.balance}，等级 ${points.level}`,
-      };
+    // match:'exact'：偏好按钮发出的是固定整句值（member-card-summary 按钮组），
+    // 整句全等命中——不入 BM25 词袋（相似查询「2楼有啥美食可逛」曾被词袋误吞，F3）
+    intents: [{ patterns: [...MEMBER_PREFERENCE_VALUES], match: 'exact' }],
+    handle: async (action, payload, _ctx, reqCtx) => {
+      if (action === 'intent') {
+        const content = typeof (payload as { content?: unknown } | undefined)?.content === 'string'
+          ? (payload as { content: string }).content.trim()
+          : '';
+        const prompt = matchMemberPreference(content);
+        // 洋葱定律 1：未识别 = 失败 = 必须放行（不再出 12 字死文案短路整轮）。
+        // exact 路由下正常不可达（全等已保证命中），防御性兜底同样放行 LLM 正常对话。
+        if (!prompt) return { cards: [], continueWith: { content } };
+
+        // 上下文统一化：运行身份 = handle 第四参 reqCtx（引擎意图分发注入）
+        const identity = reqCtx?.identity;
+        if (!identity || identity.source === 'anonymous') {
+          return { cards: [], text: '登录后才能保存会员偏好' };
+        }
+        if (!ctx.memory || ctx.memory.capabilities?.save === false) {
+          return { cards: [], text: '偏好记忆暂不可用，请稍后再试' };
+        }
+
+        const mallId = parseMallScope(reqCtx?.attributes)?.mallId;
+        await ctx.memory.save({
+          userId: identity.userId,
+          ...(mallId ? { scope: { mallId } } : {}),
+          kind: 'preference',
+          content: `会员偏好：${prompt.value}`,
+        });
+
+        return {
+          cards: [],
+          text: `记住啦，${MEMBER_PREFERENCE_ACK_TEXTS[prompt.value]}。正在为你查找相关的门店和导购服务，请稍等。\n\n`,
+          continueWith: { content: MEMBER_PREFERENCE_RECOMMENDATION_QUERIES[prompt.value] },
+        };
+      }
+
+      if (!reqCtx) return { cards: [], text: '会员服务不可用（运行上下文缺失）' };
+      const query = typeof (payload as { query?: unknown } | undefined)?.query === 'string'
+        ? (payload as { query: string }).query
+        : '';
+      const privacyRefusal = memberPrivacyRefusal(query);
+      if (privacyRefusal) return { cards: [], text: privacyRefusal };
+      const status = await resolveMemberStatus(reqCtx, ctx);
+      if (status.outcome === 'active') {
+        const userId = reqCtx.identity.userId;
+        switch (action) {
+          case 'query-points': {
+            // 017 槽位原子化：active 态按槽解析（card 面 + benefits 面；多次构造廉价）。
+            // 槽解析失败 → unavailable 收口（旧防御分支语义延续：不裸抛、不答「积分 0」）
+            let cardPort: Awaited<ReturnType<typeof resolveMemberCardPort>>;
+            let benefitsPort: Awaited<ReturnType<typeof resolveMemberBenefitsPort>>;
+            try {
+              [cardPort, benefitsPort] = await Promise.all([
+                resolveMemberCardPort(reqCtx, ctx),
+                resolveMemberBenefitsPort(reqCtx, ctx),
+              ]);
+            } catch (error) {
+              ctx.logger?.warn(`member handler：active 槽解析失败：err=${(error as Error).message}`);
+              return { cards: [], text: MEMBER_QUERY_NOTICES.unavailable };
+            }
+            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;
+            }
+            if (card?.presentation !== undefined) {
+              let usage: Awaited<ReturnType<typeof benefitsPort.listPointUsage>> | undefined;
+              let usageUnavailable = false;
+              if (card.pointsUrl) {
+                try {
+                  usage = await benefitsPort.listPointUsage(userId, 1, 10);
+                } catch {
+                  usageUnavailable = true;
+                }
+              }
+              const cardData = {
+                userId,
+                cardRef: card.cardRef,
+                cardDisplay: card.cardDisplay,
+                status: card.status,
+                ...(card.levelName ? { levelName: card.levelName } : {}),
+                availablePoints: points.balance,
+                ...(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] } : {}),
+              } as Record<string, unknown>;
+              return {
+                cards: [{ cardType: 'member-card-summary', data: cardData }],
+                text: pointsUnavailable
+                  ? '会员卡可正常查看，但当前积分余额暂不可用，暂无最近积分流水记录'
+                  : usageUnavailable
+                  ? `当前积分 ${points.balance}，暂无最近积分流水记录`
+                  : usage && usage.items.length > 0
+                  ? `当前积分 ${points.balance}，最近流水：${usage.items.map((item) => `${item.title}${item.amount}分${item.usedAt ? `（${item.usedAt}）` : ''}`).join('；')}`
+                  : `当前积分 ${points.balance}，暂未查询到最近积分流水`,
+              };
+            }
+            const usage = await benefitsPort.listPointUsage(userId, 1, 10);
+            const usageText = usage.items.length > 0
+              ? `，最近流水：${usage.items.map((item) => `${item.title}${item.amount}分${item.usedAt ? `（${item.usedAt}）` : ''}`).join('；')}`
+              : '，暂未查询到最近积分流水';
+            if (!card) {
+              return {
+                cards: [],
+                text: `当前积分 ${points.balance}${points.membershipLabel ? `，会员卡 ${points.membershipLabel}` : ''}${usageText}`,
+              };
+            }
+            return {
+              cards: [{ cardType: 'member-card-summary', data: {
+                userId,
+                cardRef: card.cardRef,
+                cardDisplay: card.cardDisplay,
+                status: card.status,
+                ...(card.levelName ? { levelName: card.levelName } : {}),
+                availablePoints: points.balance,
+                ...(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] } : {}),
+              } as Record<string, unknown> }],
+              text: `当前积分 ${points.balance}${points.membershipLabel ? `，会员卡 ${points.membershipLabel}` : ''}${usageText}`,
+            };
+          }
+          default: {
+            return { cards: [], text: '不支持的会员操作' };
+          }
+        }
+      }
+      // 非 active：门禁文案与工具路径同源（意图路径不再对未入会/未登录答「积分 0」）
+      return { cards: [], text: MEMBER_QUERY_NOTICES[status.outcome] };
     },
   };
 }