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

package/src/client/cards/promotion-entitlement-list/index.tsx

@@ -0,0 +1,163 @@
+import { CalendarBlank, CaretDown, Copy, MapPinLine, NavigationArrow, ShieldCheck, Ticket } from '@phosphor-icons/react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { callJsapi, httpGet } from '@tbox.cn/app-sdk/client';
+import type { PromotionEntitlementListCardData } from '@tbox.cn/app-contracts-mall';
+import { CouponSheet } from '../../components/CouponSheet';
+import { CouponBarcode, CouponQrCode } from '../../components/CouponQrCode';
+import type { SheetFact } from '../../components/CouponSheet';
+import { ImageWithFallback } from '../../components/ImageWithFallback';
+import couponHeaderArtUrl from '../../assets/promotion-coupon-header-pea-v1.jpg';
+import { sanitizeActivityHtml } from '../../utils/sanitize-activity-html';
+import { scrollCardBottom } from '../../utils/scroll-card-bottom';
+import { entitlementStatusLabel } from '../view';
+
+export function PromotionEntitlementListCard(props: {
+  data: PromotionEntitlementListCardData;
+  cardId?: string;
+  isHistory?: boolean;
+}) {
+  const { data } = props;
+  const [openRef, setOpenRef] = useState<string | null>(null);
+  const [expanded, setExpanded] = useState(false);
+  const [listHeights, setListHeights] = useState({ collapsed: 0, expanded: 0 });
+  const listRef = useRef<HTMLDivElement>(null);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const initialRenderRef = useRef(true);
+  useEffect(() => {
+    if (initialRenderRef.current) {
+      initialRenderRef.current = false;
+      return;
+    }
+    if (bottomRef.current) scrollCardBottom(bottomRef.current);
+  }, [expanded]);
+  useLayoutEffect(() => {
+    const list = listRef.current;
+    if (!list) return;
+    const rows = [...list.children] as HTMLElement[];
+    const boundary = rows[Math.min(maxItems, rows.length) - 1];
+    const listTop = list.getBoundingClientRect().top;
+    const collapsed = boundary ? boundary.getBoundingClientRect().bottom - listTop : list.scrollHeight;
+    setListHeights({ collapsed, expanded: list.scrollHeight });
+  }, [data.items.length, data.maxItems]);
+  const toggleExpanded = () => {
+    setExpanded((value) => !value);
+  };
+  const target = openRef ? data.items.find((item) => item.entitlementRef === openRef) : undefined;
+  const [detailTarget, setDetailTarget] = useState<typeof target>();
+  const [detailLoading, setDetailLoading] = useState(false);
+  const detailController = useRef<AbortController | null>(null);
+  const [copied, setCopied] = useState(false);
+  useEffect(() => {
+    detailController.current?.abort();
+    if (!openRef || !target) {
+      setDetailTarget(undefined);
+      setDetailLoading(false);
+      return undefined;
+    }
+    const controller = new AbortController();
+    detailController.current = controller;
+    setDetailTarget(undefined);
+    setDetailLoading(true);
+    const params = new URLSearchParams({ entitlementRef: openRef });
+    if (data.mallId) params.set('mallId', data.mallId);
+    if (data.miniAppId) params.set('miniAppId', data.miniAppId);
+    httpGet<{ data: NonNullable<typeof target> }>(`/api/m/promotion/entitlement-detail?${params.toString()}`, { signal: controller.signal })
+      .then(({ data: payload }) => { if (!controller.signal.aborted) setDetailTarget(payload.data); })
+      .catch(() => undefined)
+      .finally(() => { if (!controller.signal.aborted) setDetailLoading(false); });
+    return () => controller.abort();
+  }, [openRef, target]);
+  const sheetTarget = detailTarget ?? target;
+  const maxItems = data.maxItems ?? 4;
+  const copyCode = async (code: string) => {
+    try { await navigator.clipboard?.writeText(code); setCopied(true); window.setTimeout(() => setCopied(false), 1600); } catch { setCopied(false); }
+  };
+  return (
+    <section className="promotion-card promotion-list--coupon promotion-entitlements" aria-label="我的优惠权益">
+      <header className="promotion-activity__header promotion-activity__header--pea promotion-coupon__header">
+        <img src={couponHeaderArtUrl} alt="" aria-hidden="true" className="promotion-activity__header-art" />
+        <div className="promotion-activity__header-copy">
+          <div className="promotion-activity__header-title-row">
+            <Ticket weight="fill" />
+            <h3>我的优惠券</h3>
+          </div>
+          <p>当前账户 · 券包权益</p>
+        </div>
+      </header>
+      {!data.items.length ? <div className="promotion-card__empty"><Ticket size={28} weight="duotone" /><span>{data.noResultsReason ?? '当前账户暂无可用权益'}</span></div> : (
+        <div ref={listRef} className={`promotion-list__items${expanded ? ' promotion-list__items--expanded' : ''}`} style={{ maxHeight: expanded ? listHeights.expanded || undefined : listHeights.collapsed || undefined }} onTransitionEnd={() => { if (bottomRef.current) scrollCardBottom(bottomRef.current); }}>
+          {data.items.map((item) => (
+            <article
+              key={item.entitlementRef}
+              className={`promotion-coupon-row${item.status === 'EFFECTIVE' ? '' : ' promotion-coupon-row--disabled'}`}
+              role="button"
+              tabIndex={0}
+              aria-label={`查看「${item.title}」`}
+              onClick={() => setOpenRef(item.entitlementRef)}
+              onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setOpenRef(item.entitlementRef); } }}
+            >
+              <ImageWithFallback src={item.imageUrl} alt={item.title} className="promotion-coupon-row__thumb" />
+              <div className="promotion-coupon-row__main">
+                <strong className="promotion-coupon-row__title">{item.title}</strong>
+                {item.usageNotice
+                  && <span className="promotion-coupon-row__sub" dangerouslySetInnerHTML={{ __html: sanitizeActivityHtml(item.usageNotice) }} />}
+                <span className="promotion-coupon-row__price">
+                  <b>{item.benefitText ?? entitlementStatusLabel(item.status)}</b>
+                  {item.thresholdText && <em className="promotion-coupon-row__discount">{item.thresholdText}</em>}
+                </span>
+              </div>
+              <span
+                className={`promotion-owned-action promotion-chip promotion-chip--coupon promotion-coupon-row__state--${item.status.toLowerCase()}${item.status === 'EFFECTIVE' ? '' : ' promotion-chip--coupon-off'}`}
+                aria-hidden="true"
+              >
+                {item.status === 'EFFECTIVE' ? '去使用' : entitlementStatusLabel(item.status)}
+              </span>
+            </article>
+          ))}
+        </div>
+      )}
+      {data.items.length > maxItems && (
+        <button
+          type="button"
+          className="promotion-list__toggle"
+          aria-expanded={expanded}
+          onClick={toggleExpanded}
+        >
+          <CaretDown size={16} data-rotated={expanded || undefined} />
+          {expanded ? '收起' : `查看更多（${data.items.length - maxItems} 条）`}
+        </button>
+      )}
+      {data.items.length > maxItems && <div ref={bottomRef} className="promotion-list__bottom-anchor" aria-hidden="true" />}
+      {sheetTarget && (() => {
+        const facts = [
+          sheetFact(<MapPinLine weight="duotone" />, '使用场景', sheetTarget.usageSceneText),
+          sheetFact(<CalendarBlank weight="duotone" />, '有效期', sheetTarget.validityText ?? sheetTarget.validUntilText),
+          sheetFact(<CalendarBlank weight="duotone" />, '使用时间', sheetTarget.usageTimeText),
+          sheetFact(<ShieldCheck weight="duotone" />, '使用限制', sheetTarget.thresholdText),
+          sheetFact(<CalendarBlank weight="duotone" />, '可领取时间', sheetTarget.claimTimeText),
+          sheetFact(<Ticket weight="duotone" />, '使用规则', sheetTarget.usageRuleText),
+        ].filter(Boolean) as SheetFact[];
+        return (
+          <CouponSheet
+            title={sheetTarget.title}
+            imageUrl={sheetTarget.imageUrl}
+            priceMain={sheetTarget.benefitText}
+            aside={detailLoading ? '加载详情中' : entitlementStatusLabel(sheetTarget.status)}
+            noticeText={sheetTarget.usageNotice}
+            guaranteeText={sheetTarget.guaranteeText}
+            facts={facts}
+            onClose={() => setOpenRef(null)}
+              beforeFacts={<>{sheetTarget.qrCodeEnabled && sheetTarget.code && <><CouponBarcode value={sheetTarget.code} disabled={sheetTarget.status !== 'EFFECTIVE'} /><CouponQrCode value={sheetTarget.code} disabled={sheetTarget.status !== 'EFFECTIVE'} /></>}{(sheetTarget.code || sheetTarget.codeMasked) && <div className={`promotion-sheet__code${sheetTarget.status === 'EFFECTIVE' ? '' : ' promotion-sheet__code--disabled'}`}><span>券码</span><strong>{sheetTarget.code || sheetTarget.codeMasked}</strong><button type="button" className="promotion-sheet__copy" onClick={() => copyCode(sheetTarget.code || sheetTarget.codeMasked!)}><Copy size={16} />{copied ? '已复制' : '复制'}</button></div>}{sheetTarget.stores?.length ? <><div className="promotion-sheet__section">适用商家</div><div className="promotion-sheet__stores">{sheetTarget.stores.map((store) => <div className="promotion-sheet__store" key={store.storeId}>{store.imageUrl && <ImageWithFallback src={store.imageUrl} alt={store.storeName} className="promotion-sheet__store-image" />}<span><strong>{store.storeName}</strong>{store.businessName && store.businessName !== store.storeName && <small>{store.businessName}</small>}{store.floor && <small>{store.floor}</small>}{store.address && <small>{store.address}</small>}</span>{store.latitude !== undefined && store.longitude !== undefined && <button type="button" className="promotion-sheet__navigate" aria-label={`导航到${store.storeName}`} onClick={(event) => { event.stopPropagation(); void callJsapi('openLocation', { latitude: store.latitude, longitude: store.longitude, name: store.storeName, address: store.address ?? '' }).catch(() => undefined); }}><NavigationArrow size={18} />导航</button>}</div>)}</div></> : null}</>}
+          />
+        );
+      })()}
+    </section>
+  );
+}
+
+/** 缺字段的条目整条不出——详情请求失败时保留列表摘要，不编造空字段。 */
+function sheetFact(icon: React.ReactNode, label: string, value?: string): SheetFact | null {
+  return value ? { icon, label, value } : null;
+}
+
+export default PromotionEntitlementListCard;

package/src/client/cards/promotion-offer-detail/index.tsx

@@ -0,0 +1,116 @@
+import { CalendarBlank, CheckCircle, Clock, Gift, Info, ListChecks, MapPin, SealCheck, Ticket } from '@phosphor-icons/react';
+import { useEffect, useRef, useState } from 'react';
+import type { PromotionOfferDetailCardData } from '@tbox.cn/app-contracts-mall';
+import { markSelfRendering, navigateToAlipayPage, sendCardAction } from '@tbox.cn/app-sdk/client';
+import { ImageWithFallback } from '../../components/ImageWithFallback';
+import { offerTypeLabel } from '../view';
+import { sanitizeActivityHtml } from '../../utils/sanitize-activity-html';
+
+const modeText: Record<string, string> = {
+  AUTOMATIC_DISCOUNT: '结算时自动优惠',
+  CLAIM_THEN_PURCHASE: '先领券，再购买',
+  REGISTER_THEN_ATTEND: '先报名，再到场',
+  GROUP_PURCHASE: '发起或参与拼团',
+  UNKNOWN: '以活动页说明为准',
+};
+function isClaimSuccess(text: string, level?: string): boolean {
+  return level === 'success' || /领取成功|已存入卡包|已领取/.test(text);
+}
+
+export function PromotionOfferDetailCard({ data, cardId = '', isHistory = false, actionTokens }: { data: PromotionOfferDetailCardData; cardId?: string; isHistory?: boolean; actionTokens?: Record<string, string> }) {
+  const [acquiring, setAcquiring] = useState(false);
+  const [claimed, setClaimed] = useState(false);
+  const [claimMessage, setClaimMessage] = useState<string | null>(null);
+  const pendingClaimRef = useRef(false);
+  useEffect(() => {
+    if (!cardId || typeof window === 'undefined') return undefined;
+    const onNotice = (event: Event) => {
+      const detail = (event as CustomEvent<{ surfaceId?: string; text?: string; level?: string }>).detail;
+      if (!detail?.text || (detail.surfaceId && detail.surfaceId !== cardId)) return;
+      setAcquiring(false);
+      pendingClaimRef.current = false;
+      if (isClaimSuccess(detail.text, detail.level)) {
+        setClaimed(true);
+      }
+      setClaimMessage(detail.text);
+    };
+    const onCard = (event: Event) => {
+      const card = (event as CustomEvent<{ cardType?: string }>).detail;
+      if (card?.cardType !== 'promotion-entitlement-list' || !pendingClaimRef.current) return;
+      pendingClaimRef.current = false;
+      setAcquiring(false);
+      setClaimed(true);
+      setClaimMessage('领取成功！已存入卡包');
+    };
+    window.addEventListener('tbox:notice', onNotice);
+    window.addEventListener('tbox:card', onCard);
+    return () => {
+      window.removeEventListener('tbox:notice', onNotice);
+      window.removeEventListener('tbox:card', onCard);
+    };
+  }, [cardId]);
+  if (data.presentation === 'promotion-guide') return <PromotionGuide data={data} />;
+  // 已领取形态随券详情一起退场：我的券由 entitlement-list 的行内浮层承载，
+  // 服务端已无 entitlement presentation 与 owned* 字段的产出点
+  const coupon = data.offerType === 'COUPON' || data.presentation === 'coupon';
+  // 抢购券严禁回退到免费 acquire；缺少深链时也必须停在明确错误态。
+  const purchaseOnly = coupon && data.claimActionLabel === '抢购';
+  const label = data.presentation === 'promotion' ? '本周活动' : data.presentation === 'package' ? '组合礼包' : '会员专享';
+  return (
+    <section className={`promotion-card promotion-detail${coupon ? ' promotion-detail--coupon' : ''}`} aria-label={data.title}>
+      <div className="promotion-detail__hero">
+        <ImageWithFallback src={data.imageUrl} alt={data.title} className="promotion-detail__image" />
+        <span className="promotion-detail__hero-label">{label}</span>
+        <div className="promotion-detail__glass"><small>{data.claimable ? '可领取' : '详情'}</small><strong>{data.benefitText ?? offerTypeLabel(data.offerType)}</strong><em>{data.subtitle ?? '当前商场可用'}</em></div>
+      </div>
+      <div className="promotion-detail__body">
+        <div className="promotion-detail__status"><span className={`promotion-status promotion-status--${data.claimable ? 'available' : 'unavailable'}`}><SealCheck weight="fill" />{data.claimable ? '可领取' : '暂不可领'}</span>{data.validityText && <small><Clock />{data.validityText}</small>}</div>
+        <h3>{data.title}</h3>
+        {(data.usageNoticeText || data.guaranteeText) && <div className="promotion-detail__notice-strip">
+          {data.usageNoticeText && <span><b>须知</b>{data.usageNoticeText}</span>}
+          {data.guaranteeText && <span><b>保障</b>{data.guaranteeText}</span>}
+        </div>}
+        {(data.usageSceneText || data.validityText || data.usageTimeText || data.thresholdText || data.claimTimeText) && <div className="promotion-detail__facts">
+          {data.usageSceneText && <div><dt><MapPin weight="duotone" />使用场景</dt><dd>{data.usageSceneText}</dd></div>}
+          {data.validityText && <div><dt><CalendarBlank weight="duotone" />有效期</dt><dd>{data.validityText}</dd></div>}
+          {data.usageTimeText && <div><dt><Clock weight="duotone" />使用时间</dt><dd>{data.usageTimeText}</dd></div>}
+          {data.thresholdText && <div><dt><Ticket weight="duotone" />使用限制</dt><dd>{data.thresholdText}</dd></div>}
+          {data.claimTimeText && <div><dt><CalendarBlank weight="duotone" />可领取时间</dt><dd>{data.claimTimeText}</dd></div>}
+        </div>}
+        {(data.steps?.length ?? 0) > 0 && <div className="promotion-detail__rules">{data.steps?.slice(0, 3).map((step, index) => <span key={index}><CheckCircle weight="fill" /><b>{step.title}</b><small>{step.description ?? ''}</small></span>)}</div>}
+        {(data.usageRuleText || data.description) && <div className="promotion-detail__usage-rule"><strong>使用规则</strong><div dangerouslySetInnerHTML={{ __html: sanitizeActivityHtml(data.usageRuleText ?? data.description ?? '') }} /></div>}
+        {purchaseOnly ? <button className="promotion-coupon-main-action" type="button" disabled={!data.purchaseUrl || isHistory} onClick={() => { if (!data.purchaseUrl) return; void navigateToAlipayPage(data.purchaseUrl).catch((err: unknown) => console.warn('[PromotionOfferDetailCard] navigateTo failed', err)); }}>{data.purchaseUrl ? '去小程序抢购' : '抢购链接暂不可用'}</button>
+          : data.claimable && actionTokens?.['promotion.acquire'] && <button className={`promotion-coupon-main-action${acquiring ? ' promotion-coupon-main-action--pending' : ''}`} type="button" disabled={acquiring || claimed} onClick={() => { pendingClaimRef.current = true; setAcquiring(true); setClaimMessage('领取中，请稍候；领取成功后将自动展示我的券包'); sendCardAction(cardId, { type: 'moduleAction', actionId: 'promotion.acquire', contextToken: actionTokens['promotion.acquire'] }, { offerRef: data.offerRef }); }}>{claimed ? '已领取' : acquiring ? '领取中…' : '立即领取'}</button>}
+        {claimMessage && <p className="promotion-detail__claim-status" role="status">{claimMessage}</p>}
+        {(data.bundleItems?.length ?? 0) > 0 && <div className="promotion-detail__bundle">{data.bundleItems?.map((item, index) => <span key={index}><Gift weight="duotone" /><b>{item.name}</b><small>x{item.quantity}</small></span>)}</div>}
+        {data.notice && <div className="promotion-detail__notice"><Info />{data.notice}</div>}
+        {(data.stores?.length ?? 0) > 0 && <div className="promotion-detail__stores"><strong>适用门店</strong>{data.stores?.slice(0, 8).map((store) => <span key={store.storeId}><MapPin weight="fill" />{store.storeName}{store.floor ? ` · ${store.floor}` : ''}{store.address ? ` · ${store.address}` : ''}</span>)}</div>}
+        {!data.claimable && data.unavailableReason && <div className="promotion-detail__notice"><Info />{data.unavailableReason}</div>}
+        {data.caveats.length > 0 && <footer className="promotion-card__footer">{data.caveats.join('；')}</footer>}
+      </div>
+    </section>
+  );
+}
+
+function PromotionGuide({ data }: { data: PromotionOfferDetailCardData }) {
+  const steps: Array<{ title: string; description?: string }> =
+    data.steps ?? data.rules.map((rule) => ({ title: rule }));
+  return (
+    <section className="promotion-card promotion-guide" aria-label="活动参与方式">
+      <header className="promotion-card__header promotion-card__header--compact">
+        <span className="promotion-card__mark promotion-card__mark--cyan"><ListChecks weight="duotone" /></span>
+        <div><span className="promotion-card__eyebrow">活动参与方式</span><h3>{data.title}</h3><p>{data.validityText ?? '当前活动有效期以现场为准'}</p></div>
+        <b className={`promotion-status promotion-status--${data.claimable ? 'available' : 'unavailable'}`}>{data.claimable ? '可参与' : '查看规则'}</b>
+      </header>
+      <div className="promotion-guide__summary"><span><MapPin weight="fill" />当前商场</span><strong>{modeText[data.participationMode ?? 'UNKNOWN']}</strong></div>
+      <ol>{steps.map((step, index) => <li key={index}><b>{index + 1}</b><span><strong>{step.title}</strong><small>{step.description ?? ''}</small></span></li>)}</ol>
+      {(data.requirements?.length ?? 0) > 0 && <div className="promotion-guide__requirements">{data.requirements?.map((item) => <span key={item}><CheckCircle weight="fill" />{item}</span>)}</div>}
+      {data.notice && <div className="promotion-detail__notice"><Info weight="duotone" />{data.notice}</div>}
+      <footer className="promotion-card__footer">参与资格和场次以活动现场实时信息为准</footer>
+    </section>
+  );
+}
+
+export default PromotionOfferDetailCard;
+
+markSelfRendering(PromotionOfferDetailCard);

package/src/client/cards/promotion-offer-list/index.tsx

@@ -0,0 +1,285 @@
+import { CalendarBlank, CalendarDots, CaretDown, Lightbulb, MapPin, Sparkle, Ticket } from '@phosphor-icons/react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { ItemActionsRow, markSelfRendering, navigateToAlipayPage, sendCardAction } from '@tbox.cn/app-sdk/client';
+import type { PromotionOfferListCardData } from '@tbox.cn/app-contracts-mall';
+import { CouponSheet } from '../../components/CouponSheet';
+import type { SheetFact } from '../../components/CouponSheet';
+import { ImageWithFallback } from '../../components/ImageWithFallback';
+import couponHeaderArtUrl from '../../assets/promotion-coupon-header-pea-v1.jpg';
+import { offerTypeLabel } from '../view';
+import { scrollCardBottom } from '../../utils/scroll-card-bottom';
+
+const statusText = (status?: string, claimable?: boolean) => {
+  if (status === 'REQUIRES_ACTION') return '需操作';
+  if (status === 'UNKNOWN') return '待确认';
+  return claimable ? '可领取' : '不可领';
+};
+
+const statusTone = (status?: string, claimable?: boolean) =>
+  status?.toLowerCase() ?? (claimable ? 'available' : 'unavailable');
+
+const couponSubtitleIsTime = (subtitle: string) => {
+  const plainText = subtitle.replace(/<[^>]+>/g, ' ').replace(/&nbsp;/gi, ' ');
+  return /\d{4}\s*[-/.年]\s*\d{1,2}\s*[-/.月]\s*\d{1,2}|\d{1,2}:\d{2}/.test(plainText);
+};
+
+export function PromotionOfferListCard(props: {
+  data: PromotionOfferListCardData;
+  cardId?: string;
+  isHistory?: boolean;
+  actionTokens?: Record<string, string>;
+}) {
+  const { data, cardId = '', isHistory = false, actionTokens } = props;
+  const [openRef, setOpenRef] = useState<string | null>(null);
+  const [claimingRef, setClaimingRef] = useState<string | null>(null);
+  const [claimedRefs, setClaimedRefs] = useState<Set<string>>(() => new Set());
+  const [expanded, setExpanded] = useState(false);
+  const [listHeights, setListHeights] = useState({ collapsed: 0, expanded: 0 });
+  const listRef = useRef<HTMLDivElement>(null);
+  const bottomRef = useRef<HTMLDivElement>(null);
+  const initialRenderRef = useRef(true);
+  useEffect(() => {
+    if (initialRenderRef.current) {
+      initialRenderRef.current = false;
+      return;
+    }
+    if (bottomRef.current) scrollCardBottom(bottomRef.current);
+  }, [expanded]);
+  useLayoutEffect(() => {
+    const list = listRef.current;
+    if (!list) return;
+    const rows = [...list.children] as HTMLElement[];
+    const boundary = rows[Math.min(maxItems, rows.length) - 1];
+    const listTop = list.getBoundingClientRect().top;
+    const collapsed = boundary ? boundary.getBoundingClientRect().bottom - listTop : list.scrollHeight;
+    setListHeights({ collapsed, expanded: list.scrollHeight });
+  }, [data.items.length, data.maxItems]);
+  const toggleExpanded = () => {
+    setExpanded((value) => !value);
+  };
+  useEffect(() => {
+    if (!cardId || typeof window === 'undefined') return undefined;
+    const onNotice = (event: Event) => {
+      const detail = (event as CustomEvent<{ surfaceId?: string; text?: string; level?: string }>).detail;
+      if (!detail?.text || (detail.surfaceId && detail.surfaceId !== cardId)) return;
+      const ref = claimingRef;
+      if (!ref) return;
+      setClaimingRef(null);
+      if (detail.level === 'success' || /领取成功|已存入卡包|已领取/.test(detail.text)) {
+        setClaimedRefs((current) => new Set(current).add(ref));
+      }
+    };
+    window.addEventListener('tbox:notice', onNotice);
+    return () => window.removeEventListener('tbox:notice', onNotice);
+  }, [cardId, claimingRef]);
+  if (data.presentation === 'recommendation') {
+    const [offer, ...alternatives] = data.items;
+    if (!offer) return <Empty text={data.noResultsReason ?? '暂未找到匹配当前场景的优惠'} />;
+    return (
+      <section className="promotion-card promotion-recommendation" aria-label="更适合你的优惠">
+        <header className="promotion-card__header">
+          <span className="promotion-card__mark promotion-card__mark--violet"><Sparkle weight="fill" /></span>
+          <div><span className="promotion-card__eyebrow">智能匹配</span><h3>更适合你的优惠</h3><p>根据当前可用性与预计节省排序</p></div>
+        </header>
+        <div className="promotion-recommendation__main">
+          <ImageWithFallback src={offer.imageUrl} alt={offer.title} className="promotion-recommendation__image" />
+          <div><span className={`promotion-status promotion-status--${statusTone(offer.availabilityStatus, offer.claimable)}`}>{statusText(offer.availabilityStatus, offer.claimable)}</span><strong>{offer.title}</strong><small>{offer.subtitle ?? offer.validityText ?? '当前商场可用'}</small></div>
+          <em>{offer.benefitText ?? offerTypeLabel(offer.offerType)}</em>
+        </div>
+        <div className="promotion-recommendation__reason"><Lightbulb weight="duotone" /><span><b>推荐依据</b>{data.summary ?? '综合资格、可用性和优惠力度'}</span></div>
+        {alternatives.length > 0 && <div className="promotion-recommendation__alternatives">另有 {alternatives.length} 个候选优惠</div>}
+        <ItemActionsRow actions={offer.itemActions ?? []} cardId={cardId} isHistory={isHistory} className="promotion-recommendation__actions" chipClassName="promotion-button promotion-button--primary" />
+      </section>
+    );
+  }
+
+  const promotion = data.presentation === 'promotion';
+  const hero = data.items[0];
+  const coupon = data.presentation === 'coupon' || data.mode === 'claimable';
+  const title = promotion ? '本周营销活动' : coupon ? '商场神券' : '活动与优惠';
+  const eyebrow = promotion ? '活动发现' : coupon ? '当前商场 · 优惠精选' : '优惠精选';
+  // summary 由服务端下发，可能与 eyebrow 撞词（券列表实测就撞了）——同一句话不占两行
+  const summary = data.summary && data.summary !== eyebrow ? data.summary : undefined;
+  // 只在「可领券列表」里滤掉领不了的（列出来用户点一次才知道点不动）；
+  // 定向出某一张券时不过滤——那是用户指名要看的，滤掉就成了空列表
+  const items = data.mode === 'claimable' ? data.items.filter((item) => item.claimable) : data.items;
+  const maxItems = data.maxItems ?? 4;
+  return (
+    <section className={`promotion-card promotion-list${promotion ? ' promotion-list--promotion' : ''}${coupon ? ' promotion-list--coupon promotion-list--offers' : ''}`} aria-label={title}>
+      {promotion && hero && <div className="promotion-list__hero"><ImageWithFallback src={hero.imageUrl} alt={title} className="promotion-list__hero-image" /><div className="promotion-list__glass"><span>刚刚更新</span><strong>{data.items.length} 个活动正在进行</strong></div></div>}
+      {coupon ? (
+        <header className="promotion-activity__header promotion-activity__header--pea promotion-coupon__header">
+          <img src={couponHeaderArtUrl} alt="" aria-hidden="true" className="promotion-activity__header-art" />
+          <div className="promotion-activity__header-copy">
+            <div className="promotion-activity__header-title-row">
+              <Ticket weight="fill" />
+              <h3>{title}</h3>
+            </div>
+            <p>{eyebrow}</p>
+          </div>
+        </header>
+      ) : (
+        <header className="promotion-card__header">
+          <span className="promotion-card__mark">{promotion ? <CalendarDots weight="duotone" /> : <Sparkle weight="fill" />}</span>
+          <div><span className="promotion-card__eyebrow">{eyebrow}</span><h3>{title}</h3><p>{summary ?? '根据当前场景实时筛选'}</p></div>
+          <b className="promotion-card__count">{data.items.length} 个</b>
+        </header>
+      )}
+      {!items.length ? <Empty text={data.noResultsReason ?? '暂未找到符合条件的优惠'} /> : (
+        <div ref={listRef} className={`promotion-list__items${expanded ? ' promotion-list__items--expanded' : ''}`} style={{ maxHeight: expanded ? listHeights.expanded || undefined : listHeights.collapsed || undefined }} onTransitionEnd={() => { if (bottomRef.current) scrollCardBottom(bottomRef.current); }}>
+          {items.map((item) => coupon ? (
+            <article
+              key={item.offerRef}
+              className="promotion-coupon-row"
+              role="button"
+              tabIndex={0}
+              aria-label={`${item.claimActionLabel ?? '领取'}「${item.title}」`}
+              onClick={() => setOpenRef(item.offerRef)}
+              onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); setOpenRef(item.offerRef); } }}
+            >
+              <ImageWithFallback src={item.imageUrl} alt={item.title} className="promotion-coupon-row__thumb" />
+              <div className="promotion-coupon-row__main">
+                <strong className="promotion-coupon-row__title">{item.title}</strong>
+                {item.tags.some((tag) => !/^TOP[1-5]$/i.test(tag)) && <span className="promotion-coupon-row__tags">{item.tags.filter((tag) => !/^TOP[1-5]$/i.test(tag)).slice(0, 3).map((tag) => <em key={tag} className={/^(精选|餐饮|购物|生活)$/.test(tag) ? 'promotion-coupon-row__tag--category' : 'promotion-coupon-row__tag--meta'}>{tag}</em>)}</span>}
+                {item.subtitle && !couponSubtitleIsTime(item.subtitle)
+                  && <span className="promotion-coupon-row__sub" dangerouslySetInnerHTML={{ __html: item.subtitle }} />}
+                <span className="promotion-coupon-row__price">
+                  {/* 售价缺省时退回 benefitText：老 provider 没有价格字段，不能让这行空着 */}
+                  <b>{item.priceText ?? item.benefitText ?? offerTypeLabel(item.offerType)}</b>
+                  {item.discountLabel && <em className="promotion-coupon-row__discount">{item.discountLabel}</em>}
+                  {item.priceText && item.originalPriceText && <s>{item.originalPriceText}</s>}
+                </span>
+              </div>
+              {/* 领/抢是拉起浮层的入口，不是成交按钮：整行已是可交互控件，
+                  这里只做视觉承诺——真正的领取动作只在浮层里出现一次 */}
+              <span className="promotion-item-actions promotion-item-actions--coupon" aria-hidden="true">
+                <span className="promotion-chip promotion-chip--coupon">{item.claimActionLabel ?? '领取'}</span>
+              </span>
+            </article>
+          ) : (
+            <article key={item.offerRef}>
+              <span className="promotion-list__visual"><ImageWithFallback src={item.imageUrl} alt={item.title} className="promotion-list__thumb" /><em>{item.benefitText ?? offerTypeLabel(item.offerType)}</em></span>
+              <span className="promotion-list__copy">
+                <small>{promotion ? '本周活动' : offerTypeLabel(item.offerType)}</small>
+                <strong>{item.title}</strong>
+                <span>{item.subtitle ?? item.validityText ?? '当前商场可用'}</span>
+              </span>
+              <span className={`promotion-status promotion-status--${statusTone(item.availabilityStatus, item.claimable)}`}>{statusText(item.availabilityStatus, item.claimable)}</span>
+              <ItemActionsRow actions={item.itemActions ?? []} cardId={cardId} isHistory={isHistory} className="promotion-item-actions" chipClassName="promotion-chip" />
+            </article>
+          ))}
+        </div>
+      )}
+      {items.length > maxItems && (
+        <button
+          type="button"
+          className="promotion-list__toggle"
+          aria-expanded={expanded}
+          onClick={toggleExpanded}
+        >
+          {!coupon && <CaretDown size={16} data-rotated={expanded || undefined} />}
+          {expanded ? '收起' : `查看更多（${items.length - maxItems} 条）`}
+          {coupon && <CaretDown size={17} aria-hidden="true" data-rotated={expanded || undefined} />}
+        </button>
+      )}
+      {items.length > maxItems && <div ref={bottomRef} className="promotion-list__bottom-anchor" aria-hidden="true" />}
+      {data.nextCursor && <p className="promotion-list__more">还有更多内容，可继续查询</p>}
+      {openRef && (() => {
+        const target = items.find((i) => i.offerRef === openRef);
+        if (!target) return null;
+        const token = actionTokens?.['promotion.acquire-from-list'];
+        const label = target.claimActionLabel ?? '领取';
+        const purchaseOnly = label === '抢购';
+        const redirectOnly = purchaseOnly || target.freeCouponClaimMode === 'REDIRECT';
+        const redirectLabel = purchaseOnly ? '去小程序抢购' : '去小程序领取';
+        const facts = [
+          target.usageSceneText ? { icon: <MapPin weight="duotone" />, label: '使用场景', value: target.usageSceneText } : null,
+          target.usageTimeText ? { icon: <CalendarBlank weight="duotone" />, label: '使用时间', value: target.usageTimeText } : null,
+          target.thresholdText ? { icon: <Ticket weight="duotone" />, label: '使用限制', value: target.thresholdText } : null,
+          target.claimTimeText ? { icon: <CalendarBlank weight="duotone" />, label: '可领取时间', value: target.claimTimeText } : null,
+          target.validityText ? { icon: <CalendarBlank weight="duotone" />, label: '有效期', value: target.validityText } : null,
+          target.usageRuleText ? { icon: <Ticket weight="duotone" />, label: '使用规则', value: target.usageRuleText } : null,
+        ].filter(Boolean) as SheetFact[];
+        const priceMain = target.priceText ?? target.benefitText ?? offerTypeLabel(target.offerType);
+        return (
+          <CouponSheet
+            title={target.title}
+            imageUrl={target.imageUrl}
+            noticeText={target.usageNoticeText}
+            guaranteeText={target.guaranteeText}
+            subtitle={redirectOnly
+              ? [target.subtitle, target.purchaseUrl
+                ? `该优惠需前往小程序完成${purchaseOnly ? '购买' : '领取'}`
+                : `该优惠的${purchaseOnly ? '抢购' : '领取'}链接暂不可用`].filter(Boolean).join(' · ')
+              : target.subtitle}
+            priceMain={priceMain}
+            priceOriginal={target.priceText ? target.originalPriceText : undefined}
+            aside={target.stockText}
+            facts={facts}
+            onClose={() => {
+              setOpenRef(null);
+              setClaimingRef((current) => current === target.offerRef ? null : current);
+              setClaimedRefs((current) => {
+                if (!current.has(target.offerRef)) return current;
+                const next = new Set(current);
+                next.delete(target.offerRef);
+                return next;
+              });
+            }}
+            foot={<>
+              <span className="promotion-sheet__foot-price">
+                <b>{target.priceText ?? target.benefitText ?? ''}</b>
+                {target.priceText && target.originalPriceText && <s>{target.originalPriceText}</s>}
+              </span>
+              {redirectOnly ? (
+                <button
+                  type="button"
+                  disabled={!target.purchaseUrl}
+                  className="promotion-chip promotion-chip--coupon promotion-chip--coupon-lg"
+                  onClick={() => {
+                    if (!target.purchaseUrl) return;
+                    void navigateToAlipayPage(target.purchaseUrl).catch((err: unknown) => {
+                      console.warn('[PromotionOfferListCard] navigateTo failed', err);
+                    });
+                  }}
+                >
+                  {target.purchaseUrl ? redirectLabel : `${purchaseOnly ? '抢购' : '领取'}链接暂不可用`}
+                </button>
+              ) : token && !isHistory ? (
+              // 直接走写动作，不再绕发消息：结果以新卡片回到对话流，当前浮层保持已领取态
+              <button
+                type="button"
+                className="promotion-chip promotion-chip--coupon promotion-chip--coupon-lg"
+                onClick={() => {
+                  setClaimingRef(target.offerRef);
+                  sendCardAction(cardId, { type: 'moduleAction', actionId: 'promotion.acquire-from-list', contextToken: token }, { offerRef: target.offerRef });
+                }}
+                disabled={claimingRef === target.offerRef || claimedRefs.has(target.offerRef)}
+              >
+                {claimedRefs.has(target.offerRef) ? '已领取' : claimingRef === target.offerRef ? '领取中，请稍候…' : label}
+              </button>
+              ) : (
+                // 无令牌（历史卡、旧服务端）时退回发消息，保住可用性
+                <ItemActionsRow
+                  actions={target.itemActions ?? []}
+                  cardId={cardId}
+                  isHistory={isHistory}
+                  className="promotion-item-actions"
+                  chipClassName="promotion-chip promotion-chip--coupon promotion-chip--coupon-lg"
+                />
+              )}
+            </>}
+          />
+        );
+      })()}
+    </section>
+  );
+}
+
+markSelfRendering(PromotionOfferListCard);
+
+function Empty({ text }: { text: string }) {
+  return <div className="promotion-card__empty"><Ticket size={28} weight="duotone" /><span>{text}</span></div>;
+}
+
+export default PromotionOfferListCard;

package/src/client/cards/view.ts

@@ -0,0 +1,72 @@
+/**
+ * promotion 展示纯函数（0.4.0 D6：状态文案/色调映射，可单测）。
+ */
+export type PromotionTone = 'available' | 'unavailable' | 'succeeded' | 'pending' | 'rejected' | 'neutral';
+
+export function offerTypeLabel(offerType: string): string {
+  switch (offerType) {
+    case 'COUPON':
+      return '优惠券';
+    case 'BUNDLE':
+      return '组合券';
+    case 'PROMOTION':
+      return '促销';
+    case 'ACTIVITY':
+      return '活动';
+    case 'GROUPON':
+      return '团购';
+    default:
+      return '优惠';
+  }
+}
+
+export function entitlementStatusLabel(status: string): string {
+  switch (status) {
+    case 'EFFECTIVE':
+      return '可用';
+    case 'USED':
+      return '已使用';
+    case 'EXPIRED':
+      return '已过期';
+    case 'INVALID':
+      return '已失效';
+    default:
+      return '未知';
+  }
+}
+
+export function entitlementTone(status: string): 'available' | 'unavailable' | 'neutral' {
+  if (status === 'EFFECTIVE') return 'available';
+  if (status === 'USED' || status === 'EXPIRED' || status === 'INVALID') return 'unavailable';
+  return 'neutral';
+}
+
+export function resultTone(status: string): 'succeeded' | 'pending' | 'rejected' {
+  if (status === 'SUCCEEDED') return 'succeeded';
+  if (status === 'PENDING_AUTHORITY') return 'pending';
+  return 'rejected';
+}
+
+export function resultStatusText(status: string): string {
+  if (status === 'SUCCEEDED') return '成功';
+  if (status === 'PENDING_AUTHORITY') return '确认中';
+  return '失败';
+}
+
+export function sessionTone(status: string): 'available' | 'unavailable' | 'neutral' {
+  if (status === 'OPEN') return 'available';
+  if (status === 'FULL' || status === 'CLOSED') return 'unavailable';
+  return 'neutral';
+}
+
+export function sessionStatusText(status: string): string {
+  if (status === 'OPEN') return '可报名';
+  if (status === 'FULL') return '已满';
+  if (status === 'CLOSED') return '已结束';
+  return '未知';
+}
+
+/** 条目/活动可用性文案（offerSummary claimable 语义） */
+export function availabilityText(claimable: boolean): string {
+  return claimable ? '可领取' : '不可领';
+}