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

package/AGENTS.md

@@ -0,0 +1,16 @@
+# module-promotion —— 集成指引（AI 助手用）
+
+本模块为商圈业务模块，声明消费以下服务槽（Port 接口定义见 `src/server/ports/`）：
+
+- 服务槽清单：见 `tbox.module.json` 的 `contributes.services`（demand 侧，含 title/description meta）。
+
+## 自定义 API 对接（AI 集成）
+
+用户为本模块服务槽配置「自定义 API」后，adapter 实施落点 = `packages/provider-custom/`
+（促销：优惠券与促销活动）。实施步骤与完成判据见 `packages/provider-custom/AGENTS.md`；
+本模块 Port 接口为 adapter 的实现契约（输入 `ServiceAdapterInput`：config/instanceId/credentialRef）。
+
+## 真实厂商接入
+
+官方 provider 包形态（manifest 槽声明 + 独立包发布）参照 `modules/provider-mock` 结构样例与
+docs/reference/providers.md；厂商中立措辞纪律见该参考（本文件受 vendor-neutrality 门禁扫描）。

package/README.md

@@ -1,17 +1,96 @@
-# @tbox.cn/app-module-promotion
+# module-promotion · 营销业务组件
 
-商圈营销模块：资格校验、推荐降级链、券卡（codegen 源）。
+商圈营销域承接组件（`@tbox.cn/app-module-promotion`，componentId `promotion`）。
+查询四族（活动/优惠/权益/套餐）+ 券领取与参与写动作 + 最划算计算；provider 包供给
+（业务模块零 vendor）；联单活动整单分流给 alipay-activity。15 工具全量 withCardEmissionHint，
+其中 3 个带 actions 句（预告卡面可拉起动作）。
 
-## 安装
+## 业务职责
 
-```sh
-pnpm add @tbox.cn/app-module-promotion
-```
+| 能力族 | 承接 |
+|---|---|
+| 活动 | 类目/列表/详情/场次/参与指引（含联单分流）|
+| 优惠 | 检索/详情/推荐（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 张卡组件
 
-```sh
-tbox-app module add @tbox.cn/app-module-promotion
-```
+## 领域模型（契约真源）
+
+- 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）。