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

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

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

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

@@ -4,16 +4,15 @@ import { memberEnrollmentStatusCardDataSchema } from '@tbox.cn/app-contracts-mal
 const meta: CardMeta<typeof memberEnrollmentStatusCardDataSchema> = {
   cardType: 'member-enrollment-status',
   dataSchema: memberEnrollmentStatusCardDataSchema,
-  allowedTools: [],
   displayName: '入会状态',
-  description: '入会结果状态（成功/失败 + 会员编号）',
+  description: '入会结果状态（pending 态附显式刷新按钮，动作 member.query-enrollment-status）',
   sampleData: {
     userId: 'u_1001',
-    success: true,
-    memberRef: 'member:u_1001',
-    state: 'active',
+    attemptRef: 'att_1',
+    state: 'pending_confirmation',
+    message: '厂商确认中，可稍后再刷新',
   },
-  schemaVersion: 1,
+  schemaVersion: 2,
 };
 
 export default meta;

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

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

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

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