@tbox.cn/app-module-promotion 0.2.0 → 0.9.3

package/src/client/types/css.d.ts

@@ -0,0 +1,2 @@
+/** 0.4.0 D1：模块自持 CSS（经 tsup loader: { '.css': 'copy' } 出货，样式在应用侧生效） */
+declare module '*.css';

package/src/client/utils/sanitize-activity-html.ts

@@ -0,0 +1,48 @@
+/**
+ * sanitizeActivityHtml — 活动规则富文本过滤（零依赖，DOM API）。
+ *
+ * 数据源是支付宝开放平台 `activityRuleDetail`（半信任：来自外部 API，非用户输入直通）。
+ * 卡片经 dangerouslySetInnerHTML 渲染该 HTML——渲染前剥离全部脚本面：
+ * - 丢弃元素：script/iframe/object/embed/style/link/meta/base/form/input + svg/math
+ *   （svg/math 是 XSS 载体高发区且活动文案用不到——直接整体丢弃，攻击面收敛优于逐属性过滤）；
+ * - 丢弃事件属性（onerror 等，on* 前缀全清）；
+ * - URL 属性白名单值过滤：href/src/xlink:href/formaction/action/poster/background 命中
+ *   javascript: 或非 image data: 协议即剥离（HTML entity 解码由 DOMParser 先行完成，j 混淆无效）；
+ * - 保留其余展示属性与内联 style（现代浏览器 CSS url(javascript:) 不执行——活动文案排版依赖内联样式）。
+ */
+const DROP_TAGS = new Set([
+  'script', 'iframe', 'object', 'embed', 'style', 'link', 'meta', 'base', 'form', 'input',
+  'svg', 'math',
+]);
+/** 可承载 URL 的属性全集（含 SVG xlink 与 form 提交面）——值命中危险协议即剥离。 */
+const URL_ATTRS = new Set(['href', 'src', 'xlink:href', 'formaction', 'action', 'poster', 'background']);
+
+export function sanitizeActivityHtml(html: string): string {
+  if (typeof DOMParser === 'undefined') return '';
+  const doc = new DOMParser().parseFromString(html, 'text/html');
+  const walk = (node: Element): void => {
+    for (const child of [...node.children]) {
+      // tagName 大小写在 HTML 解析器间不稳定（浏览器大写 SVG、happy-dom 小写）——统一小写比较
+      if (DROP_TAGS.has(child.tagName.toLowerCase())) {
+        child.remove();
+        continue;
+      }
+      for (const attr of [...child.attributes]) {
+        const name = attr.name.toLowerCase();
+        if (name.startsWith('on')) {
+          child.removeAttribute(attr.name);
+          continue;
+        }
+        if (URL_ATTRS.has(name)) {
+          const value = attr.value.trim().toLowerCase();
+          const isJs = value.startsWith('javascript:');
+          const isData = value.startsWith('data:') && !value.startsWith('data:image/');
+          if (isJs || isData) child.removeAttribute(attr.name);
+        }
+      }
+      walk(child);
+    }
+  };
+  walk(doc.body);
+  return doc.body.innerHTML;
+}

package/src/client/utils/scroll-card-bottom.ts

@@ -0,0 +1,40 @@
+const MIN_BOTTOM_GAP = 96;
+
+/** 将卡片底部放在宿主固定底部操作区之上，且展开/收起都使用同一滚动基准。 */
+export function scrollCardBottom(anchor: HTMLElement): void {
+  const rootStyle = typeof document !== 'undefined' ? getComputedStyle(document.documentElement) : undefined;
+  const reservedHeight = Number.parseFloat(rootStyle?.getPropertyValue('--tbox-chat-bottom-height') ?? '') || 0;
+  const bottomGap = Math.max(MIN_BOTTOM_GAP, reservedHeight + 24);
+  let scroller = anchor.parentElement;
+  while (scroller && scroller !== document.body) {
+    const style = getComputedStyle(scroller);
+    if (/(auto|scroll|overlay)/.test(style.overflowY) && scroller.scrollHeight > scroller.clientHeight) break;
+    scroller = scroller.parentElement;
+  }
+  if (!scroller || scroller === document.body) {
+    anchor.scrollIntoView?.({ behavior: 'smooth', block: 'end' });
+    return;
+  }
+  const anchorRect = anchor.getBoundingClientRect();
+  const scrollerRect = scroller.getBoundingClientRect();
+  scroller.scrollTo?.({
+    top: scroller.scrollTop + anchorRect.bottom - scrollerRect.bottom + bottomGap,
+    behavior: 'smooth',
+  });
+}
+
+/** 在列表仍保持展开时回滚隐藏条目的高度，避免内容收缩触发 scrollTop 瞬间截断。 */
+export function scrollCardBy(anchor: HTMLElement, delta: number): void {
+  if (!delta) return;
+  let scroller = anchor.parentElement;
+  while (scroller && scroller !== document.body) {
+    const style = getComputedStyle(scroller);
+    if (/(auto|scroll|overlay)/.test(style.overflowY) && scroller.scrollHeight > scroller.clientHeight) break;
+    scroller = scroller.parentElement;
+  }
+  if (!scroller || scroller === document.body) {
+    anchor.scrollIntoView?.({ behavior: 'smooth', block: 'end' });
+    return;
+  }
+  scroller.scrollTo?.({ top: scroller.scrollTop + delta, behavior: 'smooth' });
+}

package/src/server/actions.ts

@@ -0,0 +1,217 @@
+/**
+ * promotion 写动作（015 S6：唯一写动作 acquire；execute 内预检 R3 + member.status 会员门禁）。
+ */
+import { randomUUID } from 'node:crypto';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import type { CardActionResult } from '@tbox.cn/app-contracts';
+import { memberGateCardOf, externalMemberRefOf, toMallQueryContext } from '@tbox.cn/app-contracts-mall';
+import type {
+  MemberGateCard,
+  MemberOutcome,
+  MemberStatusFactory,
+  PromotionEntitlementPort,
+  PromotionQueryContext,
+} from '@tbox.cn/app-contracts-mall';
+import { z } from 'zod';
+import { resolvePromotionAcquisitionPort, resolvePromotionEntitlementsPort } from './ports';
+import { entitlementSummary } from './tools';
+import type { PromotionRejectionKind } from '@tbox.cn/app-contracts-mall';
+
+async function listEntitlementsAfterAcquire(
+  service: PromotionEntitlementPort,
+  q: PromotionQueryContext,
+) {
+  // 厂商领取成功与券包可读存在短暂最终一致性窗口；有限重试后仍退回成功文案，
+  // 不把领取结果错误判定为失败，也避免无限等待动作请求。
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const page = await service.listEntitlements(q, { limit: 10 });
+    if (page.items.length > 0 || attempt === 2) return page;
+    await new Promise<void>((resolve) => setTimeout(resolve, 150));
+  }
+  return { items: [] };
+}
+
+/** 已知厂商码的语义兜底；上游提供 message 时不覆盖原文。 */
+export function classifyRejection(code?: string): { kind: PromotionRejectionKind; message: string } {
+  switch (code) {
+    case '30013':
+    case '30011':
+      return { kind: 'AUTH_FAILED', message: '会员登录已过期，请重新登录会员后再领取' };
+    case '636':
+    case '637':
+      return { kind: 'OUT_OF_STOCK', message: '券已被领完，可关注下次放量' };
+    case '638':
+      return { kind: 'ALREADY_ACQUIRED', message: '已领取过该券，可在「我的券」中查看' };
+    case '5113':
+      return { kind: 'ALREADY_ACQUIRED', message: '领取次数已达到上限' };
+    case '30017':
+      return { kind: 'NOT_ELIGIBLE', message: '不满足领取条件（如仅限特定等级会员）' };
+    default:
+      return { kind: 'UNKNOWN', message: '领取失败，请稍后重试' };
+  }
+}
+
+/** 卡片动作 execute 第二参（RequestContext）——门禁函数与 executeAcquire 共用 */
+type AcquireReqCtx = Parameters<NonNullable<Parameters<ServerContext['cardActions']['register']>[0]['execute']>>[1];
+
+/** acquire 会员门禁文案（active 放行不查表；表只建模拦截态） */
+const ACQUIRE_MEMBER_NOTICE = '领取需要会员身份，请先登录或办理入会后再领券';
+const ACQUIRE_ENROLL_NOTICE = '领取需要会员身份，办理入会后即可领券';
+const ACQUIRE_UNKNOWN_NOTICE = '暂时无法确认会员状态，请稍后再试';
+const ACQUIRE_GATE_COPY: Record<Exclude<MemberOutcome | 'unavailable', 'active'>, string> = {
+  unauthenticated: ACQUIRE_MEMBER_NOTICE,
+  not_enrolled: ACQUIRE_ENROLL_NOTICE,
+  closed: ACQUIRE_ENROLL_NOTICE,
+  unknown: ACQUIRE_UNKNOWN_NOTICE,
+  unavailable: ACQUIRE_UNKNOWN_NOTICE,
+};
+
+export function createPromotionActions(ctx: ServerContext): Record<string, Parameters<ServerContext['cardActions']['register']>[0]> {
+  type AcquireGate = { readonly blocked: string; readonly card?: MemberGateCard } | { readonly externalMemberRef: string };
+
+  /** 会员门禁：active 放行并解析厂商侧会员标识；其余态收口为引导文案。
+   *  软语义：unknown/unavailable 不断言「需要会员身份」——不误伤可能是会员的用户。 */
+  const resolveAcquireGate = async (reqCtx: AcquireReqCtx): Promise<AcquireGate> => {
+    const factory = ctx.services?.resolve?.('member.status') as MemberStatusFactory | undefined;
+    if (!factory) return { blocked: ACQUIRE_MEMBER_NOTICE }; // member 未装/旧版：版本偏斜兼容档
+    const status = await factory(reqCtx);
+    if (status.outcome !== 'active') {
+      // blocked 附卡：member-enrollment-cta / member-login-cta 由 TIER1 纯映射生成；
+      // 文案保留模块自有 ACQUIRE_GATE_COPY（写路径 fail-closed 语义，unknown/unavailable 也拦）
+      const card = memberGateCardOf(reqCtx?.identity?.userId ?? '', status);
+      return card ? { blocked: ACQUIRE_GATE_COPY[status.outcome], card } : { blocked: ACQUIRE_GATE_COPY[status.outcome] };
+    }
+    if (!status.account) {
+      ctx.logger?.warn('promotion.acquire：member.status active 缺账户快照（解析器原子性破坏）');
+      return { blocked: ACQUIRE_UNKNOWN_NOTICE };
+    }
+    const externalMemberRef = externalMemberRefOf(status.account) ?? '';
+    if (!externalMemberRef) {
+      ctx.logger?.warn('promotion.acquire：active 会员账户无厂商侧引用（真实卡号与 opaque 引用双缺）');
+      return { blocked: ACQUIRE_UNKNOWN_NOTICE };
+    }
+    return { externalMemberRef };
+  };
+
+  const executeAcquire = async (input: unknown, reqCtx: Parameters<NonNullable<Parameters<ServerContext['cardActions']['register']>[0]['execute']>>[1]): Promise<CardActionResult> => {
+    const { offerRef } = (input ?? {}) as { offerRef?: string };
+    const userId = reqCtx?.identity?.userId ?? '';
+    if (!offerRef || !userId || !reqCtx) {
+      // 失败态只回文字：SDK 在结果无卡时把 text 经 tbox:notice 下发为可见提示，
+      // 一句话说清原因即可，不值得为此再出一张卡
+      return { text: '领取失败：缺少优惠引用或身份' };
+    }
+
+    // 会员门禁（在幂等占位之前——门禁失败不产生占位）：member.status 判定会员态，
+    // active 经 externalMemberRefOf 取厂商侧会员标识（真实卡号优先）
+    const gate = await resolveAcquireGate(reqCtx);
+    if ('blocked' in gate) {
+      return gate.card
+        ? { card: { cardType: gate.card.cardType, data: gate.card.data }, text: gate.blocked }
+        : { text: gate.blocked };
+    }
+    const externalMemberRef = gate.externalMemberRef;
+
+    const q = toMallQueryContext(reqCtx);
+    // 双槽动作（017）：领取写 → promotion.acquisition；领后「我的券」列表 → promotion.entitlements
+    const service = await resolvePromotionAcquisitionPort(reqCtx, ctx);
+    // 每次用户明确点击都提交给 Provider；是否允许重复领取由厂商返回码决定。
+    // 仍使用随机幂等键，避免不同尝试共享上一次请求的 extend/operation 引用。
+    const idempotencyKey = randomUUID();
+
+    let operation: Awaited<ReturnType<typeof service.acquire>>;
+    try {
+      operation = await service.acquire(q, { offerRef, externalMemberRef, idempotencyKey });
+    } catch (e) {
+      // Code security: 不把第三方异常消息/响应原文写入线上日志，只保留可关联的类型与短键。
+      const errorType = e instanceof Error ? e.name : 'UnknownError';
+      ctx.logger?.warn(`领券请求异常 key=${idempotencyKey.slice(0, 8)}…：type=${errorType}`);
+      return { text: '领取请求失败，请稍后重试' };
+    }
+
+    if (operation.status === 'SUCCEEDED') {
+      // 领到手就把「我的券」推到面前：比一张只说"成功了"的结果卡更有用——
+      // 刚领的券连同券码、有效期一起可见，落点也正是用户接下来要去的地方。
+      // 列表查询失败不影响领取已成功这件事，退回文字提示即可。
+      try {
+        const entitlements = await resolvePromotionEntitlementsPort(reqCtx, ctx);
+        const page = await listEntitlementsAfterAcquire(entitlements, q);
+        if (page.items.length) {
+          return {
+            card: {
+              cardType: 'promotion-entitlement-list',
+              data: { mallId: q.scope.mallId, miniAppId: q.scope.miniAppId, items: page.items.map(entitlementSummary) },
+            },
+            text: '领取成功！已存入卡包',
+          };
+        }
+      } catch (e) {
+        ctx.logger?.warn(`领券成功但我的券列表查询失败：err=${(e as Error).message}`);
+      }
+      return { text: '领取成功！已存入卡包，可在「我的券」中查看' };
+    }
+    if (operation.status === 'PENDING_AUTHORITY') {
+      return { text: '领取已受理，正在确认结果，稍后可在「我的券」查看' };
+    }
+    const providerMessage = operation.message?.trim();
+    ctx.logger?.warn(`领券被厂商拒绝 code=${operation.code ?? 'unknown'} operation=${operation.operationRef.slice(0, 12)} message=${logText(providerMessage)}`);
+    // Code security: Provider business message is user-facing context; use the bounded SDK notice path.
+    // Keep the source-compatible semantic fallback only when the upstream response has no usable message;
+    // the raw provider code remains visible in either case.
+    const reason = providerMessage || classifyRejection(operation.code).message;
+    return { text: `领取失败：${reason}${operation.code ? `（code ${operation.code}）` : ''}` };
+  };
+
+  return {
+    acquire: {
+      actionId: 'promotion.acquire',
+      moduleId: 'promotion',
+      cardType: 'promotion-offer-detail',
+      label: '立即领取',
+      singleUse: true,
+      inputSchema: z.object({ offerRef: z.string().min(1) }),
+      execute: executeAcquire,
+    },
+    // 列表内浮层的领取入口：一张列表卡对应 N 张券，令牌必须可重复使用——
+    // singleUse 按 grantId 一次性消费，领完第一张后同卡其余券会全部撞 TOKEN_CONSUMED。
+    // 重复领同一张券由 provider 侧幂等兜底（已领会回一句文字提示）。
+    acquireFromList: {
+      actionId: 'promotion.acquire-from-list',
+      moduleId: 'promotion',
+      cardType: 'promotion-offer-list',
+      label: '领取',
+      singleUse: false,
+      inputSchema: z.object({ offerRef: z.string().min(1) }),
+      execute: executeAcquire,
+    },
+    // 门店券行领取入口（2026-09-02）：couponList 携 offerRef 的券——与优惠列表领取逐字同链路
+    // （executeAcquire 单源）。token 按 cardType 签发而注册表按 actionId 键控——两个卡上下文
+    // （shop-detail 卡直开 / shop-list 卡下钻浮层）= 两个变体 id；门店列表卡本体无领取按钮
+    // （按钮只在两个上下文打开的门店详情浮层券条目里）。
+    acquireFromShopDetail: {
+      actionId: 'promotion.acquire-from-shop-detail',
+      moduleId: 'promotion',
+      cardType: 'shop-detail',
+      label: '领取',
+      singleUse: false,
+      inputSchema: z.object({ offerRef: z.string().min(1) }),
+      execute: executeAcquire,
+    },
+    acquireFromShopList: {
+      actionId: 'promotion.acquire-from-shop-list',
+      moduleId: 'promotion',
+      cardType: 'shop-list',
+      label: '领取',
+      singleUse: false,
+      inputSchema: z.object({ offerRef: z.string().min(1) }),
+      execute: executeAcquire,
+    },
+  };
+}
+
+// Code security: external business text is bounded and JSON-escaped before entering a log line.
+function logText(value: unknown): string {
+  const text = typeof value === 'string' ? value : String(value ?? '');
+  const bounded = text.length > 200 ? `${text.slice(0, 200)}…` : text;
+  return JSON.stringify(bounded);
+}

package/src/server/cards/index.ts

@@ -0,0 +1,19 @@
+/** promotion 卡 meta 聚合：9 个稳定传输卡型，renderer 内覆盖多个展示语义。 */
+import promotionOfferList from './promotion-offer-list/meta';
+import promotionOfferDetail from './promotion-offer-detail/meta';
+import promotionEntitlementList from './promotion-entitlement-list/meta';
+import promotionActivityList from './promotion-activity-list/meta';
+import promotionActivityDetail from './promotion-activity-detail/meta';
+import promotionActivityCategoryList from './promotion-activity-category-list/meta';
+import promotionBestDeal from './promotion-best-deal/meta';
+
+export const promotionCards = {
+  'promotion-offer-list': promotionOfferList,
+  'promotion-offer-detail': promotionOfferDetail,
+  'promotion-entitlement-list': promotionEntitlementList,
+  'promotion-activity-list': promotionActivityList,
+  'promotion-activity-detail': promotionActivityDetail,
+  'promotion-activity-category-list': promotionActivityCategoryList,
+  'promotion-best-deal': promotionBestDeal,
+} as const;
+

package/src/server/cards/promotion-activity-category-list/meta.ts

@@ -0,0 +1,13 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionActivityCategoryListCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof promotionActivityCategoryListCardDataSchema> = {
+  cardType: 'promotion-activity-category-list',
+  dataSchema: promotionActivityCategoryListCardDataSchema,
+  displayName: '活动分类',
+  description: '商场活动分类入口',
+  sampleData: { items: [{ categoryId: 'family', name: '亲子' }, { categoryId: 'market', name: '市集' }] },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/promotion-activity-detail/meta.ts

@@ -0,0 +1,29 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionActivityDetailCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof promotionActivityDetailCardDataSchema> = {
+  cardType: 'promotion-activity-detail',
+  dataSchema: promotionActivityDetailCardDataSchema,
+  displayName: '活动详情',
+  description: '活动详情 + 场次 + 参与指南',
+  sampleData: {
+    presentation: 'detail',
+    activityRef: 'demo-act:3001',
+    title: '周末亲子市集',
+    subtitle: '会员限定体验',
+    categoryName: '亲子',
+    periodText: '8月22日 14:00',
+    location: '商场北座',
+    remainingQuota: 12,
+    registrationRequired: true,
+    registrationUrl: 'alipays://platformapi/startapp?appId=demo&page=v%2Fmarketing%2Factivity%2Fdetail%3Fid%3Ddemo-activity',
+    sessions: [{ sessionRef: 's_1', title: '第一场', startText: '周六 10:00', remainingQuota: 12, status: 'OPEN' }],
+    guideSteps: ['领取优惠券', '选择场次报名'],
+    guideItems: [{ title: '领取优惠券', description: '在会员中心完成资格校验' }, { title: '选择场次报名' }],
+    conditions: ['限会员本人参与'],
+  },
+  schemaVersion: 2,
+  migrate: (oldData) => oldData as Record<string, unknown>,
+};
+
+export default meta;

package/src/server/cards/promotion-activity-list/meta.ts

@@ -0,0 +1,13 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionActivityListCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof promotionActivityListCardDataSchema> = {
+  cardType: 'promotion-activity-list',
+  dataSchema: promotionActivityListCardDataSchema,
+  displayName: '活动列表',
+  description: '营销活动列表（报名要求 + 名额）',
+  sampleData: { items: [{ activityRef: 'demo-act:3001', title: '周末亲子市集', subtitle: '会员限定体验', categoryName: '亲子', registrationRequired: true, remainingQuota: 12, periodText: '8月22日 14:00', availabilityStatus: 'AVAILABLE' }] },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/promotion-best-deal/meta.ts

@@ -0,0 +1,20 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionBestDealCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof promotionBestDealCardDataSchema> = {
+  cardType: 'promotion-best-deal',
+  dataSchema: promotionBestDealCardDataSchema,
+  displayName: '优惠测算',
+  description: '优惠测算结果或备选建议',
+  sampleData: {
+    authoritative: true,
+    originalAmountCents: 20000,
+    savingsCents: 3000,
+    expectedPayCents: 17000,
+    appliedOfferRefs: ['demo:coupon:demo'],
+    message: '预计节省 30 元',
+  },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/promotion-entitlement-list/meta.ts

@@ -0,0 +1,17 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionEntitlementListCardDataSchema } from '@tbox.cn/app-contracts-mall';
+import { samples } from './samples';
+
+const meta: CardMeta<typeof promotionEntitlementListCardDataSchema> = {
+  cardType: 'promotion-entitlement-list',
+  dataSchema: promotionEntitlementListCardDataSchema,
+  displayName: '我的券',
+  description: '已领取资产列表（券码脱敏）',
+  sampleData: {
+    items: [{ entitlementRef: 'ent_1', title: '满 100 减 20 元券', entitlementType: 'COUPON', status: 'EFFECTIVE', codeMasked: 'AB**CD' }],
+  },
+  samples,
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/promotion-entitlement-list/samples.ts

@@ -0,0 +1,51 @@
+/**
+ * promotion-entitlement-list 附加预览样本（沉淀自 mall dev-gallery 我的券画廊）。
+ * 方法论：见同目录 ../promotion-offer-list/samples.ts 头注释。
+ */
+import type { CardSample } from '@tbox.cn/app-contracts';
+import type { PromotionEntitlementListCardData } from '@tbox.cn/app-contracts-mall';
+
+/** 券图占位：中性色块 + 品类色角标（与 offer-list 样本同族） */
+function couponImage(accent: string): string {
+  return 'data:image/svg+xml;utf8,'
+    + '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="180">'
+    + '<rect width="240" height="180" rx="12" fill="%23f2f4f7"/>'
+    + `<rect x="0" y="0" width="240" height="52" rx="12" fill="%23${accent}" opacity="0.85"/>`
+    + '<rect x="20" y="76" width="140" height="16" rx="4" fill="%23d5dae2"/>'
+    + '<rect x="20" y="104" width="96" height="12" rx="3" fill="%23e3e7ed"/>'
+    + '<circle cx="196" cy="128" r="26" fill="none" stroke="%23c6ccd6" stroke-width="4" stroke-dasharray="6 6"/>'
+    + '</svg>';
+}
+
+const IMG = {
+  coffee: couponImage('8a5a3b'),
+  lifestyle: couponImage('3d5a80'),
+  dining: couponImage('9e2b25'),
+} as const;
+
+export const samples: CardSample<PromotionEntitlementListCardData>[] = [
+  {
+    label: '我的券·状态矩阵',
+    note: '待使用、已使用、已过期三态及动作降级同屏',
+    group: '我的券',
+    data: {
+      items: [
+        { entitlementRef: 'ent:effective', title: '瑞幸咖啡｜30元饮品代金券', imageUrl: IMG.coffee, entitlementType: 'COUPON', status: 'EFFECTIVE', codeMasked: '**** 6688', benefitText: '¥30', thresholdText: '无门槛', usageNotice: '1F · 到店点单可用', validUntilText: '2026-09-27 到期' },
+        { entitlementRef: 'ent:used', title: 'KKV 120元优惠券', imageUrl: IMG.lifestyle, entitlementType: 'COUPON', status: 'USED', codeMasked: '**** 1058', benefitText: '¥105 · 8.8折', usageNotice: '已于 2026-08-26 使用', validUntilText: '已使用' },
+        { entitlementRef: 'ent:expired', title: '南京大牌档｜招牌菜品30元券', imageUrl: IMG.dining, entitlementType: 'COUPON', status: 'EXPIRED', benefitText: '¥30', usageNotice: '4F · 餐饮区', validUntilText: '已于 2026-08-20 过期' },
+      ],
+    },
+  },
+  {
+    label: '我的券·缺图长文案',
+    note: '无图片、长标题和 UNKNOWN 状态的容错形态',
+    group: '我的券',
+    data: { items: [{ entitlementRef: 'ent:unknown', title: '会员限定超长名称测试｜指定商户周末到店消费专享权益', entitlementType: 'COUPON', status: 'UNKNOWN', codeMasked: '**** 0000', benefitText: '满100减20', usageNotice: '使用门店和适用商品请以券详情说明为准', validUntilText: '有效期待品牌方确认' }] },
+  },
+  {
+    label: '我的券·空态',
+    note: '账户没有券时保留去领券的语义引导',
+    group: '我的券',
+    data: { items: [], noResultsReason: '还没有优惠券，先去看看本周神券吧' },
+  },
+];

package/src/server/cards/promotion-offer-detail/meta.ts

@@ -0,0 +1,25 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionOfferDetailCardDataSchema } from '@tbox.cn/app-contracts-mall';
+
+const meta: CardMeta<typeof promotionOfferDetailCardDataSchema> = {
+  cardType: 'promotion-offer-detail',
+  dataSchema: promotionOfferDetailCardDataSchema,
+  displayName: '优惠详情',
+  description: '优惠详情 + 领取（动作 promotion.acquire）',
+  sampleData: {
+    presentation: 'coupon',
+    offerRef: 'demo:coupon:1001',
+    title: '满 100 减 20 元券',
+    offerType: 'COUPON',
+    benefitText: '满 100 减 20',
+    subtitle: '会员专享',
+    validityText: '有效期至 2026-08-31',
+    rules: ['单笔满 100 可用', '限领 1 张'],
+    steps: [{ title: '领取优惠', description: '进入会员券包完成领取' }],
+    claimable: true,
+    caveats: ['优惠资格、库存和最终优惠以领取或使用时为准'],
+  },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/cards/promotion-offer-list/meta.ts

@@ -0,0 +1,20 @@
+import type { CardMeta } from '@tbox.cn/app-contracts';
+import { promotionOfferListCardDataSchema } from '@tbox.cn/app-contracts-mall';
+import { samples } from './samples';
+
+const meta: CardMeta<typeof promotionOfferListCardDataSchema> = {
+  cardType: 'promotion-offer-list',
+  dataSchema: promotionOfferListCardDataSchema,
+  displayName: '优惠列表',
+  description: '优惠、促销、券与推荐四种 legacy 展示语义',
+  sampleData: {
+    presentation: 'promotion',
+    mode: 'search',
+    summary: '本周值得关注的活动',
+    items: [{ offerRef: 'demo:promotion:1001', title: '会员夏日礼遇', subtitle: '限时会员专享', offerType: 'PROMOTION', benefitText: '满额赠礼', claimable: true, availabilityStatus: 'AVAILABLE', validityText: '有效期至 2026-08-31', tags: ['会员'] }],
+  },
+  samples,
+  schemaVersion: 1,
+};
+
+export default meta;