module-promotion · 营销业务组件

商圈营销域承接组件（@tbox.cn/app-module-promotion，componentId promotion）。 查询四族（活动/优惠/权益/套餐）+ 券领取与参与写动作 + 最划算计算；provider 包供给 （业务模块零 vendor）；联单活动整单分流给 alipay-activity。15 工具全量 withCardEmissionHint， 其中 3 个带 actions 句（预告卡面可拉起动作）。

业务职责

| 能力族 | 承接 | |---|---| | 活动 | 类目/列表/详情/场次/参与指引（含联单分流）| | 优惠 | 检索/详情/推荐（presentation 效果词表：list/detail/coupon...）| | 权益 | 我的券/权益列表（写动作：领取）| | 套餐 | 套餐详情/列表与垂直购买引导点 | | 咨询 | not-supplied 时按非接入面话术应答 |

架构分层

src/
  server/
    index.ts      模块注册（7 卡 + 15 工具，index.ts:85-87）
    tools.ts      15 工具定义（~770 行；createPromotionTools tools.ts:318）
    actions.ts    写动作链（券领取/参与确认续接）
    navigation.ts 跳转导航策略（领券后跳转等）
    ports.ts      Port 解析（provider 供给）
  client/cards/   7 张卡组件

领域模型（契约真源）

• contracts-mall promotion 分节：PromotionActivityPort（类目/列表/详情/场次四方法， adapter 侧 listActivitySessions/getActivityDetail 精确 ref 校验）、PromotionOfferPort、 PromotionEntitlementPort、PromotionQueryContext（scope + reqCtx 但合）。
• offerRef 即约定标识（如 <provider>:offer:<id> / alipay:bumpin:prize:<id>），是跨模块 卡面与工具输入姻的编解码键。

工具清单（tools.ts；createPromotionTools:318；hint 包裹 754-768；注册 index.ts:85-87）

| 工具 | 定义行 | oneLiner | carding | actions | |---|---|---|---|---| | listActivityCategories | tools.ts:410 | 活动类目列表；联单分流判定 delegateLinkedActivity（320-326）| promotion-activity-category-list | 无 | | listActivities | tools.ts:437 | 活动列表（categoryId/keyword/dataScope(CURRENT|HISTORY)/registrationRequired/startsAfter/endsBefore/cursor/limit 缺省 10；条件解析 resolveCategoryId 456-457）| promotion-activity-list | 无 | | getActivityDetail | tools.ts:481 | 活动详情；keyword 无 ref 时取列表第一条兜底（352-363）| promotion-activity-detail | 无 | | listActivitySessions | tools.ts:497 | 活动脉次；详情无 sections 时降级 detail.sessions（507-509）| 无（validation rows）| 无 | | getActivityGuide | tools.ts:516 | 参与指引 facts | 无 | 无 | | searchOffers | tools.ts:532 | 优惠检索（presentation 辞表约束卡选型）| promotion-offer-list | 无 | | getOfferDetail | tools.ts:550 | 优惠详情 + 领取入口 | promotion-offer-detail | 是 | | listEntitlements | tools.ts:582 | 我的权益/券列表 | promotion-entitlement-list | 无 | | listPromotions | tools.ts:599 | 营销活动专题列表 | promotion-activity-list | 无 | | getPromotionDetail | tools.ts:618 | 专题详情 | promotion-activity-detail | 无 | | getParticipationGuide | tools.ts:631 | 参与步骤 facts | 无 | 无 | | listCoupons | tools.ts:644 | 可领券列表 | promotion-offer-list | 是 | | getPackageDetail | tools.ts:677 | 套餐详情 + 引导点 | promotion-offer-detail | 是 | | recommendOffers | tools.ts:693 | 推荐优惠（oneLiner 引导句拼装）| promotion-offer-list | 无 | | calculateBestDeal | tools.ts:719 | 最划算试算（输入 currentAmountCents + candidateOfferRefs；输出 estimatedSavingCents/reason/candidatesConsidered）；not-supplied 不出卡（tools.ts:728-730）| 无 | 无 |

细节机制：

• 联单分流 delegateLinkedActivity（tools.ts:320-326）：listActivityCategories 结果中 命中 alipay-activity handler 且无 continueWith 整单委托——活动中心问句直出碰一碰 联单卡，不经本模块活动列表。
• not-supplied 面与真实供给面双声明（index.ts:107/109）：1030 §6.2 的接入面收口点。
• 写动作链（actions.ts）：领取/参与确认工具产出带 actions 的卡面或动作结果，导航跳转策略 由 navigation.ts 统一（跳转链路与安卓侧 pending 观测项相关）。

门禁

• 会员相关查询携 authState：GUEST 可查活动（公开营销面），领取动作由卡面 actions 拉起 客户端续接（未登录时由 member 门禁兜底）。

写动作面

| 动作 | 状态空间 | 入口 | |---|---|---| | 领取券 | StateStore: promotion.entitlements.* | getOfferDetail/listCoupons 卡面 actions | | 参与确认 | StateStore: promotion.participations.* | getPackageDetail/getParticipationGuide 链路 |

卡片清单（7 张）

promotion-activity-category-list、promotion-activity-list、promotion-activity-detail、 promotion-offer-list、promotion-offer-detail、promotion-entitlement-list、 promotion-best-deal。

跨模块协作

• ↔ alipay-activity：联单活动整单委托（delegateLinkedActivity）。
• ← shopping-guide：券信息面消费（领取动作回流本模块写动作面）。

铁律摘要

• import 边界、register 只注册不解析、卡 key = cardType（同全仓）。
• 词表外 presentation 值不得进入卡选型（tools.ts 常量词表收口）。

已知限制与文档漂移

• hasActiveQuote 字段不存在（1030 曾误登，已在本回合撤销）。
• @vendor-contract JSDoc 待 Phase 1 增补（PromotionActivityPort 语义现摘自普通 JSDoc）。