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

package/tests/cards-render.test.tsx

@@ -0,0 +1,656 @@
+// @vitest-environment happy-dom
+import { act } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { navigateToAlipayPage, sendCardAction } from '@tbox.cn/app-sdk/client';
+import {
+  PromotionActivityCategoryListCard,
+  PromotionActivityDetailCard,
+  PromotionActivityListCard,
+  PromotionBestDealCard,
+  PromotionEntitlementListCard,
+  PromotionOfferDetailCard,
+  PromotionOfferListCard,
+} from '../src/client/cards';
+import { sanitizeActivityHtml } from '../src/client/utils/sanitize-activity-html';
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock('@tbox.cn/app-sdk/client', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('@tbox.cn/app-sdk/client')>();
+  return { ...mod, navigateToAlipayPage: vi.fn(() => Promise.resolve()), sendCardAction: vi.fn() };
+});
+
+// 浮层 portal 到 body，用例间不清就会互相看见对方的残留
+afterEach(() => {
+  document.body.innerHTML = '';
+  vi.mocked(sendCardAction).mockReset();
+  vi.mocked(navigateToAlipayPage).mockReset();
+  vi.mocked(navigateToAlipayPage).mockResolvedValue(undefined);
+});
+
+function render(ui: React.ReactElement) {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  const root = createRoot(host);
+  act(() => root.render(ui));
+  return host;
+}
+
+const offer = {
+  offerRef: 'o1',
+  title: '满减会员券',
+  subtitle: '商场会员专享',
+  offerType: 'COUPON',
+  benefitText: '满 100 减 20',
+  claimable: true,
+  availabilityStatus: 'AVAILABLE',
+  validityText: '有效期至 2026-12-31',
+  tags: ['会员'],
+  itemActions: [{ kind: 'send', label: '查看详情', value: '查看「满减会员券」的优惠详情' }],
+} as const;
+
+const detail = {
+  offerRef: 'o1',
+  title: '满减会员券',
+  offerType: 'COUPON',
+  subtitle: '会员专享',
+  benefitText: '满 100 减 20',
+  validityText: '有效期至 2026-12-31',
+  rules: ['单笔订单限用一张'],
+  steps: [{ title: '领取优惠', description: '进入会员券包' }],
+  requirements: ['已登录会员'],
+  notice: '资格以厂商校验为准',
+  claimable: true,
+  caveats: ['库存实时变化'],
+} as const;
+
+const activity = {
+  activityRef: 'a1',
+  title: '周末会员手作',
+  subtitle: '限定体验',
+  categoryName: '亲子',
+  registrationRequired: true,
+  remainingQuota: 6,
+  periodText: '8月22日 14:00',
+  availabilityStatus: 'AVAILABLE',
+  itemActions: [{ kind: 'send', label: '查看活动详情', value: '查看「周末会员手作」的活动详情' }],
+} as const;
+
+const activityDetail = {
+  activityRef: 'demo-c:activity:100006450',
+  title: '周末会员手作',
+  subtitle: '限定体验',
+  categoryName: '亲子',
+  periodText: '8月22日 14:00',
+  location: '商场北座',
+  registrationRequired: true,
+  registrationUrl: 'alipays://platformapi/startapp?appId=demo&page=v%2Fmarketing%2Factivity%2Fdetail%3Fid%3Ddemo-activity',
+  remainingQuota: 6,
+  sessions: [{ sessionRef: 's1', title: '周六下午场', startText: '8月22日 14:00', remainingQuota: 6, status: 'OPEN' }],
+  guideSteps: ['验证会员身份'],
+  guideItems: [{ title: '验证会员身份', description: '到场出示会员码' }],
+  conditions: ['商场会员'],
+  notice: '当前仅展示参与说明',
+} as const;
+
+describe('legacy 19 个营销展示语义', () => {
+  it.each([
+    ['offer-list', 'offer', '活动与优惠'],
+    ['promotion-list', 'promotion', '本周营销活动'],
+    ['coupon-list', 'coupon', '商场神券'],
+  ] as const)('%s 恢复列表层级', (_name, presentation, text) => {
+    const host = render(<PromotionOfferListCard data={{ mode: 'search', presentation, items: [offer] } as never} cardId="c1" />);
+    expect(host.querySelector('.promotion-list__items')).not.toBeNull();
+    expect(host.textContent).toContain(text);
+    if (presentation === 'promotion') expect(host.querySelector('.promotion-list__hero')).not.toBeNull();
+  });
+
+  it('coupon-list 使用独立豌豆 IP 头图，并与活动中心共用标题排版', () => {
+    const host = render(<PromotionOfferListCard data={{ mode: 'claimable', presentation: 'coupon', items: [offer] } as never} cardId="c1" />);
+    const header = host.querySelector('.promotion-coupon__header');
+    expect(header?.textContent).toContain('商场神券');
+    expect(header?.textContent).toContain('当前商场 · 优惠精选');
+    expect(header?.classList.contains('promotion-activity__header--pea')).toBe(true);
+    // 素材变量链（主题轨 T-2.3）：coupon 头图经 CSS background + --tbox-asset-promotion-coupon-header；
+    // 资产值断言归构建链（css url 相对引用），渲染层断言 img 不再渲染（防回归）
+    expect(header?.querySelector('.promotion-activity__header-art')).toBeNull();
+  });
+
+  it('券列表默认最多展示 4 条，并支持查看更多/收起', () => {
+    const items = Array.from({ length: 6 }, (_, index) => ({ ...offer, offerRef: `offer-${index}`, title: `券${index}` }));
+    const host = render(<PromotionOfferListCard data={{ mode: 'claimable', presentation: 'coupon', items } as never} cardId="c1" />);
+    expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(6);
+    const toggle = host.querySelector('.promotion-list__toggle') as HTMLButtonElement;
+    expect(toggle.textContent).toContain('查看更多');
+    expect(host.querySelector('.promotion-list--offers')).not.toBeNull();
+    expect(toggle.firstChild?.nodeType).toBe(Node.TEXT_NODE);
+    expect(toggle.lastChild?.nodeName.toLowerCase()).toBe('svg');
+    expect(toggle.querySelector('svg')?.getAttribute('data-rotated')).toBeNull();
+    expect(toggle.getAttribute('aria-expanded')).toBe('false');
+    const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', { configurable: true, value: scrollIntoView });
+    vi.useFakeTimers();
+    try {
+      act(() => toggle.click());
+      expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(6);
+      expect(toggle.textContent).toContain('收起');
+      expect(toggle.querySelector('svg')?.getAttribute('data-rotated')).toBe('true');
+      expect(toggle.getAttribute('aria-expanded')).toBe('true');
+      expect(scrollIntoView).toHaveBeenCalledWith({ behavior: 'smooth', block: 'end' });
+      act(() => toggle.click());
+      act(() => vi.advanceTimersByTime(320));
+      expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(6);
+      expect(toggle.textContent).toContain('查看更多');
+      expect(scrollIntoView).toHaveBeenCalledTimes(2);
+    } finally {
+      vi.useRealTimers();
+      if (originalScrollIntoView) Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', { configurable: true, value: originalScrollIntoView });
+      else delete (HTMLElement.prototype as { scrollIntoView?: unknown }).scrollIntoView;
+    }
+  });
+
+  it('recommendation 恢复推荐主视觉、依据和候选', () => {
+    const host = render(<PromotionOfferListCard data={{ mode: 'recommend', presentation: 'recommendation', summary: '综合资格和优惠力度', items: [offer, { ...offer, offerRef: 'o2' }] } as never} cardId="c1" />);
+    expect(host.querySelector('.promotion-recommendation__main')).not.toBeNull();
+    expect(host.querySelector('.promotion-recommendation__reason')?.textContent).toContain('推荐依据');
+    expect(host.textContent).toContain('另有 1 个候选优惠');
+  });
+
+  it.each([
+    ['offer-detail', 'offer'],
+    ['promotion-detail', 'promotion'],
+    ['coupon-detail', 'coupon'],
+  ] as const)('%s 恢复 hero、玻璃利益点和规则', (_name, presentation) => {
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation } as never} />);
+    expect(host.querySelector('.promotion-detail__hero')).not.toBeNull();
+    expect(host.querySelector('.promotion-detail__glass')?.textContent).toContain('满 100 减 20');
+    expect(host.querySelector('.promotion-detail__rules')).not.toBeNull();
+  });
+
+  it('package-detail 恢复礼包子权益', () => {
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'package', offerType: 'BUNDLE', bundleItems: [{ name: '停车券', quantity: 2 }] } as never} />);
+    expect(host.querySelector('.promotion-detail__bundle')?.textContent).toContain('停车券');
+  });
+
+  it('coupon detail 可选展示适用门店且不影响历史字段', () => {
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon', claimable: false, stores: [{ storeId: 's1', storeName: '南京大排档', floor: '1F', address: '北区' }] } as never} />);
+    expect(host.querySelector('.promotion-detail__stores')?.textContent).toContain('南京大排档');
+    expect(host.querySelector('.promotion-detail__stores')?.textContent).toContain('1F');
+  });
+
+  it('promotion-guide 恢复步骤、要求和参与方式', () => {
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'promotion-guide', participationMode: 'CLAIM_THEN_PURCHASE' } as never} />);
+    expect(host.querySelector('.promotion-guide__summary')?.textContent).toContain('先领券');
+    expect(host.querySelector('.promotion-guide__requirements')).not.toBeNull();
+  });
+
+  it('entitlement-list 恢复钱包、状态、券码和安全提示', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [{ entitlementRef: 'e1', title: '停车券', entitlementType: 'COUPON', status: 'EFFECTIVE', codeMasked: '****8888', validUntilText: '有效期至 2026-12-31' }] } as never} cardId="c1" />);
+    expect(host.querySelector('.promotion-entitlements')?.classList.contains('promotion-list--coupon')).toBe(true);
+    expect(host.querySelector('.promotion-list--offers')).toBeNull();
+    expect(host.querySelector('.promotion-coupon__header')?.textContent).toContain('我的优惠券');
+    expect(host.querySelector('.promotion-coupon__header')?.textContent).toContain('当前账户 · 券包权益');
+    expect(host.querySelector('.promotion-activity__header-art')).toBeNull(); // 素材变量链：头图 img 已转 CSS background
+    // 券码不再摊在行上：一屏几张券，脱敏码谁也用不上，点开浮层才需要
+    expect(host.querySelector('.promotion-coupon-row')?.textContent).not.toContain('****8888');
+    expect(host.querySelector('.promotion-coupon-row')?.textContent).not.toContain('2026-12-31');
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    expect(document.querySelector('.promotion-sheet')?.textContent).toContain('****8888');
+    expect(document.querySelector('.promotion-sheet')?.textContent).toContain('2026-12-31');
+    expect(host.querySelector('.promotion-card__footer')).toBeNull();
+  });
+
+  it('我的优惠券默认最多展示 4 条，maxItems 可配置', () => {
+    const items = Array.from({ length: 5 }, (_, index) => ({
+      entitlementRef: `e${index}`,
+      title: `优惠券${index}`,
+      entitlementType: 'COUPON',
+      status: 'EFFECTIVE',
+    }));
+    const host = render(<PromotionEntitlementListCard data={{ items } as never} cardId="c1" />);
+    expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(5);
+    const toggle = host.querySelector('.promotion-list__toggle') as HTMLButtonElement;
+    act(() => toggle.click());
+    expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(5);
+
+    const custom = render(<PromotionEntitlementListCard data={{ items, maxItems: 2 } as never} cardId="c2" />);
+    expect(custom.querySelectorAll('.promotion-coupon-row')).toHaveLength(5);
+  });
+
+  it('best-deal 恢复预计实付 hero 和三项指标', () => {
+    const host = render(<PromotionBestDealCard data={{ authoritative: true, originalAmountCents: 20000, savingsCents: 3000, expectedPayCents: 17000, appliedOfferRefs: ['o1'] }} />);
+    expect(host.querySelector('.promotion-deal__hero')?.textContent).toContain('170.00');
+    expect(host.querySelectorAll('.promotion-deal__metrics > span')).toHaveLength(3);
+  });
+
+  it('activity-category-list 恢复双列图标入口', () => {
+    const host = render(<PromotionActivityCategoryListCard data={{ items: [{ categoryId: 'family', name: '亲子' }] }} />);
+    expect(host.querySelector('.promotion-activity__categories')?.textContent).toContain('发现精彩活动');
+    expect(host.querySelector('.promotion-activity__category-icon')).not.toBeNull();
+  });
+
+  it('activity-list 使用稳定活动中心头图，并保留业务封面、状态、日期和余量', () => {
+    const host = render(<PromotionActivityListCard data={{ items: [{ ...activity, coverUrl: 'https://example.com/activity.png' }] } as never} cardId="c1" />);
+    expect(host.querySelector('.promotion-activity__header')?.textContent).toContain('活动中心');
+    expect(host.querySelector('.promotion-activity__header')?.textContent).toContain('发现商场近期精彩活动');
+    // 素材变量链（主题轨 T-2.3）：活动中心头图经 CSS background + --tbox-asset-promotion-activity-header；
+    // 业务封面仍只在条目缩略图（下方 thumb 断言），头图 img 不再渲染
+    expect(host.querySelector('.promotion-activity__header-art')).toBeNull();
+    expect(host.querySelector('.promotion-activity__hero')).toBeNull();
+    expect(host.textContent).not.toContain('MEMBER PICKS');
+    expect(host.textContent).not.toContain('本周会员精选');
+    expect(host.querySelector('.promotion-activity__list')?.textContent).toContain('仅余 6 席');
+    const thumb = host.querySelector('.promotion-activity__thumb');
+    expect(thumb?.getAttribute('src')).toBe('https://example.com/activity.png');
+    expect(thumb?.getAttribute('loading')).toBe('eager');
+    const row = host.querySelector('.promotion-activity__list > button') as HTMLButtonElement;
+    expect(row).not.toBeNull();
+    expect(host.querySelector('.promotion-activity__list .promotion-chip')).toBeNull();
+    act(() => row.click());
+    expect(vi.mocked(sendCardAction)).toHaveBeenCalledWith('c1', {
+      type: 'sendMessage',
+      value: activity.itemActions[0].value,
+      visible: true,
+    });
+  });
+
+  it('activity-list 空态仍展示同一活动中心标题', () => {
+    const host = render(<PromotionActivityListCard data={{ items: [], noResultsReason: '近期暂无活动' }} />);
+    expect(host.querySelector('.promotion-activity__header')?.textContent).toContain('活动中心');
+    expect(host.querySelector('.promotion-activity__header--pea')).not.toBeNull(); // 空态仍保留品牌头容器（素材经 CSS background）
+    expect(host.querySelector('.promotion-card__empty')?.textContent).toContain('近期暂无活动');
+  });
+
+  it('activity-detail 恢复封面、时间名额、地点和会员礼遇', () => {
+    const host = render(<PromotionActivityDetailCard data={{ ...activityDetail, presentation: 'detail' } as never} cardId="activity-card" />);
+    expect(host.querySelector('.promotion-activity__cover-meta')?.textContent).toContain('会员专享体验');
+    expect(host.querySelector('.promotion-activity__spotlight')).not.toBeNull();
+    expect(host.querySelector('.promotion-activity__venue')?.textContent).toContain('商场北座');
+    expect(host.querySelector('.promotion-activity__detail-notice')?.textContent).toContain('当前仅展示参与说明');
+    const register = host.querySelector('.promotion-activity__register') as HTMLButtonElement;
+    expect(register.textContent).toContain('去支付宝报名');
+    act(() => register.click());
+    expect(vi.mocked(sendCardAction)).toHaveBeenCalledWith('activity-card', {
+      type: 'openLink',
+      url: activityDetail.registrationUrl,
+    });
+  });
+
+  it('activity-schedule 恢复场次编号和实时名额', () => {
+    const host = render(<PromotionActivityDetailCard data={{ ...activityDetail, presentation: 'schedule' } as never} />);
+    expect(host.querySelector('.promotion-activity__session-summary')?.textContent).toContain('实时名额');
+    expect(host.querySelector('.promotion-activity__sessions')?.textContent).toContain('01');
+  });
+
+  it('activity-guide 恢复 HOW TO JOIN、步骤和参与条件', () => {
+    const host = render(<PromotionActivityDetailCard data={{ ...activityDetail, presentation: 'guide' } as never} />);
+    expect(host.querySelector('.promotion-activity__guide-banner')?.textContent).toContain('HOW TO JOIN');
+    expect(host.querySelector('.promotion-activity__requirements')?.textContent).toContain('商场会员');
+  });
+});
+
+describe('优惠券链路视觉状态语义', () => {
+  it('可领券列表：只列可领的券，商户图与售价行齐备', () => {
+    const host = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      summary: '当前商场 · 优惠精选',
+      items: [
+        { ...offer, subtitle: '2026-09-01 00:00:00 至 2026-09-15 23:59:59', imageUrl: 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg"/>', benefitText: '¥30', tags: ['TOP1', '餐饮', '周末可用'] },
+        { ...offer, offerRef: 'o2', title: '超长商户名称与优惠说明用于验证窄屏折行稳定性', imageUrl: undefined, claimable: false, availabilityStatus: 'UNAVAILABLE' },
+      ],
+    } as never} cardId="coupon-list" />);
+
+    // 领不了的券不进列表：列出来用户点一次才知道点不动
+    expect(host.querySelectorAll('.promotion-list__items > article')).toHaveLength(1);
+    const row = host.querySelector('.promotion-coupon-row') as HTMLElement;
+    expect(row.getAttribute('role')).toBe('button');
+    expect(row.querySelector('.promotion-item-actions--coupon > .promotion-chip--coupon')?.textContent).toBe('领取');
+    expect(row.querySelector('button')).toBeNull();
+    expect(row.querySelector('img')?.getAttribute('alt')).toBe('满减会员券');
+    expect(host.textContent).toContain('¥30');
+    expect(host.querySelector('.promotion-coupon-row__tags')?.textContent).not.toContain('TOP1');
+    expect(host.querySelector('.promotion-coupon-row__tags')?.textContent).toContain('餐饮');
+    expect(row.querySelector('.promotion-coupon-row__sub')).toBeNull();
+    expect(row.textContent).not.toContain('2026-09-01');
+    expect(host.textContent).not.toContain('超长商户名称');
+    // 参考设计里没有「可领取/不可领」文字标签，也没有类目角标
+    expect(host.textContent).not.toContain('不可领');
+    expect(host.querySelector('.promotion-card__footer')).toBeNull();
+    act(() => row.click());
+    expect(document.body.textContent).toContain('有效期至 2026-12-31');
+  });
+
+  it('可领券列表保留非时间型的辅助说明', () => {
+    const host = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      items: [{ ...offer, subtitle: '商场会员专享' }],
+    } as never} cardId="coupon-list" />);
+    expect(host.querySelector('.promotion-coupon-row__sub')?.textContent).toBe('商场会员专享');
+  });
+
+  it('商场券和我的券缺图时共用居中的缩略图兜底', () => {
+    const offerHost = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      items: [{ ...offer, imageUrl: undefined }],
+    } as never} cardId="coupon-list" />);
+    const entitlementHost = render(<PromotionEntitlementListCard data={{
+      items: [{ entitlementRef: 'e1', title: '缺图优惠券', entitlementType: 'COUPON', status: 'EFFECTIVE' }],
+    } as never} cardId="entitlements" />);
+
+    for (const host of [offerHost, entitlementHost]) {
+      const fallback = host.querySelector('.promotion-coupon-row__thumb.promotion-image--fallback');
+      expect(fallback).not.toBeNull();
+      expect(fallback?.querySelector('svg')).not.toBeNull();
+    }
+  });
+
+  it('券详情只在可领取且有动作令牌时提交权威领取动作', () => {
+    vi.mocked(sendCardAction).mockClear();
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon' } as never} cardId="coupon-detail" actionTokens={{ 'promotion.acquire': 'token' }} />);
+    const claim = [...host.querySelectorAll('button')].find((button) => button.textContent === '立即领取') as HTMLButtonElement;
+    expect(claim).not.toBeUndefined();
+    act(() => claim.click());
+    expect(vi.mocked(sendCardAction)).toHaveBeenCalledWith(
+      'coupon-detail',
+      { type: 'moduleAction', actionId: 'promotion.acquire', contextToken: 'token' },
+      { offerRef: 'o1' },
+    );
+    expect(claim.disabled).toBe(true);
+    expect(claim.textContent).toBe('领取中…');
+    act(() => window.dispatchEvent(new CustomEvent('tbox:notice', {
+      detail: { level: 'info', text: '领取成功！已存入卡包', surfaceId: 'coupon-detail' },
+    })));
+    expect(claim.disabled).toBe(true);
+    expect(claim.textContent).toBe('已领取');
+    expect(host.textContent).toContain('领取成功！已存入卡包');
+
+    // 详情卡只在当前组件生命周期内保留已领取；历史卡重新挂载后恢复领取按钮
+    const remounted = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon' } as never} cardId="coupon-detail" actionTokens={{ 'promotion.acquire': 'token' }} />);
+    expect([...remounted.querySelectorAll('button')].some((button) => button.textContent === '立即领取')).toBe(true);
+
+    const missingToken = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon' } as never} cardId="coupon-detail-without-token" />);
+    expect([...missingToken.querySelectorAll('button')].some((button) => button.textContent === '立即领取')).toBe(false);
+
+    // 不可领时不渲染写动作，哪怕令牌在手
+    const unavailable = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon', claimable: false } as never} cardId="unavailable-detail" actionTokens={{ 'promotion.acquire': 'token' }} />);
+    expect([...unavailable.querySelectorAll('button')].some((button) => button.textContent === '立即领取')).toBe(false);
+  });
+
+  it('付费券详情通过 openLink 唤起购买页，不签发领取动作', () => {
+    vi.mocked(sendCardAction).mockClear();
+    const purchaseUrl = 'alipays://platformapi/startapp?appId=demo&page=pages%2Fcoupon%2Fdetail%3Fid%3Dpaid-2';
+    const host = render(<PromotionOfferDetailCard data={{ ...detail, presentation: 'coupon', claimActionLabel: '抢购', purchaseUrl } as never} cardId="paid-detail" actionTokens={{ 'promotion.acquire': 'token' }} />);
+    const purchase = [...host.querySelectorAll('button')].find((button) => button.textContent === '去小程序抢购') as HTMLButtonElement;
+    act(() => purchase.click());
+    expect(vi.mocked(navigateToAlipayPage)).toHaveBeenCalledWith(purchaseUrl);
+  });
+
+  it('历史券列表可回看浮层，但领取动作禁用', () => {
+    const host = render(<PromotionOfferListCard data={{ mode: 'claimable', presentation: 'coupon', items: [offer] } as never} cardId="history-list" isHistory />);
+    const row = host.querySelector('.promotion-coupon-row') as HTMLElement;
+    act(() => row.click());
+    // 浮层 portal 到 body：历史卡无令牌，退回 ItemActionsRow 且整体禁用
+    const claim = [...document.querySelectorAll('.promotion-sheet button')].find((b) => b.textContent === '查看详情') as HTMLButtonElement;
+    expect(claim.disabled).toBe(true);
+
+    const sheet = document.querySelector('.promotion-sheet') as HTMLElement;
+    const close = sheet.querySelector('[aria-label="关闭详情"]') as HTMLButtonElement;
+    act(() => close.click());
+    expect(sheet.classList.contains('promotion-sheet--closing')).toBe(true);
+    expect(document.querySelector('.promotion-sheet')).not.toBeNull();
+    act(() => sheet.dispatchEvent(new Event('animationend', { bubbles: true })));
+    expect(document.querySelector('.promotion-sheet')).toBeNull();
+  });
+
+  it('券列表浮层的领取按钮直接触发写动作，不绕发消息', () => {
+    const host = render(
+      <PromotionOfferListCard
+        data={{ mode: 'claimable', presentation: 'coupon', items: [{ ...offer, claimActionLabel: '领取', freeCouponClaimMode: 'DIRECT' }] } as never}
+        cardId="list-1"
+        actionTokens={{ 'promotion.acquire-from-list': 'list-token' }}
+      />,
+    );
+    // 行上的「抢购」只是浮层入口：整行才是可交互控件，行内不该再有按钮
+    expect(host.querySelectorAll('.promotion-coupon-row button').length).toBe(0);
+    const row = host.querySelector('.promotion-coupon-row') as HTMLElement;
+    act(() => row.click());
+    const claim = [...document.querySelectorAll('.promotion-sheet button')].find((b) => b.textContent === '领取') as HTMLButtonElement;
+    act(() => claim.click());
+    expect(vi.mocked(sendCardAction)).toHaveBeenCalledWith(
+      'list-1',
+      { type: 'moduleAction', actionId: 'promotion.acquire-from-list', contextToken: 'list-token' },
+      { offerRef: 'o1' },
+    );
+    // 动作发出后保留领取中态，服务端成功后会另行推送我的券包卡
+    expect(document.querySelector('.promotion-sheet')).not.toBeNull();
+    expect(claim.disabled).toBe(true);
+    expect(claim.textContent).toContain('领取中');
+    act(() => window.dispatchEvent(new CustomEvent('tbox:notice', {
+      detail: { level: 'error', text: '领取失败，请稍后重试', surfaceId: 'list-1' },
+    })));
+    expect(claim.disabled).toBe(false);
+    expect(claim.textContent).toContain('领取');
+    act(() => claim.click());
+    act(() => window.dispatchEvent(new CustomEvent('tbox:notice', {
+      detail: { level: 'info', text: '领取成功！已存入卡包', surfaceId: 'list-1' },
+    })));
+    const claimed = [...document.querySelectorAll('.promotion-sheet button')].find((b) => b.textContent === '已领取') as HTMLButtonElement;
+    expect(claimed).not.toBeUndefined();
+    expect(claimed.disabled).toBe(true);
+
+    const sheet = document.querySelector('.promotion-sheet') as HTMLElement;
+    const close = sheet.querySelector('[aria-label="关闭详情"]') as HTMLButtonElement;
+    act(() => close.click());
+    act(() => sheet.dispatchEvent(new Event('animationend', { bubbles: true })));
+    expect(document.querySelector('.promotion-sheet')).toBeNull();
+
+    act(() => row.click());
+    const reopened = [...document.querySelectorAll('.promotion-sheet button')].find((b) => b.textContent === '领取') as HTMLButtonElement;
+    expect(reopened).not.toBeUndefined();
+    expect(reopened.disabled).toBe(false);
+  });
+
+  it('免费券 redirect 仍由列表行打开详情，再复用抢购 openLink 动作；历史卡保持可点击', () => {
+    const purchaseUrl = 'alipays://platformapi/startapp?appId=demo&page=pages%2Fcoupon%2Fdetail%2Findex%3FcouponNo%3Dfree-1%26plazaId%3Dmall-1';
+    const host = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      items: [{ ...offer, freeCouponClaimMode: 'REDIRECT', purchaseUrl }],
+    } as never} cardId="redirect-list" isHistory actionTokens={{ 'promotion.acquire-from-list': 'must-not-use' }} />);
+    expect(host.querySelectorAll('.promotion-coupon-row button')).toHaveLength(0);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    expect(sendCardAction).not.toHaveBeenCalled();
+    const claim = [...document.querySelectorAll<HTMLButtonElement>('.promotion-sheet button')]
+      .find((button) => button.textContent === '去小程序领取') as HTMLButtonElement;
+    expect(claim.disabled).toBe(false);
+    act(() => claim.click());
+    expect(vi.mocked(navigateToAlipayPage)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(navigateToAlipayPage)).toHaveBeenCalledWith(purchaseUrl);
+  });
+
+  it('免费券 redirect 缺跳链时禁用，且不回退既有写动作', () => {
+    const host = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      items: [{ ...offer, freeCouponClaimMode: 'REDIRECT' }],
+    } as never} cardId="redirect-missing" actionTokens={{ 'promotion.acquire-from-list': 'must-not-use' }} />);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    const claim = [...document.querySelectorAll<HTMLButtonElement>('.promotion-sheet button')]
+      .find((button) => button.textContent === '领取链接暂不可用') as HTMLButtonElement;
+    expect(claim.disabled).toBe(true);
+    act(() => claim.click());
+    expect(sendCardAction).not.toHaveBeenCalled();
+  });
+
+  it('付费券在浮层内通过 openLink 唤起小程序购买页', () => {
+    vi.mocked(sendCardAction).mockClear();
+    const purchaseUrl = 'alipays://platformapi/startapp?appId=demo&page=pages%2Fcoupon%2Fdetail%3Fid%3Dpaid-1';
+    const host = render(<PromotionOfferListCard data={{
+      mode: 'claimable',
+      presentation: 'coupon',
+      items: [{ ...offer, claimActionLabel: '抢购', purchaseUrl, freeCouponClaimMode: 'DIRECT' }],
+    } as never} cardId="paid-list" isHistory />);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    const purchase = [...document.querySelectorAll('.promotion-sheet button')].find((b) => b.textContent === '去小程序抢购') as HTMLButtonElement;
+    expect(purchase).not.toBeUndefined();
+    expect(purchase.disabled).toBe(false);
+    act(() => purchase.click());
+    expect(vi.mocked(navigateToAlipayPage)).toHaveBeenCalledWith(purchaseUrl);
+  });
+
+  it('我的券稳定区分待使用、已使用、已过期，并保留脱敏券码', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [
+      { entitlementRef: 'e1', title: '饮品券', entitlementType: 'COUPON', status: 'EFFECTIVE', codeMasked: '****6688', benefitText: '¥30' },
+      { entitlementRef: 'e2', title: '零售券', entitlementType: 'COUPON', status: 'USED', validUntilText: '已使用' },
+      { entitlementRef: 'e3', title: '餐饮券', entitlementType: 'COUPON', status: 'EXPIRED', validUntilText: '已过期' },
+    ] } as never} cardId="entitlements" />);
+
+    expect(host.querySelectorAll('.promotion-coupon-row')).toHaveLength(3);
+    expect(host.textContent).toContain('去使用');
+    expect(host.textContent).toContain('已使用');
+    expect(host.textContent).toContain('已过期');
+    const usableAction = host.querySelector('.promotion-owned-action:not(.promotion-chip--coupon-off)');
+    expect(usableAction?.textContent).toBe('去使用');
+    expect(usableAction?.classList.contains('promotion-chip')).toBe(true);
+    // 不可再用的券右侧退成中性灰，不与「去使用」同色
+    expect(host.querySelectorAll('.promotion-owned-action.promotion-chip--coupon-off')).toHaveLength(2);
+    expect(host.querySelectorAll('.promotion-coupon-row__state--used, .promotion-coupon-row__state--expired')).toHaveLength(2);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    expect(document.querySelector('.promotion-sheet')?.textContent).toContain('****6688');
+  });
+
+  it('我的券详情展示券码并支持复制', async () => {
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText: vi.fn().mockResolvedValue(undefined) } });
+    const host = render(<PromotionEntitlementListCard data={{ items: [{ entitlementRef: 'e-copy', title: '券', entitlementType: 'COUPON', status: 'EFFECTIVE', code: 'ABC-1234', stores: [{ storeId: 's1', storeName: '商户门店', imageUrl: 'https://cdn.example/store.png' }] }] } as never} />);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    expect(document.querySelector('.promotion-sheet')?.textContent).toContain('ABC-1234');
+    expect(document.querySelector('.promotion-sheet__store')?.textContent).toContain('商户门店');
+    const copy = document.querySelector('.promotion-sheet__copy') as HTMLButtonElement;
+    await act(async () => { copy.click(); });
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith('ABC-1234');
+  });
+
+  it('我的券详情按原生结构展示须知保障、使用字段和适用商家', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [{
+      entitlementRef: 'e-native-detail',
+      title: 'Coolhut满300-50',
+      entitlementType: 'COUPON',
+      status: 'EFFECTIVE',
+      code: '279353609701670310',
+      usageNotice: '周一至周日可用',
+      guaranteeText: '随时退·过期自动退',
+      usageSceneText: '小程序扫码买单',
+      validityText: '有效期 2026-08-29 15:50:16 至 2026-08-31 23:59:59',
+      usageTimeText: '00:00:00 至 23:59:59',
+      thresholdText: '满300元可用',
+      claimTimeText: '2026-08-29 15:50:16 至 2026-08-31 23:59:59',
+      usageRuleText: '<p>不可与其他优惠叠加使用</p>',
+      stores: [{ storeId: 's1', storeName: 'Coolhut（杭州拱墅万达店）', floor: '1F-1012B', address: '杭行路666号1F' }], // guard-vendor-neutrality: allow
+    }] } as never} />);
+
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    const sheet = document.querySelector('.promotion-sheet') as HTMLElement;
+    expect(sheet.querySelector('.promotion-sheet__notice-strip')?.textContent).toContain('须知周一至周日可用');
+    expect(sheet.querySelector('.promotion-sheet__notice-strip')?.textContent).toContain('保障随时退·过期自动退');
+    expect([...sheet.querySelectorAll('.promotion-sheet__facts dt')].map((node) => node.textContent)).toEqual([
+      '使用场景', '有效期', '使用时间', '使用限制', '可领取时间', '使用规则',
+    ]);
+    expect(sheet.querySelector('.promotion-sheet__facts')?.textContent).toContain('小程序扫码买单');
+    expect(sheet.querySelector('.promotion-sheet__facts')?.textContent).toContain('满300元可用');
+    expect(sheet.querySelector('.promotion-sheet__stores')?.textContent).toContain('Coolhut（杭州拱墅万达店）'); // guard-vendor-neutrality: allow
+    expect(sheet.querySelector('.promotion-sheet__stores')?.textContent).toContain('1F-1012B');
+  });
+
+});
+
+describe('usageNotice 富文本安全渲染', () => {
+  it('券行富文本按 HTML 渲染换行，脚本面被剥离', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [{
+      entitlementRef: 'e-notice',
+      title: '满减券',
+      entitlementType: 'COUPON',
+      status: 'EFFECTIVE',
+      usageNotice: '满100减20<br>全场通用<script>alert(1)</script>',
+    }] } as never} cardId="c1" />);
+    const sub = host.querySelector('.promotion-coupon-row__sub') as HTMLElement;
+    // <br> 以标签形态进 DOM（换行生效），而不是字面文本
+    expect(sub.innerHTML).toContain('<br>');
+    expect(sub.textContent).not.toContain('<br>');
+    expect(sub.innerHTML).not.toContain('<script');
+    expect(sub.textContent).not.toContain('alert');
+  });
+
+  it('券行富文本中的事件属性被剥离', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [{
+      entitlementRef: 'e-img',
+      title: '饮品券',
+      entitlementType: 'COUPON',
+      status: 'EFFECTIVE',
+      usageNotice: '到店点单可用<img src="x" onerror="alert(1)">',
+    }] } as never} cardId="c1" />);
+    const sub = host.querySelector('.promotion-coupon-row__sub') as HTMLElement;
+    expect(sub.innerHTML).not.toContain('onerror');
+    expect(sub.querySelector('img')).not.toBeNull();
+  });
+
+  it('浮层「使用规则」同样净化：排版保留、script 剥离', () => {
+    const host = render(<PromotionEntitlementListCard data={{ items: [{
+      entitlementRef: 'e-sheet',
+      title: '餐饮券',
+      entitlementType: 'COUPON',
+      status: 'EFFECTIVE',
+      usageRuleText: '<b>周一至周日</b>可用<script>alert(1)</script>',
+    }] } as never} cardId="c1" />);
+    act(() => (host.querySelector('.promotion-coupon-row') as HTMLElement).click());
+    const dd = document.querySelector('.promotion-sheet__facts dd') as HTMLElement;
+    expect(dd.innerHTML).toContain('<b>周一至周日</b>');
+    expect(dd.innerHTML).not.toContain('<script');
+    expect(dd.textContent).not.toContain('alert');
+  });
+});
+
+describe('sanitizeActivityHtml（活动规则富文本过滤）', () => {
+  it('剥离 script/iframe/style/svg 与事件属性，保留正文文本', () => {
+    const out = sanitizeActivityHtml(
+      '<p onclick="evil()">文案</p><script>alert(1)</script><iframe src="https://x"></iframe><style>body{}</style><svg onload="alert(1)"><circle/></svg>',
+    );
+    expect(out).toContain('文案');
+    expect(out).not.toContain('<script');
+    expect(out).not.toContain('<iframe');
+    expect(out).not.toContain('<style');
+    expect(out).not.toContain('<svg');
+    expect(out).not.toContain('onclick');
+  });
+
+  it('剥离 javascript: 协议与非 image data: 协议链接，保留正常 href', () => {
+    const out = sanitizeActivityHtml(
+      '<a href="javascript:evil()">a</a><a href="data:text/html;base64,x">b</a><a href="https://ok.example">c</a><img src="data:image/png;base64,x" alt="" />',
+    );
+    expect(out).not.toContain('javascript:');
+    expect(out).not.toContain('data:text/html');
+    expect(out).toContain('https://ok.example');
+    expect(out).toContain('data:image/png');
+  });
+
+  it('HTML entity 混淆的 javascript: 协议被剥离（DOMParser 先解码）', () => {
+    expect(sanitizeActivityHtml('<a href="&#106;avascript:alert(1)">x</a>')).not.toContain('javascript:');
+  });
+
+  it('formaction / xlink:href / srcdoc 等次要 URL 载体同样剥离', () => {
+    expect(sanitizeActivityHtml('<button formaction="javascript:alert(1)">x</button>')).not.toContain('formaction');
+    expect(sanitizeActivityHtml('<iframe srcdoc="<script>alert(1)</script>"></iframe>')).not.toContain('srcdoc');
+    // svg 整体丢弃 → xlink 载体不存在
+    expect(sanitizeActivityHtml('<svg><a xlink:href="javascript:alert(1)"><text>x</text></a></svg>')).not.toContain('svg');
+  });
+
+  it('保留富文本排版（加粗/换行/内联样式）', () => {
+    const out = sanitizeActivityHtml('<p><b>满减</b><br/><span style="color:#E84749">2</span>元</p>');
+    expect(out).toContain('<b>满减</b>');
+    expect(out).toContain('color:#E84749');
+  });
+});