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

package/src/server/index.ts

@@ -1,39 +1,134 @@
-import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
-import type { MemberBenefitsPort } from '@tbox.cn/app-contracts-mall';
-import { InMemoryPromotionService } from './service';
-import couponMeta from './cards/coupon/meta';
-import { createPromotionHandler } from './handler';
+import type { ServerContext, ServerModule, PreToolDef } from '@tbox.cn/app-sdk/server';
+import { definePreTool, getRequestContext, loadModuleSkills } from '@tbox.cn/app-sdk/server';
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import { toMallQueryContext, withMallScopeFromQuery } from '@tbox.cn/app-contracts-mall';
+import { inMemoryPromotion, resolvePromotionEntitlementsPort } from './ports';
+import promotionOfferListMeta from './cards/promotion-offer-list/meta';
+import promotionOfferDetailMeta from './cards/promotion-offer-detail/meta';
+import promotionEntitlementListMeta from './cards/promotion-entitlement-list/meta';
+import promotionActivityListMeta from './cards/promotion-activity-list/meta';
+import promotionActivityDetailMeta from './cards/promotion-activity-detail/meta';
+import promotionActivityCategoryListMeta from './cards/promotion-activity-category-list/meta';
+import promotionBestDealMeta from './cards/promotion-best-deal/meta';
+import { createPromotionTools, entitlementSummary } from './tools';
+import { createPromotionActions } from './actions';
+import { createPromotionIntentHandler } from './handler';
 
 export { InMemoryPromotionService } from './service';
-export { default as couponMeta } from './cards/coupon/meta';
+export {
+  resolvePromotionOffersPort,
+  resolvePromotionEntitlementsPort,
+  resolvePromotionActivitiesPort,
+  resolvePromotionAcquisitionPort,
+  inMemoryPromotion,
+} from './ports';
+export { promotionCards } from './cards';
+
+/** 模块级 ServerContext 引用（getCtx 先例） */
+let serverCtx: ServerContext | undefined;
+const getCtx = (): ServerContext => {
+  if (!serverCtx) throw new Error('promotion 模块未注册（ServerContext 未绑定）');
+  return serverCtx;
+};
+
+const tools = createPromotionTools({ getCtx });
 
 /**
- * 模块级单例（B14）：实例在首次 register 时创建，重复调用复用同一实例（状态共享）。
- * member 查询经可变 currentCtx 引用解析到"最近注册的 ctx"——运行期（handle/事件回调）调用
- * resolveService（注册期纯净），测试多 ctx 场景也正确。
+ * 可领券问句确定性预执行（W5 P1，2026-09-01）：券意图轮零 LLM 预执行出券列表卡。
+ * - run = 零参 CLAIMABLE（可领券查询语义，与「有什么券」问词匹配）；
+ * - OWNED 意图排除：用户说「我的券/已领取/券包」需要 mode=OWNED，交模型精确传参；
+ * - silent：不发前端事件；结果 reminder 注入 + cards 经 capture 入本轮候选池；
+ * - 出参体积门：CLAIMABLE 出参 build 期实测 ≤ 2KB（promotion pretool 测试断言），超限即撤本 preTool。
  */
-let currentCtx: ServerContext | null = null;
-let promotionSingleton: InMemoryPromotionService | null = null;
+const OWNED_INTENT_RE = /我的券|已领|券包|券码/;
+
+const listCouponsPreTool = definePreTool(tools.listCoupons, {
+  routing: { mode: 'keywords', terms: ['优惠券', '领券', '有什么券', '可领'] },
+  decide: ({ text }) => {
+    if (!text?.trim()) return { decision: 'skip', reason: '空文本' };
+    if (OWNED_INTENT_RE.test(text)) return { decision: 'skip', reason: 'OWNED 意图（模型传 mode）' };
+    return { decision: 'run', args: { mode: 'CLAIMABLE' as const } };
+  },
+  silent: true,
+});
 
-/** 卡片 meta 声明 map（key 约定 = meta.cardType；数据 + 类型源） */
+const preTools = {
+  listCoupons: listCouponsPreTool,
+} satisfies Record<string, PreToolDef>;
+
+/** 卡片 meta 声明 map（key 约定 = meta.cardType；字面量形态——doctor AST 解析依赖） */
 const cards = {
-  coupon: couponMeta,
+  'promotion-offer-list': promotionOfferListMeta,
+  'promotion-offer-detail': promotionOfferDetailMeta,
+  'promotion-entitlement-list': promotionEntitlementListMeta,
+  'promotion-activity-list': promotionActivityListMeta,
+  'promotion-activity-detail': promotionActivityDetailMeta,
+  'promotion-activity-category-list': promotionActivityCategoryListMeta,
+  'promotion-best-deal': promotionBestDealMeta,
 } as const;
 
+/**
+ * 文件加载式 skill（009 两形态之二；模板 module-weather 同款）：
+ * 顶层 await loadModuleSkills → 填回声明式通道（装配端 registerAll 自动注册）。
+ * codegen 展开改写约定：第一参随包名改写（@tbox.cn/app-module-promotion → @app/module-promotion）。
+ */
+const skills = Object.fromEntries(
+  (await loadModuleSkills('@tbox.cn/app-module-promotion', import.meta.url)).map((s) => [s.name, s]),
+);
+
 /** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
 export const serverModule = {
+  declaration: {
+    moduleId: 'promotion',
+  },
   cards,
+  skills,
+  preTools,
   register(ctx: ServerContext): void {
-    currentCtx = ctx;
-    if (!promotionSingleton) {
-      promotionSingleton = new InMemoryPromotionService(() =>
-        currentCtx?.resolveService<MemberBenefitsPort>('member'),
-      );
+    serverCtx = ctx;
+    ctx.services.register('promotion', inMemoryPromotion);
+    for (const tool of Object.values(tools)) {
+      ctx.tools.register(tool);
     }
-    const promotion = promotionSingleton;
-
-    ctx.services.register('promotion', promotion);
     ctx.cards.registerMap(cards);
-    ctx.handlers.register(createPromotionHandler(ctx));
+    ctx.handlers.register(createPromotionIntentHandler(ctx));
+
+    // 券码详情弹窗按需调用独立 provider 能力；列表接口只负责券包索引。
+    const router = Router();
+    router.get('/entitlement-detail', async (req: Request, res: Response) => {
+      const entitlementRef = typeof req.query['entitlementRef'] === 'string' ? req.query['entitlementRef'].trim() : '';
+      if (!entitlementRef) {
+        res.status(400).json({ error: 'entitlementRef required' });
+        return;
+      }
+      const reqCtx = getRequestContext(req);
+      if (!reqCtx) {
+        res.status(401).json({ error: 'unauthorized' });
+        return;
+      }
+      try {
+        const scopedReqCtx = withMallScopeFromQuery(reqCtx, req.query);
+        const service = await resolvePromotionEntitlementsPort(scopedReqCtx, ctx);
+        const detail = await service.getEntitlementDetail({
+          ...toMallQueryContext(scopedReqCtx),
+        }, entitlementRef);
+        if (!detail) {
+          res.status(404).json({ error: 'not_found' });
+          return;
+        }
+        res.json({ data: entitlementSummary(detail) });
+      } catch (error) {
+        ctx.logger?.warn(`promotion entitlement-detail route failed: ${(error as Error).message}`);
+        res.status(500).json({ error: 'internal_error' });
+      }
+    });
+    ctx.routes.register('promotion', router);
+
+    // 015 S6：唯一写动作 acquire（register 闭包 ctx——SubjectBinding resolveService + 幂等）
+    const actions = createPromotionActions(ctx);
+    for (const action of Object.values(actions)) {
+      ctx.cardActions.register(action);
+    }
   },
 } satisfies ServerModule;

package/src/server/navigation.ts

@@ -0,0 +1,23 @@
+export type PromotionNavigationIntent =
+  | { kind: 'activity-detail'; title: string }
+  | { kind: 'offer-detail'; title: string }
+  | { kind: 'entitlement-detail'; title: string }
+  | { kind: 'activity-category'; name: string };
+
+export const promotionNavigationQuery = {
+  activityDetail: (title: string) => `查看「${title}」的活动详情`,
+  offerDetail: (title: string) => `查看「${title}」的优惠详情`,
+  entitlementDetail: (title: string) => `查看「${title}」这张优惠券的使用详情`,
+  activityCategory: (name: string) => `查看「${name}」分类的活动`,
+} as const;
+
+/** 只解析模块自身生成的自然语言导航句式，避免宽泛关键词误截普通用户问题。 */
+export function parsePromotionNavigationQuery(text: string): PromotionNavigationIntent | null {
+  const subject = text.match(/「([^」]{1,200})」/)?.[1]?.trim();
+  if (!subject) return null;
+  if (text === promotionNavigationQuery.activityDetail(subject)) return { kind: 'activity-detail', title: subject };
+  if (text === promotionNavigationQuery.offerDetail(subject)) return { kind: 'offer-detail', title: subject };
+  if (text === promotionNavigationQuery.entitlementDetail(subject)) return { kind: 'entitlement-detail', title: subject };
+  if (text === promotionNavigationQuery.activityCategory(subject)) return { kind: 'activity-category', name: subject };
+  return null;
+}

package/src/server/ports.ts

@@ -0,0 +1,56 @@
+/**
+ * promotion Port 分槽解析（017 槽位原子化）：四槽独立解析（offers/entitlements/
+ * activities/acquisition）。同域四槽共享厂商网关 transport（request/requestCrm 双信封），
+ * provider manifest 一槽一条目、共享 implementation id（catalog 聚合后同 impl 供给）。
+ *
+ * 预期缺席（未配置/实例缺键/禁用）→ InMemoryPromotionService 兜底；其余错误原样上抛。
+ * 部分绑定形态（offers 厂商 + acquisition InMemory）为显式行为：acquire 走 InMemory
+ * 幂等纯函数派生，与厂商侧领取状态互不可见。
+ */
+import {
+  mallScopeOf,
+  PROMOTION_ACQUISITION_SERVICE,
+  PROMOTION_ACTIVITIES_SERVICE,
+  PROMOTION_ENTITLEMENTS_SERVICE,
+  PROMOTION_OFFERS_SERVICE,
+  type PromotionAcquisitionPort,
+  type PromotionActivityPort,
+  type PromotionEntitlementPort,
+  type PromotionOfferQueryPort,
+} from '@tbox.cn/app-contracts-mall';
+import { isExpectedProviderAbsence, type RequestContext } from '@tbox.cn/app-contracts';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import { InMemoryPromotionService } from './service';
+
+/** 缺省 InMemory 单例（模块包顶层，B14；跨模块消费方 resolveService('promotion') 兼容） */
+export const inMemoryPromotion = new InMemoryPromotionService();
+
+async function resolvePromotionSlot<T>(
+  service: string,
+  reqCtx: RequestContext,
+  ctx: ServerContext | undefined,
+  fallback: T,
+): Promise<T> {
+  if (!ctx?.integrations) return fallback;
+  try {
+    return (await ctx.integrations.resolveService({
+      service,
+      scope: mallScopeOf(reqCtx),
+      request: reqCtx,
+    })) as T;
+  } catch (e) {
+    if (isExpectedProviderAbsence(e)) return fallback; // 预期缺席 → InMemory 兜底
+    throw e; // PROVIDER_NOT_IMPLEMENTED 等非预期缺席 → 上抛（配置即声明，F5 起无回退）
+  }
+}
+
+export const resolvePromotionOffersPort = (reqCtx: RequestContext, ctx?: ServerContext) =>
+  resolvePromotionSlot<PromotionOfferQueryPort>(PROMOTION_OFFERS_SERVICE, reqCtx, ctx, inMemoryPromotion);
+export const resolvePromotionEntitlementsPort = (reqCtx: RequestContext, ctx?: ServerContext) =>
+  resolvePromotionSlot<PromotionEntitlementPort>(PROMOTION_ENTITLEMENTS_SERVICE, reqCtx, ctx, inMemoryPromotion);
+export const resolvePromotionActivitiesPort = (reqCtx: RequestContext, ctx?: ServerContext) =>
+  resolvePromotionSlot<PromotionActivityPort>(PROMOTION_ACTIVITIES_SERVICE, reqCtx, ctx, inMemoryPromotion);
+export const resolvePromotionAcquisitionPort = (reqCtx: RequestContext, ctx?: ServerContext) =>
+  resolvePromotionSlot<PromotionAcquisitionPort>(PROMOTION_ACQUISITION_SERVICE, reqCtx, ctx, inMemoryPromotion);
+
+export { InMemoryPromotionService };

package/src/server/service.ts

@@ -1,29 +1,248 @@
-import type { Coupon } from '@tbox.cn/app-contracts-mall';
-import type { MemberBenefitsPort, PromotionQueryPort } from '@tbox.cn/app-contracts-mall';
-
-/** PromotionService：营销资格与发券 */
-export interface PromotionService extends PromotionQueryPort {}
-
 /**
- * 资格校验 + 推荐降级链（001 安全铁律：模型只读，发券为写入需确认——PoC 只做查询资格）。
- * 通过注入 getMember 访问会员数据，不依赖 member 实现包（结构类型子集接口）。
+ * InMemory 营销服务（015 S6：四 Port 演示实现；未装配 provider 降级 + 单测基座）。
+ * 演示数据：2 Offer（满减券/团购）+ 1 活动 + entitlements 按 acquire 落账。
  */
+import type {
+  PromotionQueryContext,
+  PromotionSearchInput,
+  PromotionOfferQueryPort,
+  PromotionEntitlementPort,
+  PromotionActivityPort,
+  PromotionAcquisitionPort,
+  PromotionOffer,
+  PromotionOfferPage,
+  PromotionEntitlement,
+  PromotionEntitlementPage,
+  PromotionActivity,
+  PromotionActivityPage,
+  PromotionActivityDetail,
+  PromotionOperation,
+  PromotionBestDeal,
+} from '@tbox.cn/app-contracts-mall';
+
+export interface PromotionService
+  extends PromotionOfferQueryPort,
+    PromotionEntitlementPort,
+    PromotionActivityPort,
+    PromotionAcquisitionPort {
+  /** 是否真正装配写通道；C 端只读 Provider 不得据 acquire 方法误判。 */
+  readonly supportsAcquisition?: boolean;
+  /** provider 是否允许输出优惠测算卡；未装配厂商能力时不构造旧候选卡。 */
+  readonly supportsBestDeal?: boolean;
+  /** 推荐结果是否统一使用可领券列表展示，避免进入旧 recommendation 分支。 */
+  readonly usesUnifiedCouponList?: boolean;
+  /** 活动分类名称 → categoryId 归一（provider 装配态实现；InMemory 缺省无——工具层 ?. 降级） */
+  resolveCategoryId?(input: string): Promise<string | undefined>;
+}
+
+const now = () => new Date().toISOString();
+const inDays = (d: number) => new Date(Date.now() + d * 86400_000).toISOString();
+
+const DEMO_OFFERS: PromotionOffer[] = [
+  {
+    offerRef: 'demo:coupon:1001',
+    offerType: 'COUPON',
+    title: '满 100 减 20 元券',
+    subtitle: '全场通用（部分特例商品除外）',
+    tags: ['通用'],
+    validity: { start: now(), end: inDays(30) },
+    facets: [{ kind: 'COUPON', discountType: 'AMOUNT', value: 2000, thresholdCents: 10000 }],
+    availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: now(), authoritative: false },
+    participation: { mode: 'CLAIM_THEN_PURCHASE', steps: [{ title: '领取', description: '点击领取后自动存入卡包' }] },
+  },
+  {
+    offerRef: 'demo:coupon:1002',
+    offerType: 'COUPON',
+    title: '餐饮 85 折券',
+    subtitle: '限餐饮楼层门店',
+    tags: ['餐饮'],
+    validity: { start: now(), end: inDays(15) },
+    facets: [{ kind: 'COUPON', discountType: 'PERCENTAGE', value: 85, thresholdCents: 5000 }],
+    availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: now(), authoritative: false },
+  },
+  {
+    offerRef: 'demo-c:groupon:2001',
+    offerType: 'GROUPON',
+    title: '双人餐团购 129 元',
+    tags: ['团购', '餐饮'],
+    validity: { end: inDays(20) },
+    facets: [{ kind: 'GROUPON', requiredParticipants: 2 }],
+    availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: now(), authoritative: true },
+  },
+];
+
+const DEMO_ACTIVITY: PromotionActivityDetail = {
+  activityRef: 'demo-act:3001',
+  title: '周末亲子市集',
+  subtitle: '手作体验 + 亲子游戏',
+  categoryId: 'family',
+  registrationRequired: true,
+  remainingQuota: 12,
+  startAt: inDays(3),
+  endAt: inDays(4),
+  offerRefs: ['demo:coupon:1002'],
+  description: '本周末中庭亲子市集，含 10+ 手作摊位',
+  sessions: [
+    { sessionRef: 's_1', title: '第一场 10:00-12:00', startAt: inDays(3), remainingQuota: 5, status: 'OPEN' },
+    { sessionRef: 's_2', title: '第二场 14:00-16:00', startAt: inDays(3), remainingQuota: 7, status: 'OPEN' },
+  ],
+  guide: {
+    steps: [
+      { title: '领取优惠券', description: '领取餐饮 85 折券，市集餐饮摊位可用' },
+      { title: '选择场次报名', description: '凭报名码入场' },
+    ],
+    conditions: ['限会员本人参与', '每场限量 20 组家庭'],
+  },
+};
+
 export class InMemoryPromotionService implements PromotionService {
-  constructor(private getMember: () => MemberBenefitsPort | undefined) {}
-
-  async queryEligibleCoupons(userId: string): Promise<Coupon[]> {
-    const member = this.getMember();
-    const points = member ? await member.queryPoints(userId) : { level: 'silver' as const };
-
-    // 推荐降级链：按会员等级降级推荐券面额
-    const coupons: Coupon[] = [
-      {
-        couponId: `coupon_${userId}_${points.level}`,
-        title: points.level === 'platinum' ? '铂金专享停车券' : points.level === 'gold' ? '金卡停车券' : '停车优惠券',
-        amount: points.level === 'platinum' ? 10 : points.level === 'gold' ? 5 : 2,
-        status: 'AVAILABLE',
-      },
-    ];
-    return coupons;
+  readonly supportsAcquisition = true;
+  private entitlements = new Map<string, PromotionEntitlement[]>();
+  private operations = new Map<string, PromotionOperation>();
+  private acquireKeys = new Map<string, string>(); // idempotencyKey → operationRef
+
+  async searchOffers(_q: PromotionQueryContext, input: PromotionSearchInput): Promise<PromotionOfferPage> {
+    const keyword = input.keyword?.trim();
+    const typed = input.offerTypes?.length
+      ? DEMO_OFFERS.filter((offer) => input.offerTypes!.includes(offer.offerType))
+      : DEMO_OFFERS;
+    const items = keyword
+      ? typed.filter((o) => o.title.includes(keyword) || o.tags.some((t) => t.includes(keyword)))
+      : typed;
+    const limit = Math.min(50, input.limit ?? 10);
+    return { items: items.slice(0, limit), hasMore: items.length > limit };
+  }
+
+  async getOfferDetail(
+    _q: PromotionQueryContext,
+    input: { offerRef?: string; entitlementRef?: string; keyword?: string },
+  ): Promise<PromotionOffer | null> {
+    if (input.offerRef) return DEMO_OFFERS.find((o) => o.offerRef === input.offerRef) ?? null;
+    if (input.entitlementRef) {
+      for (const list of this.entitlements.values()) {
+        const ent = list.find((e) => e.entitlementRef === input.entitlementRef);
+        if (ent?.offerRef) return DEMO_OFFERS.find((o) => o.offerRef === ent.offerRef) ?? null;
+      }
+      return null;
+    }
+    if (input.keyword) {
+      const page = await this.searchOffers(_q, { keyword: input.keyword, limit: 1 });
+      return page.items[0] ?? null;
+    }
+    return null;
+  }
+
+  async recommendOffers(q: PromotionQueryContext, input: PromotionSearchInput): Promise<readonly PromotionOffer[]> {
+    const page = await this.searchOffers(q, { ...input, limit: 3 });
+    return page.items;
+  }
+
+  async calculateBestDeal(
+    _q: PromotionQueryContext,
+    input: { currentAmountCents: number; candidateOfferRefs?: readonly string[] },
+  ): Promise<PromotionBestDeal> {
+    const candidates = input.candidateOfferRefs
+      ? DEMO_OFFERS.filter((o) => input.candidateOfferRefs!.includes(o.offerRef))
+      : DEMO_OFFERS;
+    let best: PromotionBestDeal = {
+      offerRef: '',
+      title: '暂无适用优惠',
+      estimatedSavingCents: 0,
+      reason: '当前金额未达到可用门槛',
+      candidatesConsidered: candidates.length,
+    };
+    for (const offer of candidates) {
+      const facet = offer.facets.find((f): f is Extract<typeof f, { kind: 'COUPON' }> => f.kind === 'COUPON');
+      if (!facet) continue;
+      const threshold = facet.thresholdCents ?? 0;
+      if (input.currentAmountCents < threshold) continue;
+      const saving = facet.discountType === 'AMOUNT' ? facet.value : Math.round((input.currentAmountCents * (100 - facet.value)) / 100);
+      if (saving > best.estimatedSavingCents) {
+        best = {
+          offerRef: offer.offerRef,
+          title: offer.title,
+          estimatedSavingCents: saving,
+          reason: `满 ${(threshold / 100).toFixed(0)} 元可用，预计省 ${(saving / 100).toFixed(2)} 元`,
+          candidatesConsidered: candidates.length,
+        };
+      }
+    }
+    return best;
+  }
+
+  async listEntitlements(q: PromotionQueryContext, _input: PromotionSearchInput): Promise<PromotionEntitlementPage> {
+    const items = this.entitlementsOf(q);
+    return { items, hasMore: false };
+  }
+
+  async getEntitlementDetail(q: PromotionQueryContext, entitlementRef: string): Promise<PromotionEntitlement | null> {
+    return this.entitlementsOf(q).find((e) => e.entitlementRef === entitlementRef) ?? null;
+  }
+
+  async listActivities(
+    _q: PromotionQueryContext,
+    input: Parameters<PromotionActivityPort['listActivities']>[1],
+  ): Promise<PromotionActivityPage> {
+    const { sessions: _s, guide: _g, ...activity } = DEMO_ACTIVITY;
+    void _s;
+    void _g;
+    const keyword = input.keyword?.trim();
+    const matchesKeyword = !keyword || `${activity.title} ${activity.subtitle ?? ''}`.includes(keyword);
+    const matchesRegistration =
+      input.registrationRequired === undefined || activity.registrationRequired === input.registrationRequired;
+    const matchesCategory = !input.categoryId || activity.categoryId === input.categoryId;
+    return {
+      items: matchesKeyword && matchesRegistration && matchesCategory ? [activity as PromotionActivity] : [],
+      hasMore: false,
+    };
+  }
+
+  async getActivityDetail(_q: PromotionQueryContext, activityRef: string): Promise<PromotionActivityDetail | null> {
+    return DEMO_ACTIVITY.activityRef === activityRef ? DEMO_ACTIVITY : null;
+  }
+
+  async listActivitySessions(_q: PromotionQueryContext, activityRef: string) {
+    return activityRef === DEMO_ACTIVITY.activityRef ? DEMO_ACTIVITY.sessions : [];
+  }
+
+  async listActivityCategories() {
+    return [{ categoryId: 'family', name: '亲子' }] as const;
+  }
+
+  async acquire(
+    q: PromotionQueryContext,
+    input: { offerRef: string; externalMemberRef: string; idempotencyKey: string },
+  ): Promise<PromotionOperation> {
+    // 幂等：同键返回首果
+    const existingRef = this.acquireKeys.get(input.idempotencyKey);
+    if (existingRef) {
+      const existing = this.operations.get(existingRef);
+      if (existing) return existing;
+    }
+    const offer = DEMO_OFFERS.find((o) => o.offerRef === input.offerRef);
+    const operationRef = `op_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const operation: PromotionOperation = offer
+      ? { operationRef, status: 'SUCCEEDED', offerRef: offer.offerRef, codeMasked: 'AB**CD**EF', observedAt: now() }
+      : { operationRef, status: 'REJECTED', offerRef: input.offerRef, code: '30017', message: '优惠不存在或不可领取', observedAt: now() };
+    if (offer) {
+      const list = this.entitlements.get(q.subjectId ?? 'anon') ?? [];
+      list.unshift({
+        entitlementRef: `ent_${operationRef}`,
+        offerRef: offer.offerRef,
+        title: offer.title,
+        entitlementType: offer.offerType,
+        status: 'EFFECTIVE',
+        codeMasked: 'AB**CD**EF',
+        validUntil: offer.validity.end,
+      });
+      this.entitlements.set(q.subjectId ?? 'anon', list);
+    }
+    this.operations.set(operationRef, operation);
+    this.acquireKeys.set(input.idempotencyKey, operationRef);
+    return operation;
+  }
+
+  private entitlementsOf(q: PromotionQueryContext): PromotionEntitlement[] {
+    return this.entitlements.get(q.subjectId ?? 'anon') ?? [];
   }
 }