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

package/dist/server/index.js

@@ -1,10 +1,20 @@
 import {
   InMemoryPromotionService,
-  meta_default,
+  inMemoryPromotion,
+  promotionCards,
+  resolvePromotionAcquisitionPort,
+  resolvePromotionActivitiesPort,
+  resolvePromotionEntitlementsPort,
+  resolvePromotionOffersPort,
   serverModule
-} from "../chunk-AD6OLHSM.js";
+} from "../chunk-QOTX4XDS.js";
 export {
   InMemoryPromotionService,
-  meta_default as couponMeta,
+  inMemoryPromotion,
+  promotionCards,
+  resolvePromotionAcquisitionPort,
+  resolvePromotionActivitiesPort,
+  resolvePromotionEntitlementsPort,
+  resolvePromotionOffersPort,
   serverModule
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-module-promotion",
-  "version": "0.1.0",
+  "version": "0.9.3",
   "type": "module",
   "description": "商圈营销模块：资格校验、推荐降级链、券卡（codegen 源）。",
   "exports": {
@@ -18,32 +18,42 @@
     }
   },
   "dependencies": {
-    "@tbox.cn/app-sdk": "^0.1.0",
-    "@tbox.cn/app-contracts": "^0.1.0",
-    "@tbox.cn/app-contracts-mall": "^0.1.0"
+    "@tbox.cn/app-contracts": "0.9.0",
+    "@tbox.cn/app-contracts-mall": "0.9.0",
+    "@tbox.cn/app-sdk": "0.17.0",
+    "jsbarcode": "^3.12.3",
+    "qrcode": "^1.5.4"
   },
   "peerDependencies": {
-    "zod": "^3.24.0",
-    "react": "^18.3.1"
+    "@phosphor-icons/react": "2.1.10",
+    "react": "18.3.1",
+    "zod": "3.25.76"
   },
   "devDependencies": {
-    "@types/react": "^18.3.12",
-    "@types/node": "^24.0.0",
-    "typescript": "^5.7.0",
-    "tsx": "^4.19.0",
-    "vitest": "^4.1.4",
-    "zod": "^3.24.0",
-    "tsup": "^8.0.0"
+    "@types/express": "4.17.25",
+    "@types/node": "24.13.3",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "express": "4.22.2",
+    "happy-dom": "20.11.2",
+    "react-dom": "18.3.1",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10",
+    "zod": "3.25.76"
   },
   "files": [
     "dist",
     "src",
     "tests",
-    "tbox.component.json",
+    "tbox.module.json",
     "tsconfig.json",
     "tsup.config.ts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "skills",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -52,6 +62,9 @@
     "access": "public"
   },
   "license": "MIT",
+  "sideEffects": [
+    "**/*.css"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",

package/skills/promotion/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: promotion
+description: 商圈营销 SOP——优惠券搜索/领取、我的券查询、最优优惠测算、营销活动与场次报名指引的标准流程。
+routingTerms:
+  - 领券
+  - 优惠券
+  - 优惠
+  - 券
+  - 折扣
+  - 团购
+  - 活动
+  - 市集
+  - 我的券
+  - 券码
+  - 满减
+  - 划算
+---
+
+# 商圈营销 SOP
+
+## 角色与语气
+
+你是商圈营销助手，像一位懂行的逛街搭子：熟悉商场里的券和活动，帮顾客用最少的钱买到想要的东西。说话热络但不推销，清楚但不堆砌：
+
+- **划算说到位**：直接说省多少、怎么用（"满 200 减 50，结账前出示就行"），不背营销术语
+- **数字不裸贴**：面额、门槛带语境（"满 200 可用"而不是 `threshold: 20000`）
+- **不替用户做决定**：推荐最优组合时给出理由，把选择权留给用户
+- **领取类动作给出口**：告诉用户"点开券看看，里面就能领"，不代劳也不催
+
+❌ `已为您领取优惠券！券号为 XJFK********82，请妥善保管。`
+
+✅ `这张券点开就能领～点卡片上那张券，里面有领取按钮，领完在"我的券"里随时能看到。`
+
+## 能力地图
+
+| 用户想要 | 调用 | 出卡 |
+|---|---|---|
+| 看有哪些可领取优惠券 | `listCoupons(mode=CLAIMABLE)` | `promotion-offer-list` |
+| 某张券的详情 | `getOfferDetail` | `promotion-offer-detail` |
+| 领券 | `listCoupons(mode=CLAIMABLE)`（用户在券行浮层内领取） | `promotion-offer-list` → `promotion-entitlement-list` |
+| 我的券/已领取/卡包 | `listEntitlements` 或 `listCoupons(mode=OWNED)` | `promotion-entitlement-list` |
+| 最优优惠测算 | `calculateBestDeal` | `promotion-best-deal` |
+| 活动列表/详情/场次/指南 | `listActivities` / `getActivityDetail` / `listActivitySessions` / `getActivityGuide` | 活动系列卡 |
+| 活动类型 | `listActivityCategories` | `promotion-activity-category-list` |
+| 营销专题 | `listPromotions` / `getPromotionDetail` / `getParticipationGuide` | 专题系列卡 |
+
+## 出卡规则
+工具结果含 cards 候选时，回复末尾另起一行输出 `<agent-ui-cards>` 引用本轮卡片 id（空格分隔）——
+不在正文里只说「已为你找到优惠」而省略卡片引用，用户看不到卡就无法领券。
+
+## 场景细则
+
+### 一：找优惠/看有哪些券
+
+触发："有什么优惠""有没有券""现在有什么折扣""推荐优惠""有没有满减"。
+
+用户问“有什么可领取/可领优惠券”时，必须调 `listCoupons` 且传 `mode=CLAIMABLE`，出可领取优惠券列表；不得调用 `listEntitlements`，不得把已领取券包当作答案。只有出现“我的/已领取/券包/持有”才进入 OWNED 流程。泛优惠（包含活动、团购）才调 `searchOffers`。用户想了解某张券的详情（面额/门槛/有效期/适用规则）时，调 `getOfferDetail`。
+
+**数据禁编**：面额、门槛、库存、有效期一律从工具返回读取，禁止推断或声称任何未查得数据——券规则说错一条，结账时就有一场纠纷。
+
+### 二：要领券
+
+触发："我要领这张券""帮我领一下""领取优惠"。
+
+处理方式（闭环 4 步，缺一不可）：
+
+1. 调 `listCoupons`（或 `searchOffers`）出券列表卡；用户想要某张指定的券就带 keyword 精筛
+2. 用户点券行拉起浮层，在浮层里点"领/抢"（`promotion.acquire-from-list` 动作，grant 授权闭环）
+3. 领取结果按三种终态回到用户面前：
+   - `SUCCEEDED`：直接出 `promotion-entitlement-list`，刚领的券连券码一起可见
+   - `PENDING_AUTHORITY`：无卡，一行提示告知稍后在"我的券"查看
+   - `REJECTED`：无卡，一行提示优先原样展示 Provider 返回的业务 message，并附 code；message 缺失时使用已知码语义兜底，未知码使用通用失败文案
+
+⚠️ **禁止**：
+
+- 未经用户点击确认卡直接代领（无写工具——领取是写操作，授权闭环必须由用户触发）
+- 在正文中预判或承诺领取成功（以卡为准——厂商侧库存与资格是实时校验的）
+- 向用户展示完整券码（脱敏为厂商与卡包职责，泄露券码等于泄露钱）
+
+用户事后问"领到了吗" → 调 `listEntitlements` 查卡包确认。
+
+> 详见 `references/claim-loop.md`
+
+### 三：查"我的券"
+
+触发："我有哪些券""我的卡包""我领了什么券""券码是什么"。
+
+调 `listEntitlements`，返回非空时**必须**出 `promotion-entitlement-list` 卡，不得只在正文列券而省略卡片引用。只有出现“我的/已领取/券包/券码”语义时才进入此流程；“可领取/有什么优惠”永远走上面的 CLAIMABLE 流程。
+
+**未入会分支**：用户已登录但未入会时，`listEntitlements`/`listCoupons(mode=OWNED)` 出参已含 `member-enrollment-cta` 引导卡——**直接引用该卡 id 即可**，无需再调 member 域 `queryEnrollmentCta`；正文简述“点击卡片完成入会后可查看券包”。
+
+### 四：问最划算的优惠组合/优惠测算
+
+触发："哪个优惠最合适""满减怎么算最省""帮我算最优组合""怎么买划算"。
+
+调 `calculateBestDeal`（需传 `currentAmountCents` 消费金额）。厂商支持时返回确定性最优方案；厂商不支持时只返回文字说明，不得构造 `promotion-best-deal` 旧卡或伪造测算结论。
+
+### 五：查活动/报名
+
+触发："商场有什么活动""本周活动""亲子活动""市集""活动怎么报名"。
+
+- 活动列表 → 调 `listActivities`，查"本周活动"时**必须传本周的 `startsAfter` 与 `endsBefore`**，不得把"当前活动"误当"本周活动"；结果非空时**必须**出 `promotion-activity-list` 卡（不得用活动分类卡替代）
+- 活动详情 → 调 `getActivityDetail`
+- 可选场次 → 调 `listActivitySessions`（只读，不执行报名）
+- 参与步骤/报名条件 → 调 `getActivityGuide`
+- 用户只问活动有哪些类型 → 调 `listActivityCategories`，出 `promotion-activity-category-list` 卡
+
+**报名由用户在厂商页面确认**：活动详情卡提供报名入口，**模型不代用户报名**，结果以厂商页面为准。
+
+### 六：查营销专题/促销活动
+
+触发："有没有满减活动""本周促销""这个专题活动详情"。
+
+- 营销专题列表 → 调 `listPromotions`
+- 专题详情 → 调 `getPromotionDetail`（传 `offerRef` 或关键词）
+- 参与步骤 → 调 `getParticipationGuide`（只读引导，不执行任何写操作）
+
+## 跨域协作
+
+本域之外的常见问题，**直接调对应域的工具作答**，不推诿：
+
+- **积分余额/会员卡**：调会员域 `queryPoints` / `queryMemberCard`，余额带单位（"320 点"）；**不得声称折扣、免费停车、生日特权等未查得权益**
+- **入会/开卡**：调会员域 `queryEnrollmentCta` 出引导卡，用户点卡片跳支付宝完成
+- **券能抵停车费吗**：以停车域 `queryParkingFee` 返回的 `selectableBenefits` 为准，在停车缴费卡上勾选，重算由卡片触发，**模型不代算**
+- **门店在哪/想去逛**：调导购域 `search-shops`（keywords=店名），位置用结果内 `location.displayText`，不编造
+
+## 硬红线
+
+- **SOP 是内部手册**：不向用户复述流程步骤或工具选择理由（「按营销 SOP 走 CLAIMABLE 流程」这类话不出现）——正文只给结果和用户所需的下一步
+- **数据必须来自工具**：优惠面额、库存、资格、活动名额一律从工具返回读取，禁止编造
+- **写操作须用户确认**：领券（`promotion.acquire`）是唯一写操作，必须经用户点击确认卡触发；模型不代操作任何写入行为（代领出错无法撤销）
+
+## 异常与兜底
+
+- 工具报错/超时 → "这边暂时没查到优惠信息，稍后再看看？"——不编面额、不猜库存
+- 搜索/列表为空 → 如实说"暂时没有"，可换个关键词再查或推荐相邻动作（如看看活动）
+- 领取结果悬而未决 → 引导查"我的券"确认，不替厂商承诺结果

package/skills/promotion/references/claim-loop.md

@@ -0,0 +1,18 @@
+# 优惠券领取闭环（7 步）
+
+1. 用户表达领券意图（「有什么优惠」「领张券」）→ 调 searchOffers 出优惠列表卡。
+2. 用户想了解某券详情 → 券列表行内点开浮层即可（券码、有效期、使用须知随列表下发）；泛指某个优惠时调 getOfferDetail 出详情卡。
+3. 用户明确要求领取 → 调 listCoupons（指名某张券时带 keyword 精筛）出券列表；不可领取或未装配 CRM 写通道时不签发写动作。
+4. 用户点券行拉起浮层，点浮层里的「领/抢」→ moduleAction `promotion.acquire-from-list`（一卡多券，令牌非单次）；服务端 execute 内预检 SubjectBinding 与幂等键。
+5. 独立 CRM Provider 执行 acquire → 三态反馈：
+   - SUCCEEDED：出 `promotion-entitlement-list`，刚领的券直接可见；
+   - PENDING_AUTHORITY：无卡，一行提示「稍后在我的券查看」；
+   - REJECTED：无卡，优先原样展示 Provider 的业务 message 并附 code；message 缺失时保留已知码语义兜底，未知码使用通用失败文案，原始 code 不丢失。
+6. 用户问「领到了吗」→ listEntitlements 查卡包确认。
+7. 使用咨询（怎么用/门槛）→ 引用我的券卡上的字段回答，必要时 getOfferDetail 取规则。
+
+## 禁止
+
+- 禁止文字里直接承诺领取成功（以动作返回的卡或提示为准）。
+- 禁止绕过卡片按钮以任何工具代领（无写工具）。
+- 禁止向用户展示完整券码（脱敏为厂商与卡包职责）。

package/src/client/assets.d.ts

@@ -0,0 +1,5 @@
+/** Static promotion image assets bundled by Vite/tsup. */
+declare module '*.jpg' {
+  const url: string;
+  export default url;
+}

package/src/client/cards/index.ts

@@ -0,0 +1,10 @@
+/**
+ * module-promotion 客户端卡片聚合（0.4.0 D6：一卡一目录）。
+ */
+export { default as PromotionOfferListCard } from './promotion-offer-list';
+export { default as PromotionOfferDetailCard } from './promotion-offer-detail';
+export { default as PromotionEntitlementListCard } from './promotion-entitlement-list';
+export { default as PromotionActivityListCard } from './promotion-activity-list';
+export { default as PromotionActivityDetailCard } from './promotion-activity-detail';
+export { default as PromotionActivityCategoryListCard } from './promotion-activity-category-list';
+export { default as PromotionBestDealCard } from './promotion-best-deal';

package/src/client/cards/promotion-activity-category-list/index.tsx

@@ -0,0 +1,34 @@
+import { GameController, Palette, Sparkle, Storefront } from '@phosphor-icons/react';
+import { ItemActionsRow } from '@tbox.cn/app-sdk/client';
+import type { PromotionActivityCategoryListCardData } from '@tbox.cn/app-contracts-mall';
+
+const icons = [GameController, Storefront, Palette, Sparkle] as const;
+
+export function PromotionActivityCategoryListCard(props: {
+  data: PromotionActivityCategoryListCardData;
+  cardId?: string;
+  isHistory?: boolean;
+}) {
+  const { data, cardId = '', isHistory = false } = props;
+  return (
+    <section className="promotion-card promotion-activity promotion-activity--categories">
+      <header className="promotion-card__header promotion-card__header--compact">
+        <span className="promotion-card__mark"><Sparkle weight="fill" /></span>
+        <div><span className="promotion-card__eyebrow">会员活动</span><h3>探索会员活动</h3><p>按兴趣找到你的专属周末</p></div>
+      </header>
+      <div className="promotion-activity__categories">
+        {data.items.map((item, index) => {
+          const Icon = icons[index % icons.length];
+          return <article key={item.categoryId}>
+            <span className={`promotion-activity__category-icon promotion-activity__category-icon--${index % 4}`}><Icon weight="duotone" /></span>
+            <span><strong>{item.name}</strong><small>发现精彩活动</small></span>
+            <ItemActionsRow actions={item.itemActions ?? []} cardId={cardId} isHistory={isHistory} className="promotion-item-actions" chipClassName="promotion-chip" />
+          </article>;
+        })}
+      </div>
+      {!data.items.length && <div className="promotion-card__empty"><Sparkle size={28} /><span>{data.noResultsReason ?? '暂无活动分类'}</span></div>}
+    </section>
+  );
+}
+
+export default PromotionActivityCategoryListCard;

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

@@ -0,0 +1,84 @@
+import { ArrowSquareOut, CalendarDots, CheckCircle, Clock, Crown, ListChecks, MapPin, Sparkle, Users } from '@phosphor-icons/react';
+import type { PromotionActivityDetailCardData } from '@tbox.cn/app-contracts-mall';
+import { sendCardAction } from '@tbox.cn/app-sdk/client';
+import { ImageWithFallback } from '../../components/ImageWithFallback';
+
+const sessionText: Record<string, string> = { OPEN: '可选', FULL: '已满', CLOSED: '已结束', UNKNOWN: '待确认' };
+
+export function PromotionActivityDetailCard({ data, cardId = '', isHistory = false }: { data: PromotionActivityDetailCardData; cardId?: string; isHistory?: boolean }) {
+  if (data.presentation === 'schedule') return <ActivitySchedule data={data} />;
+  if (data.presentation === 'guide') return <ActivityGuide data={data} />;
+  return <ActivityDetail data={data} cardId={cardId} isHistory={isHistory} />;
+}
+
+function ActivityDetail({ data, cardId, isHistory }: { data: PromotionActivityDetailCardData; cardId: string; isHistory: boolean }) {
+  const status = data.remainingQuota === 0 ? 'FULL' : 'AVAILABLE';
+  return (
+    <section className="promotion-card promotion-activity promotion-activity--detail">
+      <div className="promotion-activity__cover">
+        <ImageWithFallback src={data.coverUrl} alt={data.title} className="promotion-activity__cover-image" />
+        <span className="promotion-activity__cover-shade" />
+        <div className="promotion-activity__cover-meta"><span><Crown weight="fill" />会员专享体验</span><span className={`promotion-activity__status promotion-activity__status--${status.toLowerCase()}`}>{status === 'FULL' ? '已满' : '可报名'}</span></div>
+      </div>
+      <div className="promotion-activity__detail-body">
+        <small>{data.jumpOnly ? '首页精选 · 可跳转内容' : `活动详情 · ${data.categoryName ?? '会员活动'}`}</small>
+        <h3>{data.title}</h3>
+        {(data.subtitle ?? data.description) && <p>{data.subtitle ?? data.description}</p>}
+        <div className="promotion-activity__spotlight">
+          <span><CalendarDots weight="duotone" /><small>{data.jumpOnly ? '内容说明' : '活动时间'}</small><strong>{data.periodText ?? (data.jumpOnly ? '详情以跳转页面为准' : '以活动页为准')}</strong></span>
+          <span><Users weight="duotone" /><small>活动名额</small><strong>{data.remainingQuota !== undefined ? `剩余 ${data.remainingQuota} 席` : data.registrationRequired ? '需提前报名' : '无需报名'}</strong></span>
+        </div>
+        <div className="promotion-activity__venue"><MapPin weight="fill" /><span><small>活动地点</small><strong>{data.location ?? '当前商场'}</strong></span></div>
+        {data.registrationRequired && <div className="promotion-activity__benefit"><Crown weight="fill" /><span><b>会员专享礼遇</b>完成会员身份校验后可参与</span></div>}
+        {data.notice && <div className="promotion-activity__detail-notice"><Clock weight="duotone" /><span>{data.notice}</span></div>}
+        {(data.sessions.length > 0 || data.guideSteps.length > 0) && <div className="promotion-activity__readonly"><ListChecks weight="fill" />可继续询问参与指南和可选场次</div>}
+        {(data.registrationRequired || data.jumpOnly) && data.registrationUrl && (
+          <button
+            type="button"
+            className="promotion-activity__register"
+            disabled={isHistory}
+            onClick={() => sendCardAction(cardId, { type: 'openLink', url: data.registrationUrl! })}
+          >
+            <ArrowSquareOut weight="bold" />
+            {data.jumpOnly ? (data.jumpLabel ?? '打开小程序') : '去支付宝报名'}
+          </button>
+        )}
+        {data.jumpOnly && !data.registrationUrl && <div className="promotion-activity__detail-notice"><Clock weight="duotone" /><span>该首页资源暂无可用跳转链接</span></div>}
+      </div>
+    </section>
+  );
+}
+
+function ActivitySchedule({ data }: { data: PromotionActivityDetailCardData }) {
+  return (
+    <section className="promotion-card promotion-activity promotion-activity--schedule">
+      <ActivityHeader title="选择心仪场次" subtitle={data.title} icon="calendar" />
+      <div className="promotion-activity__session-summary"><CalendarDots weight="duotone" /><span><small>可选场次</small><strong>{data.sessions.length} 场</strong></span><em>实时名额</em></div>
+      <div className="promotion-activity__sessions">
+        {data.sessions.map((session, index) => <article key={session.sessionRef} className={session.status === 'OPEN' ? 'is-available' : 'is-full'}><b>{String(index + 1).padStart(2, '0')}</b><span><strong>{session.title}</strong><small>{session.startText}{session.endText ? ` - ${session.endText}` : ''}</small></span><span><Users weight="duotone" />{session.remainingQuota !== undefined ? `余 ${session.remainingQuota} 席` : session.location ?? '名额实时'}</span><em>{sessionText[session.status]}</em></article>)}
+        {!data.sessions.length && <div className="promotion-activity__empty-state"><Clock weight="duotone" /><span><strong>场次正在确认</strong><small>稍后再来查看最新安排</small></span></div>}
+      </div>
+      <p className="promotion-activity__readonly"><CheckCircle weight="fill" />当前仅展示场次与名额，不会直接提交报名</p>
+    </section>
+  );
+}
+
+function ActivityGuide({ data }: { data: PromotionActivityDetailCardData }) {
+  const steps: Array<{ title: string; description?: string }> =
+    data.guideItems ?? data.guideSteps.map((title) => ({ title }));
+  return (
+    <section className="promotion-card promotion-activity promotion-activity--guide">
+      <ActivityHeader title="参与指南" subtitle={data.title} icon="guide" />
+      <div className="promotion-activity__guide-banner"><Sparkle weight="fill" /><span><small>HOW TO JOIN</small><strong>提前准备，到场更从容</strong></span></div>
+      <ol className="promotion-activity__steps">{steps.map((step, index) => <li key={index}><b>{index + 1}</b><span><strong>{step.title}</strong><small>{step.description ?? ''}</small></span></li>)}</ol>
+      {data.conditions.length > 0 && <div className="promotion-activity__requirements"><b>参与条件</b><div>{data.conditions.map((item) => <span key={item}><CheckCircle weight="fill" />{item}</span>)}</div></div>}
+      <p className="promotion-activity__readonly"><CheckCircle weight="fill" />{data.notice ?? '当前仅提供参与说明，不会直接提交报名'}</p>
+    </section>
+  );
+}
+
+function ActivityHeader({ title, subtitle, icon }: { title: string; subtitle: string; icon: 'calendar' | 'guide' }) {
+  return <header className="promotion-card__header promotion-card__header--compact"><span className="promotion-card__mark">{icon === 'calendar' ? <CalendarDots weight="duotone" /> : <ListChecks weight="duotone" />}</span><div><span className="promotion-card__eyebrow">会员活动</span><h3>{title}</h3><p>{subtitle}</p></div></header>;
+}
+
+export default PromotionActivityDetailCard;

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

@@ -0,0 +1,58 @@
+import { CalendarDots, Sparkle, Ticket } from '@phosphor-icons/react';
+import { sendCardAction } from '@tbox.cn/app-sdk/client';
+import type { PromotionActivityListCardData } from '@tbox.cn/app-contracts-mall';
+import { ImageWithFallback } from '../../components/ImageWithFallback';
+import activityHeaderArtUrl from '../../assets/promotion-activity-header-pea-v2.jpg';
+
+const statusText: Record<string, string> = { AVAILABLE: '可报名', FULL: '已满', ENDED: '已结束', UPCOMING: '即将开始', UNKNOWN: '待确认' };
+
+export function PromotionActivityListCard(props: {
+  data: PromotionActivityListCardData;
+  cardId?: string;
+  isHistory?: boolean;
+}) {
+  const { data, cardId = '', isHistory = false } = props;
+  return (
+    <section className="promotion-card promotion-activity promotion-activity--list">
+      <header className="promotion-activity__header promotion-activity__header--pea">
+        <img src={activityHeaderArtUrl} alt="" aria-hidden="true" className="promotion-activity__header-art" />
+        <div className="promotion-activity__header-copy">
+          <div className="promotion-activity__header-title-row">
+            <Sparkle weight="fill" />
+            <h3>活动中心</h3>
+          </div>
+          <p>发现商场近期精彩活动</p>
+        </div>
+      </header>
+      <div className="promotion-activity__list">
+        {data.items.map((item) => {
+          const status = item.availabilityStatus ?? (item.remainingQuota === 0 ? 'FULL' : 'UNKNOWN');
+          const action = item.itemActions?.find((candidate) => candidate.kind === 'send' || candidate.kind === 'link');
+          const jumpOnly = item.jumpOnly === true;
+          return <button
+            key={item.activityRef}
+            type="button"
+            disabled={isHistory || !action}
+            aria-label={action?.label ?? (jumpOnly ? `打开${item.title}` : `查看${item.title}详情`)}
+            className={status === 'FULL' || status === 'ENDED' ? 'is-muted' : ''}
+            onClick={() => {
+              if (!action || isHistory) return;
+              if (action.kind === 'link') {
+                sendCardAction(cardId, { type: 'openLink', url: action.url });
+              } else {
+                sendCardAction(cardId, { type: 'sendMessage', value: action.value ?? action.label, visible: true });
+              }
+            }}
+          >
+            <span className="promotion-activity__visual"><ImageWithFallback src={item.coverUrl} alt={item.title} className="promotion-activity__thumb" /><span className={`promotion-activity__status promotion-activity__status--${status.toLowerCase()}`}>{statusText[status]}</span></span>
+            <span className="promotion-activity__copy"><small><Sparkle weight="fill" />{item.categoryName ?? (jumpOnly ? '首页精选' : '会员活动')}</small><strong>{item.title}</strong><span><CalendarDots weight="duotone" />{item.periodText ?? (jumpOnly ? '点击打开查看内容' : '时间以活动页为准')}</span><em>{item.remainingQuota !== undefined ? item.remainingQuota > 0 ? `仅余 ${item.remainingQuota} 席` : '名额已满' : jumpOnly ? (item.jumpLabel ?? '打开查看') : item.registrationRequired ? '需提前报名' : '无需报名'}</em></span>
+          </button>;
+        })}
+      </div>
+      {!data.items.length && <div className="promotion-card__empty"><CalendarDots size={28} /><span>{data.noResultsReason ?? '近期暂无活动'}</span></div>}
+      <footer className="promotion-activity__footer"><Ticket weight="duotone" />会员活动名额实时变化，以活动详情为准</footer>
+    </section>
+  );
+}
+
+export default PromotionActivityListCard;

package/src/client/cards/promotion-best-deal/index.tsx

@@ -0,0 +1,18 @@
+import { Calculator, TrendUp } from '@phosphor-icons/react';
+import type { PromotionBestDealCardData } from '@tbox.cn/app-contracts-mall';
+
+const money = (cents: number) => (cents / 100).toFixed(2);
+
+export function PromotionBestDealCard({ data }: { data: PromotionBestDealCardData }) {
+  const savings = data.savingsCents ?? 0;
+  const payable = data.expectedPayCents ?? Math.max(0, data.originalAmountCents - savings);
+  return (
+    <section className="promotion-card promotion-deal" aria-label="优惠测算">
+      <header className="promotion-card__header"><span className="promotion-card__mark promotion-card__mark--cyan"><Calculator weight="duotone" /></span><div><span className="promotion-card__eyebrow">优惠方案</span><h3>优惠测算</h3><p>{data.authoritative ? '实时优惠测算' : '结算前优惠建议'}</p></div></header>
+      {data.authoritative ? <div className="promotion-deal__hero"><span><small>预计实付</small><strong>¥{money(payable)}</strong></span><em>预计节省 ¥{money(savings)}</em></div> : <div className="promotion-deal__notice"><TrendUp weight="duotone" /><span><b>当前为建议结果</b>{data.message ?? '最终金额请在结算页确认'}</span></div>}
+      <div className="promotion-deal__metrics"><span><small>消费金额</small><strong>¥{money(data.originalAmountCents)}</strong></span><span><small>预计节省</small><strong>¥{money(savings)}</strong></span><span><small>候选优惠</small><strong>{data.candidates?.length ?? data.appliedOfferRefs.length}</strong></span></div>
+    </section>
+  );
+}
+
+export default PromotionBestDealCard;