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

package/src/server/tools.ts

@@ -0,0 +1,789 @@
+/** 营销域完整工具集：业务语义对齐 legacy marketing，传输遵循 tbox-app。
+ * 上下文统一化：运行上下文 = 工具 execute 第二参（requireToolRequestContext 显式读取）。 */
+import { createTool, coerceStringifiedFields, withCardEmissionHint } from '@tbox.cn/app-sdk/server';
+import type { ServerContext, ToolExecContextLike } from '@tbox.cn/app-sdk/server';
+import { requireToolRequestContext } from '@tbox.cn/app-sdk/server';
+import { resolveMemberGate, toMallQueryContext } from '@tbox.cn/app-contracts-mall';
+import type {
+  MemberStatusFactory,
+  OfferType,
+  PromotionActivity,
+  PromotionActivityDetail,
+  PromotionAcquisitionPort,
+  PromotionActivityPort,
+  PromotionEntitlement,
+  PromotionEntitlementPort,
+  PromotionOffer,
+  PromotionOfferQueryPort,
+  PromotionQueryContext,
+} from '@tbox.cn/app-contracts-mall';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { z } from 'zod';
+import type { PromotionService } from './service';
+import {
+  resolvePromotionOffersPort,
+  resolvePromotionEntitlementsPort,
+  resolvePromotionActivitiesPort,
+} from './ports';
+import { promotionNavigationQuery } from './navigation';
+
+function coerce<T extends z.ZodTypeAny>(schema: T): T {
+  return z.preprocess(coerceStringifiedFields, schema) as unknown as T;
+}
+
+function toQueryContext(reqCtx: RequestContext): { q: PromotionQueryContext; reqCtx: RequestContext } {
+  return { q: toMallQueryContext(reqCtx), reqCtx };
+}
+
+function withCards<T extends Record<string, unknown>>(facts: T, cardType: string, note: string) {
+  return { ...facts, cards: [{ cardType, data: facts, note }] };
+}
+
+function dateText(value?: string): string | undefined {
+  if (!value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf()) ? undefined : date.toLocaleDateString('zh-CN');
+}
+
+function dateRangeText(start?: string, end?: string): string | undefined {
+  const startText = dateTimeText(start);
+  const endText = dateTimeText(end);
+  if (startText && endText) return `${startText} 至 ${endText}`;
+  return startText || endText;
+}
+
+function dateTimeText(value?: string): string | undefined {
+  if (!value) return undefined;
+  const text = value.trim().replace('T', ' ');
+  return text.length > 19 ? text.slice(0, 19) : text;
+}
+
+function yuanText(cents: number): string {
+  return (cents / 100).toFixed(2).replace(/\.?(0+)$/, '');
+}
+
+function facetText(offer: Pick<PromotionOffer, 'facets'>): string | undefined {
+  const facet = offer.facets.find((item) => item.kind === 'COUPON');
+  if (facet?.discountType === 'AMOUNT') {
+    return facet.thresholdCents !== undefined
+      ? `满 ${yuanText(facet.thresholdCents)} 减 ${yuanText(facet.value)} 元`
+      : `¥${yuanText(facet.value)}`;
+  }
+  if (facet?.discountType === 'PERCENTAGE') return `${(facet.value / 10).toFixed(1)} 折`;
+  const promotion = offer.facets.find((item) => item.kind === 'PROMOTION');
+  return promotion?.kind === 'PROMOTION' ? promotion.ruleDescription : undefined;
+}
+
+function thresholdText(offer: Pick<PromotionOffer, 'facets'>): string | undefined {
+  const facet = offer.facets.find((item) => item.kind === 'COUPON');
+  return facet?.kind === 'COUPON' && facet.thresholdCents !== undefined
+    ? `满 ${yuanText(facet.thresholdCents)} 元可用`
+    : undefined;
+}
+
+function offerListPresentation(items: readonly Pick<PromotionOffer, 'offerType'>[]) {
+  return items.length > 0 && items.every((item) => item.offerType === 'COUPON')
+    ? 'coupon' as const
+    : 'offer' as const;
+}
+
+function offerPresentation(offerType: PromotionOffer['offerType']) {
+  if (offerType === 'PROMOTION') return 'promotion' as const;
+  if (offerType === 'BUNDLE') return 'package' as const;
+  return 'offer' as const;
+}
+
+export function offerSummary(offer: PromotionOffer) {
+  const validity = offer.validityText ?? dateRangeText(offer.validity.start, offer.validity.end);
+  return {
+    offerRef: offer.offerRef,
+    title: offer.title,
+    ...(offer.subtitle ? { subtitle: offer.subtitle } : {}),
+    offerType: offer.offerType,
+    ...(facetText(offer) ? { benefitText: facetText(offer) } : {}),
+    ...(thresholdText(offer) ? { thresholdText: thresholdText(offer) } : {}),
+    ...(offer.priceText ? { priceText: offer.priceText } : {}),
+    ...(offer.originalPriceText ? { originalPriceText: offer.originalPriceText } : {}),
+    ...(offer.discountLabel ? { discountLabel: offer.discountLabel } : {}),
+    ...(offer.claimActionLabel ? { claimActionLabel: offer.claimActionLabel } : {}),
+    ...(offer.purchaseUrl ? { purchaseUrl: offer.purchaseUrl } : {}),
+    ...(offer.freeCouponClaimMode ? { freeCouponClaimMode: offer.freeCouponClaimMode } : {}),
+    ...(offer.stockText ? { stockText: offer.stockText } : {}),
+    ...(offer.usageNoticeText ? { usageNoticeText: offer.usageNoticeText } : {}),
+    ...(offer.usageSceneText ? { usageSceneText: offer.usageSceneText } : {}),
+    ...(offer.usageTimeText ? { usageTimeText: offer.usageTimeText } : {}),
+    ...(offer.claimTimeText ? { claimTimeText: offer.claimTimeText } : {}),
+    ...(offer.usageRuleText ? { usageRuleText: offer.usageRuleText } : {}),
+    ...(offer.guaranteeText ? { guaranteeText: offer.guaranteeText } : {}),
+    claimable: offer.availability.status === 'AVAILABLE',
+    availabilityStatus: offer.availability.status,
+    ...(validity ? { validityText: validity } : {}),
+    ...(offer.imageUrl ? { imageUrl: offer.imageUrl } : {}),
+    tags: [...offer.tags],
+    itemActions: [
+      {
+        kind: 'send' as const,
+        label: '查看详情',
+        value: promotionNavigationQuery.offerDetail(offer.title),
+      },
+    ],
+  };
+}
+
+export function offerDetail(
+  offer: PromotionOffer,
+  supportsAcquisition: boolean,
+  presentation:
+    | 'offer'
+    | 'promotion'
+    | 'promotion-guide'
+    | 'coupon'
+    | 'package' = 'offer',
+  stores?: readonly {
+    storeId: string;
+    storeName: string;
+    businessName?: string;
+    address?: string;
+    floor?: string;
+  }[],
+) {
+  const validity = offer.validityText ?? dateRangeText(offer.validity.start, offer.validity.end);
+  const claimable = supportsAcquisition && offer.availability.status === 'AVAILABLE';
+  return {
+    presentation,
+    offerRef: offer.offerRef,
+    title: offer.title,
+    offerType: offer.offerType,
+    ...(offer.subtitle ? { subtitle: offer.subtitle } : {}),
+    ...(offer.description ? { description: offer.description } : {}),
+    ...(offer.imageUrl ? { imageUrl: offer.imageUrl } : {}),
+    ...(facetText(offer) ? { benefitText: facetText(offer) } : {}),
+    ...(thresholdText(offer) ? { thresholdText: thresholdText(offer) } : {}),
+    ...(offer.priceText ? { priceText: offer.priceText } : {}),
+    ...(offer.originalPriceText ? { originalPriceText: offer.originalPriceText } : {}),
+    ...(offer.discountLabel ? { discountLabel: offer.discountLabel } : {}),
+    ...(offer.claimActionLabel ? { claimActionLabel: offer.claimActionLabel } : {}),
+    ...(offer.purchaseUrl ? { purchaseUrl: offer.purchaseUrl } : {}),
+    ...(offer.stockText ? { stockText: offer.stockText } : {}),
+    ...(offer.usageNoticeText ? { usageNoticeText: offer.usageNoticeText } : {}),
+    ...(offer.usageSceneText ? { usageSceneText: offer.usageSceneText } : {}),
+    ...(offer.usageTimeText ? { usageTimeText: offer.usageTimeText } : {}),
+    ...(offer.claimTimeText ? { claimTimeText: offer.claimTimeText } : {}),
+    ...(offer.usageRuleText ? { usageRuleText: offer.usageRuleText } : {}),
+    ...(offer.guaranteeText ? { guaranteeText: offer.guaranteeText } : {}),
+    ...(validity ? { validityText: validity } : {}),
+    rules:
+      offer.participation?.steps.map((step) =>
+        step.description ? `${step.title}：${step.description}` : step.title,
+      ) ?? [],
+    ...(offer.participation
+      ? {
+          participationMode: offer.participation.mode,
+          steps: offer.participation.steps.map((step) => ({
+            title: step.title,
+            ...(step.description ? { description: step.description } : {}),
+          })),
+          requirements: [...(offer.participation.requirements ?? [])],
+          ...(offer.participation.notice ? { notice: offer.participation.notice } : {}),
+        }
+      : {}),
+    ...(stores && stores.length > 0 ? { stores: [...stores] } : {}),
+    ...(offer.facets.find((facet) => facet.kind === 'BUNDLE')?.kind === 'BUNDLE'
+      ? {
+          bundleItems: offer.facets
+            .filter((facet) => facet.kind === 'BUNDLE')
+            .flatMap((facet) => facet.items.map((item) => ({ ...item }))),
+        }
+      : {}),
+    claimable,
+    ...(!claimable
+      ? {
+          unavailableReason: !supportsAcquisition
+            ? '当前商场未装配优惠领取通道'
+            : offer.availability.reasonCodes.join('；') || '暂不可领取',
+        }
+      : {}),
+    caveats: ['优惠资格、库存和最终优惠以领取或使用时为准'],
+  };
+}
+
+export function entitlementSummary(entitlement: PromotionEntitlement) {
+  const validUntil = dateText(entitlement.validUntil);
+  const validity = dateRangeText(entitlement.validFrom, entitlement.validUntil);
+  return {
+    entitlementRef: entitlement.entitlementRef,
+    title: entitlement.title,
+    ...(entitlement.imageUrl ? { imageUrl: entitlement.imageUrl } : {}),
+    entitlementType: entitlement.entitlementType,
+    status: entitlement.status,
+    ...(entitlement.codeMasked ? { codeMasked: entitlement.codeMasked } : {}),
+    ...(entitlement.code ? { code: entitlement.code } : {}),
+    ...(entitlement.qrCodeEnabled !== undefined ? { qrCodeEnabled: entitlement.qrCodeEnabled } : {}),
+    ...(entitlement.benefitText ? { benefitText: entitlement.benefitText } : {}),
+    ...(entitlement.thresholdText ? { thresholdText: entitlement.thresholdText } : {}),
+    ...(entitlement.usageNotice ? { usageNotice: entitlement.usageNotice } : {}),
+    ...(entitlement.guaranteeText ? { guaranteeText: entitlement.guaranteeText } : {}),
+    ...(entitlement.usageSceneText ? { usageSceneText: entitlement.usageSceneText } : {}),
+    ...(entitlement.usageTimeText ? { usageTimeText: entitlement.usageTimeText } : {}),
+    ...(entitlement.claimTimeText ? { claimTimeText: entitlement.claimTimeText } : {}),
+    ...(entitlement.usageRuleText ? { usageRuleText: entitlement.usageRuleText } : {}),
+    ...(entitlement.stores?.length ? { stores: entitlement.stores.map((store) => ({ ...store })) } : {}),
+    // CouponSheet already supplies the "有效期" label; keep this value label-free.
+    ...(entitlement.validityText || validity ? { validityText: entitlement.validityText ?? validity } : {}),
+    ...(validUntil ? { validUntilText: `有效期至 ${validUntil}` } : {}),
+  };
+}
+
+function activityAvailability(detail: Pick<PromotionActivityDetail, 'startAt' | 'endAt' | 'remainingQuota'>) {
+  if (detail.remainingQuota === 0) return 'FULL' as const;
+  const now = Date.now();
+  if (detail.endAt && new Date(detail.endAt).valueOf() < now) return 'ENDED' as const;
+  if (detail.startAt && new Date(detail.startAt).valueOf() > now) return 'UPCOMING' as const;
+  return 'AVAILABLE' as const;
+}
+
+export function activitySummary(
+  item: PromotionActivity,
+  categoryNames: ReadonlyMap<string, string> = new Map(),
+) {
+  return {
+    activityRef: item.activityRef,
+    title: item.title,
+    ...(item.subtitle ? { subtitle: item.subtitle } : {}),
+    ...(item.coverUrl ? { coverUrl: item.coverUrl } : {}),
+    registrationRequired: item.registrationRequired,
+    ...(item.jumpOnly ? { jumpOnly: true } : {}),
+    ...(item.jumpLabel ? { jumpLabel: item.jumpLabel } : {}),
+    ...(item.categoryId && categoryNames.get(item.categoryId)
+      ? { categoryName: categoryNames.get(item.categoryId) }
+      : {}),
+    availabilityStatus: activityAvailability(item),
+    ...(item.remainingQuota !== undefined ? { remainingQuota: item.remainingQuota } : {}),
+    ...(dateText(item.startAt) ? { periodText: `${dateText(item.startAt)} 起` } : {}),
+    itemActions: item.jumpOnly && item.registrationUrl
+      ? [{ kind: 'link' as const, label: item.jumpLabel ?? '打开小程序', url: item.registrationUrl }]
+      : [{ kind: 'send' as const, label: '查看活动详情', value: promotionNavigationQuery.activityDetail(item.title) }],
+  };
+}
+
+export function activityDetail(
+  detail: PromotionActivityDetail,
+  presentation: 'detail' | 'schedule' | 'guide' = 'detail',
+) {
+  const start = dateText(detail.startAt);
+  const end = dateText(detail.endAt);
+  // 报名深链为 provider 出参快照（数据驱动，F5 起不再模块侧拼装）
+  const registrationUrl = detail.registrationUrl;
+  return {
+    presentation,
+    activityRef: detail.activityRef,
+    title: detail.title,
+    ...(detail.subtitle ? { subtitle: detail.subtitle } : {}),
+    ...(detail.description ? { description: detail.description } : {}),
+    ...(detail.coverUrl ? { coverUrl: detail.coverUrl } : {}),
+    ...(start ? { periodText: end && end !== start ? `${start} - ${end}` : `${start} 起` } : {}),
+    registrationRequired: detail.registrationRequired,
+    ...(detail.jumpOnly ? { jumpOnly: true } : {}),
+    ...(detail.jumpLabel ? { jumpLabel: detail.jumpLabel } : {}),
+    ...(registrationUrl ? { registrationUrl } : {}),
+    ...(detail.remainingQuota !== undefined ? { remainingQuota: detail.remainingQuota } : {}),
+    sessions: detail.sessions.map((session) => ({
+      sessionRef: session.sessionRef,
+      title: session.title,
+      startText: new Date(session.startAt).toLocaleString('zh-CN'),
+      ...(session.endAt ? { endText: new Date(session.endAt).toLocaleString('zh-CN') } : {}),
+      ...(session.location ? { location: session.location } : {}),
+      ...(session.remainingQuota !== undefined ? { remainingQuota: session.remainingQuota } : {}),
+      status: session.status,
+    })),
+    guideSteps:
+      detail.guide?.steps.map((step) =>
+        step.description ? `${step.title}：${step.description}` : step.title,
+      ) ?? [],
+    conditions: [...(detail.guide?.conditions ?? [])],
+    guideItems:
+      detail.guide?.steps.map((step) => ({
+        title: step.title,
+        ...(step.description ? { description: step.description } : {}),
+      })) ?? [],
+    ...(detail.guide?.notice ? { notice: detail.guide.notice } : {}),
+  };
+}
+
+const searchInput = coerce(
+  z.object({
+    keyword: z.string().optional(),
+    scene: z.string().optional(),
+    cursor: z.string().optional(),
+    limit: z.string().optional(),
+  }),
+);
+const detailInput = coerce(z.object({ offerRef: z.string().optional(), keyword: z.string().optional() }));
+const activityDetailInput = coerce(
+  z.object({ activityRef: z.string().optional(), keyword: z.string().optional() }),
+);
+
+export function createPromotionTools(opts: { getCtx: () => ServerContext }) {
+  /** 活动工具与确定性活动意图共用联单分流；未启用策略/未装模块返回 undefined。 */
+  const delegateLinkedActivity = async (reqCtx: RequestContext) => {
+    const ctx = opts.getCtx();
+    const handler = ctx.handlers.resolve('alipay-activity');
+    if (!handler) return undefined;
+    const result = await handler.handle('activity-router', { content: '活动中心' }, ctx, reqCtx);
+    return result.continueWith ? undefined : result;
+  };
+
+  /** 工具 execute 第二参 → 请求级 promotion 槽服务（require 变体 fail-visible）。
+   *  017 槽位原子化：按工具语义选槽——offer 族 → promotion.offers、权益族 →
+   *  promotion.entitlements、活动族 → promotion.activities；listCoupons 按 mode 分流。 */
+  const requireService = async <T>(
+    execCtx: ToolExecContextLike,
+    resolve: (reqCtx: RequestContext, ctx: ServerContext) => Promise<T>,
+  ): Promise<{ service: T; q: PromotionQueryContext; reqCtx: RequestContext }> => {
+    const ctx = opts.getCtx();
+    const reqCtx = requireToolRequestContext(execCtx);
+    const context = toQueryContext(reqCtx);
+    return { service: await resolve(context.reqCtx, ctx), q: context.q, reqCtx: context.reqCtx };
+  };
+  const supportsAcquire = (service: PromotionService | PromotionOfferQueryPort | PromotionAcquisitionPort) =>
+    (service as PromotionService).supportsAcquisition !== false; // 能力位运行期探测（fat 实例属性）
+  const resolveOffer = async (
+    service: PromotionOfferQueryPort,
+    q: PromotionQueryContext,
+    args: Record<string, unknown>,
+    offerTypes?: readonly OfferType[],
+  ) => {
+    if (typeof args.offerRef === 'string' && args.offerRef) {
+      return service.getOfferDetail(q, { offerRef: args.offerRef });
+    }
+    const page = await service.searchOffers(q, {
+      keyword: args.keyword as string | undefined,
+      offerTypes,
+      limit: 1,
+    });
+    return page.items[0] ?? null;
+  };
+  const resolveActivity = async (
+    service: PromotionActivityPort,
+    q: PromotionQueryContext,
+    args: Record<string, unknown>,
+  ) => {
+    if (typeof args.activityRef === 'string' && args.activityRef) {
+      return service.getActivityDetail(q, args.activityRef);
+    }
+    const page = await service.listActivities(q, { keyword: args.keyword as string | undefined, limit: 1 });
+    const first = page.items[0];
+    return first ? service.getActivityDetail(q, first.activityRef) : null;
+  };
+  const search = (
+    service: PromotionOfferQueryPort,
+    q: PromotionQueryContext,
+    args: Record<string, unknown>,
+    offerTypes?: readonly OfferType[],
+  ) =>
+    service.searchOffers(q, {
+      keyword: args.keyword as string | undefined,
+      scene: args.scene as string | undefined,
+      cursor: args.cursor as string | undefined,
+      limit: args.limit ? Number(args.limit) : 50,
+      offerTypes,
+    });
+  const entitlementFacts = async (
+    service: PromotionEntitlementPort,
+    q: PromotionQueryContext,
+    args: Record<string, unknown>,
+    reqCtx?: RequestContext,
+  ) => {
+    // 会员门禁（我的券 = 属人查询）：硬门禁态出 member 域 CTA 卡（mall 模板投影半屏闭环）；
+    // member 未装 / unknown / unavailable → 软放行（InMemory 演示态照常）
+    const ctx = opts.getCtx();
+    const factory = ctx.services?.resolve?.('member.status') as MemberStatusFactory | undefined;
+    const gate = reqCtx ? await resolveMemberGate(factory, reqCtx) : undefined;
+    if (gate) {
+      return {
+        found: false as const,
+        items: [] as never[],
+        noResultsReason: gate.notice,
+        ...(gate.card ? { cards: [gate.card] } : {}),
+      };
+    }
+    const page = await service.listEntitlements(q, {
+      cursor: args.cursor as string | undefined,
+      limit: args.limit ? Number(args.limit) : 50,
+    });
+    return {
+      mallId: q.scope.mallId,
+      miniAppId: q.scope.miniAppId,
+      items: page.items.map(entitlementSummary),
+      ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+      ...(page.items.length === 0 ? { noResultsReason: '还没有优惠券，可让我帮你找找可领优惠' } : {}),
+    };
+  };
+
+  const listActivityCategories = createTool({
+    id: 'listActivityCategories',
+    description: '查询当前商场全部活动分类，用于亲子、市集、美食等活动筛选。',
+    inputSchema: coerce(z.object({})),
+    execute: async (_args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'listActivityCategories');
+      const delegated = await delegateLinkedActivity(reqCtx);
+      if (delegated) return delegated;
+      const { service } = await requireService(execCtx, resolvePromotionActivitiesPort);
+      const items = (await service.listActivityCategories?.()) ?? [];
+      const facts = {
+        items: items.map((item) => ({
+          ...item,
+          itemActions: [
+            {
+              kind: 'send' as const,
+              label: `查看${item.name}活动`,
+              value: promotionNavigationQuery.activityCategory(item.name),
+            },
+          ],
+        })),
+        ...(items.length === 0 ? { noResultsReason: '当前商场暂未返回活动分类' } : {}),
+      };
+      return items.length ? withCards(facts, 'promotion-activity-category-list', `活动分类 ${items.length} 个${items[0] ? ` · 含${items[0]!.name}` : ''}`) : facts;
+    },
+  });
+
+  const listActivities = createTool({
+    id: 'listActivities',
+    description: '按分类、关键词、当前/往期、报名要求和日期范围查询商场活动；查询本周活动时传本周日期范围。',
+    inputSchema: coerce(
+      z.object({
+        categoryId: z.string().optional(),
+        keyword: z.string().optional(),
+        dataScope: z.enum(['CURRENT', 'HISTORY']).optional(),
+        registrationRequired: z.string().optional(),
+        startsAfter: z.string().optional(),
+        endsBefore: z.string().optional(),
+        cursor: z.string().optional(),
+        limit: z.string().optional(),
+      }),
+    ),
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'listActivities');
+      const delegated = await delegateLinkedActivity(reqCtx);
+      if (delegated) return delegated;
+      const { service, q } = await requireService(execCtx, resolvePromotionActivitiesPort);
+      let categoryId = args.categoryId as string | undefined;
+      // resolveCategoryId = 模块 fat 扩展能力口（非契约 Port 成员），运行期 typeof 探测
+      const resolveCategoryId = (service as PromotionService).resolveCategoryId;
+      if (categoryId && resolveCategoryId) categoryId = await resolveCategoryId(categoryId);
+      const page = await service.listActivities(q, {
+        categoryId,
+        keyword: args.keyword as string | undefined,
+        dataScope: args.dataScope as 'CURRENT' | 'HISTORY' | undefined,
+        registrationRequired:
+          args.registrationRequired === undefined ? undefined : args.registrationRequired === 'true',
+        startsAfter: args.startsAfter as string | undefined,
+        endsBefore: args.endsBefore as string | undefined,
+        cursor: args.cursor as string | undefined,
+        limit: args.limit ? Number(args.limit) : 10,
+      });
+      const categories = (await service.listActivityCategories?.()) ?? [];
+      const categoryNames = new Map(categories.map((item) => [item.categoryId, item.name]));
+      const facts = {
+        items: page.items.map((item) => activitySummary(item, categoryNames)),
+        ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        ...(page.items.length === 0 ? { noResultsReason: '当前筛选范围内暂无活动' } : {}),
+      };
+      return page.items.length ? withCards(facts, 'promotion-activity-list', `商场活动 ${page.items.length} 场${page.items[0] ? ` · ${page.items[0].title}` : ''}`) : facts;
+    },
+  });
+
+  const getActivityDetail = createTool({
+    id: 'getActivityDetail',
+    description: '查询指定活动详情、时间、名额和参与条件。',
+    inputSchema: activityDetailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'getActivityDetail');
+      const delegated = await delegateLinkedActivity(reqCtx);
+      if (delegated) return delegated;
+      const { service, q } = await requireService(execCtx, resolvePromotionActivitiesPort);
+      const detail = await resolveActivity(service, q, args);
+      if (!detail) return { found: false, message: '未找到该活动' };
+      const facts = { found: true as const, ...activityDetail(detail, 'detail') };
+      return withCards(facts, 'promotion-activity-detail', `活动详情：${detail.title}`);
+    },
+  });
+
+  const listActivitySessions = createTool({
+    id: 'listActivitySessions',
+    description: '查询指定活动的可选场次，只返回只读状态，不执行报名。',
+    inputSchema: activityDetailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'listActivitySessions');
+      const delegated = await delegateLinkedActivity(reqCtx);
+      if (delegated) return delegated;
+      const { service, q } = await requireService(execCtx, resolvePromotionActivitiesPort);
+      const detail = await resolveActivity(service, q, args);
+      if (!detail) return { found: false, message: '未找到该活动' };
+      const sessions = service.listActivitySessions
+        ? await service.listActivitySessions(q, detail.activityRef)
+        : detail.sessions;
+      const facts = activityDetail({ ...detail, sessions }, 'schedule');
+      return withCards(facts, 'promotion-activity-detail', `活动场次：${detail.title}`);
+    },
+  });
+
+  const getActivityGuide = createTool({
+    id: 'getActivityGuide',
+    description: '查询指定活动的报名条件和参与步骤，不执行报名。',
+    inputSchema: activityDetailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const reqCtx = requireToolRequestContext(execCtx, 'getActivityGuide');
+      const delegated = await delegateLinkedActivity(reqCtx);
+      if (delegated) return delegated;
+      const { service, q } = await requireService(execCtx, resolvePromotionActivitiesPort);
+      const detail = await resolveActivity(service, q, args);
+      if (!detail) return { found: false, message: '未找到该活动' };
+      const facts = activityDetail(detail, 'guide');
+      return withCards(facts, 'promotion-activity-detail', `活动参与方式：${detail.title}`);
+    },
+  });
+
+  const searchOffers = createTool({
+    id: 'searchOffers',
+    description: '搜索当前商场优惠、折扣、团购并支持分页。',
+    inputSchema: searchInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const page = await search(service, q, args);
+      const facts = {
+        presentation: offerListPresentation(page.items),
+        mode: 'search' as const,
+        items: page.items.map(offerSummary),
+        ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        ...(page.items.length === 0 ? { noResultsReason: '未找到相关优惠，可换个关键词试试' } : {}),
+      };
+      return page.items.length ? withCards(facts, 'promotion-offer-list', `优惠搜索 ${page.items.length} 条${page.items[0] ? ` · ${page.items[0].title}` : ''}`) : facts;
+    },
+  });
+
+  const getOfferDetail = createTool({
+    id: 'getOfferDetail',
+    description:
+      '查询通用优惠详情卡（规则、门槛、有效期及领取状态），支持 offerRef、entitlementRef 或关键词反查。',
+    inputSchema: coerce(
+      z.object({ offerRef: z.string().optional(), entitlementRef: z.string().optional(), keyword: z.string().optional() }),
+    ),
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q, reqCtx } = await requireService(execCtx, resolvePromotionOffersPort);
+      // entitlementRef 反查 = 我的券详情（属人）：仅该分支门禁；offerRef/keyword 公共反查不拦
+      if (typeof args.entitlementRef === 'string' && args.entitlementRef) {
+        const ctx = opts.getCtx();
+        const factory = ctx.services?.resolve?.('member.status') as MemberStatusFactory | undefined;
+        const gate = await resolveMemberGate(factory, reqCtx);
+        if (gate) {
+          return { found: false as const, noResultsReason: gate.notice, ...(gate.card ? { cards: [gate.card] } : {}) };
+        }
+      }
+      const offer = await service.getOfferDetail(q, {
+        offerRef: args.offerRef as string | undefined,
+        entitlementRef: args.entitlementRef as string | undefined,
+        keyword: args.keyword as string | undefined,
+      });
+      if (!offer) return { found: false, message: '未找到该优惠' };
+      const facts = {
+        found: true as const,
+        ...offerDetail(offer, supportsAcquire(service), offer.offerType === 'COUPON' ? 'coupon' : offerPresentation(offer.offerType)),
+      };
+      return withCards(facts, 'promotion-offer-detail', `优惠详情：${offer.title}`);
+    },
+  });
+
+  const listEntitlements = createTool({
+    id: 'listEntitlements',
+    description: '仅查询当前登录会员已经领取/拥有的优惠权益和券包；用户问“有什么可领取/可领优惠券”时禁止调用，改用 listCoupons(mode=CLAIMABLE)。已登录未入会时返回入会引导卡（member-enrollment-cta），无需再调 member 域 queryEnrollmentCta。',
+    inputSchema: searchInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q, reqCtx } = await requireService(execCtx, resolvePromotionEntitlementsPort);
+      const facts = await entitlementFacts(service, q, args, reqCtx);
+      return facts.items.length
+        ? withCards(
+            facts,
+            'promotion-entitlement-list',
+            `我的优惠券 ${facts.items.length} 张${facts.items[0] ? ` · ${facts.items[0].title}` : ''}`,
+          )
+        : facts;
+    },
+  });
+
+  const listPromotions = createTool({
+    id: 'listPromotions',
+    description: '查询本周营销专题和促销活动。',
+    inputSchema: searchInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const page = await search(service, q, args, ['PROMOTION']);
+      const facts = {
+        presentation: 'promotion' as const,
+        mode: 'search' as const,
+        summary: '本周值得关注的活动',
+        items: page.items.map(offerSummary),
+        ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        ...(page.items.length === 0 ? { noResultsReason: '本周暂未查询到营销专题' } : {}),
+      };
+      return page.items.length ? withCards(facts, 'promotion-offer-list', `营销专题 ${page.items.length} 个${page.items[0] ? ` · ${page.items[0].title}` : ''}`) : facts;
+    },
+  });
+
+  const getPromotionDetail = createTool({
+    id: 'getPromotionDetail',
+    description: '按营销专题标识或关键词精确查询活动详情。',
+    inputSchema: detailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const offer = await resolveOffer(service, q, args, ['PROMOTION']);
+      if (!offer) return { found: false, message: '未找到该营销专题' };
+      const facts = { found: true as const, ...offerDetail(offer, false, 'promotion') };
+      return withCards(facts, 'promotion-offer-detail', `营销活动详情：${offer.title}`);
+    },
+  });
+
+  const getParticipationGuide = createTool({
+    id: 'getParticipationGuide',
+    description: '查询营销专题的厂商参与步骤，不执行报名或领取。',
+    inputSchema: detailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const offer = await resolveOffer(service, q, args, ['PROMOTION']);
+      if (!offer) return { found: false, message: '未找到该营销专题' };
+      const facts = { found: true as const, ...offerDetail(offer, false, 'promotion-guide') };
+      return withCards(facts, 'promotion-offer-detail', `参与方式：${offer.title}`);
+    },
+  });
+
+  const listCoupons = createTool({
+    id: 'listCoupons',
+    description: '查询优惠券列表。默认只查询当前可领取优惠券（CLAIMABLE）；只有用户明确说“我的券/已领取/券包”时才传 mode=OWNED。mode=OWNED 已登录未入会时返回入会引导卡（member-enrollment-cta），无需再调 member 域 queryEnrollmentCta。',
+    inputSchema: coerce(
+      z.object({
+        mode: z.enum(['CLAIMABLE', 'OWNED']).default('CLAIMABLE'),
+        keyword: z.string().optional(),
+        cursor: z.string().optional(),
+        limit: z.string().optional(),
+      }),
+    ),
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      // 模式分流双槽（017）：OWNED = 我的券 → entitlements 槽；CLAIMABLE = 可领券 → offers 槽
+      if (args.mode === 'OWNED') {
+        const { service, q, reqCtx } = await requireService(execCtx, resolvePromotionEntitlementsPort);
+        const facts = await entitlementFacts(service, q, args, reqCtx);
+        return facts.items.length
+          ? withCards(facts, 'promotion-entitlement-list', `我的优惠券 ${facts.items.length} 张${facts.items[0] ? ` · ${facts.items[0].title ?? ''}` : ''}`)
+          : facts;
+      }
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const page = await search(service, q, args, ['COUPON']);
+      const items = page.items.filter((item) => item.availability.status === 'AVAILABLE');
+      const facts = {
+        presentation: 'coupon' as const,
+        mode: 'claimable' as const,
+        summary: '可领取优惠券',
+        items: items.map(offerSummary),
+        ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        ...(items.length === 0 ? { noResultsReason: '当前商场暂未返回可领优惠券' } : {}),
+      };
+      return items.length ? withCards(facts, 'promotion-offer-list', `可领优惠券 ${items.length} 张${items[0] ? ` · ${items[0].title}` : ''}`) : facts;
+    },
+  });
+
+  const getPackageDetail = createTool({
+    id: 'getPackageDetail',
+    description: '查询组合礼包及其子权益。',
+    inputSchema: detailInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const offer = await resolveOffer(service, q, args, ['BUNDLE']);
+      if (!offer) return { found: false, message: '未找到该优惠礼包' };
+      const facts = {
+        found: true as const,
+        ...offerDetail(offer, supportsAcquire(service), 'package'),
+      };
+      return withCards(facts, 'promotion-offer-detail', `优惠礼包：${offer.title}`);
+    },
+  });
+
+  const recommendOffers = createTool({
+    id: 'recommendOffers',
+    description: '按资格、可用性与预计节省额推荐当前商场优惠。',
+    inputSchema: searchInput,
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const items = await service.recommendOffers(q, {
+        keyword: args.keyword as string | undefined,
+        scene: args.scene as string | undefined,
+        limit: args.limit ? Number(args.limit) : 4,
+      });
+      const unifiedCouponList = (service as PromotionService).usesUnifiedCouponList === true; // 能力位运行期探测
+      const facts = {
+        presentation: unifiedCouponList ? 'coupon' as const : 'recommendation' as const,
+        mode: unifiedCouponList ? 'claimable' as const : 'recommend' as const,
+        summary:
+          items[0]?.availability.status === 'AVAILABLE'
+            ? '当前可用，并优先考虑预计节省额'
+            : '当前暂时无法确认可用优惠，请查看候选条件',
+        items: items.slice(0, 4).map(offerSummary),
+        ...(items.length === 0 ? { noResultsReason: '当前暂无可推荐优惠' } : {}),
+      };
+      return items.length ? withCards(facts, 'promotion-offer-list', `推荐优惠 ${items.length} 条${items[0] ? ` · ${items[0].title}` : ''}`) : facts;
+    },
+  });
+
+  const calculateBestDeal = createTool({
+    id: 'calculateBestDeal',
+    description: '调用已装配厂商能力进行优惠测算；未装配测算能力时仅返回文字说明，不出测算卡。',
+    inputSchema: coerce(
+      z.object({ currentAmountCents: z.string(), candidateOfferRefs: z.array(z.string()).optional() }),
+    ),
+    execute: async (args: Record<string, unknown>, execCtx: ToolExecContextLike) => {
+      const { service, q } = await requireService(execCtx, resolvePromotionOffersPort);
+      const amount = Number(args.currentAmountCents);
+      if (!Number.isSafeInteger(amount) || amount < 0) return { supported: true, message: '请提供有效的消费金额（分）' };
+      const bestDealService = service as PromotionService; // 能力位/能力口运行期探测（fat 实例属性）
+      if (!bestDealService.calculateBestDeal || bestDealService.supportsBestDeal === false) {
+        return { supported: false, originalAmountCents: amount, message: '当前商场暂不支持优惠测算，请在结算页确认最终优惠' };
+      }
+      const result = await bestDealService.calculateBestDeal(q, {
+        currentAmountCents: amount,
+        candidateOfferRefs: args.candidateOfferRefs as string[] | undefined,
+      });
+      const facts = {
+        authoritative: true,
+        originalAmountCents: amount,
+        savingsCents: result.estimatedSavingCents,
+        expectedPayCents: Math.max(0, amount - result.estimatedSavingCents),
+        appliedOfferRefs: result.offerRef ? [result.offerRef] : [],
+        message: result.reason,
+      };
+      return withCards(
+        facts,
+        'promotion-best-deal',
+        `预计省 ${(result.estimatedSavingCents / 100).toFixed(0)} 元 · 应付 ${(Math.max(0, amount - result.estimatedSavingCents) / 100).toFixed(0)} 元`,
+      );
+    },
+  });
+
+  // W2（2026-09-01）：出卡工具创建点单点 wrap（description 追加预告知句）——
+  // 注册即 wrapped 实例；领券/领取类动作卡带 actions 句。
+  return {
+    listActivityCategories: withCardEmissionHint(listActivityCategories),
+    listActivities: withCardEmissionHint(listActivities),
+    getActivityDetail: withCardEmissionHint(getActivityDetail),
+    listActivitySessions: withCardEmissionHint(listActivitySessions),
+    getActivityGuide: withCardEmissionHint(getActivityGuide),
+    searchOffers: withCardEmissionHint(searchOffers),
+    getOfferDetail: withCardEmissionHint(getOfferDetail, { actions: true }),
+    listEntitlements: withCardEmissionHint(listEntitlements),
+    listPromotions: withCardEmissionHint(listPromotions),
+    getPromotionDetail: withCardEmissionHint(getPromotionDetail),
+    getParticipationGuide: withCardEmissionHint(getParticipationGuide),
+    listCoupons: withCardEmissionHint(listCoupons, { actions: true }),
+    getPackageDetail: withCardEmissionHint(getPackageDetail, { actions: true }),
+    recommendOffers: withCardEmissionHint(recommendOffers),
+    calculateBestDeal: withCardEmissionHint(calculateBestDeal),
+  };
+}